Calorie Tracker MCP

A local, JSON-first calorie and protein tracker for agents and shell workflows. It ships a calorie-tracker CLI and a protocol-safe calorie-tracker-mcp stdio server. Every profile is stored in its own SQLite database; no service, database server, open port, or account is needed.

Prerequisites

• Fedora Linux (the release smoke target is Fedora 44).
• Python 3.12 or newer with venv and pip available.
• A project-built calorie_tracker_mcp-*.whl file.

The runtime uses the official MCP Python SDK and Pydantic. Installation may need access to the configured Python package index to resolve those declared wheel dependencies. The application itself performs no nutrition lookups, telemetry, or other network calls.

Install

Build a wheel from a trusted checkout, then give that exact artifact to the installer:

python3 -m build
./scripts/install-fedora.sh "$PWD/dist/calorie_tracker_mcp-0.2.0-py3-none-any.whl"

The script requires no elevated privileges and does not edit shell configuration. It creates an isolated venv at ${XDG_DATA_HOME:-$HOME/.local/share}/calorie-tracker/venv and prints the absolute paths of both executables. For convenience in the examples below:

CLI="$HOME/.local/share/calorie-tracker/venv/bin/calorie-tracker"

Separate agent profiles

Each agent profile must receive a unique CALORIE_TRACKER_DB absolute path. Do not point two identities at the same profile database merely because the executable is shared:

export CALORIE_TRACKER_DB="$HOME/.local/share/calorie-tracker/profiles/alex/calories.db"
export CALORIE_TRACKER_TIMEZONE=America/New_York
"$CLI" doctor

The environment timezone initializes a new profile. After initialization, the timezone stored in that database is authoritative. Inspect or deliberately change it with profile show and profile set-timezone.

V2 nutrients and database compatibility

V2 profile databases are intentionally incompatible with V1. Back up and retain the V1 database, then configure CALORIE_TRACKER_DB to a new path before starting V2. V2 never migrates, resets, or overwrites a V1 database.

Meals support optional carbohydrate, fat, fiber, sugar, and sodium estimates. All five estimates are optional, and missing summary values count as zero. Gram values use one decimal place for carbohydrate, fat, fiber, and sugar. Sodium uses whole milligrams. Meal items remain calorie/protein-only—the expanded nutrient estimates apply to authoritative meal totals.

MCP configuration

Copy and adapt docs/examples/mcp-config.json. Its command and database values are absolute paths. Keep the same installed calorie-tracker-mcp command for multiple profiles, but assign every server a distinct database:

{
  "command": "/home/alex/.local/share/calorie-tracker/venv/bin/calorie-tracker-mcp",
  "env": {
    "CALORIE_TRACKER_DB": "/home/alex/.local/share/calorie-tracker/profiles/alex/calories.db",
    "CALORIE_TRACKER_TIMEZONE": "America/New_York"
  }
}

The MCP server uses stdio only. Its standard output is reserved for JSON-RPC protocol frames; sanitized diagnostics use standard error.

CLI examples

Commands emit one stable JSON envelope by default. Add --pretty for indented JSON; selected read commands also accept --output table.

"$CLI" doctor --pretty
"$CLI" meal add --input-json '{
  "idempotency_key":"agent-run-20260717-lunch-1",
  "local_date":"2026-07-17",
  "meal_type":"lunch",
  "estimated_total_calories":500,
  "estimated_total_protein_g":35,
  "estimated_total_carbohydrate_g":42.3,
  "estimated_total_fat_g":14.7,
  "estimated_total_fiber_g":5.1,
  "estimated_total_sugar_g":3.8,
  "estimated_total_sodium_mg":620,
  "confidence":"medium",
  "raw_text":"Chicken and rice"
}'
"$CLI" meal list --from 2026-07-01 --to 2026-07-31 --output table
"$CLI" meal get MEAL_ID

Complex JSON may instead come from a file with --input meal.json or standard input with --input -. The external agent supplies all calorie and protein estimates; meal totals remain authoritative even when item estimates are included.

