nutrition-mcp/AGENTS.md

Agent Instructions

This project uses bd (beads) for issue tracking. Run bd prime for full workflow context.

Build & Test

cargo build --release          # Build binary
cargo test                     # Run unit tests
./target/release/nutrition-mcp # Run server (needs env vars)

Smoke Test

# Start server
NUTRITION_MCP_BIND=127.0.0.1:9432 NUTRITION_MCP_API_KEY=test \
  NUTRITION_MCP_DB_PATH=/tmp/test.db ./target/release/nutrition-mcp &

# Health check
curl http://127.0.0.1:9432/health

# MCP initialize
curl -X POST http://127.0.0.1:9432/mcp \
  -H "Authorization: Bearer test" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}},"id":1}'

Architecture Overview

MCP server exposing 13 tools for personal nutrition tracking. Streamable HTTP transport with Bearer token auth.

Module Map

src/
├── main.rs     — Entry point: axum server, auth middleware, /health endpoint
├── config.rs   — Config struct from env vars (bind, api_key, db_path, user_agent)
├── db.rs       — SQLite schema, migrations, DbPool type, TRACKED_NUTRIENTS const, DEFAULT_GOALS_JSON
├── api.rs      — OffClient: Search-a-licious + v3 barcode + SQLite cache (FTS5)
└── tools.rs    — NutritionServer: 13 MCP tools via #[tool_router] + ServerHandler impl

SQLite Schema

• products — OFF cache: code (PK), product_name, brands, nutriments (JSON), serving_quantity, serving_size, image_url
• products_fts — FTS5 virtual table on product_name (synced via triggers)
• entries — Food log: id, date, meal, product_code, food_name, grams, servings, nutriments (JSON, scaled to portion)
• daily_goal — Single row (id=1), goals JSON with 14 nutrient targets
• weight_log — id, date, weight_kg

Nutrient Storage

All nutrients stored as JSON blob in nutriments TEXT column (verbatim from OFF API). Daily summaries use json_extract() or Rust-side parsing to aggregate the 14 tracked nutrients.

Portion Scaling

Nutrients are stored per-100g in OFF data. When logging, scale_nutriments() multiplies each value by grams / 100.0. For servings, grams = servings * serving_quantity.

Meal Auto-Detection

• breakfast: before 11:00
• lunch: 11:00–15:00
• dinner: 15:00–21:00
• snack: after 21:00

Conventions & Patterns

• JSON nutriments — Never hardcode nutrient columns. Store OFF nutriments verbatim as JSON, query at runtime.
• "no data" vs 0 — Micronutrients (potassium, calcium, magnesium) are sparse in OFF. Summary shows "no data" when no entries have the nutrient, not 0.
• Env vars only — No config files. All settings via environment variables.
• API-first — Always check SQLite cache first, fall back to OFF API, cache results.
• User-Agent — Always send custom User-Agent to OFF API (good citizenship).

Tracked Nutrients (14)

energy_kcal    → energy-kcal_100g
protein        → proteins_100g
carbohydrates  → carbohydrates_100g
fat            → fat_100g
fiber          → fiber_100g
sugars         → sugars_100g
saturated_fat  → saturated-fat_100g
salt           → salt_100g
fructose       → fructose_100g      (gout)
alcohol        → alcohol_100g        (gout)
potassium      → potassium_100g      (hypertension)
calcium        → calcium_100g        (hypertension)
magnesium      → magnesium_100g      (hypertension)
cholesterol    → cholesterol_100g    (hypertension)

Non-Interactive Shell Commands

ALWAYS use non-interactive flags to avoid hanging on confirmation prompts.

cp -f source dest           # NOT: cp source dest
rm -f file                  # NOT: rm file

Session Completion

1. File issues for remaining work - bd create for follow-up items
2. Run quality gates - cargo build --release && cargo test
3. Close completed issues - bd close <id1> <id2> ...
4. PUSH - git add -A && git commit -m "..." && git push
5. Verify - git status must show clean working tree

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

• Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
• Run bd prime for detailed command reference and session close protocol
• Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

• Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
• Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
• Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

1. File issues for remaining work - Create beads for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. Handle git/sync by active profile:

   # Conservative/minimal/default: report status and proposed commands; wait for approval.
   git status
   
   # Team-maintainer opt-in only, unless current instructions forbid it:
   git pull --rebase
   bd dolt push
   git push
   git status
   

5. Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

• Explicit user or orchestrator instructions override this Beads block.
• Do not commit or push without clear authority from the active profile or the current user request.
• If a required sync or push is blocked, stop and report the exact command and error.

Beads Issue Tracker

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

• Use bd for all task tracking; do not create markdown TODO lists.
• Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
• Keep persistent project memory in Beads via bd remember; do not create ad hoc memory files.

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

---

Beads Workflow Integration

This project uses beads_rust (br) for issue tracking and beads_viewer (bv) for graph-aware triage. Issues are stored in .beads/ and tracked in git. Current br workspaces normally export .beads/issues.jsonl; older bd/legacy workspaces may use .beads/beads.jsonl. bv auto-discovers the supported JSONL files, so agents should use br/bv commands instead of hard-coding a single filename.

Using bv as an AI sidecar

bv is a graph-aware triage engine for Beads projects. Instead of parsing .beads/issues.jsonl / .beads/beads.jsonl directly or hallucinating graph traversal, use robot flags for deterministic, dependency-aware outputs with precomputed metrics (PageRank, betweenness, critical path, cycles, HITS, eigenvector, k-core).

Scope boundary: bv handles what to work on (triage, priority, planning). br handles creating, modifying, and closing beads.

CRITICAL: Use ONLY --robot- flags. Bare bv launches an interactive TUI that blocks your session.*

The Workflow: Start With Triage

bv --robot-triage is your single entry point. It returns everything you need in one call:

• quick_ref: at-a-glance counts + top 3 picks
• recommendations: ranked actionable items with scores, reasons, unblock info
• quick_wins: low-effort high-impact items
• blockers_to_clear: items that unblock the most downstream work
• project_health: status/type/priority distributions, graph metrics
• commands: copy-paste shell commands for next steps

bv --robot-triage        # THE MEGA-COMMAND: start here
bv --robot-next          # Minimal: just the single top pick + claim command

# Token-optimized output (TOON) for lower LLM context usage:
bv --robot-triage --format toon

Before claiming, verify current state with br show <id> --json or br ready --json. recommendations can include graph-important blocked or assigned work; only quick_ref.top_picks and non-empty claim_command fields represent claimable work.

Other bv Commands

Command	Returns
--robot-plan	Parallel execution tracks with unblocks lists
--robot-priority	Priority misalignment detection with confidence
--robot-insights	Full metrics: PageRank, betweenness, HITS, eigenvector, critical path, cycles, k-core
--robot-alerts	Stale issues, blocking cascades, priority mismatches
--robot-suggest	Hygiene: duplicates, missing deps, label suggestions, cycle breaks
--robot-diff --diff-since <ref>	Changes since ref: new/closed/modified issues
--robot-graph [--graph-format=json|dot|mermaid]	Dependency graph export

Scoping & Filtering

bv --robot-plan --label backend              # Scope to label's subgraph
bv --robot-insights --as-of HEAD~30          # Historical point-in-time
bv --recipe actionable --robot-plan          # Pre-filter: ready to work (no blockers)
bv --recipe high-impact --robot-triage       # Pre-filter: top PageRank scores

br Commands for Issue Management

br ready --json                       # Show issues ready to work (no blockers)
br list --status=open --json          # All open issues
br show <id> --json                   # Full issue details with dependencies
br create --title="..." --type=task --priority=2 --json
br update <id> --status=in_progress --json
br close <id> --reason="Completed" --json
br close <id1> <id2> --reason="Completed" --json
br sync --flush-only                  # Export DB to JSONL after Beads mutations

Workflow Pattern

1. Triage: Run bv --robot-triage to find the highest-impact actionable work
2. Claim: Use br update <id> --status=in_progress --json
3. Work: Implement the task
4. Complete: Use br close <id> --reason="Completed" --json
5. Sync: Run br sync --flush-only after Beads mutations so the JSONL export is current

Key Concepts

• Dependencies: Issues can block other issues. br ready --json shows only unblocked work.
• Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
• Types: task, bug, feature, epic, chore, docs, question
• Blocking: br dep add <issue> <depends-on> to add dependencies

Git Policy

br never commits or pushes. Follow this repository's own git instructions before staging, committing, or pushing. If the repository says "commit only when asked," that rule overrides any generic workflow advice.