@ttoss/http-server-mcp 0.12.3 → 0.12.5

package/dist/index.d.ts

@@ -1,244 +0,0 @@
-import * as koa from 'koa';
-import { Context } from 'koa';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { Router } from '@ttoss/http-server';
-export { z } from 'zod';
-
-/**
- * Options for a single `apiCall` request.
- */
-interface ApiCallOptions {
-    /**
-     * JSON-serialisable request body. Automatically serialised and sent with
-     * `Content-Type: application/json`.
-     */
-    body?: unknown;
-    /**
-     * Additional or override headers for this specific request.
-     * These are merged on top of any headers injected from the MCP request
-     * context via `getApiHeaders`, allowing per-call overrides.
-     */
-    headers?: Record<string, string>;
-}
-/**
- * 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' },
- * });
- * ```
- */
-declare const apiCall: (method: string, url: string, options?: ApiCallOptions) => Promise<unknown>;
-/**
- * Options for configuring the MCP router
- */
-interface McpRouterOptions {
-    /**
-     * The HTTP path where the MCP server will be mounted
-     * @default '/mcp'
-     */
-    path?: string;
-    /**
-     * Optional session ID generator for stateful MCP servers.
-     * When provided, a single shared transport is created and sessions are tracked.
-     * When undefined (default), the server operates in stateless mode where each
-     * HTTP request uses its own transport instance.
-     */
-    sessionIdGenerator?: () => string;
-    /**
-     * Base URL prepended to relative paths passed to `apiCall` (paths starting
-     * with `/`). Tool handlers can then call `apiCall('GET', '/resource')` without
-     * specifying a host.
-     *
-     * @example 'http://localhost:3000/api/v1'
-     */
-    apiBaseUrl?: string;
-    /**
-     * Called once per incoming MCP HTTP request. Return a plain object whose
-     * key-value pairs will be merged into the headers of every `apiCall` made
-     * within that request's tool handlers.
-     *
-     * Use this to forward any header from the MCP request — Bearer tokens, API
-     * keys, tenant IDs, trace headers, etc. — without coupling tool handlers to
-     * a specific authentication scheme.
-     *
-     * @example Forward a Bearer token
-     * ```typescript
-     * getApiHeaders: (ctx) => ({ Authorization: ctx.headers.authorization ?? '' })
-     * ```
-     *
-     * @example Forward an x-api-key header
-     * ```typescript
-     * getApiHeaders: (ctx) => ({ 'x-api-key': ctx.headers['x-api-key'] as string })
-     * ```
-     *
-     * @example Inject a static service-to-service key
-     * ```typescript
-     * getApiHeaders: () => ({ 'x-internal-key': process.env.INTERNAL_API_KEY! })
-     * ```
-     */
-    getApiHeaders?: (ctx: Context) => Record<string, string>;
-}
-/**
- * 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);
- * ```
- */
-declare const createMcpRouter: (server: McpServer, options?: McpRouterOptions) => Router<koa.DefaultState, koa.DefaultContext>;
-/**
- * A plain JSON Schema object (draft-07 compatible) describing the shape of a
- * tool's input. Used with {@link registerToolFromSchema} as an alternative to
- * providing a Zod shape, enabling lossless round-trips for schemas that contain
- * features not expressible in Zod v3 (`anyOf`, `$ref`, `pattern`, `allOf`, …).
- */
-interface JsonObjectSchema {
-    type: 'object';
-    properties?: Record<string, unknown>;
-    required?: string[];
-    [key: string]: unknown;
-}
-/**
- * Parameters accepted by {@link registerToolFromSchema}.
- */
-interface RegisterToolFromSchemaParams {
-    /** Unique tool name. */
-    name: string;
-    /** Human-readable description shown to the AI client. */
-    description?: string;
-    /**
-     * Plain JSON Schema that describes the tool's input object.
-     * This schema is forwarded verbatim over the MCP wire protocol, so any
-     * JSON Schema feature (`anyOf`, `$ref`, `pattern`, …) is preserved without
-     * loss. Defaults to `{ type: 'object', properties: {} }` when omitted.
-     */
-    inputSchema?: JsonObjectSchema;
-    /**
-     * Tool handler invoked when the AI client calls the tool.
-     * Receives the raw request arguments as a plain object (no Zod validation is
-     * applied, so the shape matches whatever the client sends).
-     */
-    handler: (args: Record<string, unknown>) => CallToolResult | Promise<CallToolResult>;
-}
-/**
- * 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}` }],
- *   }),
- * });
- * ```
- */
-declare const registerToolFromSchema: (server: McpServer, params: RegisterToolFromSchemaParams) => void;
-
-export { type ApiCallOptions, type JsonObjectSchema, type McpRouterOptions, type RegisterToolFromSchemaParams, apiCall, createMcpRouter, registerToolFromSchema };

package/dist/index.js

@@ -1,244 +0,0 @@
-/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
-"use strict";
-
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __name = (target, value) => __defProp(target, "name", {
-  value,
-  configurable: true
-});
-var __export = (target, all) => {
-  for (var name in all) __defProp(target, name, {
-    get: all[name],
-    enumerable: true
-  });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    });
-  }
-  return to;
-};
-var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
-  value: true
-}), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  McpServer: () => import_mcp.McpServer,
-  apiCall: () => apiCall,
-  createMcpRouter: () => createMcpRouter,
-  registerToolFromSchema: () => registerToolFromSchema,
-  z: () => import_zod2.z
-});
-module.exports = __toCommonJS(index_exports);
-var import_node_async_hooks = require("async_hooks");
-var import_streamableHttp = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
-var import_http_server = require("@ttoss/http-server");
-var import_zod = require("zod");
-var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_zod2 = require("zod");
-var requestContextStore = new import_node_async_hooks.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 import_streamableHttp.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 import_http_server.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 import_streamableHttp.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: import_zod.z.record(import_zod.z.string(), import_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 \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");
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  McpServer,
-  apiCall,
-  createMcpRouter,
-  registerToolFromSchema,
-  z
-});