Each item requires a nonblank free-form quantity such as 1 bowl, 2 large, or about 200 g. Missing or blank quantities are rejected as validation_error before storage.

Past dates

Meals may be recorded for current or past dates. Supply local_date; local_time is optional so historical entries do not invent precision. Dates are bucketed in the profile timezone. Impossible DST local times are rejected, while ambiguous times are retained with a warning. Future meal dates are rejected using the current date in that profile's timezone. Retrying an already-created idempotent request still returns its original meal after timezone changes.

Idempotency

Every meal creation requires a caller-generated idempotency_key. Retrying the same key with the same canonical payload returns the existing meal. Reusing it for different data returns an idempotency_conflict. Use a stable operation identifier, not a reusable label such as lunch.

Revisions

Updates, soft deletion, and restoration use optimistic revisions. Read the current revision, then provide it explicitly:

"$CLI" meal update MEAL_ID --expected-revision 1 --input-json '{"notes":"Updated"}'
"$CLI" meal delete MEAL_ID --expected-revision 2
"$CLI" meal restore MEAL_ID --expected-revision 3
"$CLI" meal history MEAL_ID --include-snapshots

A stale value returns revision_conflict. Deletes are recoverable and each mutation stores an immutable history snapshot. Successful updates return the updated meal, an item-total audit, and warnings for ambiguous DST times or material differences between authoritative meal totals and item subtotals.

Goals

Goals are effective-dated, so changing a target does not rewrite historical meaning:

"$CLI" goals set --effective-from-date 2026-07-01 \
  --daily-calorie-target 2200 --daily-protein-g-target 150
"$CLI" goals get --date 2026-07-17
"$CLI" goals history --output table

Summaries

Request one day or an inclusive range. Summaries exclude deleted meals and report totals, averages, goal progress, remaining values, meal-type breakdowns, confidence counts, and per-day details.

"$CLI" summary --date 2026-07-17 --output table
"$CLI" summary --from 2026-07-01 --to 2026-07-31

Export and backup

Exports are bounded meal-data extracts; backups are complete SQLite copies. Existing output files are refused unless --overwrite is explicit.

"$CLI" export --format json --from 2026-07-01 --to 2026-07-31 \
  --output-path "$HOME/private/calories-july.json"
"$CLI" export --format csv --output-path "$HOME/private/calories.csv"
"$CLI" db backup "$HOME/private/calories-backup.db"
"$CLI" db info --output table

Protect exports and backups like the source database. Verify a backup before relying on it.

Upgrade from V1 to V2

V2 uses a new, incompatible database. Do not install V2 until the V1 database is backed up and the exact V1 wheel is retained for rollback. The upgrade replaces both executables in the shared managed venv, but it never changes the V1 database.

1. Back up V1 and retain rollback assets

Set absolute paths for the current profile, its backup, both wheels, and the managed CLI. Place the exact trusted 0.1.0 wheel used by the current installation at V1_WHEEL before continuing:

CLI="$HOME/.local/share/calorie-tracker/venv/bin/calorie-tracker"
V1_DB="$HOME/.local/share/calorie-tracker/profiles/alex/calories.db"
V1_BACKUP="$HOME/private/calories-v1-backup.db"
V1_WHEEL="$HOME/private/calorie_tracker_mcp-0.1.0-py3-none-any.whl"
V2_WHEEL="$PWD/dist/calorie_tracker_mcp-0.2.0-py3-none-any.whl"

test -f "$V1_WHEEL"
CALORIE_TRACKER_DB="$V1_DB" "$CLI" doctor --pretty
CALORIE_TRACKER_DB="$V1_DB" "$CLI" db backup "$V1_BACKUP"

Keep both V1_DB and V1_BACKUP. Do not rename, replace, or delete the V1 database.

2. Build and install V2

From a trusted V2 checkout, build the wheel and pass that exact artifact to the installer:

