feat(mcp-gateway): scaffold runtime worker

[pandemicsyn]

Summary

• Add the initial services/mcp-gateway Worker scaffold for the app-owned control plane / Worker-owned runtime architecture, including top-level production Wrangler config, env.dev, Hyperdrive, per-instance DO binding, Analytics Engine binding, generated Worker types, and local service docs.
• Add a route-only Hono entrypoint and route-shape tests for /health, scoped /mcp-connect/... runtime routes, and generic/scoped protected-resource metadata routes; all gateway runtime routes remain 501 stubs so the service is safe to merge before OAuth/runtime implementation.
• Keep the gateway architecture notes in the planning workspace until PR2 to avoid introducing a partially overlapping spec surface in the repo before the functional implementation lands.

Verification

• Started pnpm --filter cloudflare-mcp-gateway dev and confirmed the local Worker booted on http://0.0.0.0:8806.
• Requested GET /health locally and confirmed 200 with {"status":"ok","service":"mcp-gateway"}.
• Requested GET /mcp-connect/user/user-123/config-123/route-123 locally and confirmed 501 with {"status":"not_implemented"}.
• Additional manual verification details:

Visual Changes

N/A

Reviewer Notes

• PR1 intentionally does not attach mcp.kilo.ai or implement OAuth, gateway tables/migrations, provider discovery, proxying, or DO domain behavior.
• The Worker uses a top-level production Wrangler config plus env.dev; the compatibility date is pinned to 2026-05-15 because that was the newest date supported by the local Wrangler runtime used during validation.
• The branch contains two commits: the scaffold and a follow-up that defers the copied gateway specs to PR2.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

The two previously flagged WARNING issues (discarded Zod parse return values in all four route handlers) are resolved in commit 48a0815e6 — validated params are now captured and threaded through to notImplementedResponse as a typed optional parameter.

Resolved Issues

File	Issue	Status
services/mcp-gateway/src/handlers/connect.handler.ts	parse() result was discarded	✅ Fixed — result assigned to validatedParams and passed to notImplementedResponse
services/mcp-gateway/src/handlers/protected-resource.handler.ts	parse() result was discarded	✅ Fixed — same pattern applied to both parameterized handlers

Other Observations (not in diff, unchanged)

Wildcard route params include a "*" key: Routes like /mcp-connect/user/:userId/:configId/:routeKey/* produce c.req.param() objects containing an extra "*" key (the matched wildcard segment). Zod's z.object() strips unknown keys by default, so the wildcard portion is silently discarded. This is harmless in PR1, but the intent should be documented — future handlers that need the sub-path (e.g. to proxy /tools/list downstream) must extract the * param explicitly before parsing with the schema.

dev environment duplicates production bindings verbatim in wrangler.jsonc: The env.dev block repeats durable_objects, hyperdrive, and analytics_engine_datasets identically to the top-level config. Wrangler env blocks do not inherit bindings from the top level, so duplication is required by the platform — no action needed, just noting it for reviewers unfamiliar with Wrangler's env semantics.

Files Reviewed (18 files)

• pnpm-lock.yaml
• services/mcp-gateway/.dev.vars.example
• services/mcp-gateway/AGENTS.md
• services/mcp-gateway/README.md
• services/mcp-gateway/package.json
• services/mcp-gateway/src/durable-objects/MCPGatewayInstance.do.ts
• services/mcp-gateway/src/handlers/connect.handler.ts — ✅ resolved
• services/mcp-gateway/src/handlers/health.handler.ts
• services/mcp-gateway/src/handlers/protected-resource.handler.ts — ✅ resolved
• services/mcp-gateway/src/lib/responses.ts — updated (new optional params arg)
• services/mcp-gateway/src/mcp-gateway.worker.test.ts
• services/mcp-gateway/src/mcp-gateway.worker.ts
• services/mcp-gateway/src/schemas/routes.schema.ts
• services/mcp-gateway/src/types.ts
• services/mcp-gateway/tsconfig.json
• services/mcp-gateway/vitest.config.ts
• services/mcp-gateway/worker-configuration.d.ts
• services/mcp-gateway/wrangler.jsonc

---

_{Reviewed by claude-4.6-sonnet-20260217 · 205,759 tokens}

_{Review guidance: REVIEW.md from base branch main}