Merge pull request #57 from f/copilot/fix-56

Add streamable HTTP transport support with examples for local and remote servers

Author: f

README.md

@@ -148,17 +148,39 @@ mcp tools npx -y @modelcontextprotocol/server-filesystem ~
 
 #### HTTP SSE Transport
 
-Uses HTTP and Server-Sent Events (SSE) to communicate with an MCP server via JSON-RPC 2.0. This is useful for connecting to remote servers that implement the MCP protocol.
+Uses HTTP and Server-Sent Events (SSE) to communicate with an MCP server via JSON-RPC 2.0. This is useful for connecting to remote servers that implement the legacy MCP protocol.
 
 ```bash
-mcp tools http://localhost:3001/sse
+mcp tools --transport=sse http://localhost:3001/sse
 
 # Example: Use the everything sample server
 # docker run -p 3001:3001 --rm -it tzolov/mcp-everything-server:v1
 ```
 
 _Note:_ HTTP SSE currently supports only MCP protocol version 2024-11-05.
 
+#### Streamable HTTP Transport (Recommended)
+
+Uses streamable HTTP to communicate with an MCP server via JSON-RPC 2.0. This is the modern, recommended approach for connecting to remote servers that implement the MCP protocol. It supports both streaming responses and simple request/response patterns.
+
+```bash
+# Default transport for HTTP URLs (explicit flag not needed)
+mcp tools http://localhost:3000
+
+# Explicitly specify streamable HTTP transport
+mcp tools --transport=http http://localhost:3000
+
+# Examples with remote servers
+mcp tools https://api.example.com/mcp
+mcp tools --transport=http https://ne.tools
+```
+
+_Benefits of Streamable HTTP:_
+- **Session Management**: Supports stateful connections with session IDs
+- **Resumability**: Can reconnect and resume interrupted sessions (when supported by server)
+- **Flexible Responses**: Supports both streaming and direct JSON responses
+- **Modern Protocol**: Uses the latest MCP transport specification
+
 ### Output Formats
 
 MCP Tools supports three output formats to accommodate different needs:
@@ -373,11 +395,12 @@ mcp new tool:calculate --sdk=ts
 # Create a project with a specific transport type
 mcp new tool:calculate --transport=stdio
 mcp new tool:calculate --transport=sse
+mcp new tool:calculate --transport=http
 ```
 
 The scaffolding creates a complete project structure with:
 
-- Server setup with chosen transport (stdio or SSE)
+- Server setup with chosen transport (stdio, SSE, or streamable HTTP)
 - TypeScript configuration with modern ES modules
 - Component implementations with proper MCP interfaces
 - Automatic wiring of imports and initialization
@@ -764,6 +787,48 @@ mcp guard --allow tools:search_files npx -y @modelcontextprotocol/server-filesys
 mcp guard --deny tools:write_*,delete_*,create_*,move_* npx -y @modelcontextprotocol/server-filesystem ~
 ```
 
+### Streamable HTTP Usage
+
+Create and run a local streamable HTTP server:
+
+```bash
+# Create a new MCP server with streamable HTTP transport
+mkdir my-http-server && cd my-http-server
+mcp new tool:example_tool --transport=http
+
+# Install dependencies and build
+npm install && npm run build
+
+# Start the server (will run on http://localhost:3000)
+npm start
+```
+
+In a separate terminal, connect to your local server:
+
+```bash
+# Connect to local streamable HTTP server
+mcp tools http://localhost:3000
+
+# Call a tool on the local server
+mcp call example_tool --params '{"input": "test"}' http://localhost:3000
+
+# Use with different output formats
+mcp tools --format pretty http://localhost:3000
+```
+
+Connect to remote streamable HTTP servers:
+
+```bash
+# Connect to a remote MCP server
+mcp tools https://api.example.com/mcp
+
+# Use SSE transport for legacy servers
+mcp tools --transport=sse http://legacy-server.com/sse
+
+# Example with authentication headers (when supported)
+mcp tools --transport=http https://authenticated-mcp-server.com
+```
+
 ### Script Integration
 
 Using the proxy mode with a simple shell script:

cmd/mcptools/commands/new.go

@@ -15,6 +15,7 @@ const (
 	sdkTypeScript  = "ts"
 	transportStdio = "stdio"
 	transportSSE   = "sse"
+	transportHTTP  = "http"
 )
 
 // NewCmd returns a new 'new' command for scaffolding MCP projects.
