@ganintegrity/mcp 1.0.0 → 1.1.0

package/README.md

@@ -26,15 +26,15 @@ This library packages (1)–(4) and asks the caller to plug in the parts that ge
 
 A two-minute mental model before you read the API:
 
-### The recording shim
+### Define-once, materialize-per-request
 
-`createMcpServer()` returns a `server` object that _looks_ like an `McpServer` but only implements `registerTool` — it records every registration in an in-memory list. On each HTTP request, `mount()` instantiates a brand-new `McpServer`, replays the recorded registrations onto it, hands it a fresh transport, and tears both down when the response finishes. This is how we satisfy the SDK's single-use transport contract without re-registering tools on every call site.
+`defineMcpServer({ tools })` runs your `tools(register)` callback once and captures each `register.tool(spec)` invocation onto an `McpDefinition`. On each HTTP request, the framework adapter calls `materializeSdkServer(mcp)` to build a fresh SDK `McpServer`, replays the captured registrations onto it, hands it a fresh transport, and tears both down when the response finishes. This is how we satisfy the SDK's single-use transport contract without re-registering tools on every call site.
 
-You register tools once at boot time. The library handles the per-request lifecycle.
+You write tool registrations once. The library handles the per-request lifecycle.
 
 ### The ALS scope
 
-Inside `mount()`, every tool dispatch runs inside an `AsyncLocalStorage.run(...)` scope holding a `RequestStore` (user, postgan, sessionId, logger). The `tool()` helper reads from this store to build a `ToolContext` for your handler. Your handler signature is `(args, ctx) => Promise<Output>` — no Express objects leak in, no DI container needed.
+Every tool dispatch runs inside an `AsyncLocalStorage.run(...)` scope holding a `RequestStore` (user, postgan, sessionId, logger). The wrapper that `register.tool()` builds reads from this store to assemble a `ToolContext` for your handler. Your handler signature is `(args, ctx) => Promise<Output>` — no Express objects leak in, no DI container needed.
 
 ### Per-tool transactions
 
