User MCP Servers

Streamable HTTP MCP Server：通过 HTTP 调用独立的 User REST API（my-user-service），覆盖 MCP 三要素（Tools / Resources / Prompts）。

本仓库 不包含 FastAPI / SQLite / JWT 实现。MCP 只依赖 API_BASE_URL。

架构

┌──────────────────────┐          HTTP /mcp          ┌──────────────────────┐
│  MCP Client          │ ──────────────────────────▶ │  MCP Server :3001    │
│  (Cursor / Inspect)  │                             │  Streamable HTTP     │
└──────────────────────┘                             └──────────┬───────────┘
                                                                │ httpx
                                                                ▼
                                                     ┌──────────────────────┐
                                                     │  User REST API :8000 │
                                                     │  (my-user-service)   │
                                                     └──────────────────────┘

快速开始

先启动 API（另一个仓库）：

cd /Users/jasqia/00D_PythonProject/my-user-service
source .venv/bin/activate
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

再启动 MCP：

cd /Users/jasqia/00D_PythonProject/my-mcp-servers
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # 可选；默认 API_BASE_URL=http://127.0.0.1:8000

python -m mcp_server

或一条命令拉起两边（API 目录默认同级的 ../my-user-service）：

./scripts/start_services.sh
# 自定义 API 仓库路径：
# USER_SERVICE_ROOT=/path/to/my-user-service ./scripts/start_services.sh

• MCP 端点：http://127.0.0.1:3001/mcp
• REST 文档：http://127.0.0.1:8000/docs

端口被占用（Address already in use）

启动时如果看到：

ERROR:    [Errno 48] error while attempting to bind on address ('127.0.0.1', 3001): [errno 48] address already in use

说明 3001 已被占用（拆仓后常见原因：旧仓库 my-mcp 里残留的 python -m mcp_server 还在跑）。

1. 查出占用进程：

lsof -nP -iTCP:3001 -sTCP:LISTEN

输出里的 PID 就是占用端口的进程号，例如：

COMMAND   PID   USER   FD   TYPE  ...
Python  83386 jasqia   ...  TCP 127.0.0.1:3001 (LISTEN)

2. 确认是哪个项目（可选）：

ps -p <PID> -o pid,command=

3. 停掉该进程后重试启动：

kill <PID>
# 若未退出：kill -9 <PID>

python -m mcp_server

4. 确认端口已空闲：

lsof -nP -iTCP:3001 -sTCP:LISTEN || echo "port 3001 is free"

如果不想停旧进程，也可以换端口：

MCP_PORT=3002 python -m mcp_server

Cursor / Inspect 需改连 http://127.0.0.1:3002/mcp。API :8000 被占用时，处理方式见 my-user-service README。

MCP 三要素

Tools

用户

• register_user / login_user / get_current_user / update_user_profile

账单

• create_bill / list_my_bills / list_shared_bills / get_bill
• update_bill / delete_bill
• share_bill / unshare_bill
• like_bill / unlike_bill

Resources

• user://api/health — API 健康检查
• user://docs/overview — 项目说明
• user://profile/{access_token} — 当前用户资料
• bill://mine/{access_token} — 我的账单列表
• bill://shared/{access_token} — 分享给我的账单
• bill://item/{access_token}/{bill_id} — 单条账单

Prompts

• welcome_new_user — 欢迎新用户
• help_update_profile — 协助更新资料
• help_create_bill — 协助记账
• help_share_bill — 协助分享账单
• help_like_bill — 协助点赞

Cursor 连接（Streamable HTTP）

{
  "mcpServers": {
    "user-mcp": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

本地验证

source .venv/bin/activate
pip install -r requirements-dev.txt   # 首次需要

# 单元 / 协议测试（不需要先起 API）
make test
# make test-e2e   # L4 真 Streamable HTTP

# 手工 E2E 冒烟（需 API + MCP 都已启动）
python scripts/test_mcp_user_client.py
python scripts/test_mcp_bill_client.py

测试分层说明：docs/MCP_L2_L4_EXPLAINED.zh.md

Inspect 评测

先启动 API + MCP，再：

pip install -r requirements-inspect.txt
export GOOGLE_API_KEY='...'
./scripts/run_inspect_gemini.sh google/gemini-3.6-flash evals/bill_mcp_scenarios.py
./scripts/run_inspect_gemini.sh google/gemini-3.6-flash suite

# 无 API Key：用 mockllm 本地验证 Inspect→MCP 接线
python scripts/run_inspect_user_mcp_smoke_mock.py

说明见 docs/INSPECT_MCP.zh.md。

目录结构

my-mcp-servers/
├── mcp_server/               # Streamable HTTP MCP Server
│   ├── config.py             # MCP_HOST / MCP_PORT / API_BASE_URL
│   ├── __main__.py           # python -m mcp_server
│   └── server.py             # Tools / Resources / Prompts
├── tests/mcp/
├── evals/                    # Inspect 评测
├── scripts/
├── docs/
├── Makefile
├── pytest.ini
├── requirements.txt
└── README.md