partd-mcp-cloudflare: Instructions file for Claude Code

CLAUDE.md

Project Overview

Medicare Part D MCP Server — a Model Context Protocol (MCP) server for CMS Medicare Part D drug spending and prescriber data, deployed on Cloudflare Workers. Queries public CMS data (no API key required).

Live endpoint: https://mcp-partd.medseal.app/mcp

Tech Stack

• Runtime: Cloudflare Workers (serverless edge)
• Language: TypeScript 5.7 (target ES2022, strict mode)
• MCP SDK: @modelcontextprotocol/sdk v1.0.0 with agents library for Cloudflare Workers integration
• Validation: Zod v3.22
• Build/Deploy: Wrangler CLI (esbuild under the hood, no explicit build step)

Commands

npm run dev       # Local dev server (wrangler dev)
npm run deploy    # Deploy to Cloudflare Workers (wrangler deploy)
npm install       # Install dependencies

There is no test framework configured. No linter or formatter is configured.

Project Structure

src/
  index.ts      # Worker entry point, MCP server setup, route handling
  types.ts      # Type definitions, Zod schema, CMS dataset UUIDs
  handlers.ts   # Action dispatcher + 15 action handlers + formatting utils
  client.ts     # CMSClient class wrapping CMS Data API calls

Four files total. No subdirectories, no test files.

Architecture

Single-Tool, Action-Dispatch Pattern

The server exposes one MCP tool named partd with an action parameter that dispatches to 15 handlers. This is intentional for token efficiency — LLMs only need to learn one tool schema.

Actions: drug, spending, prescribers, top, search, compare, geography, manufacturer, stats, outliers, generics, specialty, summary, api, help

Request Flow

1. index.ts — Cloudflare Worker fetch handler routes /mcp to the MCP handler, /health and / to health check
2. index.ts — createServer() registers the partd tool with Zod schema validation
3. handlers.ts — handleAction() switch-dispatches to the appropriate handler
4. client.ts — CMSClient methods call https://data.cms.gov/data-api/v1/dataset/{uuid}/data