chartpane CLAUDE.md

CLAUDE.md

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

Commands

npm run build          # Type-check (tsc --noEmit) + bundle UI into dist/mcp-app.html
npm start              # wrangler dev + vite build --watch (port 8787)
npm run dev            # wrangler dev + sandbox dev server (localhost:3456)
npm run deploy         # Deploy to Cloudflare Workers
npm test               # Run all tests (vitest)
npm run test:watch     # Run tests in watch mode

# Run a single test file
npx vitest run tests/unit/config.test.ts

# Run tests matching a name pattern
npx vitest run -t "scatter"

Architecture

MCP App that renders Chart.js charts inline in Claude's UI. Two tools: render_chart (single chart) and render_dashboard (multi-chart grid).

Data Flow

Claude tool call → server.ts (validate, pass through ChartInput as structuredContent)
    → mcp-app.ts (ontoolresult) → buildChartConfig() → Chart.js renders to canvas

The server is intentionally thin — it validates input and returns the raw ChartInput as structuredContent. All Chart.js config transformation happens browser-side in shared/config.ts.

Module Layout

• server.ts — MCP server factory: createServer(options: ServerOptions) with htmlLoader and onLog params. Platform-agnostic (no fs/path/url). Tool registration via registerAppTool/registerAppResource.
• worker.ts — Cloudflare Workers entry point: createMcpHandler from agents/mcp with apiRoute: "/mcp", ASSETS binding for static HTML, DB binding for D1 request logging, and normalizeResourceParam() workaround for OAuthProvider audience bug.
• auth-handler.ts — Hono app with /authorize (GET/POST) and /callback routes for Google OAuth via @cloudflare/workers-oauth-provider. Uses workers-oauth-utils.ts for CSRF, state management, consent dialog.
• workers-oauth-utils.ts — OAuth utilities: CSRF protection, KV-backed state, cookie signing, consent dialog HTML. Workers-only (uses crypto.subtle.timingSafeEqual).
• src/mcp-app.ts — Browser-side UI: App from @modelcontextprotocol/ext-apps, ontoolresult/ontoolinput/onhostcontextchanged handlers, Chart.js rendering.
• shared/ — Pure modules imported by both server and UI:
  • types.ts — Zod schemas (ChartInput, DashboardInput, RenderResult)
  • validation.ts — Schema parsing + business rules (scatter needs {x,y}, pie max 1 dataset, etc.)
  • config.ts — buildChartConfig() transforms ChartInput → Chart.js ChartConfiguration
  • colors.ts — 12-color palette; per-slice for pie/doughnut, per-dataset for others
  • grid.ts — calculateColumns() for dashboard layout