@ganintegrity/mcp 1.0.0

package/README.md

@@ -0,0 +1,375 @@
+# @ganintegrity/mcp
+
+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
+
+The MCP TypeScript SDK gives you a `McpServer` and a `StreamableHTTPServerTransport`, but several things sit awkwardly between the SDK and a real Express service:
+
+1. **The transport is single-use.** `StreamableHTTPServerTransport` (in stateless mode) cannot be reused across requests. So you can't just instantiate one `McpServer` at boot and forward requests to it — you need a fresh server+transport per HTTP call, with the same tools registered on each one.
+
+2. **Tool handlers need request-scoped state.** A tool needs the authenticated user, a database client (postgan), the request's session id, and a correlation logger — none of which the MCP SDK knows about. Threading these through every tool call is noisy; AsyncLocalStorage is the natural fit.
+
+3. **Tool calls want database transactions.** Each tool should run inside its own transaction so that a failure rolls back automatically. This is boilerplate every consumer would write the same way.
+
+4. **Errors need to become MCP envelopes.** When a tool throws, the agent on the other end should see a structured `CallToolResult` with `code`/`message`/`details`, not a stack trace. The library handles the envelope; your service supplies a small `errorMapper` callback that translates whatever it throws into a shape the library can emit.
+
+This library packages (1)–(4) and asks the caller to plug in the parts that genuinely differ between services.
+
+---
+
+## Concepts
+
+A two-minute mental model before you read the API:
+
+### The recording shim
+
+`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.
+
+You register tools once at boot time. 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.
+
+### Per-tool transactions
+
+When a tool fires, the helper opens a `Postgan.Transaction`, runs your handler, and commits on success or rolls back on throw. Your handler just calls `ctx.transaction.query(...)` (or `ctx.postgan.something.do(...)`) and never has to think about commit/rollback.
+
+### Error envelopes
+
+When a handler throws, the library passes the throwable to your `errorMapper`. If the mapper returns an `McpToolError` shape, the library produces a `CallToolResult` with that `code`/`message`/`details`, logging at info (`severity: "warn"`) or error (`severity: "error"`). If the mapper returns `null` — or if you didn't supply one — the library emits a generic `INTERNAL_ERROR` envelope with a redacted message and logs the original throwable at error level.
+
+---
+
+## Installation
+
+```bash
+pnpm add @ganintegrity/mcp
+```
+
+Peer dependencies (must exist in your service):
+
+| Peer                                | Range |
+| ----------------------------------- | ----- |
+| `@ganintegrity/postgan`             | `^28` |
+| `@ganintegrity/postgres-migrations` | `^16` |
+| `express`                           | `^5`  |
+| `pino`                              | `^10` |
+| `zod`                               | `^4`  |
+
+The library does not bundle any of these — your service is expected to already have them.
+
+---
+
+## Quick start
+
+```ts
+// src/mcp/bootstrap.ts
+import express from "express";
+import { createMcpServer, tool, type McpErrorMapper } from "@ganintegrity/mcp";
+import { z } from "zod";
+
+import { logger } from "../logger.ts";
+import { AppError } from "../errors.ts";
+import { decipherToken } from "../middleware/verify.js";
+import identity from "../middleware/identity/identitymodel.js";
+import setupPostgan from "../middleware/setupPostgan.js";
+
+const errorMapper: McpErrorMapper = (err) => {
+  if (err instanceof AppError) {
+    return {
+      code: err.code,
+      message: err.message,
+      severity: err.statusCode >= 500 ? "error" : "warn",
+      details: err.details,
+      cause: err.cause,
+    };
+  }
+  return null;
+};
+
+const { server, mount } = createMcpServer({
+  name: "tprm-mcp",
+  version: "1.0.0",
+  logger,
+  setupPostgan: setupPostgan(),
+  tokenToUser: async (token) => {
+    const decoded = await decipherToken(token);
+    return identity.construct({ ...decoded, id: decoded._id });
+  },
+  errorMapper,
+});
+
+// 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 };
+  },
+});
+
+// Mount onto an Express router.
+const router = express.Router();
+await mount(router);
+app.use("/mcp", router);
+```
+
+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.
+
+---
+
+## API reference
+
+### `createMcpServer(options)`
+
+Builds an MCP server and returns a `{ server, mount }` pair.
+
+**Options:**
+
+| 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. |
+
+**Returns:**
+
+| 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.                               |
+
+### `tool(server, spec)`
+
+Register a tool. The handler runs inside an ALS scope with a fresh postgan transaction.
+
+```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 */
+    };
+  },
+});
+```
+
+**`ToolContext`** (the second handler argument):
+
+| Field         | Type                                                       |
+| ------------- | ---------------------------------------------------------- |
+| `user`        | `AuthUser` (cast to your richer type as needed)            |
+| `postgan`     | `Postgan`                                                  |
+| `transaction` | `PostganTransaction` (auto-committed/rolled-back)          |
+| `sessionId`   | `string \| undefined`                                      |
+| `logger`      | `pino.Logger` (already child'd with tool name + sessionId) |
+
+**Annotations** are MCP spec hints surfaced during `tools/list`:
+
+| Field             | Meaning                              |
+| ----------------- | ------------------------------------ |
+| `title`           | Human-readable title                 |
+| `readOnlyHint`    | Tool only reads, never writes        |
+| `destructiveHint` | Tool may delete or destroy data      |
+| `idempotentHint`  | Calling twice with same args is safe |
+| `openWorldHint`   | Tool reaches out to external systems |
+
+### `mcpAuth(options)`
+
+The auth middleware that `createMcpServer` mounts internally. Exported in case you need to compose it differently.
+
+```ts
+mcpAuth({
+  tokenToUser: async (token) => {
+    /* ... */
+  },
+  logger: pinoLogger,
+});
+```
+
+Sets `req.user`, `req.headers.company`, `req.auth` (SDK-shaped `AuthInfo`), and optionally `req.mcpSessionId` (from `X-Session-Id` header).
+
+### Errors
+
+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.
+
+```ts
+import {
+  INTERNAL_ERROR,
+  toCallToolError,
+  type McpErrorMapper,
+  type McpToolError,
+} from "@ganintegrity/mcp";
+```
+
+- **`McpToolError`** — the shape an envelope is built from:
+  ```ts
+  interface McpToolError {
+    code: string; // surfaced to the agent
+    message: string; // surfaced to the agent
+    severity: "warn" | "error"; // drives log level
+    details?: Record<string, unknown>; // surfaced to the agent
+    cause?: unknown; // logged at error level only, never surfaced
+  }
+  ```
+- **`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.
+
+The `tool()` helper invokes the mapper and `toCallToolError` automatically when a handler throws — you typically don't call them directly.
+
+---
+
+## Integration notes
+
+### Express type augmentation
+
+The library augments `Express.Request` with two fields:
+
+```ts
+declare global {
+  namespace Express {
+    interface Request {
+      mcpSessionId?: string;
+      auth?: AuthInfo; // from @modelcontextprotocol/sdk
+    }
+  }
+}
+```
+
+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`).
+
+### The `AuthUser` contract
+
+`AuthUser` is the minimal shape the library reads:
+
+```ts
+interface AuthUser {
+  id: string;
+  companySubdomainName: string;
+}
+```
+
+Your `tokenToUser` returns an object that satisfies this — typically your service's richer user type (`RequestUser` etc.) which already has both fields. Inside tool handlers, `ctx.user` is typed as `AuthUser`; cast to your richer type when you need extra fields:
+
+```ts
+handler: async (args, ctx) => {
+  const user = ctx.user as Express.Request["user"];
+  return { firstName: user.firstName };
+};
+```
+
+### Postgan middleware contract
+
+`setupPostgan` is invoked after auth, so `req.user` is populated. Your middleware should read whatever it needs (typically `userToken`, `postgresId`, `postgresCompanyId`) off `req.user`, build a `Postgan`, and assign it to both `req.postgan` and `res.locals.postgan`. The library reads it back from `req.postgan`.
+
+If `req.postgan` is missing when a request lands at `POST /`, the library responds with `401 Unauthenticated` — auth + setupPostgan are presumed to have run upstream.
+
+### Bridging your error type
+
+Your service keeps its own `AppError` (or whatever throwable it already uses). The library only sees the bridge you supply via `errorMapper`. Typical shape:
+
+```ts
+import type { McpErrorMapper } from "@ganintegrity/mcp";
+import { AppError } from "../errors.ts";
+
+export const errorMapper: McpErrorMapper = (err) => {
+  if (err instanceof AppError) {
+    return {
+      code: err.code,
+      message: err.message,
+      severity: err.statusCode >= 500 ? "error" : "warn",
+      details: err.details,
+      cause: err.cause,
+    };
+  }
+  // Anything not recognised → null → redacted INTERNAL_ERROR envelope.
+  return null;
+};
+```
+
+Mapping rules to keep in mind:
+
+- **`severity`** drives log level (`"warn"` → info log, `"error"` → error log) **and** is your call. Pick `"warn"` for failures the agent can react to (not found, validation, forbidden); `"error"` for anything you'd want a human to look at.
+- **`message` and `details` are surfaced to the agent.** Don't put internals (DB error text, stack traces, internal IDs) here. Sanitise upstream if you need to.
+- **`cause` is logged but never surfaced.** Use it to attach the original error for debugging without leaking it to the agent.
+- **Returning `null`** triggers the redacted fallback: `INTERNAL_ERROR` code, generic "An unexpected error occurred." message, original error logged at error level. Use this for anything you don't want the agent to see verbatim.
+
+---
+
+## Architecture deep dive
+
+### Why a recording shim?
+
+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.
+
+### Why AsyncLocalStorage instead of passing context?
+
+Tools could receive the `Request`/`Response` directly, and pull `user`/`postgan`/etc. off them. But that:
+
+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.
+
+### Why per-tool transactions?
+
+A single MCP request can dispatch multiple tool calls. Wrapping the entire request in one transaction means a late-call failure rolls back work the agent already saw as successful. Wrapping each tool call in its own transaction gives the agent committed, observable side effects after each call — matching the "tool" mental model.
+
+The cost is more transaction begin/commits, which on a healthy postgres is negligible.
+
+### Why is `tool()` separate from the `McpServer` returned by `createMcpServer`?
+
+`tool()` is a thin wrapper 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.
+
+---
+
+## 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`
+
+`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.

package/dist/als.d.ts

@@ -0,0 +1,24 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Postgan } from "@ganintegrity/postgan";
+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.
+ */
+export interface RequestStore {
+    user: AuthUser;
+    postgan: Postgan;
+    sessionId?: string;
+    logger: Logger;
+    /**
+     * Translate thrown errors into MCP envelopes. Set by `createMcpServer`
+     * from its `errorMapper` option; tool wrappers use it before falling
+     * through to the redacted `INTERNAL_ERROR` envelope.
+     */
+    errorMapper?: McpErrorMapper;
+}
+export declare const requestStore: AsyncLocalStorage<RequestStore>;
+//# sourceMappingURL=als.d.ts.map

package/dist/als.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"als.d.ts","sourceRoot":"","sources":["../src/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/als.js

@@ -0,0 +1,3 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const requestStore = new AsyncLocalStorage();
+//# sourceMappingURL=als.js.map

package/dist/als.js.map

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

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

@@ -0,0 +1,29 @@
+import type { Logger } from "pino";
+/**
+ * Minimal user shape the library reads off authenticated requests. The
+ * caller's `tokenToUser` returns a value that satisfies this — typically a
+ * 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.
+ */
+export interface AuthUser {
+    id: string;
+    companySubdomainName: string;
+}
+/**
+ * Configuration for `mcpAuth`.
+ */
+export interface McpAuthOptions {
+    /**
+     * Resolve a bearer / X-Access-Token to a user. The library is intentionally
+     * neutral about how tokens are verified — plug in whatever cipher / JWT /
+     * identity pipeline your service already uses.
+     *
+     * Reject by throwing; the middleware catches the throw, logs it at `warn`,
+     * and responds `401`.
+     */
+    tokenToUser: (token: string) => Promise<AuthUser>;
+    /** Logger used for the "token rejected" warning on auth failure. */
+    logger: Logger;
+}
+//# sourceMappingURL=auth.types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.types.d.ts","sourceRoot":"","sources":["../../src/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/auth.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth.types.js.map

package/dist/auth/auth.types.js.map

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

package/dist/auth/index.d.ts

@@ -0,0 +1,29 @@
+import type { RequestHandler } from "express";
+import type { McpAuthOptions } from "./auth.types.ts";
+/**
+ * Bearer-token auth middleware for the MCP HTTP endpoint.
+ *
+ * Token sources, in order: `Authorization: Bearer <token>`, then
+ * `X-Access-Token`. If neither is present the middleware responds `401` and
+ * does not call `next`.
+ *
+ * On success it sets:
+ * - `req.user` — the resolved {@link AuthUser}
+ * - `req.headers.company` — `user.companySubdomainName` (for downstream
+ *   middleware that keys off the company header)
+ * - `req.auth` — SDK-shaped `AuthInfo`, surfaced to MCP tool handlers as
+ *   `RequestHandlerExtra.authInfo`
+ * - `req.mcpSessionId` — value of the `X-Session-Id` header if present, used
+ *   for log correlation
+ *
+ * Then calls `next()`.
+ *
+ * **Never throws.** All failures (missing token, `tokenToUser` rejection)
+ * are turned into `401` responses; the middleware does not call `next(err)`.
+ *
+ * Mounted automatically by `createMcpServer`'s `mount()`. Exported in case
+ * you want to compose it differently (e.g. mount under a different router,
+ * or stack additional middleware).
+ */
+export declare function mcpAuth(options: McpAuthOptions): RequestHandler;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,KAAK,EAAY,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAmChE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAwB/D"}

package/dist/auth/index.js

@@ -0,0 +1,74 @@
+const BEARER_PREFIX = /^Bearer\s+/i;
+function extractBearer(req) {
+    const auth = req.headers["authorization"];
+    if (typeof auth === "string" && BEARER_PREFIX.test(auth)) {
+        return auth.replace(BEARER_PREFIX, "").trim();
+    }
+    // Parity fallback: REST accepts X-Access-Token. Same middleware shape.
+    const xat = req.headers["x-access-token"];
+    if (typeof xat === "string" && xat && xat !== "null" && xat !== "undefined") {
+        return xat;
+    }
+    return undefined;
+}
+function applyAuthToRequest(req, user, token) {
+    req.user = user;
+    req.headers.company = user.companySubdomainName;
+    req.auth = {
+        token,
+        clientId: user.id,
+        scopes: [],
+        extra: { user },
+    };
+    const sessionId = req.headers["x-session-id"];
+    if (typeof sessionId === "string" && sessionId.length > 0) {
+        req.mcpSessionId = sessionId;
+    }
+}
+/**
+ * Bearer-token auth middleware for the MCP HTTP endpoint.
+ *
+ * Token sources, in order: `Authorization: Bearer <token>`, then
+ * `X-Access-Token`. If neither is present the middleware responds `401` and
+ * does not call `next`.
+ *
+ * On success it sets:
+ * - `req.user` — the resolved {@link AuthUser}
+ * - `req.headers.company` — `user.companySubdomainName` (for downstream
+ *   middleware that keys off the company header)
+ * - `req.auth` — SDK-shaped `AuthInfo`, surfaced to MCP tool handlers as
+ *   `RequestHandlerExtra.authInfo`
+ * - `req.mcpSessionId` — value of the `X-Session-Id` header if present, used
+ *   for log correlation
+ *
+ * Then calls `next()`.
+ *
+ * **Never throws.** All failures (missing token, `tokenToUser` rejection)
+ * are turned into `401` responses; the middleware does not call `next(err)`.
+ *
+ * Mounted automatically by `createMcpServer`'s `mount()`. Exported in case
+ * you want to compose it differently (e.g. mount under a different router,
+ * or stack additional middleware).
+ */
+export function mcpAuth(options) {
+    return async (req, res, next) => {
+        const token = extractBearer(req);
+        if (!token) {
+            res
+                .status(401)
+                .json({ error: "Missing or invalid Authorization header" });
+            return;
+        }
+        try {
+            const user = await options.tokenToUser(token);
+            applyAuthToRequest(req, user, token);
+            next();
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : "invalid token";
+            options.logger.warn({ err }, "mcp auth: token rejected");
+            res.status(401).json({ error: `Authentication failed: ${reason}` });
+        }
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAGA,MAAM,aAAa,GAAG,aAAa,CAAC;AAEpC,SAAS,aAAa,CAAC,GAAY;IACjC,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,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,uEAAuE;IACvE,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;QAC5E,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAID,SAAS,kBAAkB,CAAC,GAAY,EAAE,IAAc,EAAE,KAAa;IACpE,GAAmB,CAAC,IAAI,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,oBAAoB,CAAC;IAChD,GAAG,CAAC,IAAI,GAAG;QACT,KAAK;QACL,QAAQ,EAAE,IAAI,CAAC,EAAE;QACjB,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,EAAE,IAAI,EAAE;KAChB,CAAC;IAEF,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,YAAY,GAAG,SAAS,CAAC;IAC/B,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,OAAO,CAAC,OAAuB;IAC7C,OAAO,KAAK,EACV,GAAY,EACZ,GAAa,EACb,IAAkB,EACH,EAAE;QACjB,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,GAAG;iBACA,MAAM,CAAC,GAAG,CAAC;iBACX,IAAI,CAAC,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAC,CAAC;YAC9D,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;YAC9C,kBAAkB,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACrC,IAAI,EAAE,CAAC;QACT,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;YACpE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,0BAA0B,CAAC,CAAC;YACzD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,0BAA0B,MAAM,EAAE,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/errors/errors.types.d.ts

@@ -0,0 +1,34 @@
+import type { Logger } from "pino";
+export type McpToolErrorSeverity = "warn" | "error";
+/**
+ * Shape returned by an {@link McpErrorMapper} to describe how a thrown error
+ * should be surfaced as an MCP `CallToolResult` envelope.
+ *
+ * The library does not define an error *class* — consumers throw whatever
+ * type their service already uses, and the mapper translates it into this
+ * shape at the tool boundary.
+ */
+export interface McpToolError {
+    /** Stable machine-readable code surfaced to the agent. */
+    code: string;
+    /** Human-readable message surfaced to the agent. */
+    message: string;
+    /** Drives log level: `"warn"` → info log; `"error"` → error log. */
+    severity: McpToolErrorSeverity;
+    /** Optional structured details surfaced to the agent. */
+    details?: Record<string, unknown>;
+    /** Optional cause — logged at error level only, never surfaced to the agent. */
+    cause?: unknown;
+}
+/**
+ * Translate a thrown error into an {@link McpToolError} envelope, or
+ * return `null` to fall through to the generic `INTERNAL_ERROR` envelope
+ * with a redacted message.
+ */
+export type McpErrorMapper = (err: unknown) => McpToolError | null;
+export interface ToolErrorMeta {
+    tool: string;
+    sessionId?: string;
+    logger: Logger;
+}
+//# sourceMappingURL=errors.types.d.ts.map

package/dist/errors/errors.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.types.d.ts","sourceRoot":"","sources":["../../src/errors/errors.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,YAAY,GAAG,IAAI,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/errors/errors.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=errors.types.js.map

package/dist/errors/errors.types.js.map

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

package/dist/errors/index.d.ts

@@ -0,0 +1,27 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { McpToolError, ToolErrorMeta } from "./errors.types.ts";
+/**
+ * The only code the library itself emits — surfaced in the redacted
+ * envelope when a thrown error has no mapping. Consumer codes are theirs.
+ */
+export declare const INTERNAL_ERROR = "INTERNAL_ERROR";
+/**
+ * Build the MCP `CallToolResult` envelope for a thrown error. Called
+ * automatically by `tool()` after the consumer's {@link McpErrorMapper}
+ * has had a chance to translate the throwable. Exported for consumers
+ * writing their own tool wrappers.
+ *
+ * Behaviour:
+ * - `mapped` non-null with `severity: "warn"` → logged at info; envelope
+ *   carries the mapped `code`/`message`/`details`. The agent sees the
+ *   message so it can react.
+ * - `mapped` non-null with `severity: "error"` → logged at error (with
+ *   `cause`); envelope carries the mapped `code`/`message`/`details`.
+ * - `mapped` null → logged at error with the original throwable; envelope
+ *   is a generic `INTERNAL_ERROR` with a redacted message. The original
+ *   error message is **not** surfaced.
+ *
+ * Never throws (assumes `meta.logger` does not throw).
+ */
+export declare function toCallToolError(mapped: McpToolError | null, originalErr: unknown, meta: ToolErrorMeta): CallToolResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AA+D/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,YAAY,GAAG,IAAI,EAC3B,WAAW,EAAE,OAAO,EACpB,IAAI,EAAE,aAAa,GAClB,cAAc,CAMhB"}