// MCP server and OAuth development conventions for Savecraft. Use when working on MCP tools, OAuth flows, auth middleware, or the MCP handler in worker/src/mcp/, worker/src/oauth.ts, or worker/src/auth.ts. Triggers on MCP tool implementation, OAuth provider, token validation, Clerk integration, or protected resource metadata.
Proposes production releases for Savecraft components by finding latest git tags, diffing changes, and suggesting version bumps. Use when the user asks to deploy, release, tag, ship, or check what needs deploying to production. Triggers on "deploy to production", "what needs releasing", "propose version bumps", "cut a release", "tag for production", "ship it".
D1 database access and MTGA reference data pipeline for Savecraft. Use when working with D1 databases, wrangler d1 commands, MTGA data imports, clearing or reimporting card/draft/rules data, debugging why imports skip, or running mtga-carddb, 17lands-fetch, scryfall-fetch, rules-fetch, tagger-fetch tools. Triggers on "D1", "wrangler", "MTGA data", "reimport", "pipeline state", "import skipping", "draft ratings", "card data stale", "force import", "update-mtga".
Game plugin and adapter section design for Savecraft. Use when creating new plugins, designing GameState sections, adding sections to existing parsers, or working on section output in plugins/ or worker/src/adapters/. Triggers on section layout, progressive disclosure, GameState output, plugin sections, adapter sections, section sizing, or overview design.
Factorio plugin development for Savecraft. Use when working on files in plugins/factorio/, including the Lua mod (control.lua, info.json), WASM parser, reference modules (recipe_lookup, ratio_calculator), datagen pipeline, sprite sheet generator, or Factorio-specific views. Triggers on Factorio plugin code, Lua mod API, ratio calculator, recipe lookup, production chains, datagen, sprite sheets, or Factorio game data.
RimWorld reference module and mod development for Savecraft. Use when working on files in plugins/rimworld/, including reference modules (surgery, crops, combat, materials, drugs, raids, genes, research), the datagen XML parser, decompiling Assembly-CSharp.dll, or the Harmony mod. Triggers on RimWorld plugin code, XML Defs, datagen, reference.wasm, decompilation, patch verification, or RimWorld game formulas.
MCP Apps view development for Savecraft. Use when creating or modifying interactive views rendered in MCP host iframes (Claude, ChatGPT). Triggers on Svelte view components, Storybook stories, the view build pipeline, bridge code, or MCP Apps resource handling. Use when working on files in views/, worker/src/mcp/views/, plugins/*/reference/views/, or when adding viewResult() responses to tools.
| name | working-on-mcp |
| description | MCP server and OAuth development conventions for Savecraft. Use when working on MCP tools, OAuth flows, auth middleware, or the MCP handler in worker/src/mcp/, worker/src/oauth.ts, or worker/src/auth.ts. Triggers on MCP tool implementation, OAuth provider, token validation, Clerk integration, or protected resource metadata. |
Read docs/mcp.md for tool contracts, OAuth flow, notes, and search architecture.
Read docs/mcp-design.md for cross-platform MCP tool design best practices.
just test-worker # MCP tests are part of the Worker test suite
No SDK. The MCP server is hand-rolled JSON-RPC 2.0 in src/mcp/handler.ts. The official @modelcontextprotocol/sdk depends on ajv/express/hono (CJS, incompatible with workerd). The Cloudflare agents SDK's createMcpHandler ignores the env parameter so tools can't access D1/R2 bindings.
Tool functions are pure. Every tool in src/mcp/tools.ts takes (db, snapshots, userUuid) and returns a ToolResult or ViewToolResult. No side effects, no request objects, testable without the MCP protocol layer.
Two response formats. textResult(data, presentation?) for tools without views (legacy, being migrated). viewResult(structuredContent, narrative) for tools with MCP Apps views — returns { structuredContent, content } where the view widget renders structuredContent and the model uses content for its response. See docs/views.md and the working-on-views skill.
MCP Apps extension. Server declares extensions: { "io.modelcontextprotocol/ui": {} } in the initialize response. Handler auto-wires _meta.ui.resourceUri on tool definitions from views.gen.ts.
Protocol version: 2025-06-18. Transport: Streamable HTTP (POST + JSON responses, not SSE).
The Worker is itself the OAuth 2.1 Authorization Server via @cloudflare/workers-oauth-provider. Clerk is the upstream IdP only — users authenticate via Clerk, but the Worker issues its own opaque access tokens stored in OAUTH_KV.
Key properties:
ctx.props.userUuid flows from Clerk's sub claim through to R2 prefix scoping.OAUTH_ENDPOINTS constant in src/oauth.ts is shared with test helpers.Protected resource metadata gotcha: RFC 8707 uses exact string comparison. MCP clients send resource=https://host/ with trailing slash. The metadata resource URL MUST have the trailing slash or token validation silently fails. Our index.ts overrides the library's response to include the trailing slash.
src/auth.ts handles two separate auth concerns:
OAuthProvider wrapper in index.ts. Token → KV lookup → ctx.props.userUuid.src/auth.ts. Stub mode: bearer token IS user UUID (when CLERK_ISSUER not set). Clerk mode: JWT validation via JWKS.These are separate concerns. Don't conflate them.
ai_bots_protection must be disabled on the Cloudflare zone. Claude.ai's MCP client makes requests from Anthropic's IPs (160.79.104-106.x), and "Block AI Scrapers and Crawlers" silently blocks them at the edge. The OAuth flow completes but the authenticated MCP request never reaches the Worker.
worker/src/mcp/handler.ts # JSON-RPC 2.0 routing
worker/src/mcp/tools.ts # Pure tool functions
worker/src/oauth.ts # OAUTH_ENDPOINTS, Clerk redirect logic
worker/src/auth.ts # Session/daemon auth (stub + Clerk modes)
worker/src/index.ts # OAuthProvider wrapper, protected resource metadata override