Add HTTP transport: SDK 1.30 upgrade, request-scoped core, Cloudflare Worker

[DavertMik]

Implements the HTTP transport half of the approved design: steps 1 and 2 of its rollout, plus the worker side of step 3.

Closes #4

What ships

SDK upgrade, proven safe. A tools/list snapshot was recorded against @modelcontextprotocol/sdk@0.4.0 before the bump, driving a real JSON-RPC handshake through a capture transport. The SDK then went to ^1.30.0 and the snapshot passed byte-identical — Server + setRequestHandler survive the jump, and src/mcp/server.js needed no change beyond the new connect().

Request-scoped construction. New createMcpServer({ token, projectId, baseUrl, logger }) builds a server and API client per request. loadServerConfig() returns only { baseUrl } so HTTP mode no longer needs credentials at process start. TestomatioMCPServer.connect(transport) decouples the transport from run(). TestomatioApiClient and ToolRegistry are untouched.

TESTOMATIO_HOST / --host. beta.testomat.io becomes https://beta.testomat.io. A full URL is accepted as-is rather than producing https://https://…. Precedence: --base-url / TESTOMATIO_BASE_URL > --host / TESTOMATIO_HOST > DEFAULT_BASE_URL.

Cloudflare Worker in worker/, excluded from the npm tarball (verified with npm pack --dry-run). POST /mcp/<project_id> builds a fresh server and a stateless WebStandardStreamableHTTPServerTransport per request; GET returns 405. testomat_ / tstmt_ bearer tokens bypass OAuthProvider entirely, so IDE clients and curl keep working once OAuth is live. A backend 403 becomes a 401 with WWW-Authenticate, and the tests fetch the advertised resource_metadata URL to confirm it resolves.

Stdio is unchanged. Same startup path, same log line, same wire output.

Rails prerequisites (step 3)

The worker side of OAuth is complete; Rails still needs three things. The exchange contract is defined here, because completeAuthorization requires a user id that the design doc left unstated:

1. GET /mcp/authorize?state=<random> — consent page behind authenticate_user!. The worker redirects here after storing oauthReqInfo in OAUTH_KV under that random state. Rails never receives a callback URL; the worker callback is Rails configuration, which removes open-redirect risk.
2. Redirect back to the configured worker callback with ?code=<opaque>&state=<same random>. The opaque code lives in Rails.cache for 60s, delete-on-read.
3. POST /mcp/authorize/exchange — CSRF-exempt, authenticated by the X-Mcp-Worker-Secret header, body {"code": "<opaque>"}. It must respond:

{ "token": "testomat_…", "user_id": 42, "user_email": "qa@example.com" }

token is the McpToken key, user_id identifies the grant owner (required by completeAuthorization), user_email is optional and becomes the grant label shown in the connectors list.

Rollout

Step	State
1. SDK bump + core refactor + tests	this PR
2. Worker with bearer pass-through	this PR — deployable and curl-testable today
3. Rails authorize endpoint + Worker OAuth provider	worker side done, Rails side pending (see above)
4. Revocation UI, connect-to-Claude UI, docs	out of scope

Deploy:

cd worker
npx wrangler kv namespace create OAUTH_KV     # put the id into wrangler.jsonc
npx wrangler secret put TESTOMATIO_MCP_WORKER_SECRET
npx wrangler deploy

kv_namespaces[0].id in worker/wrangler.jsonc is a placeholder and must be replaced before the first deploy. A staging worker is the same code with TESTOMATIO_BASE_URL set to https://beta.testomat.io in its own vars block. The shared secret is a Wrangler secret and is never committed.

Tests

npm test — 29 tests, 6 files, all passing. A Tests workflow now runs npm ci && npm test on every PR; there was no test job before.

• test/tools-list.test.js — the SDK regression snapshot.
• test/load-config.test.js, test/create-server.test.js — precedence rules and per-instance isolation.
• worker/test/mcp-endpoint.test.js — StreamableHTTPClientTransport against the worker with a stubbed api/v2: initialize → tools/list → tools/call, asserting the project id from the URL reaches the api/v2 path and the token reaches the Authorization header.
• worker/test/token-revocation.test.js — 403 → 401 with a resolvable WWW-Authenticate; a 422 is not masked as an auth failure.
• worker/test/oauth-flow.test.js — DCR, /authorize storing state in KV, /callback exchanging the code with the secret header and completing the grant, path-scoped protected-resource metadata, and the static-bearer bypass.

Deviations from the design doc

• createMcpServer and TestomatioMCPServer gained optional version and jsonSchemaValidator. The spec's four-argument signature cannot thread the Cloudflare validator, and getPackageVersion() reads package.json with fs, which has no meaning in workerd. Both default to undefined, so the stdio path is unaffected.
• @cfworker/json-schema is a devDependency, not a dependency. It is an optional peer of the SDK and only the worker imports it, so stdio users should not carry it.
• 403 → 401 is done by inspecting the JSON-RPC result body. ToolRegistry.execute catches ApiError and returns it as a text result, so nothing propagates out of handleRequest, and changing registry internals was out of scope. The check is narrow: it only fires on a tool result whose JSON payload has status: 403.
• @cloudflare/vitest-pool-workers@0.22 dropped fetchMock and defineWorkersProject. Config uses the new cloudflareTest Vite plugin under Vitest 4 test.projects; upstream stubbing uses vi.stubGlobal('fetch', …), which does reach the worker's outbound calls.
• npm 11+ is required for npm install locally. npm 10.9.4 hits an arborist crash resolving vitest's peer set. CI already runs npm install -g npm@latest.

Open items from the design doc that remain open: whether mcp.testomat.io is a route on the existing zone or a workers.dev subdomain behind a custom domain.

🤖 Generated with Claude Code

https://claude.ai/code/session_019MGW7FX8fFDRxmFiKtN9pR