@tmcp/transport-http 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @tmcp/transport-http
 
+## 0.2.1
+
+### Patch Changes
+
+- f5d8390: fix: optional `getSessionId`
+
+## 0.2.0
+
+### Minor Changes
+
+- d12964e: breaking: correctly handle http requests
+
+### Patch Changes
+
+- Updated dependencies [d921480]
+    - tmcp@1.7.0
+
 ## 0.1.1
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paolo Ricciuti
+
+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

@@ -50,7 +50,7 @@ server.tool(
 	},
 );
 
-// Create the HTTP transport
+// Create the HTTP transport (defaults to '/mcp' path)
 const transport = new HttpTransport(server);
 
 // Use with your preferred HTTP server
@@ -58,25 +58,32 @@ const transport = new HttpTransport(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;
+	try {
+		let body = '';
+		req.on('data', (chunk) => (body += chunk));
+		req.on('end', async () => {
+			const request = new Request(`http://localhost${req.url}`, {
+				method: req.method,
+				headers: req.headers,
+				body: req.method === 'POST' ? body : undefined,
+			});
+
+			const response = await transport.respond(request);
+			
+			// If response is null, the request wasn't for MCP
+			if (response === null) {
+				res.statusCode = 404;
+				res.end('Not Found');
+				return;
+			}
+
+			// Copy response to Node.js response
+			response.headers.forEach((value, key) => {
+				res.setHeader(key, value);
+			});
+			res.statusCode = response.status;
 
+			if (response.body) {
 				const reader = response.body.getReader();
 				const pump = async () => {
 					const { done, value } = await reader.read();
@@ -88,14 +95,13 @@ const httpServer = createServer(async (req, res) => {
 					pump();
 				};
 				pump();
-			});
-		} catch (error) {
-			res.statusCode = 500;
-			res.end('Internal Server Error');
-		}
-	} else {
-		res.statusCode = 404;
-		res.end('Not Found');
+			} else {
+				res.end();
+			}
+		});
+	} catch (error) {
+		res.statusCode = 500;
+		res.end('Internal Server Error');
 	}
 });
 
@@ -104,12 +110,14 @@ httpServer.listen(3000, () => {
 });
 ```
 
-### With Custom Session Management
+### With Custom Configuration
 
 ```javascript
 const transport = new HttpTransport(server, {
+	// Custom MCP endpoint path (default: '/mcp')
+	path: '/api/mcp',
+	// Custom session ID generation
 	getSessionId: () => {
-		// Custom session ID generation
 		return `session-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
 	},
 });
@@ -120,9 +128,11 @@ const transport = new HttpTransport(server, {
 - **🌐 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
+- **🛤️ Configurable Path**: Customizable MCP endpoint path with automatic filtering
 - **🔧 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
+- **🔀 Multiple HTTP Methods**: Supports GET (notifications), POST (messages), and DELETE (disconnect)
 
 ## API
 
@@ -146,14 +156,15 @@ Creates a new HTTP transport instance.
 ```typescript
 interface HttpTransportOptions {
 	getSessionId: () => string; // Custom session ID generator
+	path?: string; // MCP endpoint path (default: '/mcp')
 }
 ```
 
 #### Methods
 
-##### `respond(request: Request): Promise<Response>`
+##### `respond(request: Request): Promise<Response | null>`
 
-Processes an HTTP request and returns a Response with Server-Sent Events.
+Processes an HTTP request and returns a Response with Server-Sent Events, or null if the request path doesn't match the configured MCP path.
 
 **Parameters:**
 
@@ -161,12 +172,21 @@ Processes an HTTP request and returns a Response with Server-Sent Events.
 
 **Returns:**
 
-- A Response object with SSE stream for ongoing communication
+- A Response object with SSE stream for ongoing communication, or null if the request path doesn't match the MCP endpoint
+
+**HTTP Methods:**
+
+- **POST**: Processes MCP messages and returns short-lived event stream responses
+- **GET**: Establishes long-lived connections for server notifications
+- **DELETE**: Disconnects sessions and cleans up resources
 
 ## Protocol Details
 
-### Request Format
+### HTTP Methods
 
+The transport supports three HTTP methods:
+
+#### POST - Message Processing
 Clients send JSON-RPC messages via HTTP POST requests:
 
 ```http
@@ -182,9 +202,27 @@ mcp-session-id: optional-session-id
 }
 ```
 
-### Response Format
+Response: Short-lived event stream that closes after sending the response:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+Cache-Control: no-cache
+mcp-session-id: generated-or-provided-session-id
+
+data: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}
+
+```
+
+#### GET - Notification Stream
+Establishes long-lived connections for server notifications:
+
+```http
+GET /mcp HTTP/1.1
+mcp-session-id: optional-session-id
+```
 
-The server responds with Server-Sent Events:
+Response: Long-lived event stream for server notifications:
 
 ```http
 HTTP/1.1 200 OK
@@ -193,8 +231,23 @@ Cache-Control: no-cache
 Connection: keep-alive
 mcp-session-id: generated-or-provided-session-id
 
-data: {"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}
+data: {"jsonrpc":"2.0","method":"notifications/initialized","params":{}}
+
+```
+
+#### DELETE - Session Disconnect
+Disconnects a session and cleans up resources:
 
+```http
+DELETE /mcp HTTP/1.1
+mcp-session-id: session-to-disconnect
+```
+
+Response:
+
+```http
+HTTP/1.1 204 No Content
+mcp-session-id: session-to-disconnect
 ```
 
 ### Session Management
@@ -218,10 +271,11 @@ 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);
+		const response = await transport.respond(req);
+		if (response === null) {
+			return new Response('Not Found', { status: 404 });
 		}
-		return new Response('Not Found', { status: 404 });
+		return response;
 	},
 });
 ```
@@ -236,10 +290,11 @@ 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);
+	const response = await transport.respond(req);
+	if (response === null) {
+		return new Response('Not Found', { status: 404 });
 	}
-	return new Response('Not Found', { status: 404 });
+	return response;
 });
 ```
 
