@ttoss/http-server-mcp 0.11.1 → 0.12.0

package/README.md

@@ -157,8 +157,91 @@ Generic HTTP helper for use inside MCP tool handlers.
 
 **Returns:** `Promise<unknown>` - Parsed JSON response body
 
+### `registerToolFromSchema(server, params)`
+
+Registers a tool using a **plain JSON Schema** object for `inputSchema` instead of a Zod shape.
+
+Use this when tool definitions are shared between the MCP server and an AI SDK agent (e.g. Vercel AI SDK's `tool()` helper). Both consumers accept plain JSON Schema at runtime, so a single definition can feed both without any lossy conversion.
+
+**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
+
+**Returns:** `void`
+
 ## Examples
 
+### Plain JSON Schema Tool (`registerToolFromSchema`)
+
+Use `registerToolFromSchema` when you share tool definitions across the MCP server **and** an AI SDK agent. The plain JSON Schema is forwarded verbatim over the MCP wire protocol — `anyOf`, `$ref`, `pattern`, and other features not supported by Zod v3 are preserved without loss.
+
+```typescript
+import {
+  createMcpRouter,
+  McpServer,
+  registerToolFromSchema,
+} 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' },
+      // anyOf is preserved — Zod v3 has no direct equivalent
+      status: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+    },
+    required: ['id'],
+  },
+  handler: async ({ id }) => {
+    const data = await apiCall('GET', `/projects/${id}`);
+    return { content: [{ type: 'text', text: JSON.stringify(data) }] };
+  },
+});
+```
+
+**Single source of truth across MCP and AI SDK:**
+
+```typescript
+// lib/tools.ts — shared tool definition
+export const getProjectTool = {
+  name: 'get-project',
+  description: 'Get a project by ID',
+  inputSchema: {
+    type: 'object' as const,
+    properties: { id: { type: 'string' } },
+    required: ['id'],
+  },
+};
+
+// MCP server
+import { registerToolFromSchema } from '@ttoss/http-server-mcp';
+registerToolFromSchema(mcpServer, {
+  ...getProjectTool,
+  handler: async ({ id }) => {
+    /* ... */
+  },
+});
+
+// AI SDK agent
+import { tool } from 'ai';
+import { jsonSchema } from 'ai';
+const agentTool = tool({
+  description: getProjectTool.description,
+  parameters: jsonSchema(getProjectTool.inputSchema),
+  execute: async ({ id }) => {
+    /* same logic */
+  },
+});
+```
+
 ### Basic Tool
 
 ```typescript

package/dist/esm/index.js

@@ -9,8 +9,9 @@ var __name = (target, value) => __defProp(target, "name", {
 import { AsyncLocalStorage } from "async_hooks";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Router } from "@ttoss/http-server";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 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();
@@ -147,4 +148,58 @@ var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   });
   return router;
 }, "createMcpRouter");
-export { McpServer, apiCall, createMcpRouter, z };
+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.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 };

package/dist/index.d.cts

@@ -3,6 +3,7 @@ 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';
 export { z } from 'zod';
 
 /**
@@ -163,5 +164,81 @@ interface McpRouterOptions {
  * ```
  */
 declare const createMcpRouter: (server: McpServer, options?: McpRouterOptions) => _koa_router.RouterInstance<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 McpRouterOptions, apiCall, createMcpRouter };
+export { type ApiCallOptions, type JsonObjectSchema, type McpRouterOptions, type RegisterToolFromSchemaParams, apiCall, createMcpRouter, registerToolFromSchema };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ 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';
 export { z } from 'zod';
 
 /**
@@ -163,5 +164,81 @@ interface McpRouterOptions {
  * ```
  */
 declare const createMcpRouter: (server: McpServer, options?: McpRouterOptions) => _koa_router.RouterInstance<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 McpRouterOptions, apiCall, createMcpRouter };
+export { type ApiCallOptions, type JsonObjectSchema, type McpRouterOptions, type RegisterToolFromSchemaParams, apiCall, createMcpRouter, registerToolFromSchema };

package/dist/index.js

@@ -34,14 +34,16 @@ __export(index_exports, {
   McpServer: () => import_mcp.McpServer,
   apiCall: () => apiCall,
   createMcpRouter: () => createMcpRouter,
-  z: () => import_zod.z
+  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_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 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();
@@ -178,10 +180,65 @@ var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
   });
   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.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
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "license": "MIT",
   "author": "ttoss",
@@ -29,6 +29,9 @@
     "zod": "^3.25.0",
     "@ttoss/http-server": "^0.5.9"
   },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
   "devDependencies": {
     "@types/koa": "^3.0.1",
     "jest": "^30.3.0",