Echo Streamablehttp Server Stateful

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

一个有状态的诊断MCP回声服务器，具有会话管理、消息队列和11个全面的调试工具，用于测试OAuth流和MCP协议合规性。

特性

状态会话管理

• 持续会话：跨请求的基于UUID的会话跟踪
• 消息队列：异步客户端的每会话消息缓冲区
• 自动清理：后台任务删除过期的会话
• 会话上下文：存储和检索请求之间的状态

MCP协议合规性

• 完整的MCP 2025-06-18流式HTTP传输实现
• 支持多种协议版本（可配置）
• JSON-RPC 2.0消息处理
• 正确初始化� 初始化生命周期

11调试工具

1. 回声 -使用会话上下文回显消息
2. 重播LastEcho -重播最后一条回显的消息（有状态功能！）
3. printHeader -显示分类的所有HTTP标头
4. bearer解码 -无需验证即可解码JWT令牌
5. authContext -显示OAuth身份验证上下文
6. requestTiming -显示请求性能指标
7. cors分析 -分析CORS配置
8. 环境转储 -显示经过净化的环境配置
9. HealthProbe 的 -使用会话统计数据进行深度健康检查
10. 会话信息 -显示会话信息和统计信息
11. 谁是魔鬼 -AI驱动的卓越分析仪

端点

POST/mcp

• 接受JSON-RPC 2.0请求
• 通过Mcp会话Id标头创建/管理会话
• 支持JSON和SSE响应格式
• 返回有状态客户端的会话ID

GET/mcp

• 排队消息的轮询（需要会话ID）
• 返回服务器发送事件（SSE）流
• 队列为空时发送保持活动ping

配置

环境变量：

• MCP_ECHO_HOST -要绑定的主机（默认值：0.0.0.0）
• MCP_ECHO_PORT -要绑定的端口（默认值：3000）
• MCP_ECHO_DEBUG -启用调试日志记录（默认值：true）
• MCP_SESSION_TIMEOUT -会话超时（秒）（默认值：3600）
• MCP_PROTOCOL_VERSION -默认协议版本（默认：2025-06-18）
• MCP_PROTOCOL_VERSIONS_SUPPORTED -逗号分隔的支持版本

安装

使用pip

pip install mcp-echo-streamablehttp-server-stateful

使用 pixi

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

Docker部署

FROM python:3.11-slim

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

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

# Expose the port
EXPOSE 3000

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

该服务包括：

• 通过协议验证进行健康检查
• OAuth集成的Traefik标签
• 日志的卷装载
• 通过Let’s Encrypt自动HTTPS

会话功能

消息队列

• 每个会话的FIFO队列（最多100条消息）
• 自动溢流保护
• GET请求完全耗尽队列

会话存储

每个会话维护：

• 创建和上次活动时间戳
• 协议版本和客户端信息
• 初始状态
• 自定义应用程序状态（例如，最后一条回显消息）

背景清理

• 每60秒运行一次
• 删除超过超时时间的会话
• 清除关联的消息队列

快速开始

本地运行

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

# Or using Python module
python -m mcp_echo_streamablehttp_server_stateful

# With custom configuration
MCP_ECHO_PORT=8080 MCP_SESSION_TIMEOUT=7200 mcp-echo-stateful-server

使用Docker Compose

services:
  mcp-echo-stateful:
    image: mcp-echo-stateful:latest
    build:
      context: ./mcp-echo-streamablehttp-server-stateful
    environment:
      - MCP_ECHO_HOST=0.0.0.0
      - MCP_ECHO_PORT=3000
      - MCP_ECHO_DEBUG=true
      - MCP_SESSION_TIMEOUT=3600
      - 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

示例用法

初始化会话

curl -X POST https://echo-stateful.yourdomain.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","clientInfo":{"name":"test","version":"1.0"}},"id":1}'

使用状态工具

curl -X POST https://echo-stateful.yourdomain.com/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: " \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"replayLastEcho","arguments":{}},"id":2}'

与无状态版本的差异

此有状态版本添加了：

• 具有UUID跟踪的会话管理
• 异步传递的消息队列
• 状态工具（重播LastEcho）
• 消息轮询的GET端点
• 后台清理任务
• 会话统计和监控

许可证

Apache 2.0-有关详细信息，请参阅LICENSE文件。