MCP Echo流式HTTP服务器-有状态
一个有状态的诊断MCP回声服务器，具有会话管理、消息队列和11个全面的调试工具，用于测试OAuth流和MCP协议合规性。
特性
状态会话管理
- 持续会话：跨请求的基于UUID的会话跟踪
- 消息队列：异步客户端的每会话消息缓冲区
- 自动清理：后台任务删除过期的会话
- 会话上下文：存储和检索请求之间的状态
MCP协议合规性
- 完整的MCP 2025-06-18流式HTTP传输实现
- 支持多种协议版本（可配置）
- JSON-RPC 2.0消息处理
- 正确初始化� 初始化生命周期
11调试工具
- 回声 -使用会话上下文回显消息
- 重播LastEcho -重播最后一条回显的消息（有状态功能！）
- printHeader -显示分类的所有HTTP标头
- bearer解码 -无需验证即可解码JWT令牌
- authContext -显示OAuth身份验证上下文
- requestTiming -显示请求性能指标
- cors分析 -分析CORS配置
- 环境转储 -显示经过净化的环境配置
- HealthProbe 的 -使用会话统计数据进行深度健康检查
- 会话信息 -显示会话信息和统计信息
- 谁是魔鬼 -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-statefulDocker部署
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文件。