@@ -278,6 +333,10 @@ pnpm lint
 - [`@tmcp/adapter-zod`](../adapter-zod) - Zod schema adapter
 - [`@tmcp/adapter-valibot`](../adapter-valibot) - Valibot schema adapter
 
+## Acknowledgments
+
+Huge thanks to Sean O'Bannon that provided us with the `@tmcp` scope on npm.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmcp/transport-http",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Transport for TMCP using HTTP",
   "type": "module",
   "main": "src/index.js",
@@ -13,7 +13,7 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "tmcp": "^1.5.0"
+    "tmcp": "^1.7.0"
   },
   "keywords": [
     "tmcp",
@@ -27,7 +27,7 @@
   },
   "devDependencies": {
     "publint": "^0.3.12",
-    "tmcp": "^1.5.0"
+    "tmcp": "^1.7.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.d.ts

@@ -3,7 +3,8 @@
  */
 /**
  * @typedef {{
- * 	getSessionId: () => string
+ * 	getSessionId?: () => string
+ * 	path?: string
  * }} HttpTransportOptions
  */
 export class HttpTransport {
@@ -16,12 +17,13 @@ export class HttpTransport {
     /**
      *
      * @param {Request} request
-     * @returns
+     * @returns {Promise<Response | null>}
      */
-    respond(request: Request): Promise<Response>;
+    respond(request: Request): Promise<Response | null>;
     #private;
 }
 export type HttpTransportOptions = {
-    getSessionId: () => string;
+    getSessionId?: () => string;
+    path?: string;
 };
 import type { McpServer } from "tmcp";

package/src/index.js

@@ -4,7 +4,8 @@
 
 /**
  * @typedef {{
- * 	getSessionId: () => string
+ * 	getSessionId?: () => string
+ * 	path?: string
  * }} HttpTransportOptions
  */
 
@@ -15,10 +16,15 @@ export class HttpTransport {
 	#server;
 
 	/**
-	 * @type {HttpTransportOptions}
+	 * @type {Required<HttpTransportOptions>}
 	 */
 	#options;
 
+	/**
+	 * @type {string}
+	 */
+	#path;
+
 	/**
 	 * @type {Map<string, ReadableStreamDefaultController>}
 	 */
@@ -35,9 +41,12 @@ export class HttpTransport {
 	 */
 	constructor(server, options) {
 		this.#server = server;
-		this.#options = options || {
-			getSessionId: () => crypto.randomUUID(),
-		};
+		const { getSessionId = () => crypto.randomUUID(), path = '/mcp' } =
+			options ?? {
+				getSessionId: () => crypto.randomUUID(),
+			};
+		this.#options = { getSessionId, path };
+		this.#path = path;
 		this.#server.on('send', ({ request, context: { sessions } }) => {
 			for (let [session_id, controller] of this.#session.entries()) {
 				if (sessions === undefined || sessions.includes(session_id)) {
@@ -49,42 +58,54 @@ export class HttpTransport {
 		});
 	}
 
+	/**
+	 * @param {string} session_id
+	 */
+	#handle_delete(session_id) {
+		const controller = this.#session.get(session_id);
+		if (controller) {
+			controller.close();
+			this.#session.delete(session_id);
+			this.#streams.delete(session_id);
+		}
+		return new Response(null, {
+			status: 204,
+			headers: {
+				'mcp-session-id': session_id,
+			},
+		});
+	}
+
 	/**
 	 *
-	 * @param {Request} request
+	 * @param {string} session_id
 	 * @returns
 	 */
-	async respond(request) {
+	#handle_get(session_id) {
 		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,
+		// If session already exists, return existing stream
+		const existing_stream = this.#streams.get(session_id);
+		if (existing_stream) {
+			return new Response(existing_stream, {
 				headers: {
 					'Content-Type': 'text/event-stream',
+					'Cache-Control': 'no-cache',
+					Connection: 'keep-alive',
 					'mcp-session-id': session_id,
 				},
+				status: 200,
 			});
 		}
 
+		// Create new long-lived stream for notifications
 		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.delete(session_id);
 			},
 		});
 
@@ -99,4 +120,141 @@ export class HttpTransport {
 			status: 200,
 		});
 	}
