@ttoss/http-server-mcp 0.12.4 → 0.13.0

package/README.md

@@ -127,6 +127,137 @@ const data = await apiCall('GET', 'https://partner.api.com/data', {
 
 `apiCall` throws with a clear message when called with a relative path and no `apiBaseUrl` is configured in the context.
 
+## Authentication
+
+`createMcpRouter` supports OAuth 2.0 Bearer token authentication via the `auth` option. Every incoming MCP request must include a valid `Authorization: Bearer <token>` header — invalid or missing tokens receive a `401 Unauthorized` response.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant MCP Server
+    participant Verifier
+
+    Client->>MCP Server: POST /mcp + Authorization: Bearer &lt;token&gt;
+    MCP Server->>Verifier: verify(token)
+    alt valid token
+        Verifier-->>MCP Server: identity payload
+        MCP Server->>MCP Server: run tool (identity available via getIdentity())
+        MCP Server-->>Client: 200 OK
+    else invalid or missing token
+        Verifier-->>MCP Server: error
+        MCP Server-->>Client: 401 Unauthorized
+    end
+```
+
+### Amazon Cognito
+
+Pass `cognitoUserPool` and the router creates a `CognitoJwtVerifier` (from `@ttoss/auth-core`) internally:
+
+```typescript
+import { createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
+
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: {
+      userPoolId: process.env.COGNITO_USER_POOL_ID!,
+      clientId: process.env.COGNITO_CLIENT_ID!,
+      tokenUse: 'access', // default
+    },
+  },
+});
+```
+
+### Custom verifier
+
+Pass an async `verifyToken` function for any other provider (Auth0, Keycloak, etc.):
+
+```typescript
+import { createMcpRouter } from '@ttoss/http-server-mcp';
+import { jwtVerify, createRemoteJWKSet } from 'jose';
+
+const JWKS = createRemoteJWKSet(
+  new URL('https://your-auth-server/.well-known/jwks.json')
+);
+
+const mcpRouter = createMcpRouter(mcpServer, {
+  auth: {
+    verifyToken: async (token) => {
+      const { payload } = await jwtVerify(token, JWKS);
+      return payload;
+    },
+  },
+});
+```
+
+### Accessing the verified identity
+
+Inside any tool handler, call `getIdentity()` to retrieve the verified JWT payload:
+
+```typescript
+import { getIdentity, createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
+
+mcpServer.registerTool(
+  'get-profile',
+  { description: 'Return the caller's profile', inputSchema: {} },
+  async () => {
+    const identity = getIdentity() as { sub: string; email: string };
+    return {
+      content: [{ type: 'text', text: `Hello, ${identity.email}` }],
+    };
+  }
+);
+```
+
+### Scope enforcement
+
+Scopes can be enforced at two levels.
+
+**Router-level** — gate the entire MCP endpoint. Any token missing a required scope receives a `403 Forbidden` before any tool runs:
+
+```typescript
+createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: { userPoolId: '...', clientId: '...' },
+    requiredScopes: ['mcp:access'],
+  },
+});
+```
+
+**Per-tool** — use `checkScopes()` inside individual handlers for fine-grained control. It throws an error that the MCP SDK returns as a tool error to the client:
+
+```typescript
+import { checkScopes, getIdentity } from '@ttoss/http-server-mcp';
+
+mcpServer.registerTool(
+  'delete-user',
+  { description: 'Delete a user', inputSchema: { userId: z.string() } },
+  async ({ userId }) => {
+    checkScopes(['admin', 'write:users']); // throws if either scope is missing
+
+    const identity = getIdentity() as { sub: string };
+    // proceed with deletion...
+    return { content: [{ type: 'text', text: `Deleted ${userId}` }] };
+  }
+);
+```
+
+Cognito encodes scopes as a space-separated string in `payload.scope` (e.g. `"openid mcp:access admin"`).
+
+### OAuth Protected Resource Metadata
+
+For MCP clients that support OAuth auto-discovery, add `resourceServerUrl` and `authorizationServerUrl` to expose the `/.well-known/oauth-protected-resource` endpoint (RFC 9728):
+
+```typescript
+createMcpRouter(mcpServer, {
+  auth: {
+    cognitoUserPool: { userPoolId: '...', clientId: '...' },
+    resourceServerUrl: 'https://mcp.example.com',
+    authorizationServerUrl:
+      'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_xxx',
+  },
+});
+```
+
 ## API Reference
 
 ### `createMcpRouter(server, options?)`
@@ -135,14 +266,19 @@ Creates a Koa router configured to handle MCP protocol requests.
 
 **Parameters:**
 
-- `server` (`McpServer`) - MCP server instance with registered tools and resources
-- `options` (`McpRouterOptions`) - Optional configuration
-  - `path` (`string`) - HTTP path for MCP endpoint (default: `'/mcp'`)
-  - `sessionIdGenerator` (`() => string`) - Session ID generator for stateful servers (default: `undefined` for stateless)
-  - `apiBaseUrl` (`string`) - Base URL prepended to relative paths in `apiCall`
-  - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) - Return headers to inject into every `apiCall` for this request (auth tokens, API keys, trace headers, etc.)
+- `server` (`McpServer`) — MCP server instance with registered tools and resources
+- `options` (`McpRouterOptions`) — Optional configuration
+  - `path` (`string`) — HTTP path for MCP endpoint (default: `'/mcp'`)
+  - `sessionIdGenerator` (`() => string`) — Session ID generator for stateful servers (default: `undefined` for stateless)
+  - `apiBaseUrl` (`string`) — Base URL prepended to relative paths in `apiCall`
+  - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) — Return headers to inject into every `apiCall` for this request
+  - `auth` (`McpAuthOptions`) — OAuth/JWT authentication; see [Authentication](#authentication)
+    - `auth.cognitoUserPool` — Cognito user pool config (`userPoolId`, `clientId`, `tokenUse`)
+    - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
+    - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
+    - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable `/.well-known/oauth-protected-resource`
 
-**Returns:** `Router` - Koa router instance
+**Returns:** `Router` — Koa router instance
 
 ### `apiCall(method, url, options?)`
 
@@ -150,12 +286,26 @@ Generic HTTP helper for use inside MCP tool handlers.
 
 **Parameters:**
 
-- `method` (`string`) - HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, …)
-- `url` (`string`) - Full URL **or** a path starting with `/` (prepended with `apiBaseUrl`)
-- `options.body` (`unknown`, optional) - Request body, serialised as JSON
-- `options.headers` (`Record<string, string>`, optional) - Per-call header overrides; merged on top of context-injected headers
+- `method` (`string`) — HTTP method (`'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, …)
+- `url` (`string`) — Full URL **or** a path starting with `/` (prepended with `apiBaseUrl`)
+- `options.body` (`unknown`, optional) — Request body, serialised as JSON
+- `options.headers` (`Record<string, string>`, optional) — Per-call header overrides; merged on top of context-injected headers
+
+**Returns:** `Promise<unknown>` — Parsed JSON response body
+
+### `getIdentity()`
+
+Returns the verified JWT payload for the current MCP request. Only available inside a tool handler when `auth` is configured. Returns `undefined` when called outside an authenticated context.
+
+**Returns:** `unknown` — Verified token payload (cast to your expected shape)
+
+### `checkScopes(required)`
+
+Asserts that the current request token contains all required scopes. Throws `Error: Insufficient scopes. Required: …` if any scope is missing — the MCP SDK catches this and returns a tool error to the client.
+
+**Parameters:**
 
