Hugging Face's logo

Spaces:
LeoWalker
/
foodwise-remote-mcp
Running

App Files Community
foodwise-remote-mcp / planning /agent_to_mcp.md
LeoWalker's picture
LeoWalker
chore(project): clean up project files and organize planning docs
8d62a8a
preview code
|
raw
history blame contribute delete
3.43 kB

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