planning/agent_to_mcp.md

### Objective
Use the existing MCP server as the single source of truth for tools/resources/prompts, and have the LangGraph agent call MCP rather than local Python tool implementations.

### Rationale
- Single source of truth for schemas/behavior (no drift).
- Multi-client support out of the box (Claude Desktop via supergateway, others).
- Clean security boundary via the auth proxy (no local secrets in clients).

### Architecture
- MCP server: `python -m foodwise.mcp_server` (HTTP transport, token-gated via `auth_proxy` at `/mcp/`).
- Agent: uses Adapter Tools that delegate to MCP over HTTP instead of importing `foodwise.agent.tools`.
- Feature flag: `USE_MCP_TOOLS=1` toggles MCP-backed adapters vs. current local tools during migration.

### Transport & Auth
- Prefer Authorization header: `Authorization: Bearer $MCP_AUTH_TOKEN`.
- Desktop bridge compatibility: `?key=$MCP_AUTH_TOKEN` supported (bridge only).
- Health check: `GET /health` (no auth) before first tool call.
- Agent should never embed tokens in URLs; use header-based auth.

### Implementation Plan
1) Verify server parity
   - `fastmcp_tools.py` exposes inventory + shopping tools with typed params and clear descriptions.
   - `fastmcp_resources.py` and `fastmcp_prompts.py` registered in `mcp_server/main.py` (already done).

2) Add MCP client wrapper (Python)
   - File: `src/foodwise/mcp_client/client.py`
   - Responsibilities:
     - Manage base URL, auth header/query param
     - Discover tool schemas and call tools over HTTP transport
     - Provide minimal typed helpers using Pydantic models (derive from `database/db_models.py` or shared models via `model_dump`) [[Prefer Pydantic model_dump]].

3) Agent tool adapters
   - File: `src/foodwise/agent/mcp_tools.py`
   - Define LangChain/LangGraph `Tool` objects that call the MCP client
   - Maintain current tool names/semantics for drop-in replacement
   - Switch `agent/agent.py` to use `get_mcp_tools()` when `USE_MCP_TOOLS=1`

4) Prompts and resources usage
   - Keep agent system prompt in `agent/prompts.py` unchanged
   - MCP prompts remain for MCP clients; agent doesn’t need them directly
   - Optionally fetch MCP resources at the start of an interaction to seed context (later optimization)

5) Config/env (do not edit pyproject directly)
   - `.env`/`env.example` additions:
     - Production endpoint (HF Spaces): `MCP_ENDPOINT=https://<your-space>.hf.space/mcp/`
     - Local dev alternative: `MCP_ENDPOINT=http://127.0.0.1:7860/mcp/`
     - Auth: `MCP_AUTH_TOKEN=...` (or `MCP_AUTH_TOKENS`)
     - Toggle: `USE_MCP_TOOLS=1`
   - Do NOT include tokens in the URL; clients should send `Authorization: Bearer` headers.

6) Tests
   - Unit tests for MCP client: auth header, timeouts, error propagation, happy-path tool call
   - Agent smoke: run `scripts/agent_smoke.py` with `USE_MCP_TOOLS=1` and proxy running; verify same outputs for read paths

### Rollout
- Phase 1: Behind flag in dev; local tools remain fallback
- Phase 2: Make MCP the default; keep fallback briefly
- Phase 3: Remove local tool implementations once parity confirmed

### Risks & Mitigations
- Schema drift → Source request/response from shared Pydantic models via `model_dump()`
- Network/auth errors → Early `/health` check, clear error messages, retries where sensible

### Done Criteria
- With `USE_MCP_TOOLS=1`, agent uses MCP-backed tools for inventory/shopping and passes existing smoke checks