@ttoss/http-server-mcp 0.12.3 → 0.12.5

package/dist/index.cjs

@@ -0,0 +1,319 @@
+/** 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_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();
+};
+/**
+* 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
+  } = options;
+  const isStateful = sessionIdGenerator !== void 0;
+  const needsContext = apiBaseUrl !== void 0 || getApiHeaders !== 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();
+  const handleWithContext = async (ctx, body) => {
+    const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
+    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
+      }, () => {
+        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
+        }, () => {
+          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.createMcpRouter = createMcpRouter;
+exports.registerToolFromSchema = registerToolFromSchema;
+Object.defineProperty(exports, 'z', {
+  enumerable: true,
+  get: function () {
+    return zod.z;
+  }
+});