@ganintegrity/mcp 1.0.0 → 1.1.1

package/README.md

@@ -2,8 +2,6 @@
 
 A small library for mounting a [Model Context Protocol](https://modelcontextprotocol.io) server onto an Express app inside a Gan Integrity service. It owns the MCP plumbing — Streamable-HTTP transport wiring, per-request scoping, tool-result envelopes — and **inverts the dependencies** that vary per service: auth, logging, postgan construction, and the application's own error types are all injected by the caller.
 
-If you've worked on a `src/mcp/scaffold/` folder before, this is the library extraction of that pattern.
-
 ---
 
 ## Why this library exists
@@ -26,15 +24,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 +69,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 +92,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 +288,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:
+
+```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.
 
-The auth middleware that `createMcpServer` mounts internally. Exported in case you need to compose it differently.
+### `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 +328,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 +353,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.
 
 ---
 
@@ -254,7 +376,7 @@ declare global {
 }
 ```
 
-This ships in `dist/index.d.ts` — once you import anything from `@ganintegrity/mcp`, both fields are available on `Request` throughout your project. The library does **not** declare `req.user` or `req.postgan` — those remain your service's concern (typically in your existing `types/express.d.ts`).
+This ships in `dist/express/index.d.ts` — once you import anything from `@ganintegrity/mcp/express`, both fields are available on `Request` throughout your project. The framework-neutral root entry (`@ganintegrity/mcp`) has no Express side-effects, so services that don't run Express won't see Express types in their globals. The library does **not** declare `req.user` or `req.postgan` — those remain your service's concern (typically in your existing `types/express.d.ts`).
 
 ### The `AuthUser` contract
 
@@ -316,13 +438,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 +455,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,37 +463,20 @@ 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.
 
 ---
 
-## Development
-
-```bash
-pnpm install     # install deps
-pnpm build       # tsc → dist/
-pnpm typecheck   # tsc --noEmit
-pnpm test        # vitest run
-pnpm lint        # eslint src/**/*.ts
-pnpm format      # prettier --write
-```
-
-The repo uses:
-
-- **TypeScript 6** with NodeNext module resolution and `rewriteRelativeImportExtensions` (so source can import `./foo.ts` and emit `./foo.js`).
-- **ESLint 10 flat config** + `typescript-eslint`.
-- **Vitest 4** for tests.
-- **Semantic-release** for publishing.
-- **Commitlint** with conventional-commits.
-
-### A note on `pnpm.peerDependencyRules`
+## Contributing
 
-`package.json` sets `pnpm.peerDependencyRules.allowedVersions` for several `@ganintegrity/*` packages and an `ignoreMissing` list for optional peers (`pg-native`, `tedious`, etc.). These suppress warnings caused by transitive packages declaring older peer ranges than the resolved versions. The suppression is intentional — the version skew is known and tolerated within the gan ecosystem. If a real peer mismatch appears in a future install, it'll stand out instead of being lost in noise.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development loop, the
+public-API contract (api-extractor + checked-in `.api.md` reports), how to
+ship a breaking change, and commit conventions.

package/dist/{als.d.ts → core/als.d.ts}

@@ -4,17 +4,24 @@ import type { Logger } from "pino";
 import type { AuthUser } from "./auth/auth.types.ts";
 import type { McpErrorMapper } from "./errors/errors.types.ts";
 /**
- * Internal per-request bundle. Exported only for advanced consumers who
- * write their own tool wrappers and need to read the active scope directly;
- * regular tool handlers receive `ToolContext` instead.
+ * Per-request bundle held inside the library's `AsyncLocalStorage`. Exported
+ * only for advanced consumers who write their own tool wrappers and need to
+ * read the active scope directly; regular tool handlers receive `ToolContext`
+ * instead.
+ *
+ * @public
  */
 export interface RequestStore {
+    /** Authenticated user resolved from the bearer token. */
     user: AuthUser;
+    /** Per-request Postgan instance, attached upstream by `setupPostgan`. */
     postgan: Postgan;
+    /** `X-Session-Id` header value, if the client supplied one. */
     sessionId?: string;
+    /** Logger childed with `component: "mcp"` plus per-request scope. */
     logger: Logger;
     /**
-     * Translate thrown errors into MCP envelopes. Set by `createMcpServer`
+     * Translate thrown errors into MCP envelopes. Set by `defineMcpServer`
      * from its `errorMapper` option; tool wrappers use it before falling
      * through to the redacted `INTERNAL_ERROR` envelope.
      */

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;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,IAAI,EAAE,QAAQ,CAAC;IACf,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,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;AAgCrD,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,iBAAiB,EAAgB,CAAC"}

package/dist/{auth → core/auth}/auth.types.d.ts

@@ -5,13 +5,19 @@ import type { Logger } from "pino";
  * richer service-specific user type. Inside tool handlers, `ctx.user` is
  * typed as `AuthUser`; cast to your service's richer type when you need
  * extra fields.
+ *
+ * @public
  */
 export interface AuthUser {
+    /** Stable identifier for the authenticated user. */
     id: string;
+    /** Tenant key — the user's company subdomain, used for downstream scoping. */
     companySubdomainName: string;
 }
 /**
  * Configuration for `mcpAuth`.
+ *
+ * @public
  */
 export interface McpAuthOptions {
     /**

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;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;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,34 @@
+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.
+ */
+type HeaderBag = Record<string, string | string[] | undefined>;
+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>;
+export {};
+//# 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,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAE/D,KAAK,UAAU,GACX;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"}