+
+	/**
+	 *
+	 * @param {string} session_id
+	 * @param {Request} request
+	 */
+	async #handle_post(session_id, request) {
+		// Check Content-Type header
+		const content_type = request.headers.get('content-type');
+		if (!content_type || !content_type.includes('application/json')) {
+			return new Response(
+				JSON.stringify({
+					jsonrpc: '2.0',
+					error: {
+						code: -32600,
+						message: 'Invalid Request',
+						data: 'Content-Type must be application/json',
+					},
+				}),
+				{
+					status: 415,
+					headers: {
+						'Content-Type': 'application/json',
+						'mcp-session-id': session_id,
+					},
+				},
+			);
+		}
+
+		try {
+			const body = await request.clone().json();
+			const response = await this.#server.receive(body, session_id);
+
+			// Determine status code based on response type
+			// 202 Accepted for notifications/responses, 200 OK for standard requests
+			const status = response == null || response.id == null ? 202 : 200;
+
+			// Create a short-lived stream that closes after sending the response
+			const stream = new ReadableStream({
+				start(controller) {
+					controller.enqueue(
+						'data: ' + JSON.stringify(response) + '\n\n',
+					);
+					controller.close();
+				},
+			});
+
+			return new Response(stream, {
+				headers: {
+					'Content-Type': 'text/event-stream',
+					'Cache-Control': 'no-cache',
+					'mcp-session-id': session_id,
+				},
+				status,
+			});
+		} catch (error) {
+			// Handle JSON parsing errors
+			return new Response(
+				JSON.stringify({
+					jsonrpc: '2.0',
+					error: {
+						code: -32700,
+						message: 'Parse error',
+						data: /** @type {Error} */ (error).message,
+					},
+				}),
+				{
+					status: 400,
+					headers: {
+						'Content-Type': 'application/json',
+						'mcp-session-id': session_id,
+					},
+				},
+			);
+		}
+	}
+
+	/**
+	 *
+	 * @param {string} method
+	 * @returns
+	 */
+	#handle_default(method) {
+		return new Response(
+			JSON.stringify({
+				jsonrpc: '2.0',
+				error: {
+					code: -32601,
+					message: 'Method not found',
+					data: `HTTP method ${method} not supported`,
+				},
+			}),
+			{
+				status: 405,
+				headers: {
+					'Content-Type': 'application/json',
+					Allow: 'GET, POST, DELETE',
+				},
+			},
+		);
+	}
+
+	/**
+	 *
+	 * @param {Request} request
+	 * @returns {Promise<Response | null>}
+	 */
+	async respond(request) {
+		const url = new URL(request.url);
+
+		// Check if the request path matches the configured MCP path
+		if (url.pathname !== this.#path) {
+			return null;
+		}
+		const method = request.method;
+		const session_id =
+			request.headers.get('mcp-session-id') ||
+			this.#options.getSessionId();
+
+		// Handle DELETE request - disconnect session
+		if (method === 'DELETE') {
+			return this.#handle_delete(session_id);
+		}
+
+		// Handle GET request - establish long-lived connection for notifications
+		if (method === 'GET') {
+			return this.#handle_get(session_id);
+		}
+
+		// Handle POST request - process message and respond through event stream
+		if (method === 'POST') {
+			return this.#handle_post(session_id, request);
+		}
+
+		// Method not supported
+		return this.#handle_default(method);
+	}
 }