nutrition-mcp/AGENTS.md

# Agent Instructions

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

## Build & Test

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

### Smoke Test

```bash
# 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.

```bash
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

<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:970c3bf2 -->
## Beads Issue Tracker

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

### Quick Reference

```bash
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**:
   ```bash
   # 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.
<!-- END BEADS INTEGRATION -->

<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
## 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

```bash
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.
<!-- END BEADS CODEX SETUP -->