nutrition-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

nutrition-mcp is a Model Context Protocol (MCP) server for nutrition-related functionality, built with Bun and TypeScript. Entry point is src/index.ts. It runs on MCP TypeScript SDK v2 (@modelcontextprotocol/server at runtime, @modelcontextprotocol/client only in tests) with Zod 4 as an explicit dependency; @modelcontextprotocol/sdk v1 is gone, so import McpServer, InMemoryTransport, createMcpHandler from @modelcontextprotocol/server. Every inputSchema / outputSchema here is a schema object (z.object({…})), never a raw shape: v2 still auto-wraps raw Zod 4 shapes via a deprecated overload, but the explicit form is the supported path, and it lets the exported *_OUTPUT_SCHEMA constants be .parse()d directly in tests. /mcp is a dual-era endpoint built on createMcpHandler (src/mcp.ts): it serves the 2026-07-28 revision (per-request _meta envelope, server/discover, no protocol-level sessions, Mcp-Method / Mcp-Name routing headers validated against the body) and, through the default legacy: "stateless" fallback, still answers 2025-11-25 clients with the same per-request initialize idiom the old hand-rolled transport used — one server factory backs both eras. The factory gets no Hono context: the authenticated user travels in the authInfo.extra.userId pass-through from handleMcp, and the public origin (for the icon URL) is read from ctx.requestInfo. The "/mcp over HTTP" section of src/mcp.test.ts drives both eras in-process by pointing a v2 Client's fetch at the Hono route — there is no in-memory transport for the modern era, so that is the only way to test it. It lives inside mcp.test.ts deliberately: mock.module is process-wide, and a separate file with its own mock/restore of ./supabase.js broke middleware.test.ts's mock on Linux CI (not reproducible on macOS). Two rules follow: stub ./supabase.js from an existing mock window rather than opening another, and restore from a snapshot taken before mock.module — Bun patches the namespace in place, so restoring from the live import is a no-op. listChanged is advertised false on purpose: the endpoint is stateless and refuses GET, so no channel exists to deliver a list-changed notification. Two v2 wire facts worth knowing: advertised schemas are JSON Schema 2020-12 (v1 stamped draft-07), and a POST whose Content-Type is not application/json is answered 415 before the body is read. Server version must be updated in three places: package.json, src/mcp.ts (McpServer constructor), and server.json. The server icon is at public/favicon.ico. Tool call analytics (duration, success/failure, error category) are tracked via src/analytics.ts and persisted to a tool_analytics Supabase table. Each row also carries protocol_era and client_name, because the runtime access log is a ring buffer holding well under an hour of traffic and cannot answer whether anyone still uses the 2025-era leg; retiring it is gated on select count(distinct user_id) from tool_analytics where protocol_era = 'legacy' and invoked_at > now() - interval '30 days' reaching zero — distinct users, over a window long enough to include people who log weekly. client_name is present on every modern call but only on a legacy initialize, since the stateless legacy leg builds a fresh server per request and only that one carries clientInfo. Runtime log lines (console.*) never carry a user id, email or per-user path; that is a privacy-policy promise, pinned by src/log-privacy.test.ts, and analyticsLogLine is the only analytics log formatter. Per-user questions go to tool_analytics.