@jalpp/mcp-adapter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jalpp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# mcp-adapter
+
+Lightweight adapter utilities for registering tools on an [MCP](https://modelcontextprotocol.io) server with full TypeScript type safety.
+
+## Installation
+
+```bash
+npm install mcp-adapter
+```
+
+> **Peer dependency:** `@modelcontextprotocol/sdk >= 1.0.0` must be installed in your project.
+
+## Usage
+
+### `toolAdapter`
+
+Registers a typed tool on an `McpServer`. Input schema types flow through to the callback automatically — no manual type annotations needed.
+
+**With input schema:**
+
+```ts
+import { toolAdapter, toolContentAdapter } from "mcp-adapter";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import z from "zod";
+
+const server = new McpServer({ name: "my-server", version: "1.0.0" });
+
+toolAdapter(server, {
+  name: "get-analysis",
+  config: {
+    description: "Analyze a chess position",
+    inputSchema: {
+      fen: z.string().describe("FEN string"),
+      depth: z.number().min(1).max(20),
+    },
+    annotations: { openWorldHint: true },
+  },
+  cb: async ({ fen, depth }) => {
+    const { data, error } = await myService.analyze(fen, depth);
+    return toolContentAdapter(data ?? {}, error);
+  },
+});
+```
+
+**Without input schema:**
+
+```ts
+toolAdapter(server, {
+  name: "get-status",
+  config: {
+    description: "Returns current server status",
+  },
+  cb: async () => {
+    const { data, error } = await myService.getStatus();
+    return toolContentAdapter(data ?? {}, error);
+  },
+});
+```
+
+### `toolContentAdapter`
+
+Normalizes a service result into a `CallToolResult`. If `error` is defined it takes priority; otherwise `data` is pretty-printed as JSON.
+
+```ts
+import { toolContentAdapter } from "mcp-adapter";
+
+return toolContentAdapter(data ?? {}, error);
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `data` | `object` | Successful result payload |
+| `error` | `string \| undefined` | Error message — takes priority over `data` |
+
+## API
+
+### `toolAdapter(server, adapter)`
+
+| Overload | Description |
+|----------|-------------|
+| `toolAdapter<T>(server, ToolInputAdapterWithSchema<T>)` | Tool with typed input schema |
+| `toolAdapter(server, ToolInputAdapterWithoutSchema)` | Tool with no input arguments |
+
+### `toolContentAdapter(data, error)`
+
+Returns a `CallToolResult` with a single `text` content block.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,95 @@
+import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { ToolAnnotations, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Adapter input for registering a tool that declares an input schema.
+ * The generic parameter `T` is inferred from the `inputSchema` shape and
+ * flows through to `cb`, ensuring the callback receives correctly-typed args.
+ *
+ * @template T - A Zod raw shape (e.g. `{ fen: z.ZodString }`) that defines the tool's input.
+ */
+interface ToolInputAdapterWithSchema<T extends ZodRawShapeCompat> {
+    /** Unique tool name used to identify the tool in the MCP registry. */
+    name: string;
+    config: {
+        /** Optional human-readable display title. */
+        title?: string;
+        /** Description of what the tool does, shown to the model. */
+        description?: string;
+        /** Zod shape defining the tool's input arguments. */
+        inputSchema: T;
+        /** Optional Zod shape defining the tool's structured output. */
+        outputSchema?: ZodRawShapeCompat;
+        /** Behavioural hints for the model (e.g. `openWorldHint`, `readOnlyHint`). */
+        annotations?: ToolAnnotations;
+        /** Arbitrary metadata attached to the tool registration. */
+        _meta?: Record<string, unknown>;
+    };
+    /**
+     * Tool handler callback. Receives parsed, type-safe args derived from `inputSchema`
+     * plus a `RequestHandlerExtra` context object.
+     */
+    cb: ToolCallback<T>;
+}
+/**
+ * Adapter input for registering a tool that takes no input arguments.
+ * The callback receives only the `RequestHandlerExtra` context object.
+ */
+interface ToolInputAdapterWithoutSchema {
+    /** Unique tool name used to identify the tool in the MCP registry. */
+    name: string;
+    config: {
+        /** Optional human-readable display title. */
+        title?: string;
+        /** Description of what the tool does, shown to the model. */
+        description?: string;
+        inputSchema?: undefined;
+        /** Optional Zod shape defining the tool's structured output. */
+        outputSchema?: ZodRawShapeCompat;
+        /** Behavioural hints for the model (e.g. `openWorldHint`, `readOnlyHint`). */
+        annotations?: ToolAnnotations;
+        /** Arbitrary metadata attached to the tool registration. */
+        _meta?: Record<string, unknown>;
+    };
+    /**
+     * Tool handler callback. Receives only a `RequestHandlerExtra` context object
+     * since no input schema is defined.
+     */
+    cb: ToolCallback<undefined>;
+}
+/**
+ * Normalizes a tool result into a standard `CallToolResult` text content block.
+ *
+ * If `error` is provided it is used as the text content; otherwise `data` is
+ * serialized to a pretty-printed JSON string.
+ *
+ * @param data  - The successful result payload. Used when `error` is absent.
+ * @param error - An error message string. Takes priority over `data` when present.
+ * @returns A `CallToolResult` with a single `text` content block.
+ *
+ * @example
+ * const { data, error } = await service.getData();
+ * return toolContentAdapter(data ?? {}, error);
+ */
+declare function toolContentAdapter(data: object, error: string | undefined): CallToolResult;
+/**
+ * Registers a tool that declares an input schema on an MCP server.
+ *
+ * The generic `T` is inferred from `toolInputAdapter.config.inputSchema`, making
+ * the callback args fully type-safe without manual annotation.
+ *
+ * @template T - Zod raw shape inferred from the provided `inputSchema`.
+ * @param server           - The `McpServer` instance to register the tool on.
+ * @param toolInputAdapter - Adapter object containing the tool name, config, and typed callback.
+ */
+declare function toolAdapter<T extends ZodRawShapeCompat>(server: McpServer, toolInputAdapter: ToolInputAdapterWithSchema<T>): void;
+/**
+ * Registers a tool that takes no input arguments on an MCP server.
+ *
+ * @param server           - The `McpServer` instance to register the tool on.
+ * @param toolInputAdapter - Adapter object containing the tool name, config, and no-arg callback.
+ */
+declare function toolAdapter(server: McpServer, toolInputAdapter: ToolInputAdapterWithoutSchema): void;
+
+export { toolAdapter, toolContentAdapter };

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import { McpServer, ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import { ToolAnnotations, CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Adapter input for registering a tool that declares an input schema.
+ * The generic parameter `T` is inferred from the `inputSchema` shape and
+ * flows through to `cb`, ensuring the callback receives correctly-typed args.
+ *
+ * @template T - A Zod raw shape (e.g. `{ fen: z.ZodString }`) that defines the tool's input.
+ */
+interface ToolInputAdapterWithSchema<T extends ZodRawShapeCompat> {
+    /** Unique tool name used to identify the tool in the MCP registry. */
+    name: string;
+    config: {
+        /** Optional human-readable display title. */
+        title?: string;
+        /** Description of what the tool does, shown to the model. */
+        description?: string;
+        /** Zod shape defining the tool's input arguments. */
+        inputSchema: T;
+        /** Optional Zod shape defining the tool's structured output. */
+        outputSchema?: ZodRawShapeCompat;
+        /** Behavioural hints for the model (e.g. `openWorldHint`, `readOnlyHint`). */
+        annotations?: ToolAnnotations;
+        /** Arbitrary metadata attached to the tool registration. */
+        _meta?: Record<string, unknown>;
+    };
+    /**
+     * Tool handler callback. Receives parsed, type-safe args derived from `inputSchema`
+     * plus a `RequestHandlerExtra` context object.
+     */
+    cb: ToolCallback<T>;
+}
+/**
+ * Adapter input for registering a tool that takes no input arguments.
+ * The callback receives only the `RequestHandlerExtra` context object.
+ */
+interface ToolInputAdapterWithoutSchema {
+    /** Unique tool name used to identify the tool in the MCP registry. */
+    name: string;
+    config: {
+        /** Optional human-readable display title. */
+        title?: string;
+        /** Description of what the tool does, shown to the model. */
+        description?: string;
+        inputSchema?: undefined;
+        /** Optional Zod shape defining the tool's structured output. */
+        outputSchema?: ZodRawShapeCompat;
+        /** Behavioural hints for the model (e.g. `openWorldHint`, `readOnlyHint`). */
+        annotations?: ToolAnnotations;
+        /** Arbitrary metadata attached to the tool registration. */
+        _meta?: Record<string, unknown>;
+    };
+    /**
+     * Tool handler callback. Receives only a `RequestHandlerExtra` context object
+     * since no input schema is defined.
+     */
+    cb: ToolCallback<undefined>;
+}
+/**
+ * Normalizes a tool result into a standard `CallToolResult` text content block.
+ *
+ * If `error` is provided it is used as the text content; otherwise `data` is
+ * serialized to a pretty-printed JSON string.
+ *
+ * @param data  - The successful result payload. Used when `error` is absent.
+ * @param error - An error message string. Takes priority over `data` when present.
+ * @returns A `CallToolResult` with a single `text` content block.
+ *
+ * @example
+ * const { data, error } = await service.getData();
+ * return toolContentAdapter(data ?? {}, error);
+ */
+declare function toolContentAdapter(data: object, error: string | undefined): CallToolResult;
+/**
+ * Registers a tool that declares an input schema on an MCP server.
+ *
+ * The generic `T` is inferred from `toolInputAdapter.config.inputSchema`, making
+ * the callback args fully type-safe without manual annotation.
+ *
+ * @template T - Zod raw shape inferred from the provided `inputSchema`.
+ * @param server           - The `McpServer` instance to register the tool on.
+ * @param toolInputAdapter - Adapter object containing the tool name, config, and typed callback.
+ */
+declare function toolAdapter<T extends ZodRawShapeCompat>(server: McpServer, toolInputAdapter: ToolInputAdapterWithSchema<T>): void;
+/**
+ * Registers a tool that takes no input arguments on an MCP server.
+ *
+ * @param server           - The `McpServer` instance to register the tool on.
+ * @param toolInputAdapter - Adapter object containing the tool name, config, and no-arg callback.
+ */
+declare function toolAdapter(server: McpServer, toolInputAdapter: ToolInputAdapterWithoutSchema): void;
+
+export { toolAdapter, toolContentAdapter };

package/dist/index.js

@@ -0,0 +1,58 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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, {
+  toolAdapter: () => toolAdapter,
+  toolContentAdapter: () => toolContentAdapter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/toolAdapter.ts
+function toolContentAdapter(data, error) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: error || JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+function toolAdapter(server, toolInputAdapter) {
+  if (toolInputAdapter.config.inputSchema) {
+    server.registerTool(
+      toolInputAdapter.name,
+      toolInputAdapter.config,
+      toolInputAdapter.cb
+    );
+  } else {
+    server.registerTool(
+      toolInputAdapter.name,
+      toolInputAdapter.config,
+      toolInputAdapter.cb
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  toolAdapter,
+  toolContentAdapter
+});

package/dist/index.mjs

@@ -0,0 +1,30 @@
+// src/toolAdapter.ts
+function toolContentAdapter(data, error) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: error || JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+function toolAdapter(server, toolInputAdapter) {
+  if (toolInputAdapter.config.inputSchema) {
+    server.registerTool(
+      toolInputAdapter.name,
+      toolInputAdapter.config,
+      toolInputAdapter.cb
+    );
+  } else {
+    server.registerTool(
+      toolInputAdapter.name,
+      toolInputAdapter.config,
+      toolInputAdapter.cb
+    );
+  }
+}
+export {
+  toolAdapter,
+  toolContentAdapter
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@jalpp/mcp-adapter",
+  "version": "0.1.0",
+  "description": "Adapter utilities for registering MCP tools",
+  "author": "jalpp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jalpp/mcp-adapter.git"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "zod": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "zod": ">=3.0.0",
+    "typescript": "^5.0.0",
+    "tsup": "^8.0.0",
+    "@types/node": "^20.0.0"
+  }
+}