mcp-py-service 0.1.0

MVP MCP server in Python with extensible transport layout.

mcp-py-service (MVP)

这是一个使用 Python 实现的最小可运行 MCP Server 示例，目录结构按“可扩展多场景（stdio / http）”设计，当前已提供 stdio 和 streamable-http 两种 MVP 启动方式。

1. 目录结构

mcp-py-service/
  ├─ src/
  │  └─ mcp_py_service/
  │     ├─ server.py                 # 业务工具定义（与传输层解耦）
  │     ├─ main.py                   # 启动入口，按 transport 分发
  │     └─ transports/
  │        ├─ stdio.py               # MVP 已实现
  │        └─ http.py                # MVP 已实现（streamable-http）
  ├─ examples/
  │  └─ cursor-mcp.json              # Cursor MCP 配置示例
  ├─ pyproject.toml
  └─ README.md

这种结构可以保证后续新增 http/sse、鉴权、日志、场景化工具包时，不需要重构核心目录。

2. 安装依赖

cd test-mcp-service/mcp-py-service
pip install -e .

若网络/代理导致 pip install -e . 在“Installing build dependencies”阶段失败，可使用以下命令（方案 A）：

pip install -e . --no-build-isolation

若仍因依赖下载受限失败，可先确认本地已安装 mcp，再执行：

pip install -e . --no-build-isolation --no-deps

3. 本地运行

3.1 stdio

python -m mcp_py_service.main --transport stdio

3.2 streamable-http

python -m mcp_py_service.main --transport http --host 127.0.0.1 --port 8000 --path /mcp

可选参数：

• --json-response
• --stateless-http

当前 MVP 提供工具：

• echo(text: str) -> str
• add(a: float, b: float) -> float
• queryTestInfo(base_url: str | None = None) -> str：请求 sy-backend-service 免 Token 接口 GET /tdengine/test/health（SecurityConfig 中 permitAll("/tdengine/test/**")），用于验证 Cursor → MCP → 业务 HTTP 全链路。默认基址 http://127.0.0.1:8099/api，可通过环境变量 SY_BACKEND_BASE_URL 或工具参数 base_url 覆盖（需含 context-path，一般以 /api 结尾）。

4. Cursor MCP JSON 配置

参考 examples/cursor-mcp.json，也可直接使用：

{
  "mcpServers": {
    "mcp-py-service-mvp": {
      "command": "python",
      "args": [
        "-m",
        "mcp_py_service.main",
        "--transport",
        "stdio"
      ],
      "cwd": "E:/project/2026/ai/openpoject/vibecoding-backend/test-mcp-service/mcp-py-service"
    }
  }
}

5. 后续扩展建议

• 在 server.py 中拆分场景化工具模块（如 tools/docs.py、tools/db.py）
• 文档问答/知识库检索场景：把项目文档、接口文档、运维手册挂成 MCP 资源与工具，支持“查文档 + 总结 + 版本对比”
• 数据库查询与分析场景：提供只读 SQL 查询工具（带白名单/限流），用于排查数据、统计报表、数据核对
• 增加 transports/sse.py，补齐 SSE 场景
• 增加配置层（config.py）和统一日志、错误码封装

6. HTTP 连通性验证示例

先启动服务：

python -m mcp_py_service.main --transport http --host 127.0.0.1 --port 8000 --path /mcp

新开一个终端执行：

python examples/http-client-demo.py --base-url http://127.0.0.1:8000 --path /mcp

说明：

• 脚本会先 GET /mcp 做基础连通性检查
• 再发送一个最小 initialize JSON-RPC 请求模板（POST /mcp）
• 返回状态码 < 400 可认为端点基础可用
• 若出现 HTTP 406 且提示 Accept / text/event-stream：streamable HTTP 要求请求头包含正确 Accept（示例脚本已内置；自建客户端时请对齐）

7. tools/list + tools/call 完整示例

先启动服务：

python -m mcp_py_service.main --transport http --host 127.0.0.1 --port 8000 --path /mcp

新开一个终端执行：

python examples/http-tools-demo.py --base-url http://127.0.0.1:8000 --path /mcp

打印完整请求/响应原文（调试模式）：

python examples/http-tools-demo.py --base-url http://127.0.0.1:8000 --path /mcp --raw

该脚本会按顺序执行：

• initialize
• notifications/initialized
• tools/list
• tools/call（调用 echo 和 add）

说明：streamable HTTP 的响应常为 SSE（text/event-stream），脚本已解析 data: 行或逐行 JSON，勿用纯 json.loads(整段响应)。

若出现 Missing session ID：有状态模式下，initialize 的响应头会返回 mcp-session-id，后续请求必须在请求头中携带；http-tools-demo.py 已自动处理。若希望无会话（每请求独立），可启动服务时加 --stateless-http（行为与有状态不同，按需选用）。