Expose the catalog to AI clients over MCP at /mcp

Adds a FastMCP server mounted onto the existing FastAPI app, so it ships in the
same container and answers on the same host rather than needing a process of
its own.

Fifteen tools, all read-only: catalog search and browse, nutrition facts and
health scores, healthier alternatives, per-store inventory and pricing,
discounts, trending and sales analytics. Each wraps a service function the REST
API already reaches through a GET. None of the write or compute endpoints are
exposed, because a tool list is chosen from by a model rather than by a person,
and catalog generation or model retraining is not something to leave one tool
call away.

The tools are written by hand rather than generated from the OpenAPI schema.
Mirroring all 63 routes would work, but a model picks a tool by reading its
description, and 63 near-identical generated entries is a worse thing to choose
from than a dozen written to be told apart.

Authentication reuses the access token from POST /api/auth/login - no separate
MCP credential, the same Principal and expiry as the REST API. The check lives
in one middleware rather than at the top of each tool, so a tool added later
cannot be left unguarded by forgetting a line. Note that this requires passing
include={"authorization"} to get_http_headers(), which strips that header by
default to avoid forwarding it downstream; without it the header is invisible
and every request looks unauthenticated, valid ones included.

Mounting a sub-app does not run its lifespan - only the outermost app's is
executed - so the MCP app's lifespan is chained through the FastAPI one. Without
that the endpoint accepts a connection and then fails on the first message with
a session manager that was never started.

Adds GET /api/mcp/info and POST /api/mcp/tools/{name} for the admin UI. The MCP
endpoint speaks streamable HTTP with session handling, so rendering a tool list
in the browser would otherwise mean shipping a full MCP client in React.

fastmcp needs Python 3.10+. The image is 3.11; on anything older the import
fails and the REST API starts without the MCP endpoint instead of not starting.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

app/main.py

@@ -24,7 +24,7 @@ from app.infrastructure.settings import API_CORS_ORIGINS
 from app.api.routers import health, brands, search, chat, catalog, system
 from app.api.routers import stores, discounts, analytics as store_analytics, trending, recommendations, store_admin
 from app.api.routers import nutrition, nutrition_admin, upload
-from app.api.routers import auth, user_products, admin_train
+from app.api.routers import auth, user_products, admin_train, mcp_info
 from app.services.store_db import ensure_store_intelligence_schema
 from app.services.nutrition_db import ensure_nutrition_schema
 
@@ -34,6 +34,18 @@ logging.basicConfig(
 )
 logger = logging.getLogger(__name__)
 
+try:
+    from app.mcp_server import MCP_PATH, build_http_app as build_mcp_app
+
+    _mcp_app = build_mcp_app()
+except Exception as e:  # pragma: no cover - depends on an optional dependency
+    # fastmcp needs Python >=3.10. The image is 3.11, but an older local
+    # interpreter should lose the MCP endpoint, not the whole API.
+    logging.getLogger(__name__).warning("MCP server unavailable: %s", e)
+    _mcp_app = None
+    MCP_PATH = "/mcp"
+
+
 @asynccontextmanager
 async def lifespan(_app: FastAPI):
     """
@@ -64,7 +76,17 @@ async def lifespan(_app: FastAPI):
             logger.warning("Startup background init warning: %s", e)
 
     threading.Thread(target=_async_init, daemon=True).start()
-    yield
+
+    # The mounted MCP app carries its own lifespan, which starts the session
+    # manager its request handler depends on. Mounting a sub-app does NOT run
+    # that lifespan - only the outermost app's is executed - so without this
+    # the endpoint exists, accepts a connection, and then fails on the first
+    # message with a session manager that was never started.
+    if _mcp_app is not None:
+        async with _mcp_app.lifespan(_mcp_app):
+            yield
+    else:
+        yield
 
 
 app = FastAPI(
@@ -140,6 +162,15 @@ app.include_router(store_admin.router, prefix="/api")
 app.include_router(nutrition.router, prefix="/api")
 app.include_router(nutrition_admin.router, prefix="/api")
 app.include_router(upload.router, prefix="/api")
+app.include_router(mcp_info.router, prefix="/api")
+
+# MCP lives outside /api on purpose: it is a protocol endpoint for AI clients,
+# not part of the REST surface, and the catch-all SPA route below only skips
+# paths it recognises. Mounted rather than routed because it is a whole ASGI
+# app with its own request handling.
+if _mcp_app is not None:
+    app.mount(MCP_PATH, _mcp_app)
+    logger.info("MCP server mounted at %s", MCP_PATH)
 
 # Serve built frontend static files if dist exists (single-port unified
 # deployment). Off in the normal setup: the React app is served by its own
@@ -179,7 +210,10 @@ if FRONTEND_DIST.exists() and (FRONTEND_DIST / "assets").exists():
         # endpoint would look like a successful call to any client. 404 is the
         # honest answer, and it matters now that the API is also reachable
         # directly at api.{$DOMAIN} rather than only behind the frontend.
-        if full_path.startswith(("api", "docs", "redoc", "openapi.json")):
+        # "mcp" is in this list for the case where the MCP app failed to load:
+        # the mount would be absent, and without this the SPA fallback would
+        # answer an MCP client with index.html and a 200.
+        if full_path.startswith(("api", "docs", "redoc", "openapi.json", "mcp")):
             raise HTTPException(status_code=404, detail="Not found")
         file_path = FRONTEND_DIST / full_path
         if file_path.exists() and file_path.is_file():