python3 -m build
test -f "$V2_WHEEL"
./scripts/install-fedora.sh "$V2_WHEEL"

The installer upgrades the existing managed venv in place. Its calorie-tracker CLI and calorie-tracker-mcp server now both run version 0.2.0; their absolute paths stay the same.

3. Initialize the new V2 database for the CLI

Choose a new absolute path. Never set V2_DB to V1_DB:

V2_DB="$HOME/.local/share/calorie-tracker/profiles/alex-v2/calories.db"
export CALORIE_TRACKER_DB="$V2_DB"
export CALORIE_TRACKER_TIMEZONE=America/New_York

"$CLI" doctor --pretty
"$CLI" profile show --pretty
"$CLI" meal list --pretty

doctor creates the V2 database and reports schema version 2. A new V2 profile starts with no meals or goals.

4. Update the MCP configuration

Point the MCP server at the same new V2 database. For example:

{
  "command": "/home/alex/.local/share/calorie-tracker/venv/bin/calorie-tracker-mcp",
  "env": {
    "CALORIE_TRACKER_DB": "/home/alex/.local/share/calorie-tracker/profiles/alex-v2/calories.db",
    "CALORIE_TRACKER_TIMEZONE": "America/New_York"
  }
}

Save the configuration, restart the MCP client, and verify that its calorie-tracker server starts cleanly and exposes the expected tools, including log_meal, list_meals, and get_summary.

5. Understand the data boundary

V2 does not import or migrate V1 meal data. The new V2 database starts empty, while the original V1 database remains unchanged at V1_DB. Keep the two database paths separate; do not share a database between V1 and V2 processes.

6. Roll back to V1

Stop the MCP client before rollback. Reinstall the retained V1 wheel, restore the original CLI database environment, and change the MCP configuration back to the original V1 database path:

./scripts/install-fedora.sh "$V1_WHEEL"
export CALORIE_TRACKER_DB="$V1_DB"
CALORIE_TRACKER_DB="$V1_DB" "$CLI" doctor --pretty

Then restore the MCP configuration's CALORIE_TRACKER_DB value to the absolute V1 path and restart the MCP client. Never open the V1 database with the V2 executable. Data written to the separate V2 database is not merged back into V1.

Removal

The safe default removes only the managed venv and preserves all profile databases:

./scripts/uninstall-fedora.sh

Permanent removal is a separate, explicit operation. The script prints the exact data directory before deleting it:

./scripts/uninstall-fedora.sh --delete-data

Back up first. --delete-data removes the configured ${XDG_DATA_HOME:-$HOME/.local/share}/calorie-tracker path and securely erases every profile through its pinned directory descriptor. To guarantee that a concurrent path replacement can never cause an unrelated directory to be removed, the operation intentionally retains one empty, private 0700 directory named .calorie-tracker-deleted-* under the same XDG data root. Future installs and removals ignore these data-free tombstones.

Privacy

Data remains local unless you deliberately export, back it up, or expose it through another tool. The profile directory is created with mode 0700; database, backup, and export files are protected with mode 0600. SQL is parameterized, operational logs omit meal contents, and MCP cannot change its configured database path. There is no telemetry or application-initiated network access.

Troubleshooting

• Python 3.12 or newer is required: install a supported Fedora Python and retry.
• Wheel not found: pass the path to an existing .whl, not a package name or source tree.
• Dependency installation fails: verify pip's configured index/network and retry the same wheel.
• configuration_error: check CALORIE_TRACKER_DB, the IANA timezone, and absolute paths.
• storage_error or a failed doctor check: verify directory ownership, free disk space, database writability, integrity output, and that no unsupported older process is holding the profile.
• Wrong meals appear: two agents likely share CALORIE_TRACKER_DB; give each a unique database.
• Revision conflict: fetch the current meal, review the new revision, and retry intentionally.
• Database busy: allow the bounded lock wait to complete and ensure long-lived clients close.

Run calorie-tracker --help or command-level --help for the complete JSON command contract.