@@ -30,7 +31,7 @@ func NewCmd() *cobra.Command {
 Examples:
   mcp new tool:hello_world resource:file prompt:hello
   mcp new tool:hello_world --sdk=ts
-  mcp new tool:hello_world --transport=stdio|sse`,
+  mcp new tool:hello_world --transport=stdio|sse|http`,
 		SilenceUsage: true,
 		RunE: func(_ *cobra.Command, args []string) error {
 			if len(args) == 0 {
@@ -48,8 +49,8 @@ Examples:
 			}
 
 			// Validate transport flag
-			if transportFlag != "" && transportFlag != transportStdio && transportFlag != transportSSE {
-				return fmt.Errorf("unsupported transport: %s (supported options: stdio, sse)", transportFlag)
+			if transportFlag != "" && transportFlag != transportStdio && transportFlag != transportSSE && transportFlag != transportHTTP {
+				return fmt.Errorf("unsupported transport: %s (supported options: stdio, sse, http)", transportFlag)
 			}
 
 			// Set default transport if not specified
@@ -84,7 +85,7 @@ Examples:
 
 	// Add flags
 	cmd.Flags().StringVar(&sdkFlag, "sdk", "", "Specify the SDK to use (ts)")
-	cmd.Flags().StringVar(&transportFlag, "transport", "", "Specify the transport to use (stdio, sse)")
+	cmd.Flags().StringVar(&transportFlag, "transport", "", "Specify the transport to use (stdio, sse, http)")
 
 	return cmd
 }
@@ -128,6 +129,8 @@ func createProjectStructure(components map[string]string, sdk, transport string)
 	var serverTemplateFile string
 	if transport == transportSSE {
 		serverTemplateFile = filepath.Join(templatesDir, "server_sse.ts")
+	} else if transport == transportHTTP {
+		serverTemplateFile = filepath.Join(templatesDir, "server_http.ts")
 	} else {
 		// Use stdio by default
 		serverTemplateFile = filepath.Join(templatesDir, "server_stdio.ts")

cmd/mcptools/commands/root.go

@@ -16,6 +16,7 @@ const (
 	FlagHelp        = "--help"
 	FlagHelpShort   = "-h"
 	FlagServerLogs  = "--server-logs"
+	FlagTransport   = "--transport"
 )
 
 // entity types.
@@ -34,6 +35,9 @@ var (
 	ParamsString string
 	// ShowServerLogs is a flag to show server logs.
 	ShowServerLogs bool
+	// TransportOption is the transport option for HTTP connections, valid values are "sse" and "http".
+	// Default is "http" (streamable HTTP).
+	TransportOption = "http"
 )
 
 // RootCmd creates the root command.
@@ -48,6 +52,7 @@ It allows you to discover and call tools, list resources, and interact with MCP-
 	cmd.PersistentFlags().StringVarP(&FormatOption, "format", "f", "table", "Output format (table, json, pretty)")
 	cmd.PersistentFlags().
 		StringVarP(&ParamsString, "params", "p", "{}", "JSON string of parameters to pass to the tool (for call command)")
+	cmd.PersistentFlags().StringVar(&TransportOption, "transport", "http", "HTTP transport type (http, sse)")
 
 	return cmd
 }

cmd/mcptools/commands/utils.go

@@ -47,7 +47,17 @@ var CreateClientFunc = func(args []string, _ ...client.ClientOption) (*client.Cl
 	var err error
 
 	if len(args) == 1 && IsHTTP(args[0]) {
-		c, err = client.NewSSEMCPClient(args[0])
+		// Validate transport option for HTTP URLs
+		if TransportOption != "http" && TransportOption != "sse" {
+			return nil, fmt.Errorf("invalid transport option: %s (supported: http, sse)", TransportOption)
+		}
+		
+		if TransportOption == "sse" {
+			c, err = client.NewSSEMCPClient(args[0])
+		} else {
+			// Default to streamable HTTP
+			c, err = client.NewStreamableHttpClient(args[0])
+		}
 		if err != nil {
 			return nil, err
 		}
@@ -91,6 +101,7 @@ var CreateClientFunc = func(args []string, _ ...client.ClientOption) (*client.Cl
 
 // ProcessFlags processes command line flags, sets the format option, and returns the remaining
 // arguments. Supported format options: json, pretty, and table.
+// Supported transport options: http and sse.
 //
 // For example, if the input arguments are ["tools", "--format", "pretty", "npx", "-y",
 // "@modelcontextprotocol/server-filesystem", "~"], it would return ["npx", "-y",
@@ -104,6 +115,9 @@ func ProcessFlags(args []string) []string {
 		case (args[i] == FlagFormat || args[i] == FlagFormatShort) && i+1 < len(args):
 			FormatOption = args[i+1]
 			i += 2
+		case args[i] == FlagTransport && i+1 < len(args):
+			TransportOption = args[i+1]
+			i += 2
 		case args[i] == FlagServerLogs:
 			ShowServerLogs = true
 			i++

cmd/mcptools/transport_test.go

@@ -0,0 +1,60 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/f/mcptools/cmd/mcptools/commands"
+)
+
+func TestTransportFlag(t *testing.T) {
+	// Save original values
+	origTransport := commands.TransportOption
+
+	// Test default value
+	if commands.TransportOption != "http" {
+		t.Errorf("Expected default transport to be 'http', got '%s'", commands.TransportOption)
+	}
+
+	// Test ProcessFlags with transport flag
+	args := []string{"tools", "--transport", "sse", "http://localhost:3000"}
+	remainingArgs := commands.ProcessFlags(args)
+
+	expectedArgs := []string{"tools", "http://localhost:3000"}
+	if len(remainingArgs) != len(expectedArgs) {
+		t.Errorf("Expected %d args, got %d", len(expectedArgs), len(remainingArgs))
+	}
+
+	for i, arg := range expectedArgs {
+		if remainingArgs[i] != arg {
+			t.Errorf("Expected arg %d to be '%s', got '%s'", i, arg, remainingArgs[i])
+		}
+	}
+
+	if commands.TransportOption != "sse" {
+		t.Errorf("Expected transport to be 'sse', got '%s'", commands.TransportOption)
+	}
+
+	// Restore original values
+	commands.TransportOption = origTransport
+}
+
+func TestIsHTTP(t *testing.T) {
+	testCases := []struct {
+		url      string
+		expected bool
+	}{
+		{"http://localhost:3000", true},
+		{"https://example.com", true},
+		{"localhost:3000", true},
+		{"stdio", false},
+		{"", false},
+		{"file:///path", false},
+	}
+
+	for _, tc := range testCases {
+		result := commands.IsHTTP(tc.url)
+		if result != tc.expected {
+			t.Errorf("IsHTTP(%s) = %v, expected %v", tc.url, result, tc.expected)
+		}
+	}
+}

templates/README.md

@@ -27,9 +27,10 @@ mcp new tool:hello_world resource:file prompt:hello
 # Create a project with a specific SDK (currently only TypeScript/ts supported)
 mcp new tool:hello_world --sdk=ts
 
-# Create a project with a specific transport (stdio or sse)
+# Create a project with a specific transport (stdio, sse, or http)
 mcp new tool:hello_world --transport=stdio
 mcp new tool:hello_world --transport=sse
+mcp new tool:hello_world --transport=http
 ```
 
 ## Available Templates
@@ -41,6 +42,7 @@ mcp new tool:hello_world --transport=sse
 - **prompt**: Prompt implementation template
 - **server_stdio**: Server with stdio transport
 - **server_sse**: Server with SSE transport
+- **server_http**: Server with streamable HTTP transport
 - **full_server**: Complete server with all three capabilities
 
 ## Project Structure

templates/ts/server_http.ts

@@ -0,0 +1,42 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { z } from "zod";
+import { randomUUID } from "crypto";
+
+// Initialize server
+const server = new McpServer({
+  name: "PROJECT_NAME",
+  version: "1.0.0"
+});
+
+// Initialize components here
+// COMPONENT_INITIALIZATION
+
+// Setup Express app
+const app = express();
+
+// Enable JSON parsing for request bodies
+app.use(express.json());
+
+// Create a streamable HTTP transport
+const transport = new StreamableHTTPServerTransport({
+  // Enable session management with auto-generated UUIDs
+  sessionIdGenerator: () => randomUUID(),
+  // Optional: Enable JSON response mode for simple request/response
+  enableJsonResponse: false
+});
+
+// Handle all HTTP methods on the root path
+app.all("/", async (req, res) => {
+  await transport.handleRequest(req, res, req.body);
+});
+
+// Connect the server to the transport
+await server.connect(transport);
+
+// Start HTTP server
+const port = 3000;
+app.listen(port, () => {
+  console.log(`MCP server running on http://localhost:${port}`);
+});