Skip to content

Latest commit

 

History

History
200 lines (148 loc) · 6.84 KB

README.md

File metadata and controls

200 lines (148 loc) · 6.84 KB

Minimal HTTP MCP Server

This directory contains a minimal implementation of the MCP (Model Conversation Protocol) server that uses HTTP as its transport layer. This implementation supports both the 2024-11-05 and 2025-03-26 protocol versions.

Features

  • JSON-RPC 2.0 over HTTP implementation
  • Support for both MCP protocol versions (2024-11-05 and 2025-03-26)
  • Basic tools: echo, add, sleep
  • Support for synchronous and asynchronous tool calls
  • Support for resources (2025-03-26 only)
  • Error handling and validation
  • CORS support for browser clients
  • Batch request support
  • Session management via the Mcp-Session-Id header

Files

  • minimal_http_server.py: The main HTTP server implementation
  • test_http_server.py: A test script to verify server functionality
  • test_with_session.py: A test script that demonstrates proper session handling
  • check_server.py: A utility script to verify if the server is running

Running the Server

To start the server:

# Start with default settings (localhost:8000)
python minimal_http_server.py

# Start with custom host and port
python minimal_http_server.py --host 0.0.0.0 --port 8080

# Enable debug logging
python minimal_http_server.py --debug

Troubleshooting Server Start

If you encounter an "Address already in use" error, you can kill existing instances:

# Kill any existing server instances
pkill -9 -f "minimal_http_server"
sleep 2
python minimal_http_server.py --port 8888 --debug

Testing the Server

You can test the server using the included test scripts:

# Test with default settings
python test_http_server.py --url http://localhost:8000/mcp

# Test with custom server URL
python test_http_server.py --url http://localhost:8080/mcp

# Test with specific protocol version
python test_http_server.py --url http://localhost:8000/mcp --protocol-version 2024-11-05

# Enable debug logging
python test_http_server.py --url http://localhost:8000/mcp --debug

Testing with Session Management

Session management is a critical aspect of the MCP protocol. All requests after initialization must include the session ID from the Mcp-Session-Id header. Use our session-aware test script:

# Test with session handling
python test_with_session.py

# Test with custom server URL
python test_with_session.py --url http://localhost:8080/mcp

# Enable debug output
python test_with_session.py --debug

For detailed testing instructions and troubleshooting, see MCP_SERVER_TESTING.md.

Comprehensive Compliance Testing

You can run comprehensive compliance tests against the server using the MCP testing framework:

# Run HTTP tests using the scripts directory module
python -m mcp_testing.scripts.http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26

# Run HTTP tests using the executable script
./mcp_testing/bin/http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26

# Generate a compliance report
python -m mcp_testing.scripts.http_test --server-url http://localhost:8000/mcp --protocol-version 2025-03-26 --output-dir ./reports

The HTTP testing module tests the following aspects:

  • CORS support via OPTIONS requests
  • Session management via headers
  • Protocol initialization
  • Tools listing and execution
  • Asynchronous tool execution
  • Error handling and edge cases

See the HTTP Testing README for more details on the testing capabilities.

Manual Testing with curl

You can also test the server manually using curl. Important: You must capture and include the session ID in all requests after initialization:

# Initialize the server and capture the session ID
SESSION_ID=$(curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2025-03-26", "clientInfo": {"name": "curl", "version": "1.0.0"}, "capabilities": {"tools": true}}, "id": 1}' \
  -i | grep -i "Mcp-Session-Id" | cut -d ' ' -f 2 | tr -d '\r')

echo "Session ID: $SESSION_ID"

# Get server info
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "server/info", "id": 2}'

# List available tools
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 3}'

# Call the echo tool
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "echo", "parameters": {"message": "Hello, MCP!"}}, "id": 4}'

# Call the add tool
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "add", "parameters": {"a": 5, "b": 7}}, "id": 5}'

# Make an async tool call (2025-03-26 only)
TASK_ID=$(curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/call-async", "params": {"name": "sleep", "parameters": {"seconds": 2}}, "id": 6}' \
  | jq -r '.result.id')

echo "Task ID: $TASK_ID"

# Check async result
sleep 3
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d "{\"jsonrpc\": \"2.0\", \"method\": \"tools/result\", \"params\": {\"id\": \"$TASK_ID\"}, \"id\": 7}"

# List resources (2025-03-26 only)
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "resources/list", "id": 8}'

# Send a batch request
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '[{"jsonrpc": "2.0", "method": "server/info", "id": 9}, {"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "echo", "parameters": {"message": "Batch message"}}, "id": 10}]'

# Shutdown the server
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "shutdown", "id": 11}'

Protocol Notes

Version 2024-11-05

  • Uses inputSchema for tool parameters
  • Uses arguments for tool call parameters
  • Uses mcp/tools instead of tools/list
  • Uses mcp/tools/call instead of tools/call

Version 2025-03-26

  • Uses parameters for tool parameters
  • Uses parameters for tool call parameters
  • Supports async tool calls via tools/call-async, tools/result, and tools/cancel
  • Supports resources via resources/list and resources/get

License

AGPL-3.0-or-later

This server is provided as a reference implementation for educational purposes.