Establish Git-first TasksNest documentation and audit baseline
This commit is contained in:
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"last_successful_audit": "2026-11-04T10:39:16Z",
|
||||
"last_audited_commit": "01133370e68a6404f755b64c4a6d48243292ee20"
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
# TasksNest architecture reference
|
||||
|
||||
This is a source-checked snapshot of the working tree on 2026-11-04, including uncommitted features. Recheck code before making changes. The repository is authoritative; Project Manager's documentation index is read-only.
|
||||
|
||||
| Area | Start here |
|
||||
| --- | --- |
|
||||
| Runtime and components | [Architecture](architecture/overview.md) |
|
||||
| Data and migrations | [Models](data/models.md) |
|
||||
| HTTP routes and contracts | [Routing](api/routing.md) |
|
||||
| MCP registration and contracts | [MCP overview](mcp/overview.md), [tool inventory](mcp/tools.md) |
|
||||
| Domain workflows | [Features](features/overview.md) |
|
||||
| Setup, deployment and tests | [Operations](operations/overview.md) |
|
||||
| Audit process and findings | [Audit guide](audits/README.md) |
|
||||
|
||||
Existing `main/README.md`, `main/API.md`, `main/MCP.md`, and design specs remain useful background but may contain older or proposed behavior. This reference follows the registered code, not proposals.
|
||||
@@ -0,0 +1,7 @@
|
||||
# API authentication and permissions
|
||||
|
||||
`/api/v1/` uses bearer personal access tokens/OAuth tokens; `food/api.py` contains the scope/ownership helpers and `food/oauth_pat.py` handles PATs. `/api/v1/auth/whoami/` validates a token for the MCP process. OAuth authorization and token routes come from django-oauth-toolkit plus `food/oauth_authorize.py`; scopes are declared in `tasksnest/settings.py`: `food:read/write`, `inventory:read/write`, `journal:read/write`, and `dietary_preferences:read/write`. Scope checks do not replace row ownership checks.
|
||||
|
||||
Browser views use Django sessions and CSRF. `planner/middleware_demo.py` blocks privileged demo paths and OAuth exchanges and rate limits demo writes; the account is identified by `UserSettings.is_demo`. `food/api_middleware.py` makes fallback API errors JSON. The OpenAPI document at `/api/v1/schema/` declares common 400, 401, 403 and 404 responses, but some newer paths may not have full per-field schema coverage. Confirm exact method, validation and pagination in the view and tests before integrating.
|
||||
|
||||
The API uses `Idempotency-Key` for many writes. MCP tool descriptions request clear user intent for destructive or consequential actions; API enforcement is the actual boundary. Dietary conflicts require explicit confirmation at write boundaries where implemented. See [MCP](../mcp/overview.md).
|
||||
@@ -0,0 +1,80 @@
|
||||
# HTTP routing and API inventory
|
||||
|
||||
`main/tasksnest/urls.py` mounts Django admin, OAuth authorization/metadata, `/api/v1/`, and the planner, food, recipes, groceries, Home Assistant, stress and dreams browser URLconfs. The browser routes are in each app’s `urls.py`; methods and CSRF/session handling are specified by their views. This table lists all direct `/api/v1/` registrations from `main/food/api_urls.py` as of 2026-11-04. A path may support more than one method; inspect the view’s method guard and endpoint tests for the exact contract.
|
||||
|
||||
| Path after `/api/v1/` | View |
|
||||
| --- | --- |
|
||||
| `auth/whoami/` | `api.whoami` |
|
||||
| `stress/` | `stress_api.collection` |
|
||||
| `stress/<uuid:identifier>/` | `stress_api.item` |
|
||||
| `dreams/` | `dream_api.collection` |
|
||||
| `dreams/<uuid:identifier>/` | `dream_api.item` |
|
||||
| `schema/` | `api_schema.schema` |
|
||||
| `food/today/` | `api.today` |
|
||||
| `food/products/` | `api.products` |
|
||||
| `food/products/lookup/` | `api.product_lookup` |
|
||||
| `food/products/create/` | `api.product_create` |
|
||||
| `food/products/import/` | `api.product_import` |
|
||||
| `food/log/` | `api.log_create` |
|
||||
| `food/log/<uuid:identifier>/` | `api.log_item` |
|
||||
| `food/log/<uuid:identifier>/attachments/` | `api.attachment_create` |
|
||||
| `food/attachments/<uuid:identifier>/file/` | `api.attachment_file` |
|
||||
| `food/attachments/<uuid:identifier>/` | `api.attachment_delete` |
|
||||
| `kitchen/items/` | `api.inventory_collection` |
|
||||
| `housekeeping/search/` | `housekeeping.search` |
|
||||
| `housekeeping/scan/` | `housekeeping.scan` |
|
||||
| `housekeeping/preview/` | `housekeeping.preview` |
|
||||
| `housekeeping/apply/` | `housekeeping.apply` |
|
||||
| `housekeeping/history/` | `housekeeping.history` |
|
||||
| `nutrition/preview/` | `nutrition_api.preview` |
|
||||
| `nutrition/commit/` | `nutrition_api.commit` |
|
||||
| `nutrition/ingredients/` | `nutrition_api.ingredients` |
|
||||
| `nutrition/ingredients/<uuid:identifier>/` | `nutrition_api.ingredient_correct` |
|
||||
| `nutrition/sources/` | `nutrition_api.sources` |
|
||||
| `nutrition/sources/<uuid:identifier>/` | `nutrition_api.source_item` |
|
||||
| `nutrition/suggestion-exclusions/` | `nutrition_api.suggestion_exclusion` |
|
||||
| `nutrition/recipe-feedback/` | `nutrition_api.recipe_feedback` |
|
||||
| `nutrition/recipe-reviews/` | `nutrition_api.recipe_reviews` |
|
||||
| `nutrition/find-meals/` | `nutrition_api.find_meals` |
|
||||
| `dietary-preferences/` | `dietary_api.collection` |
|
||||
| `dietary-preferences/audit/` | `dietary_api.history` |
|
||||
| `dietary-preferences/evaluate-recipe/` | `dietary_api.evaluate_recipe` |
|
||||
| `dietary-preferences/<uuid:identifier>/` | `dietary_api.item` |
|
||||
| `dietary-preferences/<uuid:identifier>/archive/` | `dietary_api.archive` |
|
||||
| `dietary-preferences/<uuid:identifier>/exceptions/` | `dietary_api.exception_collection` |
|
||||
| `dietary-preferences/<uuid:identifier>/exceptions/<uuid:exception_id>/` | `dietary_api.exception_item` |
|
||||
| `kitchen/import-groceries/` | `api.inventory_import_groceries` |
|
||||
| `kitchen/bulk-update/` | `api.inventory_bulk_update` |
|
||||
| `kitchen/bulk-delete/` | `api.inventory_bulk_delete` |
|
||||
| `kitchen/items/<uuid:identifier>/` | `api.inventory_item` |
|
||||
| `kitchen/stock/` | `api.inventory_stock` |
|
||||
| `kitchen/consumption/preview/` | `api.inventory_preview` |
|
||||
| `kitchen/consumption/` | `api.inventory_consume` |
|
||||
| `kitchen/consumption/<uuid:identifier>/undo/` | `api.inventory_undo` |
|
||||
| `hydration/daily/` | `api.hydration_daily` |
|
||||
| `hydration/manual/` | `api.hydration_log` |
|
||||
| `hydration/manual/<uuid:identifier>/` | `api.hydration_manual_entry` |
|
||||
| `hydration/settings/` | `api.hydration_settings` |
|
||||
| `groceries/` | `grocery_api.collection` |
|
||||
| `groceries/<uuid:identifier>/` | `grocery_api.item` |
|
||||
| `groceries/recipe/<uuid:identifier>/` | `grocery_api.recipe_import` |
|
||||
| `recipes/` | `recipe_api.recipe_search` |
|
||||
| `recipes/cook-later/` | `recipe_api.recipe_cook_later_collection` |
|
||||
| `recipes/cook-later/<uuid:identifier>/` | `recipe_api.recipe_cook_later_item` |
|
||||
| `recipes/create/` | `recipe_api.recipe_create` |
|
||||
| `recipes/compositions/preview/` | `recipe_api.recipe_composition_preview` |
|
||||
| `recipes/compositions/` | `recipe_api.recipe_composition_create` |
|
||||
| `recipes/<uuid:identifier>/` | `recipe_api.recipe_item` |
|
||||
| `recipes/<uuid:identifier>/links/` | `recipe_api.recipe_links` |
|
||||
| `recipes/<uuid:identifier>/links/<uuid:link_id>/` | `recipe_api.recipe_link_item` |
|
||||
| `recipes/<uuid:identifier>/variations/` | `recipe_api.recipe_variation` |
|
||||
| `recipes/<uuid:identifier>/ingredients/` | `recipe_api.recipe_ingredient_create` |
|
||||
| `recipes/<uuid:identifier>/ingredients/<int:item_id>/` | `recipe_api.recipe_ingredient_item` |
|
||||
| `recipes/<uuid:identifier>/subrecipes/` | `recipe_api.recipe_subrecipe_create` |
|
||||
| `recipes/<uuid:identifier>/subrecipes/<int:item_id>/` | `recipe_api.recipe_subrecipe_delete` |
|
||||
| `recipes/<uuid:identifier>/stock/preview/` | `recipe_api.recipe_stock_preview` |
|
||||
| `recipes/<uuid:identifier>/stock/confirm/` | `recipe_api.recipe_stock_confirm` |
|
||||
| `recipes/stock-use/<uuid:identifier>/undo/` | `recipe_api.recipe_stock_undo` |
|
||||
| `recipes/<uuid:identifier>/log/` | `recipe_api.recipe_log` |
|
||||
|
||||
Total direct API paths: **72**. No API v2 route is registered. `/api/v1/schema/` is the server’s schema endpoint; it is the first place to check request and response definitions. See [authentication](authentication.md) and [MCP](../mcp/overview.md).
|
||||
@@ -0,0 +1,7 @@
|
||||
# Configuration and dependencies
|
||||
|
||||
`main/requirements.txt` pins Django 6.1.1, uvicorn, WhiteNoise, django-oauth-toolkit, MCP 2.3.0, cryptography, Pillow, Markdown, nh3 and h3. `main/frontend/package.json` uses Vite 7, Sass and HTMX 2. `tasksnest-host` is the host virtual environment; dependencies should be checked against lock or requirements files before upgrading.
|
||||
|
||||
`main/tasksnest/settings.py` reads `DJANGO_SECRET_KEY` and `DJANGO_DEBUG` from the process environment or ignored root `.env`; missing secret key is fatal. It uses SQLite at `main/db.sqlite3`, private uploads under `main/private_media`, collected static files under `main/staticfiles`, and `Europe/Amsterdam` as the default time zone. Production enables secure cookies and HTTPS redirection; a trusted reverse proxy supplies HTTPS headers.
|
||||
|
||||
Relevant optional settings include `TASKNEST_DEMO_PASSWORD`, `TASKNEST_RECIPE_MATCH_DEMO_USERNAME`, `TASKNEST_MCP_PUBLIC_URL`, `TASKNEST_OAUTH_ISSUER_URL`, `TASKNEST_API_BASE_URL`, `TASKNEST_MCP_FILE_HOSTS`, `OPENFOODFACTS_*`, `GITEA_*`, and `VITE_*`. The MCP process reads its own environment in `mcp_server/server.py`. Never copy values from `.env` or token storage into documentation.
|
||||
@@ -0,0 +1,18 @@
|
||||
# Application architecture
|
||||
|
||||
TasksNest is a Django 6.1 application with SQLite, server-rendered templates and HTMX interactions. Vite builds Sass and JavaScript; WhiteNoise serves collected static files. `main/tasksnest/settings.py` defines installed apps and middleware. `main/tasksnest/urls.py` mounts the web applications, `/api/v1/`, and OAuth endpoints. `main/manage.py`, `tasksnest/wsgi.py`, and `tasksnest/asgi.py` are Django entry points.
|
||||
|
||||
| Component | Responsibility |
|
||||
| --- | --- |
|
||||
| `planner` | Tasks, occurrences, settings, health trackers, dashboard and demo policy |
|
||||
| `food` | Food diary, products, kitchen stock, hydration, nutrition imports, dietary preferences, API and OAuth |
|
||||
| `recipes` | Recipes, composition, variations, cook later, stock use and meal logging |
|
||||
| `groceries` | Shopping list, recipe demand and transfer to inventory |
|
||||
| `home_assistant` | Per-user connection and to-do sync; separate from MCP |
|
||||
| `stress`, `dreams` | Private journals and API endpoints |
|
||||
| `mcp_server` | Separate streamable HTTP process translating MCP calls to the Django API |
|
||||
| `frontend` | Vite asset build and HTMX package |
|
||||
|
||||
Web requests pass through Django middleware, including `DemoAccountPolicyMiddleware`, timezone selection and API error handling. API views use bearer token scope checks and ownership filters; browser views use sessions, CSRF and per-user queries. The MCP process validates a bearer token through `/api/v1/auth/whoami/`, then calls API endpoints on loopback. There is no in-process service injection between MCP and Django.
|
||||
|
||||
Background work is command/service based rather than Celery. Inspect `main/*/management/commands/`, `home_assistant` scheduling code and deployed timers before altering jobs. External integrations include Open Food Facts, optional Gitea contribution data, ntfy and Home Assistant. See [configuration](configuration.md), [routing](../api/routing.md) and [operations](../operations/overview.md).
|
||||
@@ -0,0 +1,26 @@
|
||||
# Initial architecture and documentation audit — 2026-11-04
|
||||
|
||||
**Review status: completed.** Reviewed the working tree at 2026-11-04 10:39 UTC against source, configuration, migrations, registered routes, MCP decorators and relevant tests. Git HEAD was `01133370e68a6404f755b64c4a6d48243292ee20`. The working tree already contained substantial user changes; this report and the documentation reflect those changes without modifying them. The stored commit is a history anchor, not a claim that the dirty working tree was committed.
|
||||
|
||||
## Evidence and checks
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Django app and middleware configuration | Reviewed `main/tasksnest/settings.py` and `urls.py` |
|
||||
| Models and migrations | Reviewed model class inventory, relationships, constraints and migration heads across seven domain apps |
|
||||
| API | 72 direct `/api/v1/` paths extracted from `main/food/api_urls.py`; browser mounts checked in root URLconf |
|
||||
| MCP | 93 `@server.tool` registrations extracted by existing `tool_catalog_audit.catalog()`; ten domains; existing catalog JSON also says 93; no resource or prompt registration found |
|
||||
| Internal Markdown links | `python3 scripts/docs_audit.py --force`: zero broken links; due, no previous audit; semantic review flag false as designed |
|
||||
| Application checks | `manage.py check`: zero issues; `makemigrations --check --dry-run`: no changes detected |
|
||||
| Tests | `mcp_server.test_tool_catalog`: 5 passed; `tests.test_docs_audit`: 3 passed |
|
||||
| Whitespace | `git diff --check`: passed |
|
||||
|
||||
## Findings and follow-up
|
||||
|
||||
- `food` has two differently named `0017` migration files. Django currently reports no model changes, but a later schema change should inspect the migration dependency graph rather than infer order by number.
|
||||
- Current `planner/0025`, `food/0017`–`0024` and other feature files are untracked or modified. Subsequent audits should compare both Git history and tracked working-tree changes, and manually inspect untracked feature files.
|
||||
- The MCP inventory has 93 registrations, while task-management MCP CRUD and whole-house possessions inventory remain proposed Project Manager work. Do not count those as implemented.
|
||||
- `/api/v1/schema/` is a compact OpenAPI document; deeper per-field coverage for newer API paths and exhaustive MCP output/error contracts remain follow-up documentation work. Endpoint and integration tests are the stronger source for those paths.
|
||||
- This review did not run the full Django suite or verify live services. Documentation-only changes do not require a web restart or browser visual test.
|
||||
|
||||
Next recurring audit is due at least 14 days after the successful UTC timestamp in `.audit-state.json`, or sooner with `--force`.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Documentation audit reports
|
||||
|
||||
Run `python3 scripts/docs_audit.py` before card work. `--force` makes the audit eligible regardless of age. The JSON output lists UTC due status, stored commit validity/reachability, tracked source changes and unresolved local Markdown links. It explicitly reports `semantic_review_performed: false`.
|
||||
|
||||
For a due audit, compare changed code with the relevant documents, routes, models, migrations and MCP registrations; inspect tests and record discrepancies. Aim for roughly 20 minutes in recurring audits. Save `YYYY-MM-DD.md` with scope, evidence, checks, findings, unresolved work and whether the review completed. Partial attempts do not advance `last_successful_audit`. Coordinate edits to `.audit-state.json` with other sessions; re-read it immediately before writing and never overwrite a newer successful audit. The state records a completed review, not a passing script run.
|
||||
@@ -0,0 +1,5 @@
|
||||
# Migrations
|
||||
|
||||
Django migrations are stored per app under `main/<app>/migrations/`. Current working tree heads include `planner/0025`, `food/0024`, `recipes/0007`, `groceries/0003`, `home_assistant/0004`, `stress/0002`, and `dreams/0001`. Some heads are untracked in Git at this audit; deployment state may differ. `food` contains two migrations numbered `0017` with different names. Check their dependencies and run `showmigrations` and `makemigrations --check` before schema work; do not infer ordering from filenames.
|
||||
|
||||
Several migrations backfill or preserve data, including food package quantities, hydration contributions, API UUIDs and task ownership/completion. Avoid editing applied migrations; add new migrations after validating the current graph.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Data model map
|
||||
|
||||
Models are in each app's `models.py`; migrations, not this page, define the deployed schema. Most personal records reference Django's auth user. UUID API identifiers often coexist with integer database primary keys. Verify exact constraints and `on_delete` rules before writing data migrations.
|
||||
|
||||
| App | Models and purpose |
|
||||
| --- | --- |
|
||||
| `planner` | `Task`, `TaskOccurrence`, `TaskOccurrenceEvent`, `TaskWeatherShift` manage scheduling; `UserSettings`, fasting and water models hold user settings and tracking; workout, pain, tooth, bowel and sleep models record health events. |
|
||||
| `food` | `FoodProduct`, `FoodPortion`, `FoodLogEntry`, `FoodLogAttachment`, `FoodFavourite`; `KitchenInventoryItem`, package/consumption and scanner models; `CanonicalIngredient`, nutrition import/source/review, suggestions and links; `DietaryPreference`, exception and audit; OAuth PAT, idempotency, housekeeping and Open Food Facts records. |
|
||||
| `recipes` | `Recipe`, ingredient, substitution, subrecipe and link models; selection and cook-later records; stock use lines and cooking runs. |
|
||||
| `groceries` | `GroceryItem`, `GrocerySource`, `GroceryRecipeDemand` connect shopping entries to recipe demand and inventory transfer. |
|
||||
| `home_assistant` | `HomeAssistantConnection`, `HomeAssistantSyncRun`, `HomeAssistantItemMap` store connection, sync history and stable mapping. |
|
||||
| `stress`, `dreams` | `StressEntry`, `DreamEntry` store private journal records. |
|
||||
|
||||
Key cross-app relations: recipe ingredients can point to food products; recipe stock-use lines reference inventory consumption; grocery items can point to products and recipe demand; food diary entries snapshot nutrition so later recipe/product edits do not rewrite history. Recipe links are suggestions; subrecipes are composition. See [features](../features/overview.md).
|
||||
|
||||
Validation lives in model `clean()` methods, forms, API helpers and services, not solely database constraints. Examples include positive quantities and serving counts, no self-link and uniqueness for recipe links, ownership checks, dietary revision checks, and idempotency on creation. Use the relevant service/API tests when changing these rules.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Implemented domain workflows
|
||||
|
||||
| Area | Implemented behavior and code entry points |
|
||||
| --- | --- |
|
||||
| Tasks and boards | `planner/models.py` and `planner/services/occurrences.py` model tasks, recurrence, occurrence state and weather shifts. The planner UI groups and filters tasks; no separate user-defined board model was found. Task CRUD is currently a browser feature; task MCP CRUD is proposed on a Project Manager card, not registered in `mcp_server/server.py`. |
|
||||
| Food diary and hydration | `food/views.py`, `food/api.py`, `food/services/diary.py`, `food/services/hydration.py`; product nutrition snapshots are logged, and eligible drink entries contribute to hydration. |
|
||||
| Kitchen inventory | `food/inventory.py`, `food/services/inventory_consumption.py`, scanner services and API; package-aware deductions, previews, undo and grocery transfer exist. |
|
||||
| Recipes | `recipes/models.py`, `recipes/services/analysis.py`, `cooking.py`, `stock_use.py`; ingredients, substitutions, subrecipes, suggestion links, variations, Cook Later, scaled stock analysis and food logging. A suggestion link does not compose recipes. |
|
||||
| Nutrition curation | `food/nutrition.py`, `nutrition_api.py`, migrations 0017/0021–0024; imported sources, canonical ingredients, recipe reviews, exclusions and user corrections. |
|
||||
| Dietary preferences | `food/dietary_preferences.py` stores private preferences, narrow exceptions, audit history and recipe/product evaluations; uncertain results remain reviewable. |
|
||||
| Groceries | `groceries/services.py` tracks needed/purchased shopping items, recipe demand, and explicit inventory transfer. Marking purchased does not add stock. |
|
||||
| Home Assistant | `home_assistant/sync.py`, `task_sync.py`, models and management command; per-user to-do mapping and scheduled sync. This is separate from the MCP service. |
|
||||
| Health and journals | `planner` health/fasting trackers; `stress` and `dreams` private journals with API and MCP access. |
|
||||
|
||||
Planned cards are not implementation evidence. In particular, whole-house possessions inventory and task-management MCP tools are future work. See [model map](../data/models.md) and [tool inventory](../mcp/tools.md).
|
||||
@@ -0,0 +1,7 @@
|
||||
# MCP server
|
||||
|
||||
`main/mcp_server/server.py` builds a separate `MCPServer` and exposes stateless streamable HTTP at `/mcp` through Uvicorn. The deployment unit is `main/deploy/systemd/tasknest-mcp.service`; it listens on a Tailscale address and calls the Django `/api/v1/` service on loopback. `ApiTokenVerifier` calls `auth/whoami/`. Each tool uses `api_request()` for bearer forwarding, idempotency and errors. The MCP transport advertises OAuth protected-resource metadata; endpoint scopes and ownership are enforced by Django.
|
||||
|
||||
The [tool inventory](tools.md) is extracted from actual `@server.tool` registrations: **93 tools** in the working tree on 2026-11-04. There are no `@server.resource` or `@server.prompt` registrations in `server.py`; no MCP resources or prompts are implemented there. `main/mcp_server/test_tool_catalog.py` checks catalog discovery; `main/mcp_server/tests.py` exercises HTTP transport and selected tool flows. A catalog entry is not proof that every endpoint contract is fully tested.
|
||||
|
||||
Names and descriptions are model-facing API guidance. They distinguish search/preview from writes, ask for user confirmation for destructive actions, and call for idempotency keys on retried creates. Typed Pydantic inputs live above `create_server()` in `server.py`. Outputs are structured when supported, with `ToolError` on API failures. See [API authentication](../api/authentication.md).
|
||||
@@ -0,0 +1,161 @@
|
||||
# Registered MCP tools
|
||||
|
||||
Source: `main/mcp_server/server.py` through `create_server()`, extracted by `main/mcp_server/tool_catalog_audit.py`. **93 tool decorators are registered in the current working tree.** This is a registration inventory; server-side API validation and scope checks remain authoritative. Parameters below are top-level names; typed nested fields and bounds are in `server.py`.
|
||||
|
||||
| Domain | Count |
|
||||
| --- | ---: |
|
||||
| dietary | 10 |
|
||||
| dream | 5 |
|
||||
| food | 10 |
|
||||
| grocery | 6 |
|
||||
| housekeeping | 5 |
|
||||
| hydration | 6 |
|
||||
| inventory | 12 |
|
||||
| nutrition | 10 |
|
||||
| recipe | 24 |
|
||||
| stress | 5 |
|
||||
|
||||
## Dietary
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `dietary_preference_archive` | Archive an owned dietary preference after explicit confirmation | `preference_id`, `expected_revision`, `confirmed` | POST `f'dietary-preferences/{preference_id}/archive/'` |
|
||||
| `dietary_preference_create` | Create a user-reported dietary or cooking preference only after the user explicitly confirms this exact proposed record | `category`, `target_type`, `target_name`, `enforcement`, `idempotency_key`, `impact_description`, `notes`, `confirmed` | POST `'dietary-preferences/'` |
|
||||
| `dietary_preference_exception_add` | Add a narrow, exact product or food tolerance exception to an owned preference after explicit confirmation | `preference_id`, `target_name`, `idempotency_key`, `product_id`, `quantity`, `unit`, `preparation`, `form`, `conditions`, `notes`, `confirmed` | POST `f'dietary-preferences/{preference_id}/exceptions/'` |
|
||||
| `dietary_preference_exception_archive` | Archive an owned exact tolerance exception after explicit confirmation | `preference_id`, `exception_id`, `expected_revision`, `confirmed` | POST `f'dietary-preferences/{preference_id}/exceptions/{exception_id}/'` |
|
||||
| `dietary_preference_exception_update` | Correct an owned exact tolerance exception after explicit user confirmation | `preference_id`, `exception_id`, `expected_revision`, `changes`, `confirmed` | PATCH `f'dietary-preferences/{preference_id}/exceptions/{exception_id}/'` |
|
||||
| `dietary_preference_update` | Update an owned dietary preference after explicit confirmation | `preference_id`, `expected_revision`, `changes`, `confirmed` | PATCH `f'dietary-preferences/{preference_id}/'` |
|
||||
| `dietary_preferences_evaluate_recipe` | Evaluate one owned recipe against your saved dietary preferences | `recipe_id` | GET `'dietary-preferences/evaluate-recipe/'` |
|
||||
| `dietary_preferences_get` | Read one of your own dietary preferences and its exact exceptions | `preference_id` | GET `f'dietary-preferences/{preference_id}/'` |
|
||||
| `dietary_preferences_history` | Read bounded, content-free history of your dietary preference and exception changes | `limit`, `offset` | GET `'dietary-preferences/audit/'` |
|
||||
| `dietary_preferences_list` | Read your own dietary and cooking preferences, including exact exceptions | `active_only`, `limit`, `offset` | GET `'dietary-preferences/'` |
|
||||
|
||||
## Dream
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `dream_create` | Create a private dream for its wake-up date | `entry`, `idempotency_key` | POST `'dreams/'` |
|
||||
| `dream_delete` | Permanently delete an owned dream entry by ID | `entry_id` | DELETE `f'dreams/{entry_id}/'` |
|
||||
| `dream_get` | Read one private dream entry by ID, including its original narrative and separately stored interpretation | `entry_id` | GET `f'dreams/{entry_id}/'` |
|
||||
| `dream_search` | List or search your private dreams by keywords, tag, wake-up date or date range | `query`, `tag`, `date`, `date_from`, `date_to`, `limit`, `offset` | GET `'dreams/'` |
|
||||
| `dream_update` | Update or append user-supplied corrections to an existing owned dream ID | `entry_id`, `changes`, `idempotency_key` | PATCH `f'dreams/{entry_id}/'` |
|
||||
|
||||
## Food
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `food_attach_image` | Attach a client-supplied JPEG, PNG, or WebP image to one owned food entry | `entry_id`, `image_base64`, `image_file`, `mime_type`, `filename`, `caption`, `idempotency_key` | via helper (`_attach`) |
|
||||
| `food_create_product` | Create a manual food product owned by the authenticated user from supplied facts | `product`, `idempotency_key` | POST `'food/products/create/'` |
|
||||
| `food_delete_entry` | Permanently delete one food log entry belonging to the authenticated user | `entry_id` | DELETE `f'food/log/{entry_id}/'` |
|
||||
| `food_get_today` | Read the authenticated user’s food diary for a specific local calendar day, grouped by meal with totals, goals, and remaining calories/macros | `date` | GET `'food/today/'` |
|
||||
| `food_import_product` | Save a selected Open Food Facts product by numeric barcode into your product catalogue | `barcode`, `idempotency_key` | POST `'food/products/import/'` |
|
||||
| `food_log` | Create one Food Diary entry | `food`, `idempotency_key` | POST `'food/log/'` |
|
||||
| `food_log_with_image` | Create one food entry and attach the user-supplied image in one operation | `food`, `image_base64`, `image_file`, `mime_type`, `filename`, `caption`, `idempotency_key` | POST `'food/log/'` |
|
||||
| `food_lookup_product` | Find food product candidates in saved products and optionally Open Food Facts | `query`, `barcode`, `brand`, `package_quantity`, `package_unit`, `limit`, `include_open_food_facts` | GET `'food/products/lookup/'` |
|
||||
| `food_search_products` | Search the authenticated user’s saved TaskNest food products before logging a known food | `query`, `limit`, `include_dietary_context` | GET `'food/products/'` |
|
||||
| `food_update_entry` | Update only the supplied fields of one owned food log entry by opaque ID | `entry_id`, `changes` | PATCH `f'food/log/{entry_id}/'` |
|
||||
|
||||
## Grocery
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `grocery_add` | Add one item to your grocery list | `item`, `idempotency_key` | POST `'groceries/'` |
|
||||
| `grocery_add_recipe` | Preview or confirm missing ingredients for an owned recipe, scaled to servings and selected substitutions | `recipe_id`, `options`, `confirm`, `confirm_uncertain`, `idempotency_key` | POST `f'groceries/recipe/{recipe_id}/'`; GET `f'groceries/recipe/{recipe_id}/'` |
|
||||
| `grocery_delete` | Delete one owned grocery item by stable UUID | `item_id` | DELETE `f'groceries/{item_id}/'` |
|
||||
| `grocery_edit` | Edit an owned grocery item, including purchase status | `item_id`, `changes` | PATCH `f'groceries/{item_id}/'` |
|
||||
| `grocery_list` | List your grocery items by needed, purchased, or all status | `status`, `limit`, `offset` | GET `'groceries/'` |
|
||||
| `grocery_search` | Search your grocery list by text, category, product, and purchase status | `query`, `category`, `product_id`, `status`, `limit`, `offset` | GET `'groceries/'` |
|
||||
|
||||
## Housekeeping
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `housekeeping_apply` | Apply a recent owner-scoped housekeeping preview after explicit confirmation | `confirmation`, `idempotency_key`, `confirmed_same_entity`, `confirmed_link` | POST `'housekeeping/apply/'` |
|
||||
| `housekeeping_history` | Read the authenticated user’s housekeeping audit history | `limit`, `offset` | GET `'housekeeping/history/'` |
|
||||
| `housekeeping_preview` | Preview an owned location/category rename or merge, a category reclassification, a canonical ingredient category/subcategory/descriptive-tag correction, or a canonical ingredient link/unlink | `dataset`, `action`, `source_id`, `new_name`, `target_id`, `target_dataset`, `relation_type`, `confidence`, `new_category`, `new_subcategory`, `new_tags` | POST `'housekeeping/preview/'` |
|
||||
| `housekeeping_scan` | Scan owned records for label variants, missing categories and unlinked recipe ingredients | `dataset`, `limit`, `offset`, `candidate_type` | GET `'housekeeping/scan/'` |
|
||||
| `housekeeping_search` | Search owned locations, categories, products, recipes, canonical ingredients, recipe ingredients, inventory items, source suggestions, recipe tags or reviewed ingredient links | `dataset`, `query`, `exact`, `limit`, `offset`, `category`, `status`, `min_confidence` | GET `'housekeeping/search/'` |
|
||||
|
||||
## Hydration
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `hydration_delete` | Delete an owned standalone manual hydration entry by ID | `entry_id` | DELETE `f'hydration/manual/{entry_id}/'` |
|
||||
| `hydration_get_daily` | Read combined daily hydration, separate manual and Food Diary drink contributions, the daily goal, and remaining amount | `date` | GET `'hydration/daily/'` |
|
||||
| `hydration_log` | Add a standalone manual fluid entry | `amount_ml`, `beverage_type`, `recorded_at`, `idempotency_key` | POST `'hydration/manual/'` |
|
||||
| `hydration_settings_get` | Read hydration goal and automatic drink counting settings for the authenticated user. | — | GET `'hydration/settings/'` |
|
||||
| `hydration_settings_update` | Update hydration goal, automatic Food Diary drink counting, liquid-food inclusion, widget breakdown, manual adjustment permission, or beverage-specific rules. | `changes` | PATCH `'hydration/settings/'` |
|
||||
| `hydration_update` | Correct an owned standalone manual hydration entry by ID | `entry_id`, `amount_ml`, `beverage_type`, `recorded_at` | PATCH `f'hydration/manual/{entry_id}/'` |
|
||||
|
||||
## Inventory
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `inventory_add` | Add an owned saved food product to the authenticated user’s kitchen inventory | `product_id`, `quantity`, `location`, `category`, `notes`, `opened`, `best_before`, `original_amount`, `unit`, `pieces_per_package`, `remaining_pieces`, `piece_amount`, `inner_packs_per_package`, `pieces_per_inner_pack`, `inner_pack_amount`, `inner_pack_label`, `piece_label`, `idempotency_key` | POST `'kitchen/items/'` |
|
||||
| `inventory_bulk_delete` | Preview or archive up to 20 explicit owned inventory rows, without deleting products or consumption history | `item_ids`, `idempotency_key`, `dry_run`, `confirm`, `atomic` | POST `'kitchen/bulk-delete/'` |
|
||||
| `inventory_bulk_update` | Preview or update up to 50 owned inventory rows | `items`, `idempotency_key`, `dry_run`, `atomic` | POST `'kitchen/bulk-update/'` |
|
||||
| `inventory_consume` | Consume an exact quantity from owned inventory packages atomically | `product_id`, `amount`, `unit`, `idempotency_key`, `package_id`, `source_reference`, `description`, `allow_partial` | POST `'kitchen/consumption/'` |
|
||||
| `inventory_get_stock` | Read stock for an owned product ID or search query, optionally limited to a location ID | `product_id`, `query`, `location_id` | GET `'kitchen/stock/'` |
|
||||
| `inventory_import_groceries` | Add up to 20 groceries to your inventory in one operation | `items`, `idempotency_key`, `create_missing_products` | POST `'kitchen/import-groceries/'` |
|
||||
| `inventory_list` | List a bounded page of the authenticated user’s current kitchen inventory | `limit`, `offset`, `include_dietary_context` | GET `'kitchen/items/'` |
|
||||
| `inventory_preview_consumption` | Preview package deductions for one owned product without changing stock | `product_id`, `amount`, `unit`, `package_id` | POST `'kitchen/consumption/preview/'` |
|
||||
| `inventory_remove` | Permanently remove one kitchen inventory item belonging to the authenticated user | `item_id` | DELETE `f'kitchen/items/{item_id}/'` |
|
||||
| `inventory_search` | Search the authenticated user’s current kitchen inventory by food name, brand, barcode, location, or category | `query`, `limit`, `include_dietary_context` | GET `'kitchen/items/'` |
|
||||
| `inventory_undo_consumption` | Undo a previous owned inventory consumption transaction when its affected packages have not changed since | `transaction_id` | POST `f'kitchen/consumption/{transaction_id}/undo/'` |
|
||||
| `inventory_update` | Update only supplied inventory fields | `item_id`, `changes` | PATCH `f'kitchen/items/{item_id}/'` |
|
||||
|
||||
## Nutrition
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `nutrition_find_meals` | Find existing owned recipes with exact ingredient-name or saved-alias matches to one imported nutrition source | `source_id`, `limit`, `offset`, `include_dietary_context` | GET `'nutrition/find-meals/'` |
|
||||
| `nutrition_import_commit` | Commit exactly the previously previewed structured PDF extraction after explicit user approval | `payload`, `confirmation`, `idempotency_key` | POST `'nutrition/commit/'` |
|
||||
| `nutrition_import_preview` | Read-only preview of one PDF (payload {source, ingredients}) or a batch of 1–10 PDFs (payload {documents:[{source, ingredients}]}), up to 100 rows total | `payload` | POST `'nutrition/preview/'` |
|
||||
| `nutrition_ingredient_correct` | Manually correct the category, subcategory or aliases of one owned canonical ingredient after review | `ingredient_id`, `changes` | PATCH `f'nutrition/ingredients/{ingredient_id}/'` |
|
||||
| `nutrition_ingredients_search` | Search your source-suggested canonical ingredients with category, source/week and frequency filters | `category`, `subcategory`, `programme`, `query`, `form`, `verified`, `inventory_status`, `source_id`, `week_start`, `week_end`, `minimum_frequency`, `excluded_only`, `limit`, `offset`, `include_links` | GET `'nutrition/ingredients/'` |
|
||||
| `nutrition_recipe_feedback` | Record the authenticated user’s explicit decision on an existing owned recipe for one imported nutrition source | `source_id`, `recipe_id`, `decision`, `notes`, `adapted_recipe_id` | POST `'nutrition/recipe-feedback/'` |
|
||||
| `nutrition_recipe_reviews` | Read persisted recipe decisions for the authenticated user, optionally filtered to one nutrition source, recipe, or decision | `source_id`, `recipe_id`, `decision`, `limit`, `offset` | GET `'nutrition/recipe-reviews/'` |
|
||||
| `nutrition_source_get` | Read one owned source document record and its original ingredient occurrences, including source label, quantity, preparation, page and linked catalogue product | `source_id` | GET `f'nutrition/sources/{source_id}/'` |
|
||||
| `nutrition_sources_list` | List owner-scoped Body Support/nutrition source documents with week dates, batch IDs, import time and row counts | `programme`, `week_start`, `week_end`, `limit`, `offset` | GET `'nutrition/sources/'` |
|
||||
| `nutrition_suggestion_exclusion` | Exclude or restore one canonical ingredient in future suggestions after explicit user confirmation | `ingredient_id`, `excluded`, `idempotency_key`, `confirmed`, `note` | POST `'nutrition/suggestion-exclusions/'` |
|
||||
|
||||
## Recipe
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `recipe_check_inventory` | Check scaled ingredient availability and nutrition, with exact package deductions | `recipe_id`, `options` | POST `f'recipes/{recipe_id}/stock/preview/'` |
|
||||
| `recipe_composition_create` | Create a new draft recipe that explicitly includes selected owned component recipes | `composition`, `idempotency_key` | POST `'recipes/compositions/'` |
|
||||
| `recipe_composition_preview` | Preview an explicitly selected set of owned component recipes | `components` | POST `'recipes/compositions/preview/'` |
|
||||
| `recipe_cook_later_add` | Save one owned recipe to your Cook Later list | `recipe_id` | POST `'recipes/cook-later/'` |
|
||||
| `recipe_cook_later_list` | List your Cook Later recipes with stable recipe IDs, titles, summaries and save dates | `search`, `limit`, `offset` | GET `'recipes/cook-later/'` |
|
||||
| `recipe_cook_later_remove` | Remove one owned recipe from your Cook Later list | `recipe_id` | DELETE `f'recipes/cook-later/{recipe_id}/'` |
|
||||
| `recipe_create` | Create an owned recipe | `recipe`, `idempotency_key` | POST `'recipes/create/'` |
|
||||
| `recipe_create_variation` | Create an independently editable copy linked as a variation of the owned recipe | `recipe_id`, `title`, `idempotency_key` | POST `f'recipes/{recipe_id}/variations/'` |
|
||||
| `recipe_deduct_inventory` | Deduct the exact recipe packages approved in a recent recipe_check_inventory preview | `recipe_id`, `confirmation` | POST `f'recipes/{recipe_id}/stock/confirm/'` |
|
||||
| `recipe_delete` | Delete one owned recipe and its ingredients | `recipe_id` | DELETE `f'recipes/{recipe_id}/'` |
|
||||
| `recipe_get` | Read one owned recipe with Markdown instructions, ingredients, substitutions, related variations, and subrecipes | `recipe_id`, `include_dietary_context` | GET `f'recipes/{recipe_id}/'` |
|
||||
| `recipe_ingredient_add` | Add a measured ingredient to one owned recipe | `recipe_id`, `ingredient`, `idempotency_key` | POST `f'recipes/{recipe_id}/ingredients/'` |
|
||||
| `recipe_ingredient_delete` | Remove one ingredient from an owned recipe | `recipe_id`, `ingredient_id` | DELETE `f'recipes/{recipe_id}/ingredients/{ingredient_id}/'` |
|
||||
| `recipe_ingredient_update` | Correct only the supplied fields of an ingredient in an owned recipe. | `recipe_id`, `ingredient_id`, `changes` | PATCH `f'recipes/{recipe_id}/ingredients/{ingredient_id}/'` |
|
||||
| `recipe_link_create` | Create a one-way or reciprocal suggestion between two owned recipes | `recipe_id`, `link`, `idempotency_key` | POST `f'recipes/{recipe_id}/links/'` |
|
||||
| `recipe_link_list` | List up to 100 linked recipe suggestions for an owned recipe | `recipe_id` | GET `f'recipes/{recipe_id}/links/'` |
|
||||
| `recipe_link_remove` | Remove an owned suggestion link | `recipe_id`, `link_id` | DELETE `f'recipes/{recipe_id}/links/{link_id}/'` |
|
||||
| `recipe_link_update` | Edit the relationship, note, or reciprocal visibility of an owned recipe link. | `recipe_id`, `link_id`, `changes` | PATCH `f'recipes/{recipe_id}/links/{link_id}/'` |
|
||||
| `recipe_log_meal` | Log a personally consumed portion of an owned recipe using a historical nutrition snapshot | `recipe_id`, `consumed_servings`, `meal`, `servings`, `date`, `time`, `include_optional`, `substitutions`, `confirm_dietary`, `idempotency_key` | POST `f'recipes/{recipe_id}/log/'` |
|
||||
| `recipe_search` | Search your own recipes by title, description, or ingredient name | `query`, `category`, `limit`, `include_nutrition_context`, `include_dietary_context`, `body_support` | GET `'recipes/'` |
|
||||
| `recipe_subrecipe_add` | Attach another owned recipe as a reusable subrecipe | `recipe_id`, `component_id`, `quantity`, `unit`, `note`, `idempotency_key` | POST `f'recipes/{recipe_id}/subrecipes/'` |
|
||||
| `recipe_subrecipe_remove` | Remove one reusable subrecipe link from an owned recipe; the component recipe remains. | `recipe_id`, `subrecipe_id` | DELETE `f'recipes/{recipe_id}/subrecipes/{subrecipe_id}/'` |
|
||||
| `recipe_undo_inventory` | Undo a confirmed recipe inventory deduction when the affected packages have not changed since | `stock_use_id` | POST `f'recipes/stock-use/{stock_use_id}/undo/'` |
|
||||
| `recipe_update` | Update supplied fields of one owned recipe, including Markdown and serving yield | `recipe_id`, `changes` | PATCH `f'recipes/{recipe_id}/'` |
|
||||
|
||||
## Stress
|
||||
|
||||
| Tool | Purpose | Top-level parameters | API method/path |
|
||||
| --- | --- | --- | --- |
|
||||
| `stress_create` | Create a private 0–10 stress check-in | `entry`, `idempotency_key` | POST `'stress/'` |
|
||||
| `stress_delete` | Permanently delete one owned stress check-in | `entry_id` | DELETE `f'stress/{entry_id}/'` |
|
||||
| `stress_get` | Read one stress check-in owned by the authenticated user using its ID | `entry_id` | GET `f'stress/{entry_id}/'` |
|
||||
| `stress_search` | Search or list your private stress check-ins | `query`, `date`, `timing`, `limit`, `offset` | GET `'stress/'` |
|
||||
| `stress_update` | Update only supplied fields of one owned stress check-in | `entry_id`, `changes` | PATCH `f'stress/{entry_id}/'` |
|
||||
|
||||
Errors: `api_request()` converts Django JSON `error.code` and `error.message` into MCP `ToolError`; transport failures and unexpected redirects have separate messages. Actual output shapes vary by endpoint. Structured output is requested on every tool decorator; inspect `main/food/api_schema.py` and endpoint tests for contracts.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Development, deployment and testing
|
||||
|
||||
Install pinned Python requirements from `main/requirements.txt` into a virtual environment, configure a secret key in an ignored root `.env` or process environment, then run `main/manage.py migrate`. Frontend dependencies are in `main/frontend/package.json`; `npm run build` builds Vite assets. Use the existing `tasknest-web.service` for ordinary verification on this host. `npm run deploy:assets` builds, collects static files and restarts the web service, so run it only when deployment is authorized.
|
||||
|
||||
Web service: `main/deploy/systemd/tasknest-web.service`, Uvicorn ASGI on port 1234. MCP service: `main/deploy/systemd/tasknest-mcp.service`, separate Uvicorn process on port 8002. The repository also contains timers for demo reset, fasting notification and Home Assistant sync; inventory scans use a management command. Check service/timer status and logs on the target host before diagnosing scheduling.
|
||||
|
||||
Run Django tests with `tasksnest-host/bin/python main/manage.py test <app or test module>` from the repository root. Relevant suites include `main/mcp_server/test_tool_catalog.py`, `main/mcp_server/tests.py`, API and model tests in `food`, `recipes`, `groceries`, `planner`, `home_assistant`, `stress` and `dreams`. Frontend changes require Playwright MCP inspection per `AGENTS.md`. `python3 scripts/docs_audit.py` checks audit due date, local Markdown links and tracked source changes; it does not perform semantic review.
|
||||
|
||||
Pitfalls: the working tree may contain unapplied/uncommitted migrations; never reset the shared demo account to test; do not treat an MCP tool description as a permission check; do not restart or deploy services for documentation-only edits. See [audit guide](../audits/README.md).
|
||||
Reference in New Issue
Block a user