Echo Streamablehttp Server Stateless

MCP Echo流式HTTP服务器-无状态

实现StreamableHTTP传输规范的无状态诊断MCP（模型上下文协议）服务器。该服务器为MCP协议开发和OAuth身份验证流分析提供了全面的调试工具。

概述

这是一个 无状态 实施专门为以下目的设计的MCP回声服务器：

• 协议调试和验证
• 身份验证流分析
• 系统诊断和健康监测
• MCP客户端集成测试

与有状态变体不同，此服务器在请求之间不维护会话状态，使每个请求完全独立。

特性

9诊断工具

1. 回声 -用于基本连接测试的简单消息回声
2. printHeader -显示按类别组织的所有HTTP标头
3. bearer解码 -解码JWT承载令牌（无需验证）以进行调试
4. authContext -提供完整的身份验证上下文分析
5. requestTiming -显示请求性能指标和系统统计数据
6. cors分析 -分析CORS配置和标头
7. 环境转储 -显示经过净化的环境配置
8. HealthProbe 的 -通过系统资源监控执行深度健康检查
9. 谁是魔鬼 -揭示编程智慧的复活节彩蛋

协议支持

• MCP协议版本：2025-06-18（可配置）
• 运输：具有JSON和SSE响应格式的流式HTTP
• JSON-RPC：符合2.0标准
• 会话管理：无状态，通过标头跟踪会话ID

身份验证集成

• 设计用于使用ForwardAuth中间件在Traefik后面工作
• 读取Traefik转发的身份验证标头
• 提供JWT令牌解码以进行调试（无需验证）
• 通过诊断工具公开完整的身份验证上下文

安装

使用pip

pip install mcp-echo-streamablehttp-server-stateless

使用 pixi

pixi add --pypi mcp-echo-streamablehttp-server-stateless

Docker部署

FROM python:3.11-slim

# Install the package
RUN pip install mcp-echo-streamablehttp-server-stateless

# Set environment variables
ENV MCP_ECHO_HOST=0.0.0.0
ENV MCP_ECHO_PORT=3000
ENV MCP_ECHO_DEBUG=false

# Expose the port
EXPOSE 3000

# Run the server
CMD ["python", "-m", "mcp_echo_streamablehttp_server_stateless"]

配置

环境变量

# Server Configuration
MCP_ECHO_HOST=127.0.0.1          # Server bind address (default: 127.0.0.1)
MCP_ECHO_PORT=3000               # Server port (default: 3000)
MCP_ECHO_DEBUG=false             # Enable debug logging (default: false)

# Protocol Configuration
MCP_PROTOCOL_VERSION=2025-06-18  # Default MCP protocol version
MCP_PROTOCOL_VERSIONS_SUPPORTED=2025-06-18,2024-11-05  # Comma-separated supported versions

# Logging
LOG_FILE=/logs/mcp-echo-stateless.log  # Optional log file path

Docker编写集成

services:
  mcp-echo-stateless:
    image: mcp-echo-stateless:latest
    build:
      context: ./mcp-echo-streamablehttp-server-stateless
    environment:
      - MCP_ECHO_HOST=0.0.0.0
      - MCP_ECHO_PORT=3000
      - MCP_ECHO_DEBUG=false
      - MCP_PROTOCOL_VERSION=2025-06-18
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/mcp", "-X", "POST",
             "-H", "Content-Type: application/json",
             "-d", '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"healthcheck","version":"1.0"}},"id":1}']
      interval: 30s
      timeout: 5s
      retries: 3

该服务包括全面的Docker配置，包括：

• 使用MCP协议初始化进行健康检查
• 具有适当优先级的Traefik布线标签
• 与OAuth网关架构集成

快速开始

本地运行

# Using pip/pixi installation
mcp-echo-stateless-server

# Or using Python module
python -m mcp_echo_streamablehttp_server_stateless

# With custom configuration
MCP_ECHO_PORT=8080 MCP_ECHO_DEBUG=true mcp-echo-stateless-server

使用示例

仅使用命令进行测试

# Test basic echo functionality
just test-mcp-tool mcp-echo-stateless echo '{"message": "Hello, World!"}'

# Analyze authentication context
just test-mcp-tool mcp-echo-stateless authContext '{}'

# View all HTTP headers
just test-mcp-tool mcp-echo-stateless printHeader '{}'

# Check system health
just test-mcp-tool mcp-echo-stateless healthProbe '{}'

# Decode a Bearer token
just test-mcp-tool mcp-echo-stateless bearerDecode '{"token": "your-jwt-token-here"}'

API直接使用

# Initialize connection
curl -X POST https://mcp-echo-stateless.yourdomain.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0"
      }
    },
    "id": 1
  }'

# Call a tool
curl -X POST https://mcp-echo-stateless.yourdomain.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello from MCP!"
      }
    },
    "id": 2
  }'

建筑

无状态设计

• 请求之间没有会话持久性
• 请求上下文仅在每个请求的持续时间内存在
• 无Redis或数据库依赖关系
• 使用Python的上下文变量进行请求隔离的线程安全

与OAuth网关集成

该服务旨在作为MCP OAuth网关架构的一部分工作：

1. Traefik根据域/路径路由请求
2. ForwardAuth中间件验证OAuth令牌
3. 经过身份验证的请求将与用户上下文标头一起转发
4. 服务处理请求并返回响应

健康监测

该服务包括全面的健康检查，包括：

• 验证MCP协议的实施
• 检查系统资源（CPU、内存）
• 验证服务响应能力
• 使用实际的协议初始化进行验证

发展

本地运行

# Start the service
just up mcp-echo-stateless

# View logs
just logs mcp-echo-stateless

# Run tests
just test mcp-echo-stateless

调试

启用详细日志记录的调试模式：

MCP_ECHO_DEBUG=true just up mcp-echo-stateless

重要提示

• 不用于生产认证：此服务仅出于调试目的对令牌进行解码而不进行验证
• 无状态操作：请求之间没有数据持续存在
• 诊断重点：设计用于调试和测试，而不是生产工作负载
• CORS处理：CORS标头由Traefik管理，而不是服务本身

相关服务

• mcp echo流式http服务器有状态：具有会话持久性的状态变量
• 认证：提供令牌验证的OAuth身份验证服务
• Traefik：反向代理处理路由和身份验证中间件