@tmcp/transport-http 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @tmcp/transport-http
+
+## 0.1.1
+
+### Patch Changes
+
+- 41fb096: fix: use new sessions management
+- Updated dependencies [41fb096]
+    - tmcp@1.4.0

package/README.md

@@ -0,0 +1,283 @@
+# @tmcp/transport-http
+
+An HTTP transport implementation for TMCP (TypeScript Model Context Protocol) servers. This package provides HTTP Streaming based communication for MCP servers over HTTP, enabling web-based clients to interact with your MCP server through standard HTTP requests.
+
+## Installation
+
+```bash
+npm install @tmcp/transport-http tmcp
+# or
+pnpm add @tmcp/transport-http tmcp
+# or
+yarn add @tmcp/transport-http tmcp
+```
+
+## Usage
+
+### Basic Setup
+
+```javascript
+import { McpServer } from 'tmcp';
+import { HttpTransport } from '@tmcp/transport-http';
+
+// Create your MCP server
+const server = new McpServer(
+	{
+		name: 'my-http-server',
+		version: '1.0.0',
+		description: 'My HTTP MCP server',
+	},
+	{
+		adapter: new YourSchemaAdapter(),
+		capabilities: {
+			tools: { listChanged: true },
+			prompts: { listChanged: true },
+			resources: { listChanged: true },
+		},
+	},
+);
+
+// Add your tools, prompts, and resources
+server.tool(
+	{
+		name: 'example_tool',
+		description: 'An example tool',
+	},
+	async () => {
+		return {
+			content: [{ type: 'text', text: 'Hello from HTTP!' }],
+		};
+	},
+);
+
+// Create the HTTP transport
+const transport = new HttpTransport(server);
+
+// Use with your preferred HTTP server
+// Example with Node.js built-in server:
+import { createServer } from 'http';
+
+const httpServer = createServer(async (req, res) => {
+	if (req.method === 'POST' && req.url === '/mcp') {
+		try {
+			let body = '';
+			req.on('data', (chunk) => (body += chunk));
+			req.on('end', async () => {
+				const request = new Request('http://localhost/mcp', {
+					method: 'POST',
+					headers: req.headers,
+					body: body,
+				});
+
+				const response = await transport.respond(request);
+
+				// Copy response to Node.js response
+				response.headers.forEach((value, key) => {
+					res.setHeader(key, value);
+				});
+				res.statusCode = response.status;
+
+				const reader = response.body.getReader();
+				const pump = async () => {
+					const { done, value } = await reader.read();
+					if (done) {
+						res.end();
+						return;
+					}
+					res.write(value);
+					pump();
+				};
+				pump();
+			});
+		} catch (error) {
+			res.statusCode = 500;
+			res.end('Internal Server Error');
+		}
+	} else {
+		res.statusCode = 404;
+		res.end('Not Found');
+	}
+});
+
+httpServer.listen(3000, () => {
+	console.log('MCP HTTP server listening on port 3000');
+});
+```
+
+### With Custom Session Management
+
+```javascript
+const transport = new HttpTransport(server, {
+	getSessionId: () => {
+		// Custom session ID generation
+		return `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+	},
+});
+```
+
+## Features
+
+- **🌐 HTTP/SSE Communication**: Uses Server-Sent Events for real-time bidirectional communication
+- **🔄 Session Management**: Maintains client sessions with automatic session ID generation
+- **📡 Streaming Responses**: Supports streaming responses through SSE
+- **🔧 Framework Agnostic**: Works with any HTTP server framework (Fastify, Bun, Deno, etc.)
+- **⚡ Real-time Updates**: Server can push notifications and updates to connected clients
+- **🛡️ Error Handling**: Graceful error handling for malformed requests
+
+## API
+
+### `HttpTransport`
+
+#### Constructor
+
+```typescript
+new HttpTransport(server: McpServer, options?: HttpTransportOptions)
+```
+
+Creates a new HTTP transport instance.
+
+**Parameters:**
+
+- `server` - A TMCP server instance to handle incoming requests
+- `options` - Optional configuration for the transport
+
+**Options:**
+
+```typescript
+interface HttpTransportOptions {
+	getSessionId: () => string; // Custom session ID generator
+}
+```
+
+#### Methods
+
+##### `respond(request: Request): Promise<Response>`
+
+Processes an HTTP request and returns a Response with Server-Sent Events.
+
+**Parameters:**
+
+- `request` - A Web API Request object containing the JSON-RPC message
+
+**Returns:**
+
+- A Response object with SSE stream for ongoing communication
+
+## Protocol Details
+
+### Request Format
+
+Clients send JSON-RPC messages via HTTP POST requests:
+
+```http
+POST /mcp HTTP/1.1
+Content-Type: application/json
+mcp-session-id: optional-session-id
+
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/list",
+  "params": {}
+}
+```
+
+### Response Format
+
+The server responds with Server-Sent Events:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Cache-Control: no-cache
+Connection: keep-alive
+mcp-session-id: generated-or-provided-session-id
+
+data: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}
+
+```
+
+### Session Management
+
+- **Session ID Header**: `mcp-session-id`
+- **Automatic Generation**: If no session ID is provided, one is generated automatically
+- **Session Persistence**: Sessions persist across multiple requests until the client disconnects
+- **Server Notifications**: Server can send notifications to all active sessions
+
+## Framework Examples
+
+### Bun
+
+```javascript
+import { McpServer } from 'tmcp';
+import { HttpTransport } from '@tmcp/transport-http';
+
+const server = new McpServer(/* ... */);
+const transport = new HttpTransport(server);
+
+Bun.serve({
+	port: 3000,
+	async fetch(req) {
+		if (req.method === 'POST' && new URL(req.url).pathname === '/mcp') {
+			return await transport.respond(req);
+		}
+		return new Response('Not Found', { status: 404 });
+	},
+});
+```
+
+### Deno
+
+```javascript
+import { McpServer } from 'tmcp';
+import { HttpTransport } from '@tmcp/transport-http';
+
+const server = new McpServer(/* ... */);
+const transport = new HttpTransport(server);
+
+Deno.serve({ port: 3000 }, async (req) => {
+	if (req.method === 'POST' && new URL(req.url).pathname === '/mcp') {
+		return await transport.respond(req);
+	}
+	return new Response('Not Found', { status: 404 });
+});
+```
+
+## Error Handling
+
+The transport includes comprehensive error handling:
+
+- **Malformed JSON**: Invalid JSON requests return appropriate error responses
+- **Session Management**: Automatic cleanup of disconnected sessions
+- **Server Errors**: Server processing errors are propagated to clients
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate TypeScript declarations
+pnpm generate:types
+
+# Lint the code
+pnpm lint
+```
+
+## Requirements
+
+- Node.js 16+ (for native ES modules and Web API support)
+- A TMCP server instance
+- An HTTP server framework or runtime
+- A schema adapter (Zod, Valibot, etc.)
+
+## Related Packages
+
+- [`tmcp`](../tmcp) - Core TMCP server implementation
+- [`@tmcp/transport-stdio`](../transport-stdio) - Standard I/O transport
+- [`@tmcp/adapter-zod`](../adapter-zod) - Zod schema adapter
+- [`@tmcp/adapter-valibot`](../adapter-valibot) - Valibot schema adapter
+
+## License
+
+MIT

package/jsconfig.json

@@ -0,0 +1,16 @@
+{
+	"compilerOptions": {
+		"target": "esnext",
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"allowJs": true,
+		"checkJs": true,
+		"declaration": true,
+		"emitDeclarationOnly": false,
+		"strict": true,
+		"noEmit": true,
+		"skipLibCheck": true
+	},
+	"include": ["src/**/*"],
+	"exclude": ["node_modules"]
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@tmcp/transport-http",
+  "version": "0.1.1",
+  "description": "Transport for TMCP using HTTP",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "tmcp": "^1.5.0"
+  },
+  "keywords": [
+    "tmcp",
+    "http",
+    "transport"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paoloricciuti/tmcp.git",
+    "directory": "packages/transport-http"
+  },
+  "devDependencies": {
+    "publint": "^0.3.12",
+    "tmcp": "^1.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "generate:types": "tsc ./src/*.js --declaration --emitDeclarationOnly --target esnext --allowJs --moduleresolution nodenext --module nodenext && publint",
+    "prepublish": "pnpm generate:types"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @import { McpServer, ClientCapabilities } from "tmcp";
+ */
+/**
+ * @typedef {{
+ * 	getSessionId: () => string
+ * }} HttpTransportOptions
+ */
+export class HttpTransport {
+    /**
+     *
+     * @param {McpServer<any>} server
+     * @param {HttpTransportOptions} [options]
+     */
+    constructor(server: McpServer<any>, options?: HttpTransportOptions);
+    /**
+     *
+     * @param {Request} request
+     * @returns
+     */
+    respond(request: Request): Promise<Response>;
+    #private;
+}
+export type HttpTransportOptions = {
+    getSessionId: () => string;
+};
+import type { McpServer } from "tmcp";

package/src/index.js

@@ -0,0 +1,102 @@
+/**
+ * @import { McpServer, ClientCapabilities } from "tmcp";
+ */
+
+/**
+ * @typedef {{
+ * 	getSessionId: () => string
+ * }} HttpTransportOptions
+ */
+
+export class HttpTransport {
+	/**
+	 * @type {McpServer<any>}
+	 */
+	#server;
+
+	/**
+	 * @type {HttpTransportOptions}
+	 */
+	#options;
+
+	/**
+	 * @type {Map<string, ReadableStreamDefaultController>}
+	 */
+	#session = new Map();
+	/**
+	 * @type {Map<string, ReadableStream>}
+	 */
+	#streams = new Map();
+
+	/**
+	 *
+	 * @param {McpServer<any>} server
+	 * @param {HttpTransportOptions} [options]
+	 */
+	constructor(server, options) {
+		this.#server = server;
+		this.#options = options || {
+			getSessionId: () => crypto.randomUUID(),
+		};
+		this.#server.on('send', ({ request, context: { sessions } }) => {
+			for (let [session_id, controller] of this.#session.entries()) {
+				if (sessions === undefined || sessions.includes(session_id)) {
+					controller.enqueue(
+						'data: ' + JSON.stringify(request) + '\n\n',
+					);
+				}
+			}
+		});
+	}
+
+	/**
+	 *
+	 * @param {Request} request
+	 * @returns
+	 */
+	async respond(request) {
+		const sessions = this.#session;
+		const streams = this.#streams;
+
+		const body = await request.json();
+		const session_id =
+			request.headers.get('mcp-session-id') ||
+			this.#options.getSessionId();
+		const controller = sessions.get(session_id);
+		const response = await this.#server.receive(body, session_id);
+
+		if (controller) {
+			controller.enqueue('data: ' + JSON.stringify(response) + '\n\n');
+			return new Response(null, {
+				status: 204,
+				headers: {
+					'Content-Type': 'text/event-stream',
+					'mcp-session-id': session_id,
+				},
+			});
+		}
+
+		const stream = new ReadableStream({
+			start(controller) {
+				sessions.set(session_id, controller);
+				controller.enqueue(
+					'data: ' + JSON.stringify(response) + '\n\n',
+				);
+			},
+			cancel() {
+				sessions.delete(session_id);
+			},
+		});
+
+		streams.set(session_id, stream);
+		return new Response(stream, {
+			headers: {
+				'Content-Type': 'text/event-stream',
+				'Cache-Control': 'no-cache',
+				Connection: 'keep-alive',
+				'mcp-session-id': session_id,
+			},
+			status: 200,
+		});
+	}
+}