@mcpmake/core 0.2.0

package/dist/emitter/worker-templates/config.ts.hbs

@@ -0,0 +1,93 @@
+/**
+ * Runtime configuration, sourced from the Workers `env` binding (not the Node
+ * process environment). Same `AppConfig` shape the shared HTTP executor + auth
+ * modules consume, so those are reused verbatim from the Node templates.
+ */
+export interface AppConfig {
+  baseUrl: string;
+{{#each authSchemes}}
+{{#if (eq type "apiKey")}}
+  apiKey?: string;
+{{/if}}
+{{#if (eq type "http-bearer")}}
+  bearerToken?: string;
+{{/if}}
+{{#if (eq type "http-basic")}}
+  basicUsername?: string;
+  basicPassword?: string;
+{{/if}}
+{{/each}}
+  maxRetries: number;
+  requestIntervalMs: number;
+  /** Extra headers added to every upstream request (non-breaking; empty by default). */
+  defaultHeaders: Record<string, string>;
+}
+
+type EnvLike = Record<string, string | undefined>;
+
+/**
+ * Resolve the upstream base URL with optional named environments.
+ * `MCP_ENVIRONMENTS` is a JSON object mapping name → base URL; `API_ENVIRONMENT`
+ * selects one. Falls back to `BASE_URL` when unset or unknown.
+ */
+function resolveBaseUrl(env: EnvLike): string {
+  const raw = env.MCP_ENVIRONMENTS;
+  const selected = env.API_ENVIRONMENT;
+  if (raw && selected) {
+    try {
+      const envs = JSON.parse(raw) as Record<string, unknown>;
+      const url = envs[selected];
+      if (typeof url === 'string' && url) {
+        return url.replace(/\/$/, '');
+      }
+    } catch {
+      // Malformed MCP_ENVIRONMENTS — fall through to BASE_URL.
+    }
+  }
+  return requireEnv(env, 'BASE_URL').replace(/\/$/, '');
+}
+
+/** Parse `MCP_DEFAULT_HEADERS` (JSON object of header → value) into a map. */
+function loadDefaultHeaders(env: EnvLike): Record<string, string> {
+  const raw = env.MCP_DEFAULT_HEADERS;
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const headers: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (typeof value === 'string') headers[key] = value;
+    }
+    return headers;
+  } catch {
+    return {};
+  }
+}
+
+export function loadConfig(env: EnvLike): AppConfig {
+  return {
+    baseUrl: resolveBaseUrl(env),
+{{#each authSchemes}}
+{{#if (eq type "apiKey")}}
+    apiKey: env.{{envVarName}},
+{{/if}}
+{{#if (eq type "http-bearer")}}
+    bearerToken: env.{{envVarName}},
+{{/if}}
+{{#if (eq type "http-basic")}}
+    basicUsername: env.BASIC_USERNAME,
+    basicPassword: env.BASIC_PASSWORD,
+{{/if}}
+{{/each}}
+    maxRetries: parseInt(env.MAX_RETRIES ?? '3', 10),
+    requestIntervalMs: parseInt(env.REQUEST_INTERVAL_MS ?? '100', 10),
+    defaultHeaders: loadDefaultHeaders(env),
+  };
+}
+
+function requireEnv(env: EnvLike, name: string): string {
+  const value = env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}

package/dist/emitter/worker-templates/dev-vars.example.hbs

@@ -0,0 +1,27 @@
+# Local dev secrets for `wrangler dev`. Copy to `.dev.vars` (gitignored) and fill in.
+# In production these are set with `wrangler secret put <NAME>` instead.
+
+# Bearer token clients must send as `Authorization: Bearer <token>`.
+# Leave empty to disable auth (local/dev only — never deploy without it).
+MCP_AUTH_TOKEN=
+{{#each authEnvVars}}
+# {{description}}
+{{name}}=
+{{/each}}
+
+# Runtime tool filtering (optional, comma-separated tool names).
+# MCP_TOOLS=
+# MCP_EXCLUDE_TOOLS=
+
+# Named environments (optional). JSON map of name → base URL; API_ENVIRONMENT
+# selects one. Falls back to BASE_URL when unset.
+{{#if environmentsJson}}
+MCP_ENVIRONMENTS={{environmentsJson}}
+API_ENVIRONMENT={{defaultEnvironment}}
+{{else}}
+# MCP_ENVIRONMENTS={"production":"{{baseUrl}}","sandbox":"https://sandbox.example.com"}
+# API_ENVIRONMENT=production
+{{/if}}
+
+# Custom default headers added to every upstream request (optional, JSON object).
+# MCP_DEFAULT_HEADERS={"X-Tenant-Id":"acme"}

package/dist/emitter/worker-templates/gitignore.hbs

@@ -0,0 +1,6 @@
+node_modules/
+.dev.vars
+.wrangler/
+dist/
+*.tgz
+.DS_Store

package/dist/emitter/worker-templates/package.json.hbs

@@ -0,0 +1,24 @@
+{
+  "name": "{{serverName}}",
+  "version": "{{serverVersion}}",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "start": "wrangler dev",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "zod-to-json-schema": "^3.24.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20241127.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "wrangler": "^3.90.0"
+  }
+}

package/dist/emitter/worker-templates/readme.md.hbs

@@ -0,0 +1,73 @@
+# {{serverName}}
+
+An MCP server for **{{baseUrl}}**, generated by [mcpmake](https://mcpmake.dev) for
+**Cloudflare Workers** (`--target cloudflare`).
+
+It runs as a stateless [Fetch handler](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/):
+every `POST /mcp` carries one self-contained JSON-RPC message and gets one JSON
+response — which maps cleanly onto the **2026-07-28** stateless transport (still a
+release candidate), so no session state is kept and any request can hit any edge
+location. Cloudflare's free plan covers 100,000 requests/day.
+
+The `initialize` handshake negotiates to the current **stable** revision
+(`2025-11-25`) or to the client's requested version when it is one this server
+implements; it does not blindly echo arbitrary versions. This is a **tools-only**
+server (no resources, prompts, Tasks, or OAuth) — use `--target node` if you need
+those.
+
+## Tools
+
+This server exposes **{{tools.length}}** tool(s). Run `tools/list` to see them.
+
+Every tool also accepts two optional per-call arguments: `jq_filter` (a jq-style
+selector like `.data` or `.items[]` applied to the response to trim it) and
+`idempotency_key` (sent as the `Idempotency-Key` header on mutating requests).
+
+## Runtime configuration (optional)
+
+Set these as Workers vars/secrets (none are required):
+
+- `MCP_TOOLS` / `MCP_EXCLUDE_TOOLS` — comma-separated allow/deny list of tool
+  names to expose without redeploying.
+- `MCP_ENVIRONMENTS` (JSON map of name → base URL) + `API_ENVIRONMENT` — select
+  an upstream environment by name; falls back to `BASE_URL`.
+- `MCP_DEFAULT_HEADERS` — JSON object of headers added to every upstream request.
+
+## Develop
+
+```bash
+npm install
+cp .dev.vars.example .dev.vars   # fill in MCP_AUTH_TOKEN + API credentials
+npm run dev                      # wrangler dev — local Workers runtime
+npm run typecheck
+```
+
+## Deploy
+
+```bash
+# One-time: store each secret in Cloudflare (never commit them).
+npx wrangler secret put MCP_AUTH_TOKEN     # bearer token clients must present
+{{#each authEnvVars}}
+npx wrangler secret put {{name}}
+{{/each}}
+
+npx wrangler deploy
+```
+
+`BASE_URL` and HTTP tuning live in `wrangler.toml` under `[vars]`; secrets are
+set with `wrangler secret put` and injected via the `env` binding at runtime.
+
+## Connect a client
+
+Point an MCP client at `https://<your-worker>.workers.dev/mcp` with the header
+`Authorization: Bearer <MCP_AUTH_TOKEN>`. Health checks: `GET /health`, `GET /ready`.
+
+## Notes & limits (Workers target)
+
+- **Auth:** every path except `/health` and `/ready` requires the bearer token
+  (constant-time check) when `MCP_AUTH_TOKEN` is set.
+- **Stateless only:** there is no SSE stream or `Mcp-Session-Id` session; `GET`/
+  `DELETE /mcp` are not used. Long-running tools resolve within the request (no
+  Tasks extension / background polling).
+- Need MCP resources, prompts, the Tasks extension, or OAuth2 outbound auth?
+  Regenerate with `--target node` (the default) for the full feature set.

package/dist/emitter/worker-templates/server.test.ts.hbs

@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { tools } from '../src/tools/index.js';
+
+describe('{{serverName}} worker tools', () => {
+  it('registers every tool with a usable definition', () => {
+    expect(tools.length).toBe({{tools.length}});
+    for (const { definition, handler } of tools) {
+      expect(definition.name).toMatch(/^[a-zA-Z0-9_-]+$/);
+      expect(typeof definition.description).toBe('string');
+      expect(typeof handler).toBe('function');
+      // The input schema must accept a safeParse call (used for tools/call validation).
+      expect(typeof definition.inputSchema.safeParse).toBe('function');
+    }
+  });
+
+  it('has unique tool names', () => {
+    const names = tools.map((t) => t.definition.name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});

package/dist/emitter/worker-templates/tool-handler.ts.hbs

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { executeRequest } from '../http.js';
+import { applyJqFilter } from '../response-filter.js';
+import type { AppConfig } from '../config.js';
+
+// Per-call control arguments shared by every generated tool. Optional and
+// stripped before the upstream request, so omitting them is a no-op.
+const controlSchema = {
+  jq_filter: z
+    .string()
+    .optional()
+    .describe(
+      'Optional jq-style filter applied to the JSON response before it is returned ' +
+        '(e.g. ".data", ".items[0].id", ".items[]"). Trims large responses.',
+    ),
+  idempotency_key: z
+    .string()
+    .optional()
+    .describe(
+      'Optional Idempotency-Key header for safe retries of mutating requests. ' +
+        'Ignored for read-only operations.',
+    ),
+};
+
+const inputSchema = ({{{inputSchemaCode}}}).extend(controlSchema);
+
+export const definition = {
+  name: '{{name}}',
+  title: '{{title}}',
+  description: `{{{description}}}`,
+  inputSchema,
+{{#if annotations}}
+  annotations: {
+{{#if annotations.readOnlyHint}}
+    readOnlyHint: true,
+{{/if}}
+{{#if annotations.destructiveHint}}
+    destructiveHint: true,
+{{/if}}
+{{#if annotations.idempotentHint}}
+    idempotentHint: true,
+{{/if}}
+  } as Record<string, boolean>,
+{{/if}}
+};
+
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+  isError?: boolean;
+}
+
+/**
+ * Execute this tool. On the Workers (stateless) target a tool always runs to
+ * completion within the request — there is no Tasks extension / background
+ * polling, so async operations resolve synchronously here.
+ */
+export async function handler(
+  input: Record<string, unknown>,
+  config: AppConfig,
+): Promise<ToolResult> {
+  try {
+    const result = await runRequest(input, config);
+    return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+  }
+}
+
+async function runRequest(rawInput: Record<string, unknown>, config: AppConfig): Promise<unknown> {
+  // Pull off the per-call control args so they are never forwarded upstream.
+  const { jq_filter: jqFilter, idempotency_key: idempotencyKey, ...input } = rawInput;
+  const url = buildUrl(input, config.baseUrl);
+
+  const response = await executeRequest({
+    method: '{{method}}',
+    url,
+{{#if hasRequestBody}}
+    body: input.body,
+    contentType: '{{requestBodyContentType}}',
+{{/if}}
+    headers: {},
+    config,
+    idempotencyKey: typeof idempotencyKey === 'string' ? idempotencyKey : undefined,
+  });
+
+  let result: unknown = response.data;
+{{#if jqFilter}}
+  // Build-time x-mcp-jq-filter (applied first when no per-call filter is given).
+  if (typeof jqFilter !== 'string') {
+    result = applyJqFilter(result, '{{{jqFilter}}}');
+  }
+{{/if}}
+  // Per-call jq_filter takes precedence (absent → unchanged).
+  if (typeof jqFilter === 'string' && jqFilter) {
+    result = applyJqFilter(result, jqFilter);
+  }
+  return result;
+}
+
+function buildUrl(params: Record<string, unknown>, baseUrl: string): string {
+{{{buildUrlBody}}}
+}

package/dist/emitter/worker-templates/tool-index.ts.hbs

@@ -0,0 +1,28 @@
+import type { z } from 'zod';
+import type { AppConfig } from '../config.js';
+{{#each tools}}
+import {
+  definition as def{{capitalize functionName}},
+  handler as handler{{capitalize functionName}},
+} from './{{fileName}}.js';
+{{/each}}
+
+export interface ToolEntry {
+  definition: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodTypeAny;
+    annotations?: Record<string, boolean>;
+  };
+  handler: (
+    input: Record<string, unknown>,
+    config: AppConfig,
+  ) => Promise<{ content: { type: 'text'; text: string }[]; isError?: boolean }>;
+}
+
+export const tools: ToolEntry[] = [
+{{#each tools}}
+  { definition: def{{capitalize functionName}}, handler: handler{{capitalize functionName}} },
+{{/each}}
+];

package/dist/emitter/worker-templates/tsconfig.json.hbs

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types", "node"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/dist/emitter/worker-templates/worker.ts.hbs

@@ -0,0 +1,286 @@
+/**
+ * Cloudflare Workers entry — stateless MCP server (Fetch handler).
+ *
+ * The MCP 2026-07-28 transport is stateless (no Mcp-Session-Id, no persistent
+ * connection): each `POST /mcp` carries one self-contained JSON-RPC message (or
+ * a batch) and receives one JSON response. That maps cleanly onto the Workers
+ * request/response model, so we dispatch JSON-RPC by hand here instead of using
+ * the SDK's StreamableHTTPServerTransport, which is bound to node:http req/res
+ * objects and cannot run on Workers.
+ *
+ * Secrets (API credentials + the MCP bearer token) arrive via the `env` binding,
+ * not process.env — set them with `wrangler secret put <NAME>`.
+ */
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { loadConfig, type AppConfig } from './config.js';
+import { tools, type ToolEntry } from './tools/index.js';
+import { deriveContext, runWithTrace } from './trace.js';
+
+export interface Env {
+  [key: string]: string | undefined;
+}
+
+// initialize handshake. We answer with our preferred stable revision, or the
+// client's requested version when it is one we actually implement — we never
+// blindly echo an arbitrary requested string (that would claim compatibility
+// this tools-only Worker has not implemented). The basic initialize/tools flow
+// is unchanged across these revisions, so all are genuinely supported.
+const PROTOCOL_VERSION = '2025-11-25'; // preferred (current stable)
+const SUPPORTED_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+const PROTOCOL_REVISION = '2026-07-28'; // server/discover preflight only (SEP-2575); NOT the negotiated initialize version
+const SERVER_INFO = { name: '{{serverName}}', version: '{{serverVersion}}' } as const;
+const MAX_BODY = 4 * 1024 * 1024; // 4 MB
+
+const toolByName = new Map<string, ToolEntry>(tools.map((t) => [t.definition.name, t]));
+
+/* ── Runtime tool filtering (additive) ───────────────────────────────────
+ * Two optional env vars narrow which tools are exposed without rebuilding:
+ *   MCP_TOOLS          comma-separated allowlist (only these names)
+ *   MCP_EXCLUDE_TOOLS  comma-separated denylist (applied after the allowlist)
+ * When neither is set every tool is exposed exactly as before. */
+function parseList(raw: string | undefined): Set<string> | undefined {
+  if (!raw) return undefined;
+  const names = raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return names.length > 0 ? new Set(names) : undefined;
+}
+function toolEnabled(name: string, env: Env): boolean {
+  const allow = parseList(env.MCP_TOOLS);
+  const deny = parseList(env.MCP_EXCLUDE_TOOLS);
+  if (allow && !allow.has(name)) return false;
+  if (deny && deny.has(name)) return false;
+  return true;
+}
+function enabledTools(env: Env): ToolEntry[] {
+  return tools.filter((t) => toolEnabled(t.definition.name, env));
+}
+
+/* ── Constant-time bearer check ──────────────────────────────────────────
+ * HMACs both tokens to fixed-length digests with a random per-isolate key,
+ * then compares the bytes — constant time and independent of token length, so
+ * neither equality nor length leaks through timing. The key is created lazily
+ * on first use: Workers forbids generating random values in global scope, so it
+ * must be minted inside a request handler. */
+let cmpKeyPromise: Promise<CryptoKey> | null = null;
+function compareKey(): Promise<CryptoKey> {
+  if (!cmpKeyPromise) {
+    cmpKeyPromise = crypto.subtle.importKey(
+      'raw',
+      crypto.getRandomValues(new Uint8Array(32)),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign'],
+    );
+  }
+  return cmpKeyPromise;
+}
+async function safeEqual(a: string, b: string): Promise<boolean> {
+  const key = await compareKey();
+  const enc = new TextEncoder();
+  const da = new Uint8Array(await crypto.subtle.sign('HMAC', key, enc.encode(a)));
+  const db = new Uint8Array(await crypto.subtle.sign('HMAC', key, enc.encode(b)));
+  let diff = 0;
+  for (let i = 0; i < da.length; i++) diff |= da[i] ^ db[i];
+  return diff === 0;
+}
+async function isAuthorized(request: Request, expected: string | undefined): Promise<boolean> {
+  if (!expected) return true; // auth disabled when MCP_AUTH_TOKEN is unset (local/dev only)
+  const header = request.headers.get('authorization');
+  if (!header || !header.startsWith('Bearer ')) return false;
+  const presented = header.slice(7).trim();
+  if (!presented) return false;
+  return safeEqual(presented, expected);
+}
+
+/* ── HTTP / CORS helpers ─────────────────────────────────────────────── */
+function corsHeaders(origin?: string | null): Record<string, string> {
+  return {
+    'access-control-allow-origin': origin || '*',
+    'access-control-allow-methods': 'POST, GET, OPTIONS',
+    'access-control-allow-headers':
+      'authorization, content-type, mcp-method, mcp-name, mcp-protocol-version, traceparent, tracestate',
+  };
+}
+function json(body: unknown, status = 200, extra?: Record<string, string>): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', ...corsHeaders(), ...extra },
+  });
+}
+function ok(id: unknown, result: unknown): object {
+  return { jsonrpc: '2.0', id: id ?? null, result };
+}
+function err(id: unknown, code: number, message: string): object {
+  return { jsonrpc: '2.0', id: id ?? null, error: { code, message } };
+}
+function rpcErrorResponse(id: unknown, code: number, message: string): Response {
+  return json(err(id, code, message));
+}
+
+/* ── server/discover (SEP-2575) — VERIFY result shape against the final spec ── */
+function discoverResult(env: Env): Record<string, unknown> {
+  return {
+    server: SERVER_INFO,
+    protocolRevision: PROTOCOL_REVISION,
+    capabilities: { tools: { count: enabledTools(env).length } },
+    extensions: [],
+    cacheTtlSeconds: 300,
+  };
+}
+
+/** A tool's `tools/list` entry: its input schema rendered as JSON Schema. */
+function toListEntry(t: ToolEntry): Record<string, unknown> {
+  const schema = zodToJsonSchema(t.definition.inputSchema, {
+    $refStrategy: 'none',
+  }) as Record<string, unknown>;
+  delete schema.$schema;
+  return {
+    name: t.definition.name,
+    title: t.definition.title,
+    description: t.definition.description,
+    inputSchema: schema,
+    ...(t.definition.annotations ? { annotations: t.definition.annotations } : {}),
+  };
+}
+
+async function handleToolCall(
+  id: unknown,
+  params: { name?: unknown; arguments?: unknown } | undefined,
+  config: AppConfig,
+  env: Env,
+): Promise<object> {
+  const name = typeof params?.name === 'string' ? params.name : '';
+  const entry = toolByName.get(name);
+  if (!entry || !toolEnabled(name, env)) return err(id, -32602, `Unknown tool: ${name}`);
+  const parsed = entry.definition.inputSchema.safeParse(params?.arguments ?? {});
+  if (!parsed.success) {
+    return err(id, -32602, `Invalid arguments for ${name}: ${parsed.error.message}`);
+  }
+  const result = await entry.handler(parsed.data as Record<string, unknown>, config);
+  return ok(id, result);
+}
+
+/** Dispatch one JSON-RPC message. Returns null for notifications (no reply). */
+async function handleRpc(
+  msg: { id?: unknown; method?: unknown; params?: unknown } | null,
+  config: AppConfig,
+  env: Env,
+): Promise<object | null> {
+  const id = msg?.id;
+  const method = msg?.method;
+  switch (method) {
+    case 'initialize': {
+      // Negotiate, don't echo: honor the client's requested version only when
+      // we implement it; otherwise answer with our preferred version so the
+      // client can decide whether to proceed.
+      const requested = (msg?.params as { protocolVersion?: unknown })?.protocolVersion;
+      const negotiated =
+        typeof requested === 'string' && SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+          ? requested
+          : PROTOCOL_VERSION;
+      return ok(id, {
+        protocolVersion: negotiated,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: SERVER_INFO,
+      });
+    }
+    case 'ping':
+      return ok(id, {});
+    case 'tools/list':
+      return ok(id, { tools: enabledTools(env).map(toListEntry) });
+    case 'tools/call':
+      return handleToolCall(
+        id,
+        msg?.params as { name?: unknown; arguments?: unknown },
+        config,
+        env,
+      );
+    case 'server/discover':
+      return ok(id, discoverResult(env));
+    default:
+      // Notifications (e.g. notifications/initialized) carry no id and get no reply.
+      if (id === undefined || id === null) return null;
+      return err(id, -32601, `Method not found: ${String(method)}`);
+  }
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    const origin = request.headers.get('origin');
+
+    if (request.method === 'OPTIONS') {
+      return new Response(null, { status: 204, headers: corsHeaders(origin) });
+    }
+    if (url.pathname === '/health') return json({ status: 'ok' });
+    if (url.pathname === '/ready') return json({ status: 'ready' });
+
+    // Bearer authentication (every path except /health and /ready).
+    if (!(await isAuthorized(request, env.MCP_AUTH_TOKEN))) {
+      return json({ error: 'Unauthorized: missing or invalid bearer token' }, 401, {
+        'www-authenticate': 'Bearer',
+      });
+    }
+
+    // Routing-header observability (SEP-2243, additive — never rejects).
+    const mcpMethod = request.headers.get('mcp-method');
+    const mcpName = request.headers.get('mcp-name');
+    if (mcpMethod || mcpName) {
+      console.log(JSON.stringify({ level: 'info', msg: 'mcp-meta-headers', mcpMethod, mcpName }));
+    }
+
+    if (url.pathname !== '/mcp') return json({ error: 'Not found' }, 404);
+    if (request.method !== 'POST') {
+      // Stateless: no SSE stream to open (GET) or session to delete (DELETE).
+      return rpcErrorResponse(null, -32601, 'Only POST is supported on this stateless server');
+    }
+
+    // Origin guard (DNS-rebinding protection). Enforced only when configured —
+    // a Workers endpoint is public and gated by the bearer token, not by origin.
+    const allowedOrigin = env.ALLOWED_ORIGIN;
+    if (allowedOrigin && origin && origin !== allowedOrigin) {
+      return json({ error: 'Forbidden: invalid origin' }, 403);
+    }
+
+    const contentLength = Number(request.headers.get('content-length') ?? '0');
+    if (contentLength > MAX_BODY) return rpcErrorResponse(null, -32600, 'Request body too large');
+    const raw = await request.text();
+    if (raw.length > MAX_BODY) return rpcErrorResponse(null, -32600, 'Request body too large');
+    if (!raw) return rpcErrorResponse(null, -32600, 'Empty request body');
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return rpcErrorResponse(null, -32700, 'Parse error');
+    }
+
+    const config = loadConfig(env);
+    // Bind a W3C Trace Context for this request so upstream API calls made inside
+    // the tool handlers carry the traceparent and the trace spans the API hop.
+    const trace = deriveContext(
+      request.headers.get('traceparent') ?? undefined,
+      request.headers.get('tracestate') ?? undefined,
+    );
+
+    return runWithTrace(trace, async () => {
+      if (Array.isArray(parsed)) {
+        const settled = await Promise.all(
+          parsed.map((m) => handleRpc(m as { id?: unknown; method?: unknown }, config, env)),
+        );
+        const responses = settled.filter((r): r is object => r !== null);
+        if (responses.length === 0) {
+          return new Response(null, { status: 202, headers: corsHeaders(origin) });
+        }
+        return json(responses);
+      }
+      const response = await handleRpc(parsed as { id?: unknown; method?: unknown }, config, env);
+      if (response === null) {
+        return new Response(null, { status: 202, headers: corsHeaders(origin) });
+      }
+      return json(response);
+    });
+  },
+};