Metadata-Version: 2.4
Name: mcp-py-service
Version: 0.1.0
Summary: MVP MCP server in Python with extensible transport layout.
Author: Vibecoding Backend Team
License: Proprietary
Keywords: mcp,model-context-protocol,cursor,stdio,streamable-http
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: pymysql
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=5.1.1; extra == "dev"

# mcp-py-service (MVP)

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

## 1. 目录结构

```text
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. 安装依赖

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

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

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

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

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

## 3. 本地运行

### 3.1 stdio

```bash
python -m mcp_py_service.main --transport stdio
```

### 3.2 streamable-http

```bash
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`，也可直接使用：

```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 连通性验证示例

先启动服务：

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

新开一个终端执行：

```bash
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 完整示例

先启动服务：

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

新开一个终端执行：

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

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

```bash
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`**（行为与有状态不同，按需选用）。
