@ttoss/http-server-mcp 0.12.4 → 0.13.0

package/dist/index.mjs

@@ -0,0 +1,382 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CognitoJwtVerifier } from "@ttoss/auth-core/amazon-cognito";
+import { Router } from "@ttoss/http-server";
+import { z, z as z$1 } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+//#region src/index.ts
+const requestContextStore = new 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 = 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 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 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 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: z$1.record(z$1.string(), z$1.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
+export { McpServer, apiCall, checkScopes, createMcpRouter, getIdentity, registerToolFromSchema, z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.12.4",
+  "version": "0.13.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -35,14 +35,15 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
-    "@ttoss/http-server": "^0.5.13"
+    "@ttoss/auth-core": "^0.4.13",
+    "@ttoss/http-server": "^0.5.14"
   },
   "devDependencies": {
     "@types/koa": "^3.0.2",
     "jest": "^30.3.0",
     "supertest": "^7.2.2",
-    "tsup": "^8.5.1",
-    "@ttoss/config": "^1.37.12"
+    "tsdown": "^0.22.0",
+    "@ttoss/config": "^1.37.13"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
@@ -52,7 +53,7 @@
     "provenance": true
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "test": "jest --projects tests/unit"
   }
 }

package/dist/esm/index.js

@@ -1,205 +0,0 @@
-/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-var __defProp = Object.defineProperty;
-var __name = (target, value) => __defProp(target, "name", {
-  value,
-  configurable: true
-});
-
-// src/index.ts
-import { AsyncLocalStorage } from "async_hooks";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { Router } from "@ttoss/http-server";
-import { z } from "zod";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z as z2 } from "zod";
-var requestContextStore = new AsyncLocalStorage();
-var apiCall = /* @__PURE__ */__name(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 void 0;
-  }
-  const contentType = response.headers.get("content-type");
-  if (contentType?.includes("application/json")) {
-    return response.json();
-  }
-  return response.text();
-}, "apiCall");
-var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
-  const {
-    path = "/mcp",
-    sessionIdGenerator,
-    apiBaseUrl,
-    getApiHeaders
-  } = options;
-  const isStateful = sessionIdGenerator !== void 0;
-  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== void 0;
-  let sharedTransport;
-  if (isStateful) {
-    sharedTransport = new StreamableHTTPServerTransport({
-      sessionIdGenerator,
-      enableJsonResponse: true
-    });
-    server.connect(sharedTransport);
-  }
-  let statelessQueue = Promise.resolve();
-  const enqueueStateless = /* @__PURE__ */__name(work => {
-    const result = statelessQueue.then(() => {
-      return work();
-    });
-    statelessQueue = result.catch(() => {});
-    return result;
-  }, "enqueueStateless");
-  const router = new Router();
-  const handleWithContext = /* @__PURE__ */__name(async (ctx, body) => {
-    const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
-    const runRequest = /* @__PURE__ */__name(async transport => {
-      await transport.handleRequest(ctx.req, ctx.res, body);
-      ctx.respond = false;
-    }, "runRequest");
-    if (isStateful && sharedTransport) {
-      if (needsContext) {
-        await requestContextStore.run({
-          apiBaseUrl,
-          apiHeaders
-        }, () => {
-          return runRequest(sharedTransport);
-        });
-      } else {
-        await runRequest(sharedTransport);
-      }
-    } else {
-      await enqueueStateless(async () => {
-        const transport = new StreamableHTTPServerTransport({
-          sessionIdGenerator: void 0,
-          enableJsonResponse: true
-        });
-        try {
-          await server.connect(transport);
-          if (needsContext) {
-            await requestContextStore.run({
-              apiBaseUrl,
-              apiHeaders
-            }, () => {
-              return runRequest(transport);
-            });
-          } else {
-            await runRequest(transport);
-          }
-        } finally {
-          await transport.close();
-        }
-      });
-    }
-  }, "handleWithContext");
-  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;
-}, "createMcpRouter");
-var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();
-var patchedServerSet = /* @__PURE__ */new WeakSet();
-var registerToolFromSchema = /* @__PURE__ */__name((server, params) => {
-  const {
-    name,
-    description,
-    inputSchema = {
-      type: "object",
-      properties: {}
-    },
-    handler
-  } = params;
-  if (!rawSchemaRegistryMap.has(server)) {
-    rawSchemaRegistryMap.set(server, /* @__PURE__ */new Map());
-  }
-  const registry = rawSchemaRegistryMap.get(server);
-  registry.set(name, inputSchema);
-  server.registerTool(name, {
-    description,
-    inputSchema: z.record(z.string(), 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 \u2014 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;
-          })
-        };
-      });
-    }
-  }
-}, "registerToolFromSchema");
-export { McpServer, apiCall, createMcpRouter, registerToolFromSchema, z2 as z };