@ttoss/http-server-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Terezinha Tech Operations (ttoss)
+
+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,214 @@
+# @ttoss/http-server-mcp
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) server integration for [@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server).
+
+## Installation
+
+```bash
+pnpm add @ttoss/http-server-mcp
+```
+
+## Quick Start
+
+```typescript
+import { App, bodyParser, cors } from '@ttoss/http-server';
+import {
+  createMcpRouter,
+  Server as McpServer,
+  z,
+} from '@ttoss/http-server-mcp';
+
+// Create MCP server
+const mcpServer = new McpServer({
+  name: 'my-mcp-server',
+  version: '1.0.0',
+});
+
+// Register tools
+mcpServer.registerTool(
+  'get-weather',
+  {
+    description: 'Get weather information for a location',
+    inputSchema: {
+      location: z.string().describe('City name'),
+    },
+  },
+  async ({ location }) => ({
+    content: [
+      {
+        type: 'text',
+        text: `Weather in ${location}: Sunny, 72°F`,
+      },
+    ],
+  })
+);
+
+// Create HTTP server
+const app = new App();
+app.use(cors());
+app.use(bodyParser());
+
+// Mount MCP router
+const mcpRouter = createMcpRouter(mcpServer);
+app.use(mcpRouter.routes());
+
+app.listen(3000, () => {
+  console.log('MCP server running on http://localhost:3000/mcp');
+});
+```
+
+## API Reference
+
+### `createMcpRouter(server, options?)`
+
+Creates a Koa router configured to handle MCP protocol requests.
+
+**Parameters:**
+
+- `server` (`McpServer`) - MCP server instance with registered tools and resources
+- `options` (`McpRouterOptions`) - Optional configuration
+  - `path` (`string`) - HTTP path for MCP endpoint (default: `'/mcp'`)
+  - `sessionIdGenerator` (`() => string`) - Session ID generator for stateful servers (default: `undefined` for stateless)
+
+**Returns:** `Router` - Koa router instance
+
+## Examples
+
+### Basic Tool
+
+```typescript
+import { Server as McpServer, z } from '@ttoss/http-server-mcp';
+
+const server = new McpServer({
+  name: 'calculator',
+  version: '1.0.0',
+});
+
+server.registerTool(
+  'add',
+  {
+    description: 'Add two numbers',
+    inputSchema: {
+      a: z.number().describe('First number'),
+      b: z.number().describe('Second number'),
+    },
+  },
+  async ({ a, b }) => ({
+    content: [
+      {
+        type: 'text',
+        text: `${a} + ${b} = ${a + b}`,
+      },
+    ],
+  })
+);
+```
+
+### Multiple Tools
+
+```typescript
+server.registerTool(
+  'multiply',
+  {
+    description: 'Multiply two numbers',
+    inputSchema: {
+      a: z.number(),
+      b: z.number(),
+    },
+  },
+  async ({ a, b }) => ({
+    content: [{ type: 'text', text: String(a * b) }],
+  })
+);
+
+server.registerTool(
+  'divide',
+  {
+    description: 'Divide two numbers',
+    inputSchema: {
+      a: z.number(),
+      b: z.number(),
+    },
+  },
+  async ({ a, b }) => {
+    if (b === 0) {
+      throw new Error('Division by zero');
+    }
+    return {
+      content: [{ type: 'text', text: String(a / b) }],
+    };
+  }
+);
+```
+
+### Custom Path
+
+```typescript
+const router = createMcpRouter(server, {
+  path: '/api/mcp',
+});
+```
+
+### Resources
+
+```typescript
+server.resource(
+  'config://app',
+  'Application configuration',
+  'application/json',
+  async () => ({
+    contents: [
+      {
+        uri: 'config://app',
+        mimeType: 'application/json',
+        text: JSON.stringify({ version: '1.0.0', env: 'production' }),
+      },
+    ],
+  })
+);
+```
+
+### With CORS and Multiple Endpoints
+
+```typescript
+import { App, bodyParser, cors, Router } from '@ttoss/http-server';
+import { createMcpRouter } from '@ttoss/http-server-mcp';
+
+const app = new App();
+app.use(cors());
+app.use(bodyParser());
+
+// Health check endpoint
+const healthRouter = new Router();
+healthRouter.get('/health', (ctx) => {
+  ctx.body = { status: 'ok' };
+});
+
+// MCP endpoint
+const mcpRouter = createMcpRouter(mcpServer);
+
+app.use(healthRouter.routes());
+app.use(mcpRouter.routes());
+
+app.listen(3000);
+```
+
+## Protocol Details
+
+This package implements the [Model Context Protocol](https://spec.modelcontextprotocol.io/) over HTTP using JSON responses (no SSE streaming). It uses the `StreamableHTTPServerTransport` from the MCP SDK with `enableJsonResponse: true` and adapts Koa's context-based middleware to work with the MCP SDK's Node.js request/response expectations.
+
+**Supported HTTP methods:**
+
+- `POST /mcp` - Send JSON-RPC requests/notifications
+- `DELETE /mcp` - Terminate session (optional)
+
+## Related Packages
+
+- [@ttoss/http-server](https://ttoss.dev/docs/modules/packages/http-server) - HTTP server foundation
+- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
+
+## Resources
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [MCP SDK TypeScript](https://github.com/modelcontextprotocol/typescript-sdk)

package/dist/esm/index.js

@@ -0,0 +1,52 @@
+/** 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 { 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";
+var createMcpRouter = /* @__PURE__ */__name((server, options = {}) => {
+  const {
+    path = "/mcp",
+    sessionIdGenerator
+  } = options;
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator,
+    enableJsonResponse: true
+  });
+  server.connect(transport);
+  const router = new Router();
+  router.post(path, async ctx => {
+    try {
+      await transport.handleRequest(ctx.req, ctx.res, ctx.request.body);
+      ctx.respond = false;
+    } 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 transport.handleRequest(ctx.req, ctx.res, void 0);
+      ctx.respond = false;
+    } catch (error) {
+      if (!ctx.res.headersSent) {
+        ctx.status = 500;
+        ctx.body = {
+          error: error instanceof Error ? error.message : "Internal server error"
+        };
+      }
+    }
+  });
+  return router;
+}, "createMcpRouter");
+export { McpServer as Server, createMcpRouter, z };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+import * as _koa_router from '@koa/router';
+import * as koa from 'koa';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { McpServer, McpServer as Server } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { z } from 'zod';
+
+/**
+ * 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
+     * Set to undefined for stateless servers
+     */
+    sessionIdGenerator?: () => 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, Server as 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) => _koa_router.RouterInstance<koa.DefaultState, koa.DefaultContext>;
+
+export { type McpRouterOptions, createMcpRouter };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ttoss/http-server-mcp",
+  "version": "0.3.0",
+  "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
+  "license": "MIT",
+  "author": "ttoss",
+  "contributors": [
+    "Pedro Arantes <pedro@arantespp.com> (https://arantespp.com)"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ttoss/ttoss.git",
+    "directory": "packages/http-server-mcp"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.25.76",
+    "@ttoss/http-server": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/koa": "^3.0.1",
+    "jest": "^30.2.0",
+    "supertest": "^7.1.4",
+    "tsup": "^8.5.1",
+    "@ttoss/config": "^1.35.12"
+  },
+  "keywords": [
+    "ai",
+    "koa",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "server"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "jest --projects tests/unit"
+  }
+}