MCP Echo Service

About

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 -m mcp_echo.server

# Or run via FastMCP
uv run fastmcp run src/mcp_echo/server.py

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

• Health check: GET /health
• MCP endpoint: POST /mcp

Building MCPB Bundle

This server is distributed as an MCPB bundle. To build locally:

# Install mcpb CLI (requires Node.js)
npm install -g @anthropic-ai/mcpb

# Build the bundle
mcpb pack . mcp-echo.mcpb

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
• 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
  }'

Simple Health Check

curl http://localhost:8000/health

Development

Testing

# Install with dev dependencies
uv sync --group dev

# Run unit tests
uv run pytest tests/

# Run with coverage
uv run pytest tests/ --cov=mcp_echo

E2E Tests

E2E tests require the mcpb CLI and Docker:

# Install mcpb CLI
npm install -g @anthropic-ai/mcpb

# Run e2e tests
uv run pytest e2e/

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.

Links

Part of the NimbleTools Registry, an open source collection of production-ready MCP servers. For enterprise deployment, check out NimbleBrain.

• MCPB CLI
• FastMCP Documentation
• MCP Documentation