@vvedantb/server 0.0.0-stage → 0.1.0

package/docs/convex.md

@@ -0,0 +1,69 @@
+# @vvedantb/server/convex
+
+Plain Convex backend helpers. No React, no generated Convex imports. Compiled ESM with types. Import it as `@vvedantb/server/convex`.
+
+## Install
+
+```sh
+npm install @vvedantb/server
+```
+
+## Peers
+
+None required. `@clerk/backend` is an optional peer: install it only if you use `getClerkClient`, and pass its `createClerkClient`.
+
+## Usage
+
+```ts
+// convex/auth.config.ts
+import { clerkAuthConfig } from "@vvedantb/server/convex";
+export default clerkAuthConfig(); // domain from CLERK_FRONTEND_API_URL, applicationID "convex"
+```
+
+```ts
+import { createClerkClient } from "@clerk/backend";
+import { getClerkClient, requiredEnvUrl, extractBearerToken } from "@vvedantb/server/convex";
+
+const clerk = getClerkClient(createClerkClient); // throws if CLERK_SECRET_KEY or CLERK_PUBLISHABLE_KEY is missing
+const issuer = requiredEnvUrl("CLERK_FRONTEND_API_URL"); // trailing slash removed
+const token = extractBearerToken(request.headers.get("Authorization"));
+```
+
+```ts
+import { corsPreflight, jsonWithCors, defineMcpServerInfo } from "@vvedantb/server/convex";
+
+if (request.method === "OPTIONS") return corsPreflight();
+return jsonWithCors({ error: "Unauthorized" }, { status: 401, extraHeaders: { "WWW-Authenticate": "Bearer" } });
+
+const serverInfo = defineMcpServerInfo({ name: "my-mcp", version: "1.0.0" });
+```
+
+```ts
+import { formatConvexQueryError, isConvexResourceLimitError } from "@vvedantb/server/convex";
+import { assertMcpTools, expectMcpToolCount } from "@vvedantb/server/convex";
+
+assertMcpTools(toolNames, ["search", "write"]); // sorted, unique comparison
+expectMcpToolCount(toolNames, 2);
+```
+
+| Export | What it does |
+| --- | --- |
+| `isConvexResourceLimitError`, `formatConvexQueryError` | Detect Convex read, write and time limit failures and add a remedy to the message. |
+| `clerkAuthConfig(env?)` | `auth.config.ts` provider list. |
+| `getClerkClient(factory, env?)` | Clerk backend client from env, with an injected factory. |
+| `extractBearerToken(header)` | Token from an `Authorization` header, or `null`. |
+| `requiredEnv(name, env?)`, `requiredEnvUrl(name, env?)` | Required env value, optionally stripping a trailing slash. |
+| `mcpCorsHeaders`, `corsPreflight`, `jsonWithCors` | CORS for MCP HTTP handlers. Methods `GET,POST,DELETE,OPTIONS`; headers `Authorization,Content-Type`; credentials `false`. |
+| `defineMcpServerInfo({ name, version })` | MCP `serverInfo`. The caller owns both values. |
+| `expectMcpToolCount`, `assertMcpTools` | Test helpers. They throw plain errors, so they work with any runner. |
+
+Not included: Clerk user helpers, `ensureUserExists`, rate limits, crypto, MCP scaffolding.
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/server build
+pnpm --filter @vvedantb/server test
+```
+
+Publish steps for the whole package are in the root `README.md`.

package/docs/mcp.md

@@ -0,0 +1,227 @@
+# `@vvedantb/server/mcp`
+
+MCP server scaffolding for Convex `httpAction`s: the `/mcp` bearer-auth handler, OAuth metadata endpoints, a pure JSON-RPC dispatcher, tool helpers and user-scoped explorer tools. Web-standard `Request`/`Response` only, no Node APIs, no MCP SDK dependency. Compiled ESM with types. Import it as `@vvedantb/server/mcp`.
+
+It replaces the near-copies of `convex/mcp/native.ts`, the `handleMcpRequest` body and the explorer tools in app-a, app-b, app-c and app-d. app-e uses only the metadata, CORS and protocol-version helpers. See [docs/migration.md](docs/migration.md) for per-app steps and measured line counts.
+
+## Install
+
+```sh
+npm install @vvedantb/server
+```
+
+## Dependencies and peers
+
+- `@vvedantb/server/convex` ships in the same package. The MCP kit imports its `extractBearerToken`, `requiredEnvUrl`, `mcpCorsHeaders`, `McpServerInfo` and `EnvSource` through relative imports, so there is no second install step and no version to match.
+- `zod` is an optional peer (`^3.25.0 || ^4.0.0`). The kit never imports zod. `defineTool` accepts any object with zod's `safeParse` (zod 3.25+ or 4), and calls the schema's own `toJSONSchema()` (zod 4) for `tools/list`. With zod 3, pass `jsonSchema` per tool or a `toJsonSchema` converter (see below).
+- Nothing else. The MCP SDK is optional and stays in the app (`runSdkMcpRequest` takes its classes as arguments).
+
+## Quick start
+
+Today's architecture: the HTTP layer runs in `httpAction`; JSON-RPC runs in a `"use node"` internalAction with the MCP SDK.
+
+```ts
+// convex/mcp/native.ts
+import { httpAction, type ActionCtx } from "../_generated/server";
+import { internal } from "../_generated/api";
+import {
+  createAuthorizationServerMetadataProxy,
+  createHealthHandler,
+  createMcpHttpHandler,
+  createProtectedResourceMetadata,
+} from "@vvedantb/server/mcp";
+
+export const oauthMetadata = httpAction(createAuthorizationServerMetadataProxy());
+export const protectedResourceMetadata = httpAction(createProtectedResourceMetadata());
+export const health = httpAction(createHealthHandler());
+
+export const mcpHandler = httpAction(
+  createMcpHttpHandler<{ clerkUserId: string }, ActionCtx>({
+    authenticate: ({ ctx, token }) =>
+      ctx.runAction(internal.mcp.nodeActions.verifyAccessToken, { token }),
+    handleRpc: ({ ctx, principal, body }) =>
+      ctx.runAction(internal.mcp.nodeActions.handleMcpRequest, { clerkUserId: principal.clerkUserId, body }),
+  }),
+);
+```
+
+```ts
+// convex/mcp/nodeActions.ts ("use node")
+import { runSdkMcpRequest } from "@vvedantb/server/mcp";
+
+export const handleMcpRequest = internalAction({
+  args: { clerkUserId: v.string(), body: v.string() },
+  returns: v.object({ status: v.number(), body: v.string() }),
+  handler: async (ctx, { clerkUserId, body }) =>
+    runSdkMcpRequest({
+      body,
+      Transport: WebStandardStreamableHTTPServerTransport,
+      createServer: () => {
+        const server = new McpServer(defineMcpServerInfo({ name: "my-mcp", version: "1.0.0" }));
+        registerTools(server, clerkUserId, ctx);
+        return server;
+      },
+    }),
+});
+```
+
+Self-contained alternative (no SDK, no `"use node"`): replace `handleRpc` with the kit dispatcher.
+
+```ts
+const dispatcher = createMcpDispatcher<Principal, ActionCtx>({
+  serverInfo: defineMcpServerInfo({ name: "my-mcp", version: "1.0.0" }),
+  tools: [searchTool, ...createExplorerTools({ tables, execute })],
+});
+
+export const mcpHandler = httpAction(
+  createMcpHttpHandler<Principal, ActionCtx>({ authenticate, handleRpc: dispatcher.handleRpc }),
+);
+```
+
+## API
+
+### HTTP layer
+
+| Export | What it does |
+| --- | --- |
+| `createMcpHttpHandler(config)` | `/mcp` handler for `httpAction`. Order: CORS preflight (if `cors`), optional early method check, bearer token (`extractBearerToken`), `authenticate`, method check, body parsing, `handleRpc`. |
+| `createAuthorizationServerMetadataProxy(options)` | `GET /.well-known/oauth-authorization-server`: fetches `<issuer>/.well-known/oauth-authorization-server`. 502 `{"error":"Failed to fetch authorization server metadata"}` on a non-2xx upstream. |
+| `createProtectedResourceMetadata(options)` | `{ resource, authorization_servers, bearer_methods_supported: ["header"], resource_documentation }`. |
+| `createHealthHandler(options)` | 200 `{"status":"ok"}` (body configurable). |
+| `createOptionsHandler({ cors })` | 204 preflight with only the CORS headers. |
+| `mcpCors(overrides?, origin?)` | `mcpCorsHeaders(origin)` from `@vvedantb/server/convex` with overrides on top. |
+| `readEnvUrl(source, env?)` | Env URL with optional fallback var, through `requiredEnvUrl` from `@vvedantb/server/convex`. |
+| `consoleMcpLogger` | Default log hook with the app-a strings. |
+| `runSdkMcpRequest(options)` | The apps' `handleMcpRequest` body: stateless JSON-response SDK transport, 500 JSON-RPC -32603 on any throw. SDK classes are passed in. |
+| `mcpInternalError(err)` | `{ status: 500, body: '{"jsonrpc":"2.0","error":{"code":-32603,"message":...},"id":null}' }`. |
+
+`createMcpHttpHandler` config:
+
+| Key | Default | Notes |
+| --- | --- | --- |
+| `authenticate({ token, request, ctx, scope })` | required | Return the principal or `null` (401 "Invalid or expired token"). A throw escapes (Convex answers 500), as in the apps today; `onAuthenticateError: "unauthorized"` maps it to 401 instead. |
+| `handleRpc({ principal, body, json, request, ctx, scope })` | required | Returns `{ status, body }`, sent with `Content-Type: application/json` plus CORS. `body` is the JSON text, `json` the parsed value. |
+| `scope` | none | Opaque value passed to both callbacks (app-a `"personal"` / `"team"`). |
+| `resourceMetadataPath` / `resourceMetadataUrl(request)` | `/.well-known/oauth-protected-resource` | Used in `WWW-Authenticate: Bearer resource_metadata="<origin><path>"`. |
+| `rejectMethods` | `["GET", "DELETE"]` | 405 "Method not supported in stateless mode". |
+| `methodCheck` | `"after-auth"` | All four apps check after auth; app-e before. |
+| `body` | `"json"` | `"json"`: `JSON.stringify(await request.json())` (app-a, app-b, app-c). `"text"`: raw text checked with `JSON.parse` (app-d). Bad JSON: 400 "Invalid JSON body". |
+| `cors` | none | `false`, a header map, or `(request) => headers`. With CORS, `OPTIONS` returns a 204 preflight. |
+| `headers` | none | Extra headers on every response. |
+| `messages` | apps' strings | `missingToken`, `invalidToken`, `methodNotAllowed`, `invalidJson`. |
+| `log` | `consoleMcpLogger` | Events: `auth-failed`, `invalid-json`, `authenticate-threw`. `false` for none. |
+
+Env fallback modes (`EnvUrl = string | { name, fallback?, fallbackMode? }`). They differ only when vars are missing or empty:
+
+| `fallbackMode` | Rule | App |
+| --- | --- | --- |
+| `"fallback-if-set"` (default) | `!env[name] && !!env[fallback] ? fallback : name` | app-d |
+| `"prefer-primary"` | `env[name] ? name : fallback` (error names the fallback when both are missing) | app-c |
+| `"nullish"` | `env[name] ?? env[fallback]`, read as `name` (an empty primary does not fall back) | app-b |
+| plain string | no fallback | app-a, app-e |
+
+### JSON-RPC dispatcher
+
+| Export | What it does |
+| --- | --- |
+| `createMcpDispatcher(config)` | `{ handleRpc }` for stateless HTTP: `initialize`, `ping`, `tools/list`, `tools/call`, notifications (202, empty body), batches. Other methods: -32601 "Method not found". |
+| `negotiateProtocolVersion(requested, { versions, fallback })` | Echo a supported version, else the fallback. |
+| `SDK_PROTOCOL_VERSIONS` | `["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"]`, the list in MCP SDK 1.29.0 to 1.32.1. |
+| `parseRpcBody(text)` | Parse a body, or the SDK's 400 -32700 "Parse error: Invalid JSON" result. |
+| `rpcResult`, `rpcError`, `JSON_RPC_ERROR` | Response builders with the SDK's key order. |
+
+Config: `serverInfo` (or a function of the scope), `tools`, `protocol` (`versions`, `fallback`; default SDK list, fallback `"2025-11-25"` as the SDK), `capabilities` (default `{ tools: { listChanged: true } }` as `McpServer`), `instructions`, `toJsonSchema`.
+
+### Tools
+
+| Export | What it does |
+| --- | --- |
+| `defineTool({ name, description, inputSchema, handler, annotations?, scopes?, title?, jsonSchema? })` | zod schema (3.25+ or 4), or a raw JSON Schema plus `parseArgs`. `description` may be a function of the scope. `call()` validates, runs the handler, and shapes errors like MCP SDK 1.30+. |
+| `toolTextResult(text)`, `toolJsonResult(data)`, `toolErrorResult(message)` | `{content:[{type:"text",text}]}`, pretty JSON text, and `{content:[...], isError:true}`, as in the apps. |
+| `runTool(fn, { errorLabel? })` | app-d `jsonTool`: value as pretty JSON, a throw as an error result. |
+| `createToolRegistry(tools)`, `toolsToList`, `assertUniqueToolNames` | Duplicate names throw. Scope filtering (app-a `scopes`). `registry.names(scope)` feeds `assertMcpTools` from `@vvedantb/server/convex`. |
+| `formatIssues`, `invalidArgumentsResult` | SDK-style validation messages. |
+
+zod 3 converter, typed without a cast:
+
+```ts
+import { ZodType } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+const toJsonSchema: JsonSchemaConverter = (schema) => (schema instanceof ZodType ? zodToJsonSchema(schema) : {});
+```
+
+### Explorer tools
+
+`createExplorerTools({ tables, execute, runQuery?, limits?, features?, names?, descriptions?, messages?, scopes? })` returns `list_tables`, `query_table`, `count_table`, `get_document` and, with `runQuery`, `run_query`. All are marked `readOnlyHint`.
+
+- `tables`: a list of names or `{ name, fields? }` entries (app-b, app-d), or a predicate (app-c's deny-list). Names must match `^[A-Za-z_][A-Za-z0-9_]*$`.
+- `execute(op, { principal, ctx, scope })`: the app's user-scoped executor. `op` is `list_tables`, `query_table` (`table`, `order`, `limit`, `cursor`, `filters`), `count_table` or `get_document`. Return a string (sent as-is), any other JSON value (pretty JSON) or `null` (denied). A throw becomes an error result with its message.
+- Checked before `execute` runs: table in catalog, argument types, `order`, `limit` (default 100, max 1000, floored and clamped to at least 1), filter field names (identifiers; in `fields` when the entry lists them, plus `_id` and `_creationTime`), document id `^[a-zA-Z0-9_]+$`, `run_query` tables. An unknown table never reaches the executor.
+- `features`: `cursor` (app-b), `filters` (`eq`/`gte`/`lte`, app-d), `getDocument` (default on), `runQueryTables` (app-d `tables`/`limitPerTable`).
+- `createExplorerTools` throws at creation without `execute` or `tables`.
+
+## Configuration per app
+
+| | app-a | app-b | app-c | app-d | app-e |
+| --- | --- | --- | --- | --- | --- |
+| MCP routes | `/mcp`, `/mcp/team` | `/mcp` (+OPTIONS) | `/mcp` | `/mcp` (+OPTIONS) | own gateway |
+| `scope` | `personal` / `team` | none | none | none | n/a |
+| `resourceMetadataPath` | default; team `/.well-known/oauth-protected-resource/mcp/team` | default | default | default | default |
+| `cors` | none | `mcpCors({ Allow-Headers: "Content-Type, Authorization, MCP-Protocol-Version", Max-Age: "86400" })` | none | `mcpCors({ Allow-Headers: "Authorization, Content-Type, Accept, MCP-Protocol-Version, MCP-Session-Id", Expose-Headers: "WWW-Authenticate, MCP-Session-Id" })` | function reflecting `Origin` |
+| `body` | `json` | `json` | `json` | `text` | n/a |
+| `log` | default | `false` | `auth-failed` only | `false` | n/a |
+| principal | `{ clerkUserId }` | `{ clerkUserId, isPro }` | `{ clerkUserId }` | `{ clerkUserId }` (Clerk or legacy JWT) | API key / Clerk JWT |
+| AS proxy `forward` | `json` | `stream` | `text` | `text` | `json` + `fetch` hook |
+| issuer env | `CLERK_FRONTEND_API_URL` | + `NEXT_PUBLIC_…` `nullish` | + `NEXT_PUBLIC_…` `prefer-primary` | + `NEXT_PUBLIC_…` `fallback-if-set` | `CLERK_FRONTEND_API_URL` |
+| documentation env | `WEB_APP_URL` | `WEB_APP_URL` | + `SITE_URL` `prefer-primary` | + `SITE_URL` `fallback-if-set` | `WEB_APP_URL` |
+| health | `/health` | none | `/health` | `/mcp/health`, with CORS | `/health`, `{status, service}` |
+| SDK version locked | 1.29.0 | 1.30.0 | 1.30.0 | 1.32.1 | none |
+
+The exact configs are in `tests/mcp/fixtures/apps/<app>.kit.ts` and `docs/migrated/<app>/`.
+
+## Security model
+
+The kit does not do authentication, authorisation or data access.
+
+- `authenticate` is the app's. Clerk verification, app-b's Pro claim, app-d's legacy HS256 tokens, app-e's API keys and scopes, and user creation all stay in the app.
+- Per-user scoping stays in the app: app-b `userScope.ts`/`scoping.ts`/`owned.ts`/`queries.ts`, app-c `scoping.ts`/`owned.ts`/`queries.ts`, app-d `scope.ts`/`owned.ts`/`queries.ts`, app-a `memoryScope.ts`.
+- The explorer `execute` and `runQuery` callbacks MUST enforce per-user scoping. The kit passes the principal through as an opaque value and has no bypass option. It only narrows input: an unknown table or malformed field name never reaches the callback.
+- `run_query` code is never evaluated by the kit.
+- A missing bearer token is rejected before `authenticate` runs. A thrown `authenticate` is not swallowed unless you opt in.
+
+## Compatibility
+
+**HTTP layer: byte-for-byte compatible with each app today.** `tests/mcp/appParity.test.ts` runs each app's current `native.ts` (ported verbatim under `tests/mcp/fixtures/apps/*.reference.ts`) and the kit config side by side over 14 request scenarios, 5 env combinations and both upstream outcomes. Status, every header, body bytes, `console.error` calls and the arguments sent to `handleMcpRequest` must be equal. One addition: with `cors` set, the `/mcp` handler also answers `OPTIONS`; the apps route `OPTIONS` to a separate handler, which gives the same response.
+
+**`runSdkMcpRequest`: byte-for-byte compatible.** Run with each app's real SDK build (1.29.0, 1.30.0, 1.32.1), it returned exactly the captured responses for all 14 or 15 exchanges per app. This was a one-off check: the SDK is not a dev dependency. `tests/mcp/sdk.test.ts` covers the same behaviour with a fake transport.
+
+**Pure dispatcher: protocol-equivalent, not byte-identical.** Compared with `tests/mcp/fixtures/sdk/*.sdk.json`, captured from each app's SDK by `scripts/capture-sdk-fixtures.mjs`:
+
+| Exchange | Same bytes? |
+| --- | --- |
+| initialize (supported, latest, unsupported version), notifications/initialized (202, empty), ping, tools/call ok, handler throw, unknown tool, resources/list and unknown methods (-32601), batches, parse error | yes |
+| invalid arguments | yes against SDK 1.30+; SDK 1.29.0 (app-a) dumps raw zod issues instead |
+| tools/list | names, descriptions and annotations yes; the SDK adds `execution: {taskSupport: "forbidden"}`; schemas are equal with zod 4 and depend on the converter with zod 3 |
+| invalid JSON-RPC message | no: the kit answers 400 -32600 "Invalid Request" (JSON-RPC spec); the SDK answers 400 -32700 "Parse error: Invalid JSON-RPC message" |
+
+Not implemented in the dispatcher: resources, prompts, completions, `logging/setLevel`, tasks, elicitation, sampling and output-schema validation. app-a registers resources and an MCP app, so app-a keeps the SDK.
+
+## Develop
+
+```sh
+pnpm --filter @vvedantb/server build
+pnpm --filter @vvedantb/server test
+pnpm --filter @vvedantb/server typecheck
+```
+
+Tests and typecheck read `@vvedantb/server/convex` and `@vvedantb/server/mcp` from source (`vitest.config.ts` alias, `tsconfig.test.json` paths), so they run without building first. `zod` (4) and `zod3` (`npm:zod@^3.25.76`) are dev dependencies so both zod majors are tested.
+
+To recapture SDK fixtures from an installed SDK (read-only):
+
+```sh
+node scripts/capture-sdk-fixtures.mjs <path>/node_modules/@modelcontextprotocol/sdk app-d-mcp 1.2.0 no tests/mcp/fixtures/sdk/app-d.sdk.json
+```
+
+## Publish
+
+Publish steps for the whole package are in the root `README.md`.

package/docs/migration.md

@@ -0,0 +1,163 @@
+# Migrating the apps to `@vvedantb/server/mcp`
+
+Read-only sources: `/workspace/cvx/<app>/packages/backend` at origin/main on 12 October 2026 (app-a `8c972b1a`, app-b `f7b61259`, app-c `4d0ab45`, app-d `3bdce79`, app-e `7077eaf`). All paths below are relative to `packages/backend` in each app.
+
+There are two phases per app. Ship them as separate PRs.
+
+- **Phase 1, HTTP layer and SDK runner.** Replace `convex/mcp/native.ts` with kit factories, shorten `handleMcpRequest` with `runSdkMcpRequest`, and use the kit's result helpers. The MCP SDK stays. Responses are byte-identical: `tests/mcp/appParity.test.ts` checks every route, and the SDK runner was checked against each app's real SDK build.
+- **Phase 2, explorer tools on the pure dispatcher.** Replace `list_tables`, `query_table`, `count_table`, `get_document` and `run_query` with `createExplorerTools`. Kit tools are not SDK `server.tool` registrations, so the whole server must move to `defineTool` + `createMcpDispatcher` (one server answers `tools/list`). After that the SDK and, for MCP, `"use node"` can go. Protocol-equivalent, not byte-identical (see the README compatibility table and the behaviour changes below).
+
+Add the dependency in each app's `packages/backend/package.json` (after `@vvedantb/server` is published):
+
+```json
+"@vvedantb/server": "^0.1.0"
+```
+
+`http.ts` route tables do not change in any app: the exported names stay the same.
+
+## app-a
+
+Phase 1 only. app-a registers resources (`resources.ts`) and an MCP app (`memoryGraphApp.ts`), which the dispatcher does not support, so the SDK stays and there are no explorer tools.
+
+1. Replace `convex/mcp/native.ts` with [migrated/app-a/native.ts](migrated/app-a/native.ts). Delete `requestOrigin`, `createProtectedResourceMetadataAction`, `unauthorized`, `runMcpEndpoint` and the inline handlers. The two scopes are two `createMcpHttpHandler` instances with `scope` and the team `resourceMetadataPath`.
+2. In `convex/mcp/nodeActions.ts`, replace `handleMcpRequest` (lines 56-116) with [migrated/app-a/nodeActions.handleMcpRequest.ts](migrated/app-a/nodeActions.handleMcpRequest.ts). The `url` option keeps `http://localhost/mcp/team` for the team scope.
+3. Keep: `verifyAccessToken` (Clerk `authenticateRequest`, `isMcpAcceptedTokenType`), `serverInfo.ts`, `memoryScope.ts`, `tools.ts`/`toolTypes.ts`/`toolCatalog.ts`/`content.ts` (their `errorLabel` formatting and image content are app-a-specific; `bindToolSpec` stays on the SDK), resources and the graph app.
+
+Checklist:
+
+- [ ] 401 `{"error":"Missing Authorization header"}` / `{"error":"Invalid or expired token"}`, `Content-Type: application/json`, `WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource"` (team: `.../oauth-protected-resource/mcp/team`). No CORS headers.
+- [ ] 405 `{"error":"Method not supported in stateless mode"}` for GET/DELETE after auth; 400 `{"error":"Invalid JSON body"}`.
+- [ ] Logs: "[MCP][mcpHandler] token verification failed", "[MCP][mcpHandler] failed to parse JSON body:", "[MCP][handleMcpRequest] threw:" (all kit defaults).
+- [ ] Body forwarded re-encoded (`JSON.stringify(await request.json())`); `scope` passed to `handleMcpRequest`.
+- [ ] Metadata: `resource` `<origin>/mcp` and `<origin>/mcp/team`; `CLERK_FRONTEND_API_URL`, `WEB_APP_URL` (no fallbacks); AS metadata re-encoded JSON; 502 body unchanged.
+- [ ] `serverInfo` `app-a-mcp` / `app-a-mcp-team` `2.0.0`; protocol strings from SDK 1.29.0 (unchanged).
+- [ ] Routes unchanged: `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, `/.well-known/oauth-protected-resource/mcp/team`, `/mcp` and `/mcp/team` (POST/GET/DELETE), `/health`.
+- [ ] Run: `convex/mcp/serverInfo.test.ts`, `tests/mcp/*.test.ts` (toolCatalog, toolPaths, memoryTools, skillResources, contextPack, extreme, retrieveQuality), and `tests/mcp/live.integration.test.ts` against a dev deployment.
+
+## app-b
+
+1. Replace `convex/mcp/native.ts` with [migrated/app-b/native.ts](migrated/app-b/native.ts): `cors = mcpCors({...})` with app-b's two overrides, the `nullish` Clerk fallback, `forward: "stream"`, `log: false`, `createOptionsHandler` for `mcpOptions`. Delete `clerkFrontendApiUrl`, `requestOrigin`, `MCP_CORS_OVERRIDES`, `corsHeaders`, `unauthorized`, `runMcpEndpoint`.
+2. In `convex/mcp/nodeActions.ts`, replace `handleMcpRequest` (lines 201-261) with [migrated/app-b/nodeActions.handleMcpRequest.ts](migrated/app-b/nodeActions.handleMcpRequest.ts).
+3. In `convex/mcp/toolShared.ts`, replace `TextContent`, `textContent`, `errorResult`, `textResult` (lines 5-22) with [migrated/app-b/toolShared.resultHelpers.ts](migrated/app-b/toolShared.resultHelpers.ts) (re-export, plus an import for `runMcpTool`). `runMcpTool` stays: it wraps primitives in `{ result }`, which `runTool` does not.
+4. Phase 2: replace the five explorer registrations in `convex/mcp/tools.ts` (lines 32-169) with [migrated/app-b/tools.explorer.ts](migrated/app-b/tools.explorer.ts), and move the other tools to `defineTool` + `createMcpDispatcher`.
+5. Keep: `verifyAccessToken` with `claimsFromJwt` + `claimsIndicatePro` (the Pro claim), `runTestQuery`/`runTestQueryRemote`/deploy key lookup, `userScope.ts`, `scoping.ts`, `owned.ts`, `queries.ts`, `catalog.ts`, all product tools, `MCP_SERVER_VERSION`.
+
+Checklist:
+
+- [ ] Every MCP response carries `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Methods: GET,POST,DELETE,OPTIONS`, `Access-Control-Allow-Headers: Content-Type, Authorization, MCP-Protocol-Version`, `Access-Control-Allow-Credentials: false`, `Access-Control-Max-Age: 86400`; OPTIONS `/mcp` 204 with only those.
+- [ ] 401/405/400 messages and `WWW-Authenticate` as app-a personal; no `console.error` on auth or JSON failure.
+- [ ] `isPro` and `clerkUserId` passed to `handleMcpRequest`; body re-encoded.
+- [ ] AS metadata streamed (`res.body`) as `application/json` with CORS; 502 with CORS.
+- [ ] `CLERK_FRONTEND_API_URL ?? NEXT_PUBLIC_CLERK_FRONTEND_API_URL` (an empty primary does not fall back); `WEB_APP_URL` with no fallback.
+- [ ] Routes unchanged, including `/.well-known/oauth-protected-resource/mcp`; app-b has no health route.
+- [ ] `serverInfo` `app-b-mcp` `1.15.0`; SDK 1.30.0 protocol strings.
+- [ ] Phase 2 behaviour changes: `limit` above 1000 is clamped (was a validation error) and below 1 becomes 1; property descriptions are the kit's; tools gain `readOnlyHint`; `tools/list` has no `execution` field. Messages kept via config: `Cannot query table "<t>". Use list_tables.`, `Cannot count table "<t>".`, `Invalid document ID format.`.
+- [ ] Run: `convex/mcp/tools.test.ts` (in phase 2, list names from `createToolRegistry(...).names()` instead of an SDK client).
+
+## app-c
+
+1. Replace `convex/mcp/native.ts` with [migrated/app-c/native.ts](migrated/app-c/native.ts): `prefer-primary` fallbacks for the Clerk URL and `WEB_APP_URL`→`SITE_URL`, `forward: "text"`, and a log hook that keeps only `auth-failed`.
+2. In `convex/mcp/nodeActions.ts`, replace `handleMcpRequest` (lines 324-383) with [migrated/app-c/nodeActions.handleMcpRequest.ts](migrated/app-c/nodeActions.handleMcpRequest.ts).
+3. In `convex/mcp/tools.ts`, replace `textResult`/`errorResult` (lines 12-23) with the import in [migrated/app-c/tools.resultHelpers.ts](migrated/app-c/tools.resultHelpers.ts).
+4. Phase 2: replace the explorer registrations (lines 55-195) with [migrated/app-c/tools.explorer.ts](migrated/app-c/tools.explorer.ts). `tables: isTableAllowed` keeps the deny-list; `resolveUserId` is the existing `getContext` lookup.
+5. Keep: `verifyAccessToken`, `runTestQuery`, `listTables` (remote shapes + `FALLBACK_TABLES`), deploy-key bootstrap, `scoping.ts`, `owned.ts`, `queries.ts`, every product tool.
+
+Checklist:
+
+- [ ] No CORS headers anywhere. 401/405/400 as app-a personal. Logs "[MCP][mcpHandler] token verification failed" only (no JSON-parse log).
+- [ ] AS metadata forwarded as text; 502 unchanged.
+- [ ] Env: `process.env.CLERK_FRONTEND_API_URL ? it : NEXT_PUBLIC_CLERK_FRONTEND_API_URL`; with neither set the error names `NEXT_PUBLIC_CLERK_FRONTEND_API_URL`. Same rule for `WEB_APP_URL`/`SITE_URL`.
+- [ ] Routes unchanged: two well-known routes, `/mcp` (POST/GET/DELETE), `/health`.
+- [ ] `serverInfo` `app-c-mcp` `1.2.4`; SDK 1.30.0 protocol strings.
+- [ ] Phase 2: `limit` clamped to 1..1000; `Access denied: table "<t>" is not available via MCP.` unchanged (kit default); invalid id message unchanged (kit default).
+- [ ] Run: `convex/mcp/tools.test.ts` (its regex counts `server.tool("...")` registrations, so update it in phase 2), `convex/mcpProduct.test.ts`, `convex/mcpWrites.test.ts`, `convex/mcp/content.test.ts`, `convex/mcp/date.test.ts`.
+
+## app-d
+
+1. Replace `convex/mcp/native.ts` with [migrated/app-d/native.ts](migrated/app-d/native.ts). It keeps `legacyRefreshToken`, `readTokenBody` and `refreshBodySchema` unchanged; `json()` becomes a 3-line `Response.json(data, { status, headers: cors })` (same headers as `jsonWithCors` + extras); `getClerkFrontendApiUrl()` becomes `readEnvUrl(clerk)`.
+2. In `convex/mcp/nodeActions.ts`, replace `handleMcpRequest` (lines 224-277) with [migrated/app-d/nodeActions.handleMcpRequest.ts](migrated/app-d/nodeActions.handleMcpRequest.ts) (`parsedBody: false`, as app-d does not pass it today).
+3. Replace `convex/mcp/toolResult.ts` with the re-export in [migrated/app-d/toolResult.ts](migrated/app-d/toolResult.ts). `runTool` matches `jsonTool` exactly, including "Result is not JSON" and "Tool failed".
+4. Phase 2: replace the explorer schemas and registrations in `convex/mcp/tools.ts` (lines 12-43 and 103-238) with [migrated/app-d/tools.explorer.ts](migrated/app-d/tools.explorer.ts). The `run_query` snapshot and sandbox code moves into the `runQuery` callback unchanged.
+5. Keep: `verifyAccessToken` (legacy HS256 path with `MCP_JWT_SECRET`, then Clerk, then `ensureUser`), `refreshToken`, `scope.ts`, `owned.ts`, `queries.ts`, `sandbox.ts`, `validators.ts`, product tools, `whoami`.
+
+Checklist:
+
+- [ ] Every MCP response, including `/mcp/health` and the refresh endpoint, carries `Access-Control-Allow-Origin: *`, `Access-Control-Allow-Methods: GET,POST,DELETE,OPTIONS`, `Access-Control-Allow-Headers: Authorization, Content-Type, Accept, MCP-Protocol-Version, MCP-Session-Id`, `Access-Control-Allow-Credentials: false`, `Access-Control-Expose-Headers: WWW-Authenticate, MCP-Session-Id`. OPTIONS `/mcp` and `/mcp/oauth/token`: 204.
+- [ ] Raw request text forwarded after `JSON.parse` validation; no logs on auth or JSON failure.
+- [ ] AS metadata as text with CORS; served on `/.well-known/oauth-authorization-server` and `/.well-known/oauth-authorization-server/mcp`.
+- [ ] Env: `!env[name] && !!env[fallback] ? fallback : name` for the Clerk URL and `WEB_APP_URL`/`SITE_URL`.
+- [ ] Refresh endpoint: `invalid_request` / `unsupported_grant_type` / `invalid_grant` bodies unchanged.
+- [ ] `serverInfo` `app-d-mcp` `1.2.0`; SDK 1.32.1 protocol strings.
+- [ ] Phase 2 behaviour changes: an unknown table becomes an `isError` result (same JSON text `{"error":"Table \"<t>\" is not queryable"}`; it was a non-error text result); `get_document` now rejects ids outside `^[a-zA-Z0-9_]+$` (it returned null); filter field names must be identifiers in the table's `fields` or `_id`/`_creationTime` (unknown fields matched nothing before); `limit` default 50, max `MAX_QUERY_LIMIT` (200), as `clampLimit`.
+- [ ] Run: `tests/mcpOauth.test.ts` (discovery, bearer auth, legacy tokens, refresh), `tests/mcpProduct.test.ts`, `tests/mcpWrites.test.ts`, `tests/scope.test.ts`, `tests/sandbox.test.ts`.
+
+## app-e (partial)
+
+app-e's `/mcp` handler stays: it checks methods before auth, reads the body with a 1 MiB limit (413), authenticates API keys and Clerk JWTs inside the node action, maps 401/429 results to `WWW-Authenticate`/`Retry-After`, and answers 202 without a `Content-Type`. The gateway (`gateway.ts`, `protocol.ts`, `proxy.ts`, `oauth.ts`, `clerkAuth.ts`, `clerkJwt.ts`) stays. app-e already took `extractBearerToken` and `requiredEnvUrl` from `@vvedantb/server/convex` in `7077eaf`.
+
+1. In `convex/mcp/native.ts`, replace `optionsHandler`, `oauthMetadata`, `protectedResourceMetadata` and `health` with [migrated/app-e/native.partial.ts](migrated/app-e/native.partial.ts). `corsHeaders(request)` stays and is passed as the `cors` function. `assertOutboundUrl` moves into the proxy's `fetch` hook. It checks protocol, credentials, host and port, which the full metadata URL shares with the issuer base URL.
+2. Optional: `negotiateProtocolVersion(requested, { versions: SUPPORTED_PROTOCOL_VERSIONS, fallback: PROTOCOL_VERSION })` can replace the 6-line function in `protocol.ts`. It is not counted below.
+3. Run: `tests/e2e.test.ts`, `tests/mcpApiKeys.test.ts`, `tests/gateway.test.ts`, `tests/hardening.test.ts`, `tests/limits.test.ts`, `tests/keyAccess.test.ts`, `tests/envelope.test.ts`, `tests/twoUsers.test.ts`.
+
+## Measured lines removed
+
+Reproduce with `node packages/server/docs/count-loc.mjs /workspace/cvx`.
+
+How counted:
+
+- Physical lines, blank and comment lines included (`wc -l`). A file without a final newline counts its last line.
+- "removable" is the whole file or the listed blocks in the app today. Blocks run from a start pattern to the line where brackets balance again, plus the comment lines directly above.
+- "remains" is the replacement in `docs/migrated/<app>/`: real code using the kit's real exports and each app's real names, written out in full. It includes moved strings (the `run_query` descriptions and app-d's blocked-table list) and the new import lines.
+- Not counted:
+  - imports that become unused, such as `extractBearerToken` in nodeActions (a few more lines saved);
+  - phase 2 rewiring of the other tools from `server.tool(name, desc, shape, fn)` to `defineTool({ ... })`, which is roughly line-neutral;
+  - `tests/` changes in the apps;
+  - `http.ts` (unchanged).
+
+| app | phase | file | LOC now | removable | remains (wiring) | net |
+| --- | --- | --- | ---: | ---: | ---: | ---: |
+| app-a | 1 | `convex/mcp/native.ts` | 122 | 122 | 38 | -84 |
+| app-a | 1 | `convex/mcp/nodeActions.ts` | 116 | 61 | 19 | -42 |
+| app-b | 1 | `convex/mcp/native.ts` | 141 | 141 | 44 | -97 |
+| app-b | 1 | `convex/mcp/nodeActions.ts` | 261 | 61 | 18 | -43 |
+| app-b | 1 | `convex/mcp/toolShared.ts` | 61 | 15 | 2 | -13 |
+| app-b | 2 | `convex/mcp/tools.ts` | 170 | 134 | 54 | -80 |
+| app-c | 1 | `convex/mcp/native.ts` | 107 | 107 | 43 | -64 |
+| app-c | 1 | `convex/mcp/nodeActions.ts` | 383 | 60 | 18 | -42 |
+| app-c | 1 | `convex/mcp/tools.ts` | 430 | 11 | 1 | -10 |
+| app-c | 2 | `convex/mcp/tools.ts` | 430 | 137 | 46 | -91 |
+| app-d | 1 | `convex/mcp/native.ts` | 186 | 186 | 116 | -70 |
+| app-d | 1 | `convex/mcp/nodeActions.ts` | 277 | 54 | 17 | -37 |
+| app-d | 1 | `convex/mcp/toolResult.ts` | 23 | 23 | 5 | -18 |
+| app-d | 2 | `convex/mcp/tools.ts` | 241 | 160 | 68 | -92 |
+| app-e | 1 | `convex/mcp/native.ts` | 183 | 41 | 21 | -20 |
+
+| app | phase 1 net | phase 2 net | total net |
+| --- | ---: | ---: | ---: |
+| app-a | -126 | 0 | -126 |
+| app-b | -153 | -80 | -233 |
+| app-c | -116 | -91 | -207 |
+| app-d | -125 | -92 | -217 |
+| app-e | -20 | 0 | -20 |
+| **all** | **-540** | **-263** | **-803** |
+
+Removed ranges (line numbers in the app file today):
+- app-a convex/mcp/native.ts: whole file 1-122
+- app-a convex/mcp/nodeActions.ts: handleMcpRequest 56-116
+- app-b convex/mcp/native.ts: whole file 1-141
+- app-b convex/mcp/nodeActions.ts: handleMcpRequest 201-261
+- app-b convex/mcp/toolShared.ts: TextContent 5-5; textContent 7-9; errorResult 11-16; textResult 18-22
+- app-b convex/mcp/tools.ts: tool list_tables 32-43; tool query_table 45-86; tool get_document 88-108; tool count_table 110-130; tool run_query 132-169
+- app-c convex/mcp/native.ts: whole file 1-107
+- app-c convex/mcp/nodeActions.ts: handleMcpRequest 324-383
+- app-c convex/mcp/tools.ts: textResult 12-16; errorResult 18-23
+- app-c convex/mcp/tools.ts: tool list_tables 55-66; tool query_table 68-108; tool get_document 110-133; tool run_query 135-168; tool count_table 170-195
+- app-d convex/mcp/native.ts: whole file 1-186
+- app-d convex/mcp/nodeActions.ts: handleMcpRequest 224-277
+- app-d convex/mcp/toolResult.ts: whole file 1-23
+- app-d convex/mcp/tools.ts: filterValueSchema 12-17; queryTableSchema 19-26; countTableSchema 28-33; getDocumentSchema 35-37; runQuerySchema 39-43; tool list_tables 103-129; tool query_table 131-153; tool count_table 155-175; tool get_document 177-194; tool run_query 196-238
+- app-e convex/mcp/native.ts: optionsHandler 22-24; oauthMetadata 26-45; protectedResourceMetadata 47-58; health 105-110
+
+### Package cost
+
+`packages/server/src/mcp` is 1,565 physical lines, 1,153 without blank and comment lines. Most of it is JSDoc, explorer validation that the apps did not have, and the pure dispatcher. That is more than the R4 estimate of about 500, so across all repos the line count goes up: -803 in the apps against +1,565 in the package. The gain is one tested copy instead of four drifting ones, not fewer lines overall. On phase 1 alone the apps lose 540 lines. If phase 2 is not adopted, the explorer (408 lines) and dispatcher (151 lines) could be dropped from the package.

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@vvedantb/server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Shared Convex backend helpers and MCP server scaffolding: query-limit errors, Clerk auth config, bearer tokens, env, CORS, a bearer-auth MCP HTTP handler, OAuth metadata, a JSON-RPC dispatcher and explorer tools.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vvedantb/packages.git",
+    "directory": "packages/server"
+  },
+  "exports": {
+    "./convex": {
+      "types": "./dist/convex/index.d.ts",
+      "import": "./dist/convex/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp/index.d.ts",
+      "import": "./dist/mcp/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs/convex.md",
+    "docs/mcp.md",
+    "docs/migration.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@clerk/backend": ">=1",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@clerk/backend": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0",
+    "zod": "^4.0.0",
+    "zod3": "npm:zod@^3.25.76"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
 }