fatsecret-mcp-server: 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

FatSecret MCP Server - A Model Context Protocol server for the FatSecret nutrition API, deployed on Cloudflare Workers. Implements OAuth 1.0a authentication with HMAC-SHA1 signing.

Build & Development Commands

npm install           # Install dependencies
npm run dev           # Run local dev server (wrangler dev on port 8787)
npm run deploy        # Deploy to Cloudflare Workers
npm run type-check    # TypeScript type checking
npm run test          # Run tests
npm run test:run      # Run tests once
npm run format        # Format code with Biome
npm run lint:fix      # Lint and auto-fix with Biome

Architecture

src/
├── index.ts              # Entry point - exports Hono app & Durable Object
├── app.ts                # Hono app with CORS, routes, error handling
├── mcp-agent.ts          # FatSecretMCP class with all MCP tools
├── mcp-handlers.ts       # MCP handler exports (streamableHTTP, SSE)
├── middleware/
│   └── auth.ts           # Bearer token authentication
├── lib/
│   ├── oauth.ts          # OAuth 1.0a signing (HMAC-SHA1)
│   ├── client.ts         # FatSecretClient API wrapper
│   ├── schemas.ts        # Zod schemas for validation
│   ├── transforms.ts     # Date conversion, data cleaning
│   ├── errors.ts         # Error handling utilities
│   └── token-storage.ts  # AES-GCM encrypted KV storage
└── routes/
    ├── mcp.ts            # MCP protocol endpoints
    ├── oauth.ts          # FatSecret OAuth flow
    └── utility.ts        # Health, home page

Key Technologies: Cloudflare Workers, Hono, MCP SDK, Zod, Durable Objects, KV

OAuth 1.0a Flow

1. POST /oauth/setup with clientId, clientSecret → returns state + authorizationUrl
2. User visits authorization URL, gets verifier code
3. POST /oauth/complete with state, verifier → returns sessionToken
4. Use sessionToken as Bearer token for MCP requests