Add documentation and tests for streamable HTTP transport

Co-authored-by: f <[email protected]>

Author: Copilot

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
@@ -749,6 +772,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/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