MCP Echo Service

A Model Context Protocol (MCP) service that provides echo tools for testing MCP protocol functionality.

Features

• echo_message: Echo back a message with optional uppercase formatting
• echo_with_delay: Echo back a message after a simulated delay (max 5 seconds)
• echo_json: Echo back structured JSON data with analysis

Quick Start

Local Development

# Clone the repository
git clone https://github.com/NimbleBrainInc/mcp-echo.git
cd mcp-echo

# Install dependencies with uv
uv sync

# Run the server
uv run python server.py

# Or install in editable mode
uv pip install -e .
python server.py

The server will start on http://localhost:8000 with:

• Health check: GET /health
• MCP endpoint: POST /mcp/ (note the trailing slash)

Docker

# Build the image
docker build -t nimbletools/mcp-echo .

# Run the container
docker run -p 8000:8000 nimbletools/mcp-echo

MCP Protocol Support

This server implements the full MCP (Model Context Protocol) specification:

• Transport: Streamable HTTP with Server-Sent Events (SSE)
• Session Management: Proper initialization handshake required
• Protocol Version: 2024-11-05
• Framework: FastMCP 2.11.2
• Python Version: 3.13+

Session Management

The server requires proper MCP initialization:

1. Initialize: Send initialize request to establish session
2. Initialized: Send notifications/initialized notification
3. Tools: Use session ID for all subsequent requests

API Usage

Complete MCP Example

# Step 1: Initialize session
INIT_RESPONSE=$(curl -s -i -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "example-client", "version": "1.0.0"}
    },
    "id": 1
  }')

# Extract session ID
SESSION_ID=$(echo "$INIT_RESPONSE" | grep -i "mcp-session-id" | cut -d' ' -f2 | tr -d '\r')

# Step 2: Send initialized notification
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

# Step 3: List available tools
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 2}'

# Step 4: Call echo_message tool
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call", 
    "params": {
      "name": "echo_message",
      "arguments": {"message": "Hello Echo!", "uppercase": true}
    },
    "id": 3
  }'

# Step 5: Call echo_with_delay tool  
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "echo_with_delay",
      "arguments": {"message": "Delayed Echo", "delay_seconds": 1}
    },
    "id": 4
  }'

# Step 6: Call echo_json tool
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "echo_json", 
      "arguments": {"data": {"test": "value", "number": 42}}
    },
    "id": 5
  }'

Simple Health Check

curl http://localhost:8000/health

Development

Testing

# Install with dev dependencies
uv sync --group dev

# Run tests (includes async MCP client tests)
uv run python -m pytest

# Run with coverage
uv run python -m pytest --cov=server

# Run specific test
uv run python -m pytest tests/test_server.py::test_echo_message_tool -v

Building and Deployment

# Build Docker image
docker build -t mcp-echo .

# Test the container
docker run -d --name mcp-test -p 8000:8000 mcp-echo

# Check health
curl http://localhost:8000/health

# Clean up
docker stop mcp-test && docker rm mcp-test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

About

Part of the NimbleTools ecosystem. From the makers of NimbleBrain.

License

MIT License - see LICENSE file for details.