@@ -71,7 +71,8 @@ The library does not bundle any of these — your service is expected to already
 ```ts
 // src/mcp/bootstrap.ts
 import express from "express";
-import { createMcpServer, tool, type McpErrorMapper } from "@ganintegrity/mcp";
+import { defineMcpServer, type McpErrorMapper } from "@ganintegrity/mcp";
+import { createMcpRouter } from "@ganintegrity/mcp/express";
 import { z } from "zod";
 
 import { logger } from "../logger.ts";
@@ -93,80 +94,178 @@ const errorMapper: McpErrorMapper = (err) => {
   return null;
 };
 
-const { server, mount } = createMcpServer({
+// Register tools at boot, inside the `tools` callback. The callback runs
+// once at define time; the registrations are replayed onto a fresh SDK
+// `McpServer` per HTTP request.
+const mcp = defineMcpServer({
   name: "tprm-mcp",
   version: "1.0.0",
+  errorMapper,
+  tools(register) {
+    register.tool({
+      name: "summarise_entity",
+      description: "Produce a short summary of an entity by uuid.",
+      inputSchema: z.object({ uuid: z.string().uuid() }),
+      handler: async ({ uuid }, ctx) => {
+        const entity = await ctx.postgan.entity.fetch({ uuid });
+        return { summary: entity.name, fetchedBy: ctx.user.id };
+      },
+    });
+  },
+});
+
+// Mount onto an Express app.
+const mcpRouter = createMcpRouter(mcp, {
   logger,
   setupPostgan: setupPostgan(),
   tokenToUser: async (token) => {
     const decoded = await decipherToken(token);
     return identity.construct({ ...decoded, id: decoded._id });
   },
+});
+app.use("/mcp", mcpRouter);
+```
+
+That's it. The MCP server is reachable at `POST /mcp/`, authenticates via `Authorization: Bearer <token>`, and executes tools inside a postgan transaction with full ALS context.
+
+---
+
+## Framework adapters
+
+The library is split into a framework-neutral core and per-framework adapters. Consumers import from a subpath that matches their HTTP framework.
+
+| Import                      | Status        | Use                                                                                                               |
+| --------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `@ganintegrity/mcp`         | Implemented   | Framework-neutral surface: `defineMcpServer`, `materializeSdkServer`, error envelope plumbing, every shared type. |
+| `@ganintegrity/mcp/express` | Implemented   | Express ^5 adapter: `createMcpRouter`, `mcpAuth`, `CreateMcpRouterOptions`.                                       |
+| `@ganintegrity/mcp/koa`     | Not yet built | Koa ^2 adapter; intended API documented below. Same names against Koa types.                                      |
+
+A bootstrap file imports from both — framework-neutral helpers from the root, the adapter factory from `/express`. A tool definition file imports from the root only; it stays adapter-agnostic.
+
+Importing from `/express` (or `/koa`, when implemented) loads the framework's ambient type augmentation (e.g. `Express.Request` gains `mcpSessionId` / `auth`). The root entry has no such side effects — services that don't run Express won't see Express types in their globals.
+
+The shared core lives under `src/core/` and contains:
+
+- **`defineMcpServer({ name, version, errorMapper, tools })`** — the public entry point. Captures tool registrations into an `McpDefinition` once at define time.
+- **`materializeSdkServer(mcp): McpServer`** — builds a fresh SDK `McpServer` and replays the captured registrations onto it. Adapters call this per HTTP request (the SDK's stateless transport is single-use). Exposed for tests + advanced consumers writing custom adapters.
+- **`resolveAuth(headers, options): AuthResult`** — extracts the bearer token + session id from a header bag, calls `tokenToUser`, returns a discriminated success/failure union.
+- **`dispatchMcpRequest(mcp, logger, scope, invokeTransport, onTransportError)`** — owns the per-request lifecycle: builds the `RequestStore`, materializes the SDK server, runs the framework-supplied transport invocation inside `requestStore.run(...)`, tears everything down on `finally`.
+- The error envelope plumbing (`toCallToolError`, `INTERNAL_ERROR`) and the postgan-transaction wrapper.
+
+Each adapter is a thin layer that bridges its native request/response shape to these neutral helpers.
+
+### Intended Koa API
+
+When the Koa adapter is built, it mirrors the Express one:
+
+```ts
+// src/mcp/bootstrap.ts
+import Koa from "koa";
+import Router from "@koa/router";
+import bodyParser from "@koa/bodyparser";
+
+import { defineMcpServer, type McpErrorMapper } from "@ganintegrity/mcp";
+import { createMcpRouter } from "@ganintegrity/mcp/koa";
+
+const mcp = defineMcpServer({
+  name: "tprm-mcp",
+  version: "1.0.0",
   errorMapper,
+  tools(register) {
+    register.tool({
+      /* identical to express — same ToolContext, same handler signature */
+    });
+  },
 });
 
-// Register tools at boot.
-tool(server, {
-  name: "summarise_entity",
-  description: "Produce a short summary of an entity by uuid.",
-  inputSchema: z.object({ uuid: z.string().uuid() }),
-  handler: async ({ uuid }, ctx) => {
-    const entity = await ctx.postgan.entity.fetch({ uuid });
-    return { summary: entity.name, fetchedBy: ctx.user.id };
+const mcpRouter = createMcpRouter(mcp, {
+  logger,
+  setupPostgan: setupPostganKoa(), // Koa.Middleware that sets ctx.state.postgan
+  tokenToUser: async (token) => {
+    /* same shape as express */
   },
 });
 
-// Mount onto an Express router.
-const router = express.Router();
-await mount(router);
-app.use("/mcp", router);
+const app = new Koa();
+app.use(bodyParser()); // caller-provided; the library does not bundle one
+app.use(mcpRouter.routes()).use(mcpRouter.allowedMethods());
 ```
 
-That's it. The MCP server is reachable at `POST /mcp/`, will authenticate via `Authorization: Bearer <token>` (or `X-Access-Token`), and will execute tools inside a postgan transaction with full ALS context.
+Differences from the Express adapter the implementation needs to handle:
+
+- **`setupPostgan: Koa.Middleware`** — sets `ctx.state.postgan` instead of `req.postgan`. The auth middleware sets `ctx.state.user` (and `ctx.state.mcpSessionId` if present).
+- **`mcpAuth(options): Koa.Middleware`** — parallel to the Express middleware. Same options shape (`tokenToUser`, `logger`); internally calls `resolveAuth(ctx.headers, options)` and either responds 401 (`ctx.status` / `ctx.body`) or writes onto `ctx.state` and calls `next()`.
+- **`createMcpRouter(mcp, options)`** — returns a fresh `@koa/router` Router with the JSON-RPC route attached; the consumer mounts it via `app.use(router.routes()).use(router.allowedMethods())`.
+- **Body parser is the consumer's responsibility.** Koa has no built-in JSON parser. The Express adapter mounts `express.json()` automatically; the Koa adapter expects the caller to mount `bodyParser()` (or equivalent) on the Koa app upstream of the MCP router.
+- **`handleMcpRequest`** — the dispatcher's `invokeTransport` callback becomes:
+  ```ts
+  (transport) => {
+    ctx.respond = false; // opt out of Koa's response handling
+    return transport.handleRequest(ctx.req, ctx.res, ctx.request.body);
+  };
+  ```
+  Koa's `ctx.req` / `ctx.res` are the underlying Node `IncomingMessage` / `ServerResponse`, which is what the MCP SDK transport expects.
+- **`onTransportError`** — `() => { if (!ctx.headerSent) { ctx.status = 500; ctx.body = { error: "Internal MCP transport error" }; } }`.
+- **No global type augmentation.** The Express adapter augments `Express.Request` with `mcpSessionId` / `auth`; Koa uses typed `ctx.state<T>`. The Koa adapter exports a `KoaState` interface consumers can compose with their own state typing.
+
+Tool handlers see the same `ToolContext` regardless of adapter — the framework-specific bits stop at the auth + dispatch boundary.
+
+### Planned Koa peer dependencies
+
+When the Koa adapter ships, these peers will be added (only required if you actually import the `/koa` subpath):
+
+| Peer          | Range | Why                                 |
+| ------------- | ----- | ----------------------------------- |
+| `koa`         | `^2`  | adapter is built against it.        |
+| `@koa/router` | `^13` | `createMcpRouter` returns a Router. |
+
+`@koa/bodyparser` is **not** a peer — the consumer chooses and mounts a body parser on their app.
 
 ---
 
 ## API reference
 
-### `createMcpServer(options)`
+> Each export below is annotated with the subpath it lives on — `@ganintegrity/mcp` (framework-neutral) or `@ganintegrity/mcp/express` (Express adapter). See [Framework adapters](#framework-adapters) for the full split.
 
-Builds an MCP server and returns a `{ server, mount }` pair.
+### `defineMcpServer(options)` — `@ganintegrity/mcp`
 
-**Options:**
+Captures an MCP server definition. The `tools` callback runs **once at define time**; the `register.tool(spec)` invocations inside it are recorded and replayed onto a fresh SDK `McpServer` per HTTP request.
 
-| Field          | Type                                   | Description                                                                                                                                                                                       |
-| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`         | `string`                               | MCP server name advertised to clients.                                                                                                                                                            |
-| `version`      | `string`                               | MCP server version advertised to clients.                                                                                                                                                         |
-| `logger`       | `pino.Logger`                          | Service logger. The library calls `logger.child({ component: "mcp" })` internally.                                                                                                                |
-| `tokenToUser`  | `(token: string) => Promise<AuthUser>` | Resolve a bearer token to a user. The library is neutral about how tokens are verified — plug in your service's existing JWT/cipher/identity pipeline.                                            |
-| `setupPostgan` | `RequestHandler`                       | Express middleware that attaches a `Postgan` instance to `req.postgan`. The library mounts this between auth and the JSON-RPC dispatcher.                                                         |
-| `errorMapper?` | `McpErrorMapper`                       | Translate a thrown error into an MCP envelope. Return `null` for the redacted `INTERNAL_ERROR` fallback. Without a mapper, every thrown error becomes `INTERNAL_ERROR` with the message redacted. |
+**Options:**
 
-**Returns:**
+| Field          | Type                               | Description                                                                                                                                                             |
+| -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`         | `string`                           | MCP server name advertised to clients.                                                                                                                                  |
+| `version`      | `string`                           | MCP server version advertised to clients.                                                                                                                               |
+| `tools`        | `(register: ToolRegister) => void` | Registration callback. Call `register.tool(spec)` once per tool. Anything beyond registration runs once at define time, not per request.                                |
+| `errorMapper?` | `McpErrorMapper`                   | Translate a thrown error into an MCP envelope. Return `null` for the redacted `INTERNAL_ERROR` fallback. Without a mapper, every thrown error becomes `INTERNAL_ERROR`. |
 
-| Field    | Type                                | Description                                                                                                        |
-| -------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `server` | `McpServer` (recording shim)        | Pass to `tool()` to register tools. Only `registerTool` is exposed; other `McpServer` methods are not implemented. |
-| `mount`  | `(target: Router) => Promise<void>` | Attaches the MCP route handlers to an Express router. Caller decides the mount path.                               |
+**Returns:** an opaque `McpDefinition` you hand to a per-framework adapter (`createMcpRouter`, etc.). Don't inspect or mutate it — adapters and `materializeSdkServer` are the only consumers.
 
-### `tool(server, spec)`
+### `register.tool(spec)` — `@ganintegrity/mcp`
 
-Register a tool. The handler runs inside an ALS scope with a fresh postgan transaction.
+The method on the `register` argument inside `defineMcpServer`'s `tools` callback. Wraps your handler with ALS scope, an auto-committed postgan transaction, and the error envelope pipeline before recording it onto the definition.
 
 ```ts
-tool(server, {
-  name: "tool_name",
-  description: "What this tool does",
-  inputSchema: z.object({
-    /* ... */
-  }),
-  annotations: { readOnlyHint: true }, // optional
-  handler: async (args, ctx) => {
-    // ctx.user, ctx.postgan, ctx.transaction, ctx.sessionId, ctx.logger
-    return {
-      /* plain object — surfaced as both text and structuredContent */
-    };
+const mcp = defineMcpServer({
+  name: "tprm-mcp",
+  version: "1.0.0",
+  errorMapper,
+  tools(register) {
+    register.tool({
+      name: "tool_name",
+      description: "What this tool does",
+      inputSchema: z.object({
+        /* ... */
+      }),
+      annotations: { readOnlyHint: true }, // optional
+      handler: async (args, ctx) => {
+        // ctx.user, ctx.postgan, ctx.transaction, ctx.sessionId, ctx.logger
+        return {
+          /* plain object — surfaced as both text and structuredContent */
+        };
+      },
+    });
   },
 });
 ```
@@ -191,9 +290,34 @@ tool(server, {
 | `idempotentHint`  | Calling twice with same args is safe |
 | `openWorldHint`   | Tool reaches out to external systems |
 
-### `mcpAuth(options)`
+### `createMcpRouter(mcp, options)` — `@ganintegrity/mcp/express`
+
+Build an Express `Router` that serves the supplied `McpDefinition`. Mount on whatever path the caller likes:
 
-The auth middleware that `createMcpServer` mounts internally. Exported in case you need to compose it differently.
+```ts
+const mcpRouter = createMcpRouter(mcp, {
+  logger,
+  setupPostgan: setupPostgan(),
+  tokenToUser: async (token) => {
+    /* ... */
+  },
+});
+app.use("/mcp", mcpRouter);
+```
+
+**Options:**
+
+| Field          | Type                                   | Description                                                                                                                            |
+| -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `logger`       | `pino.Logger`                          | Service logger. The library calls `logger.child({ component: "mcp" })` internally and further childs per request and per tool call.    |
+| `tokenToUser`  | `(token: string) => Promise<AuthUser>` | Resolve a bearer token to a user. Reject by throwing — the router responds 401.                                                        |
+| `setupPostgan` | `RequestHandler`                       | Express middleware that attaches a `Postgan` instance to `req.postgan`. The router mounts it between auth and the JSON-RPC dispatcher. |
+
+**Returns:** an `express.Router` with `express.json()` → `mcpAuth` → `setupPostgan` → JSON-RPC dispatch composed onto it. Each request runs through the chain once.
+
+### `mcpAuth(options)` — `@ganintegrity/mcp/express`
+
+The auth middleware that `createMcpRouter` mounts internally. Exported in case you need to compose it differently.
 
 ```ts
 mcpAuth({
@@ -206,7 +330,7 @@ mcpAuth({
 
 Sets `req.user`, `req.headers.company`, `req.auth` (SDK-shaped `AuthInfo`), and optionally `req.mcpSessionId` (from `X-Session-Id` header).
 
-### Errors
+### Errors — `@ganintegrity/mcp`
 
 The library deliberately does **not** define an error class. Your service throws whatever it already throws (an `AppError`, a `ZodError`, anything), and you supply an `McpErrorMapper` callback to translate those throwables into MCP envelopes at the tool boundary.
 
@@ -231,9 +355,9 @@ import {
   ```
 - **`McpErrorMapper`** — `(err: unknown) => McpToolError | null`. Return `null` to fall through to a redacted `INTERNAL_ERROR` envelope (the original message is **not** leaked to the agent).
 - **`INTERNAL_ERROR`** — string constant, the only code the library itself emits.
-- **`toCallToolError(mapped, originalErr, meta)`** — used internally by `tool()`. Exported in case you build your own tool wrappers.
+- **`toCallToolError(mapped, originalErr, meta)`** — used internally by `register.tool()`. Exported in case you build your own tool wrappers.
 
-The `tool()` helper invokes the mapper and `toCallToolError` automatically when a handler throws — you typically don't call them directly.
+The `register.tool()` wrapper invokes the mapper and `toCallToolError` automatically when a handler throws — you typically don't call them directly.
 
 ---
 
@@ -316,13 +440,15 @@ Mapping rules to keep in mind:
 
 ## Architecture deep dive
 
-### Why a recording shim?
+### Why `defineMcpServer` + `materializeSdkServer` instead of `new McpServer()`?
 
 The natural shape would be: `const server = new McpServer(...); server.registerTool(...); app.post("/mcp", (req, res) => transport.handleRequest(req, res, req.body))`. This breaks because `StreamableHTTPServerTransport` in stateless mode is single-use — once it has handled one request, it cannot be reused. The MCP SDK enforces this internally.
 
 The fix is to instantiate a transport per request. But then the `McpServer` would also need to be per-request (the SDK couples the two via `connect()`), which means re-registering every tool on every request.
 
-The recording shim solves this: tools are registered once into a list, and `mount()` replays the list onto a fresh `McpServer` per request. The replay is cheap — `registerTool` just stores function references, and the McpServer constructor is similarly lightweight. End-to-end latency is dominated by the actual tool work.
+The library splits the two concerns: `defineMcpServer` captures registrations once into an `McpDefinition`; `materializeSdkServer(mcp)` builds a fresh SDK server with the same tools per request. The replay is cheap — `registerTool` just stores function references, and the `McpServer` constructor is similarly lightweight. End-to-end latency is dominated by the actual tool work.
+
+The earlier shape used a "recording shim" — a fake `McpServer` whose only working method was `registerTool`. That dishonesty (it looked like an `McpServer`, but `.close()` and friends would have failed) is what `defineMcpServer` replaces.
 
 ### Why AsyncLocalStorage instead of passing context?
 
@@ -331,7 +457,7 @@ Tools could receive the `Request`/`Response` directly, and pull `user`/`postgan`
 1. Couples every tool to Express. If the MCP server ever needs to be invoked over a different transport (a worker, a CLI, a test), every tool breaks.
 2. Forces every helper called by a tool to also receive the context, polluting helper signatures throughout the service.
 
-ALS lets tool helpers reach context anywhere down the call stack without parameter threading, while keeping the tool-handler signature `(args, ctx)` clean and transport-agnostic. The `requestStore.run(...)` boundary in `mount()` is the only place ALS knows about Express.
+ALS lets tool helpers reach context anywhere down the call stack without parameter threading, while keeping the tool-handler signature `(args, ctx)` clean and transport-agnostic. The `requestStore.run(...)` boundary in `dispatchMcpRequest` is the only place ALS knows about Express.
 
 ### Why per-tool transactions?
 
@@ -339,15 +465,15 @@ A single MCP request can dispatch multiple tool calls. Wrapping the entire reque
 
 The cost is more transaction begin/commits, which on a healthy postgres is negligible.
 
-### Why is `tool()` separate from the `McpServer` returned by `createMcpServer`?
+### Why `register.tool(spec)` instead of `server.registerTool(...)`?
 
-`tool()` is a thin wrapper that:
+`register.tool(spec)` is a thin wrapper around the SDK's `registerTool` that:
 
 1. Reads the ALS store to build a `ToolContext`.
 2. Opens a transaction, runs your handler, commits or rolls back.
 3. Maps thrown errors to `CallToolResult` envelopes.
 
-You could call `server.registerTool(...)` directly and skip all of this — useful if you want raw access to the SDK's request/response shape. But you'd lose ALS, transactions, and the error mapping. `tool()` is what makes the rest of the library useful; `server.registerTool` is the escape hatch.
+You could call `materializeSdkServer(mcp).registerTool(...)` directly and skip all of this — useful if you want raw access to the SDK's request/response shape. But you'd lose ALS, transactions, and the error mapping. `register.tool()` is what makes the rest of the library useful; the SDK API is the escape hatch.
 
 ---
 

package/dist/core/als.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"als.d.ts","sourceRoot":"","sources":["../../src/core/als.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,eAAO,MAAM,YAAY,iCAAwC,CAAC"}

package/dist/core/als.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"als.js","sourceRoot":"","sources":["../../src/core/als.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAyBrD,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,iBAAiB,EAAgB,CAAC"}

package/dist/core/auth/auth.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/auth.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClD,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/{auth → core/auth}/auth.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.types.js","sourceRoot":"","sources":["../../src/auth/auth.types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"auth.types.js","sourceRoot":"","sources":["../../../src/core/auth/auth.types.ts"],"names":[],"mappings":""}

package/dist/core/auth/index.d.ts

@@ -0,0 +1,33 @@
+import type { AuthUser, McpAuthOptions } from "./auth.types.ts";
+/**
+ * Framework-neutral header bag. Both Express's `req.headers` and Koa's
+ * `ctx.headers` satisfy this shape — Node lowercases the keys at the HTTP
+ * layer, so `"authorization"` and `"x-session-id"` reads work for either.
+ */
+export type HeaderBag = Record<string, string | string[] | undefined>;
+export type AuthResult = {
+    ok: true;
+    user: AuthUser;
+    token: string;
+    sessionId?: string;
+} | {
+    ok: false;
+    status: 401;
+    message: string;
+};
+/**
+ * Resolve a request's auth from its headers. Reads `Authorization: Bearer
+ * <token>` and (optionally) `X-Session-Id`, then calls `tokenToUser` to
+ * resolve the token to an {@link AuthUser}.
+ *
+ * Returns a discriminated union — never throws. Per-framework adapters
+ * translate the result into a 401 response or a request-augmenting `next()`.
+ *
+ * - Missing/invalid Authorization header → `{ ok: false, status: 401,
+ *   message: "Missing or invalid Authorization header" }`.
+ * - `tokenToUser` throws → `{ ok: false, status: 401, message:
+ *   "Authentication failed: <reason>" }`. The throwable is logged at `warn`
+ *   on `options.logger` before the result is returned.
+ */
+export declare function resolveAuth(headers: HeaderBag, options: McpAuthOptions): Promise<AuthResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAIhE;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAEtE,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBhD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,UAAU,CAAC,CA0BrB"}

package/dist/core/auth/index.js

@@ -0,0 +1,57 @@
+const BEARER_PREFIX = /^Bearer\s+/i;
+function extractBearer(headers) {
+    const auth = headers["authorization"];
+    if (typeof auth === "string" && BEARER_PREFIX.test(auth)) {
+        return auth.replace(BEARER_PREFIX, "").trim();
+    }
+    return undefined;
+}
+function extractSessionId(headers) {
+    const sessionId = headers["x-session-id"];
+    return typeof sessionId === "string" && sessionId.length > 0
+        ? sessionId
+        : undefined;
+}
+/**
+ * Resolve a request's auth from its headers. Reads `Authorization: Bearer
+ * <token>` and (optionally) `X-Session-Id`, then calls `tokenToUser` to
+ * resolve the token to an {@link AuthUser}.
+ *
+ * Returns a discriminated union — never throws. Per-framework adapters
+ * translate the result into a 401 response or a request-augmenting `next()`.
+ *
+ * - Missing/invalid Authorization header → `{ ok: false, status: 401,
+ *   message: "Missing or invalid Authorization header" }`.
+ * - `tokenToUser` throws → `{ ok: false, status: 401, message:
+ *   "Authentication failed: <reason>" }`. The throwable is logged at `warn`
+ *   on `options.logger` before the result is returned.
+ */
+export async function resolveAuth(headers, options) {
+    const token = extractBearer(headers);
+    if (!token) {
+        return {
+            ok: false,
+            status: 401,
+            message: "Missing or invalid Authorization header",
+        };
+    }
+    try {
+        const user = await options.tokenToUser(token);
+        return {
+            ok: true,
+            user,
+            token,
+            sessionId: extractSessionId(headers),
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : "invalid token";
+        options.logger.warn({ err }, "mcp auth: token rejected");
+        return {
+            ok: false,
+            status: 401,
+            message: `Authentication failed: ${reason}`,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/core/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/auth/index.ts"],"names":[],"mappings":"AAEA,MAAM,aAAa,GAAG,aAAa,CAAC;AAapC,SAAS,aAAa,CAAC,OAAkB;IACvC,MAAM,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACtC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAChD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAkB;IAC1C,MAAM,SAAS,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1C,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC;QAC1D,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAkB,EAClB,OAAuB;IAEvB,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,yCAAyC;SACnD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAC9C,OAAO;YACL,EAAE,EAAE,IAAI;YACR,IAAI;YACJ,KAAK;YACL,SAAS,EAAE,gBAAgB,CAAC,OAAO,CAAC;SACrC,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACpE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,0BAA0B,CAAC,CAAC;QACzD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,0BAA0B,MAAM,EAAE;SAC5C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/core/define.d.ts

@@ -0,0 +1,64 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpErrorMapper } from "./errors/errors.types.ts";
+import type { ToolRegister, ToolRegistration } from "./tool/tool.types.ts";
+/**
+ * Options for {@link defineMcpServer}.
+ */
+export interface DefineMcpServerOptions {
+    /** MCP server name advertised to clients during initialisation. */
+    name: string;
+    /** MCP server version advertised to clients during initialisation. */
+    version: string;
+    /**
+     * Registration callback. Called **once at define time** with a
+     * `register` object whose `tool(spec)` method captures each tool into
+     * an internal array. Adapters replay the array onto a fresh `McpServer`
+     * per HTTP request.
+     *
+     * Don't put expensive setup in here — it's intended only for
+     * `register.tool(...)` calls.
+     */
+    tools: (register: ToolRegister) => void;
+    /**
+     * Translate a thrown error into an MCP envelope. Return `null` to fall
+     * through to a redacted `INTERNAL_ERROR` envelope. Without a mapper,
+     * every thrown error becomes `INTERNAL_ERROR` with the message redacted.
+     */
+    errorMapper?: McpErrorMapper;
+}
+/**
+ * The serialisable shape adapters consume. Holds the captured tool
+ * registrations alongside the metadata needed to materialise an SDK server
+ * per request. Treat as opaque outside of adapters and tests.
+ */
+export interface McpDefinition {
+    readonly name: string;
+    readonly version: string;
+    readonly registrations: readonly ToolRegistration[];
+    readonly errorMapper?: McpErrorMapper;
+}
+/**
+ * Define an MCP server. Returns an {@link McpDefinition} that adapters
+ * (e.g. `@ganintegrity/mcp/express`'s `createMcpRouter`) materialise into
+ * a real SDK server per request.
+ *
+ * The `tools` callback runs once, here, at define time. The `register`
+ * argument captures each `register.tool(spec)` invocation; the wrapped
+ * handler bakes in ALS-reading, transaction lifecycle, and error mapping
+ * so per-request adapters can replay the registrations onto a fresh
+ * `McpServer` without any extra wiring.
+ */
+export declare function defineMcpServer(options: DefineMcpServerOptions): McpDefinition;
+/**
+ * Build a fresh SDK `McpServer` from an {@link McpDefinition} and replay
+ * every recorded tool registration onto it.
+ *
+ * Adapters call this once per HTTP request — the SDK's stateless
+ * Streamable-HTTP transport is single-use, which is why registrations
+ * are stored separately and replayed.
+ *
+ * Exposed for tests and advanced consumers writing custom adapters.
+ * Typical consumers don't call this directly.
+ */
+export declare function materializeSdkServer(mcp: McpDefinition): McpServer;
+//# sourceMappingURL=define.d.ts.map

package/dist/core/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/core/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG3E;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,KAAK,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,aAAa,CAcf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,CAiBlE"}

package/dist/core/define.js

@@ -0,0 +1,48 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { wrapToolHandler } from "./tool/index.js";
+/**
+ * Define an MCP server. Returns an {@link McpDefinition} that adapters
+ * (e.g. `@ganintegrity/mcp/express`'s `createMcpRouter`) materialise into
+ * a real SDK server per request.
+ *
+ * The `tools` callback runs once, here, at define time. The `register`
+ * argument captures each `register.tool(spec)` invocation; the wrapped
+ * handler bakes in ALS-reading, transaction lifecycle, and error mapping
+ * so per-request adapters can replay the registrations onto a fresh
+ * `McpServer` without any extra wiring.
+ */
+export function defineMcpServer(options) {
+    const registrations = [];
+    const register = {
+        tool: (spec) => {
+            registrations.push(wrapToolHandler(spec));
+        },
+    };
+    options.tools(register);
+    return {
+        name: options.name,
+        version: options.version,
+        registrations,
+        errorMapper: options.errorMapper,
+    };
+}
+/**
+ * Build a fresh SDK `McpServer` from an {@link McpDefinition} and replay
+ * every recorded tool registration onto it.
+ *
+ * Adapters call this once per HTTP request — the SDK's stateless
+ * Streamable-HTTP transport is single-use, which is why registrations
+ * are stored separately and replayed.
+ *
+ * Exposed for tests and advanced consumers writing custom adapters.
+ * Typical consumers don't call this directly.
+ */
+export function materializeSdkServer(mcp) {
+    const server = new McpServer({ name: mcp.name, version: mcp.version });
+    const register = server.registerTool.bind(server);
+    for (const reg of mcp.registrations) {
+        register(reg.name, reg.config, reg.handler);
+    }
+    return server;
+}
+//# sourceMappingURL=define.js.map

package/dist/core/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/core/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAwClD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA+B;IAE/B,MAAM,aAAa,GAAuB,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAiB;QAC7B,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;YACb,aAAa,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,aAAa;QACb,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAkB;IACrD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IASvE,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,CAAC,IAAI,CACvC,MAAM,CACsB,CAAC;IAC/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACpC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/dispatch.d.ts

@@ -0,0 +1,34 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { Postgan } from "@ganintegrity/postgan";
+import type { Logger } from "pino";
+import type { AuthUser } from "./auth/auth.types.ts";
+import { type McpDefinition } from "./define.ts";
+/**
+ * Per-request scope handed to {@link dispatchMcpRequest}. The framework
+ * adapter pulls these out of its native request shape (Express `req.user` /
+ * `req.postgan` / `req.mcpSessionId`; Koa `ctx.state.*`).
+ */
+export interface DispatchScope {
+    user: AuthUser;
+    postgan: Postgan;
+    sessionId?: string;
+}
+/**
+ * Framework-neutral per-request dispatcher.
+ *
+ * Builds the {@link RequestStore} from `scope` + `mcp.errorMapper`,
+ * materialises a fresh SDK `McpServer` (with all tools replayed onto it),
+ * connects a fresh transport, runs `invokeTransport` inside
+ * `requestStore.run(...)` so tool handlers can pull request context from
+ * ALS, and tears server + transport down in `finally`. A failing close is
+ * logged at warn but never re-thrown.
+ *
+ * If `invokeTransport` throws, the error is logged at error level and
+ * `onTransportError` is called so the framework adapter can write a 500
+ * onto its native response object (with whatever headers-sent guard it
+ * uses). The error is otherwise swallowed — this is the request boundary.
+ *
+ * Never throws.
+ */
+export declare function dispatchMcpRequest(mcp: McpDefinition, logger: Logger, scope: DispatchScope, invokeTransport: (transport: StreamableHTTPServerTransport) => Promise<void>, onTransportError: () => void): Promise<void>;
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/core/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","sourceRoot":"","sources":["../../src/core/dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AACnG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAGnC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEvE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,EAClB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,EACpB,eAAe,EAAE,CAAC,SAAS,EAAE,6BAA6B,KAAK,OAAO,CAAC,IAAI,CAAC,EAC5E,gBAAgB,EAAE,MAAM,IAAI,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmCf"}