MCP Streamable HTTP Server

基本能力

产品定位

mcp-streamable-http-server 是一个基于 Model Context Protocol (MCP) 的 Streamable HTTP 服务开发模板，旨在提供一个功能完善的服务框架。

核心功能

• 灵活的鉴权机制：支持通过 URL query 及 JWT token 进行参数传递与鉴权。
• 上下文感知的用户识别：能够通过上下文向工具内部传递 session_id，确保工具能够快速识别请求用户。
• 动态服务注册与启动：支持在系统运行时热注册并启动新的服务，增强了系统的灵活性和可扩展性。
• 可定制的中间件：允许开发者在项目中自定义中间件，轻松实现 IP 拦截、高级鉴权等定制化逻辑。
• 便捷的工具配置：支持通过 YAML 文件定义工具方法的输入参数，简化了配置流程，提升了开发效率。

适用场景

• 需要快速构建和扩展 HTTP 服务的开发场景。
• 需要灵活鉴权和用户识别的服务开发。
• 需要动态注册和启动服务的场景。
• 需要定制中间件以实现特定逻辑的场景。

工具列表

• demo.py：演示工具，用于获取 session_id 和处理用户输入。
• notify.py：通知工具，用于发送日志/通知消息。

常见问题解答

• 如何调试服务？ 可以使用 MCP Inspector 工具进行可视化调试。
• 如何安装依赖？ 推荐使用 uv 或 pip 安装依赖。
• 如何配置环境变量？ 复制 .env.example 文件为 .env，并根据需求修改配置项。

使用教程

使用依赖

1. 环境要求:
2. Python >= 3.13
3. uv (推荐) 或 pip

4. Git

5. 克隆项目: bash git clone https://github.com/purity3/mcp-streamable-http-server.git cd mcp-streamable-http-server

6. 创建并激活虚拟环境 (推荐):

7. 使用 venv: bash python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows

8. 安装依赖:

9. 使用 uv (推荐): bash uv pip install -e .[dev] # 安装项目及其开发依赖

10. 或者使用 pip: bash pip install -e .[dev] # 安装项目及其开发依赖

11. 环境配置:

12. 复制 .env.example 文件为 .env，并根据您的本地环境需求修改其中的配置项 (例如 DATABASE_URL, HOST, PORT 等)。

安装教程

1. 启动服务:
2. 完成上述所有配置和安装步骤后，使用以下命令启动 MCP 服务器： bash uv run server
3. 启动成功后，您可以根据 .env 文件中的 HOST 和 PORT 配置 (默认为 http://0.0.0.0:3000 或 http://localhost:3000) 访问服务。

调试方式

1. 运行 mcp-streamable-http-server: 参照"安装"部分的步骤 6 启动您的本地服务器 (默认 http://localhost:3000)。

2. 启动 MCP Inspector: 在新的终端中执行： bash npx @modelcontextprotocol/inspector Inspector UI 默认运行在 http://localhost:6274。

3. 连接服务器:

4. 打开 Inspector UI (http://localhost:6274)。
5. 设置 Transport Type: streamable-http。
6. 设置 Server URL: 您的服务器地址，例如 http://localhost:3000/mcp (具体路径如 /mcp 可能需根据服务器路由调整)。

7. 如服务器有鉴权，请在 UI 中填写凭证。

8. 开始调试: 连接成功后，即可在 Inspector UI 中查看和调用服务器的 Tools, Resources, Prompts。

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。