# 11 — MCP Integration Plan (AI & Terminal Logging Surface)

## Purpose

Health Debug will **fully support the Model Context Protocol (MCP)** so that users can log protocol events and query engine state from any MCP-capable AI assistant (Claude Code, Claude Desktop, other agents) or directly from the terminal — without opening an app. This was added to the spec by Fady on 2026-09-01 and makes MCP a **first-class client surface** alongside the web dashboard, native apps, Chrome extension, and Electron desktop client.

The MCP server obeys the same architectural rule as every other client: it is a **thin presentation/transport layer**. It holds **no protocol logic** and **no AI keys**; every tool call translates to a request against the ToGO backend REST API, which remains the Single Source of Truth for all temporal and state logic.

## Architecture

```
AI assistant / terminal (MCP client)
        │  stdio or streamable HTTP
        ▼
healthdebug-mcp (Go binary, part of the ToGO monorepo)
        │  HTTPS + personal access token
        ▼
ToGO Backend REST API  (protocol engines, SSOT)
```

- **Language / packaging:** Go, in the same monorepo as the ToGO backend so API client types are shared (mirrors the existing `brain-mcp.exe` pattern from the ToGO ecosystem — the old cabrain MCP binary is the in-house reference implementation for a Go MCP server).
- **Transports:** stdio (for local AI clients and terminal use) first; streamable HTTP as a later option for remote/hosted use.
- **Auth:** a Health Debug **personal access token** minted via TOGO auth, supplied through env (e.g. `HEALTHDEBUG_TOKEN`) in the MCP client config — never an AI provider key. Tokens are separately revocable, same as the mobile/watch clients' tokens.
- **Idempotency:** logging tools send an `Idempotency-Key` header so an AI retry cannot double-log water or medication. The server-side 30-second hydration cooldown still applies and is the final guard.

## Planned MCP tools (initial set)

| Tool | Action | Backend call (sketch) |
|---|---|---|
| `log_water` | Log +250ml (unit fixed by the Hydration Engine; server enforces 5000ml cap + 30s cooldown) | POST hydration entry |
| `log_caffeine` | Log a caffeine drink by kind (categorical — kind only, never mg) | POST caffeine entry |
| `log_meal` | Log a food item; server returns its Trigger Family classification (Gout / IBS-GERD / Fatty Liver / Safe) | POST nutrition entry |
| `log_medication` | Log a medication within the 60-minute Medication Grace window | POST medication entry |
| `check_trigger` | Ask whether a named food/ingredient is Safe or Trigger-bearing (categorical answer only) | GET trigger lookup |
| `today_status` | Full computed day: all engine states, GERD window countdown, caffeine block, hydration progress | GET today state |
| `pomodoro_status` | Current work/break state of the Kinetic Pomodoro Engine (read-only — breaks are validated by wearable motion, never by an MCP call) | GET pomodoro state |
| `list_notifications` | Unread notification items | GET notifications |

Deliberately **excluded** tools:
- No `complete_break` — a Pomodoro break registers only via wearable-detected movement; an AI must not be able to fake it.
- No cycle/fertility prediction tool beyond what the backend already exposes; the Cycle Engine's fail-safe rules apply unchanged.
- No AI-analysis passthrough that could produce diagnosis-like output. Any AI text generated *about* Health Debug data still goes through the server-side BYOK proxy with its "Consult your doctor" guardrails (Core Opinion 2).

## Core Opinions applied

1. **Categorical, not quantitative:** tool inputs are kinds/identities (`log_meal name`, `log_caffeine kind`), never quantities beyond the fixed 250ml hydration unit. `check_trigger` answers Safe / Trigger-bearing only.
2. **No medical certainty:** the MCP server returns engine state verbatim from the backend; it adds no interpretation. Descriptions in tool schemas explicitly instruct client AIs that outputs are behavioral-tracking data, not medical advice.

## Terminal use

The same binary doubles as a plain CLI (`healthdebug log water`, `healthdebug status`) so terminal users get 1-command logging without an MCP client — same API, same token. PENDING DESIGN: none of this surface depends on the visual design; it can be built any time after Phase 1's API exists.

## Phasing

- Ships as **Phase 1.5**: immediately after the Phase 1 backend exposes the hydration/today endpoints, since it is the thinnest possible client and doubles as an API smoke-test harness.
- Tool list grows with the engines: each new engine endpoint added in later phases gets a matching MCP tool in the same change.

## Open questions

- Distribution: single downloadable binary vs. published npm/go-install package for MCP client configs.
- Whether the hosted (streamable HTTP) transport should ship at all before B2B partners ask for it.
- Rate limits for AI-driven logging beyond the engines' own cooldowns.