-**Returns:** `Promise<unknown>` - Parsed JSON response body
+- `required` (`string[]`) — Scope strings that must all be present in `payload.scope`
 
 ### `registerToolFromSchema(server, params)`
 
@@ -165,11 +315,11 @@ Use this when tool definitions are shared between the MCP server and an AI SDK a
 
 **Parameters:**
 
-- `server` (`McpServer`) - The MCP server instance
-- `params.name` (`string`) - Unique tool name
-- `params.description` (`string`, optional) - Human-readable description
-- `params.inputSchema` (`JsonObjectSchema`, optional) - Plain JSON Schema object (defaults to `{ type: 'object', properties: {} }`)
-- `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) - Tool handler receiving the raw request arguments
+- `server` (`McpServer`) — The MCP server instance
+- `params.name` (`string`) — Unique tool name
+- `params.description` (`string`, optional) — Human-readable description
+- `params.inputSchema` (`JsonObjectSchema`, optional) — Plain JSON Schema object (defaults to `{ type: 'object', properties: {} }`)
+- `params.handler` (`(args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>`) — Tool handler receiving the raw request arguments
 
 **Returns:** `void`
 

package/dist/index.cjs

@@ -0,0 +1,401 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+Object.defineProperty(exports, Symbol.toStringTag, {
+  value: 'Module'
+});
+let node_async_hooks = require("node:async_hooks");
+let _modelcontextprotocol_sdk_server_streamableHttp_js = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+let _ttoss_auth_core_amazon_cognito = require("@ttoss/auth-core/amazon-cognito");
+let _ttoss_http_server = require("@ttoss/http-server");
+let zod = require("zod");
+let _modelcontextprotocol_sdk_server_mcp_js = require("@modelcontextprotocol/sdk/server/mcp.js");
+
+//#region src/index.ts
+const requestContextStore = new node_async_hooks.AsyncLocalStorage();
+/**
+* Generic HTTP helper for use inside MCP tool handlers.
+*
+* Accepts any full URL (third-party APIs, public APIs, etc.) or a path
+* relative to the `apiBaseUrl` configured in `createMcpRouter`.
+*
+* Headers configured via `getApiHeaders` in `createMcpRouter` are injected
+* automatically into every request, allowing transparent forwarding of auth
+* tokens, API keys, or any other header — without coupling this helper to a
+* specific authentication scheme. Per-call `options.headers` take precedence
+* over context-injected headers.
+*
+* @param method - HTTP method (e.g. `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`)
+* @param url - Full URL **or** a path starting with `/` (appended to `apiBaseUrl`)
+* @param options - Optional body and per-call header overrides
+* @returns Parsed JSON response body
+*
+* @example Bearer token forwarding (configured once in `createMcpRouter`)
+* ```typescript
+* import { apiCall, createMcpRouter, McpServer } from '@ttoss/http-server-mcp';
+*
+* // Tool handler – no manual auth wiring needed
+* mcpServer.registerTool('list-portfolios', { description: '...', inputSchema: {} }, async () => {
+*   const data = await apiCall('GET', '/portfolios');
+*   return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+* });
+*
+* const mcpRouter = createMcpRouter(mcpServer, {
+*   apiBaseUrl: `http://localhost:${process.env.PORT}/api/v1`,
+*   // Forward the caller's Bearer token to every apiCall
+*   getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' }),
+* });
+* ```
+*
+* @example x-api-key forwarding
+* ```typescript
+* const mcpRouter = createMcpRouter(mcpServer, {
+*   apiBaseUrl: 'https://internal-service/api',
+*   getApiHeaders: (ctx) => ({
+*     'x-api-key': ctx.headers['x-api-key'] as string,
+*   }),
+* });
+* ```
+*
+* @example Third-party or public API (full URL, no context required)
+* ```typescript
+* const weather = await apiCall('GET', 'https://api.weather.com/current?city=Berlin');
+* const created = await apiCall('POST', 'https://api.example.com/items', {
+*   body: { name: 'widget' },
+*   headers: { Authorization: 'Bearer fixed-service-token' },
+* });
+* ```
+*/
+const apiCall = async (method, url, options) => {
+  const context = requestContextStore.getStore();
+  let resolvedUrl = url;
+  if (url.startsWith("/")) {
+    if (!context?.apiBaseUrl) throw new Error(`apiCall received a relative path ("${url}") but no apiBaseUrl is configured. Either pass a full URL or set apiBaseUrl in createMcpRouter options.`);
+    resolvedUrl = `${context.apiBaseUrl.replace(/\/$/, "")}${url}`;
+  }
+  const hasBody = options?.body !== void 0;
+  const headers = {
+    ...(context !== void 0 ? context.apiHeaders : {}),
+    ...(options?.headers ?? {})
+  };
+  const hasExplicitContentType = Object.keys(headers).some(headerName => {
+    return headerName.toLowerCase() === "content-type";
+  });
+  if (hasBody && !hasExplicitContentType) headers["Content-Type"] = "application/json";
+  const response = await fetch(resolvedUrl, {
+    method,
+    headers,
+    body: hasBody ? JSON.stringify(options.body) : void 0
+  });
+  if (!response.ok) {
+    const err = await response.json().catch(() => {
+      return {
+        error: response.statusText
+      };
+    });
+    throw new Error(err.error || `HTTP ${response.status}`);
+  }
+  if (response.status === 204 || response.status === 205) return;
+  if (response.headers.get("content-type")?.includes("application/json")) return response.json();
+  return response.text();
+};
+/**
+* Returns the verified JWT payload for the current MCP request.
+* Only available inside a tool handler when `auth` is configured on the router.
+*/
+const getIdentity = () => {
+  return requestContextStore.getStore()?.identity;
+};
+/**
+* Asserts that the current request's token contains all required scopes.
+* Throws if any scope is missing — the MCP SDK catches this and returns a
+* tool error to the client. Use inside tool handlers for per-tool authorization.
+*
+* Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+*
+* @example
+* ```typescript
+* server.tool('delete-user', schema, async (args) => {
+*   checkScopes(['admin', 'write:users']);
+*   // proceed only if caller has both scopes
+* });
+* ```
+*/
+const checkScopes = required => {
+  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  if (required.filter(s => {
+    return !tokenScopes.includes(s);
+  }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
+};
+const buildTokenVerifier = auth => {
+  if (auth.cognitoUserPool) {
+    const v = _ttoss_auth_core_amazon_cognito.CognitoJwtVerifier.create({
+      tokenUse: "access",
+      ...auth.cognitoUserPool
+    });
+    return t => {
+      return v.verify(t);
+    };
+  }
+  if (auth.verifyToken) return auth.verifyToken;
+  throw new Error("McpAuthOptions requires either cognitoUserPool or verifyToken");
+};
+const registerAuthRoutes = (router, path, auth, tokenVerifier) => {
+  router.use(path, async (ctx, next) => {
+    const authHeader = ctx.headers.authorization;
+    const token = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : "";
+    let identity;
+    try {
+      identity = await tokenVerifier(token);
+    } catch {
+      ctx.status = 401;
+      ctx.set("WWW-Authenticate", "Bearer");
+      ctx.body = "Unauthorized";
+      return;
+    }
+    if (auth.requiredScopes?.length) {
+      const tokenScopes = (identity?.scope ?? "").split(" ");
+      if (auth.requiredScopes.filter(s => {
+        return !tokenScopes.includes(s);
+      }).length > 0) {
+        ctx.status = 403;
+        ctx.body = "Forbidden";
+        return;
+      }
+    }
+    ctx.state.identity = identity;
+    await next();
+  });
+  if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
+    ctx.body = {
+      resource: auth.resourceServerUrl,
+      authorization_servers: [auth.authorizationServerUrl]
+    };
+  });
+};
+/**
+* Creates a Koa router configured to handle MCP protocol requests
+*
+* @param server - The MCP server instance with registered tools and resources
+* @param options - Configuration options for the router
+* @returns A Koa Router instance configured for MCP
+*
+* @example
+* ```typescript
+* import { App, bodyParser } from '@ttoss/http-server';
+* import { createMcpRouter, McpServer, z } from '@ttoss/http-server-mcp';
+*
+* const mcpServer = new McpServer({
+*   name: 'my-server',
+*   version: '1.0.0',
+* });
+*
+* mcpServer.registerTool(
+*   'hello',
+*   {
+*     description: 'Say hello',
+*     inputSchema: { name: z.string() },
+*   },
+*   async ({ name }) => ({
+*     content: [{ type: 'text', text: `Hello, ${name}!` }],
+*   })
+* );
+*
+* const app = new App();
+* app.use(bodyParser());
+*
+* const mcpRouter = createMcpRouter(mcpServer);
+* app.use(mcpRouter.routes());
+*
+* app.listen(3000);
+* ```
+*/
+const createMcpRouter = (server, options = {}) => {
+  const {
+    path = "/mcp",
+    sessionIdGenerator,
+    apiBaseUrl,
+    getApiHeaders,
+    auth
+  } = options;
+  const isStateful = sessionIdGenerator !== void 0;
+  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0 || auth !== void 0;
+  let sharedTransport;
+  if (isStateful) {
+    sharedTransport = new _modelcontextprotocol_sdk_server_streamableHttp_js.StreamableHTTPServerTransport({
+      sessionIdGenerator,
+      enableJsonResponse: true
+    });
+    server.connect(sharedTransport);
+  }
+  let statelessQueue = Promise.resolve();
+  const enqueueStateless = work => {
+    const result = statelessQueue.then(() => {
+      return work();
+    });
+    statelessQueue = result.catch(() => {});
+    return result;
+  };
+  const router = new _ttoss_http_server.Router();
+  if (auth) registerAuthRoutes(router, path, auth, buildTokenVerifier(auth));
+  const handleWithContext = async (ctx, body) => {
+    const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
+    const identity = ctx.state.identity;
+    const runRequest = async transport => {
+      await transport.handleRequest(ctx.req, ctx.res, body);
+      ctx.respond = false;
+    };
+    if (isStateful && sharedTransport) {
+      if (needsContext) await requestContextStore.run({
+        apiBaseUrl,
+        apiHeaders,
+        identity
+      }, () => {
+        return runRequest(sharedTransport);
+      });else await runRequest(sharedTransport);
+    } else await enqueueStateless(async () => {
+      const transport = new _modelcontextprotocol_sdk_server_streamableHttp_js.StreamableHTTPServerTransport({
+        sessionIdGenerator: void 0,
+        enableJsonResponse: true
+      });
+      try {
+        await server.connect(transport);
+        if (needsContext) await requestContextStore.run({
+          apiBaseUrl,
+          apiHeaders,
+          identity
+        }, () => {
+          return runRequest(transport);
+        });else await runRequest(transport);
+      } finally {
+        await transport.close();
+      }
+    });
+  };
+  router.post(path, async ctx => {
+    try {
+      await handleWithContext(ctx, ctx.request.body);
+    } catch (error) {
+      if (!ctx.res.headersSent) {
+        ctx.status = 500;
+        ctx.body = {
+          error: error instanceof Error ? error.message : "Internal server error"
+        };
+      }
+    }
+  });
+  router.delete(path, async ctx => {
+    try {
+      await handleWithContext(ctx);
+    } catch (error) {
+      if (!ctx.res.headersSent) {
+        ctx.status = 500;
+        ctx.body = {
+          error: error instanceof Error ? error.message : "Internal server error"
+        };
+      }
+    }
+  });
+  return router;
+};
+const rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
+const patchedServerSet = /* @__PURE__ */new WeakSet();
+/**
+* Registers a tool on an MCP server using a **plain JSON Schema** object for
+* `inputSchema` instead of a Zod shape.
+*
+* This is useful when tool definitions are shared between the MCP server and an
+* AI SDK agent (e.g. Vercel AI SDK's `tool()` helper), because both consume a
+* plain JSON Schema at runtime. Using this helper eliminates the lossy
+* JSON-Schema→Zod conversion that would otherwise be required.
+*
+* Internally the helper:
+* 1. Registers the tool via the standard `McpServer.registerTool` API using a
+*    Zod `z.record(z.unknown())` pass-through schema so that the existing MCP
+*    `tools/call` handler correctly routes requests and delivers raw args to
+*    your handler.
+* 2. Stores the original JSON Schema and patches the `tools/list` response
+*    handler so clients receive the verbatim JSON Schema over the wire.
+*
+* @param server - The `McpServer` instance to register the tool on.
+* @param params - Tool configuration including name, description, inputSchema,
+*   and handler.
+*
+* @example
+* ```typescript
+* import { registerToolFromSchema, McpServer } from '@ttoss/http-server-mcp';
+*
+* const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+*
+* registerToolFromSchema(server, {
+*   name: 'get-project',
+*   description: 'Get a project by ID',
+*   inputSchema: {
+*     type: 'object',
+*     properties: { id: { type: 'string', description: 'Project public ID' } },
+*     required: ['id'],
+*   },
+*   handler: async ({ id }) => ({
+*     content: [{ type: 'text', text: `Project: ${id}` }],
+*   }),
+* });
+* ```
+*/
+const registerToolFromSchema = (server, params) => {
+  const {
+    name,
+    description,
+    inputSchema = {
+      type: "object",
+      properties: {}
+    },
+    handler
+  } = params;
+  if (!rawSchemaRegistryMap.has(server)) rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
+  rawSchemaRegistryMap.get(server).set(name, inputSchema);
+  server.registerTool(name, {
+    description,
+    inputSchema: zod.z.record(zod.z.string(), zod.z.unknown())
+  }, async args => {
+    return handler(args);
+  });
+  if (!patchedServerSet.has(server)) {
+    patchedServerSet.add(server);
+    const rawServer = server.server;
+    const origHandler = rawServer?._requestHandlers?.get("tools/list");
+    if (!origHandler && process.env.NODE_ENV !== "production") console.warn("[registerToolFromSchema] Could not patch tools/list — internal MCP SDK structure may have changed. The tool will still be callable, but tools/list may return a Zod-derived schema instead of the verbatim JSON Schema.");
+    if (origHandler) rawServer._requestHandlers.set("tools/list", async (rawRequest, extra) => {
+      const result = await origHandler(rawRequest, extra);
+      const schemas = rawSchemaRegistryMap.get(server);
+      if (!schemas) return result;
+      return {
+        ...result,
+        tools: result.tools.map(tool => {
+          const raw = schemas.get(tool.name);
+          if (raw !== void 0) return {
+            ...tool,
+            inputSchema: raw
+          };
+          return tool;
+        })
+      };
+    });
+  }
+};
+
+//#endregion
+Object.defineProperty(exports, 'McpServer', {
+  enumerable: true,
+  get: function () {
+    return _modelcontextprotocol_sdk_server_mcp_js.McpServer;
+  }
+});
+exports.apiCall = apiCall;
+exports.checkScopes = checkScopes;
+exports.createMcpRouter = createMcpRouter;
+exports.getIdentity = getIdentity;
+exports.registerToolFromSchema = registerToolFromSchema;
+Object.defineProperty(exports, 'z', {
+  enumerable: true,
+  get: function () {
+    return zod.z;
+  }
+});