┌──────────────────────┐          HTTP /mcp          ┌──────────────────────┐
│  MCP Client          │ ──────────────────────────▶ │  MCP Server :3001    │
│  (Cursor / scripts)  │                             │  Streamable HTTP     │
└──────────────────────┘                             │  tools/resources/    │
                                                     │  prompts             │
                                                     └──────────┬───────────┘
                                                                │ httpx
                                                                ▼
                                                     ┌──────────────────────┐
                                                     │  User REST API :8000 │
                                                     │  FastAPI + SQLite    │
                                                     └──────────────────────┘

cd /Users/jasqia/00D_PythonProject/my-mcp
source .venv/bin/activate
pip install -r requirements.txt

# 终端 1：启动 REST API
uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload

# 终端 2：启动 MCP Server（Streamable HTTP）
python -m mcp_server
# 等价：python -m mcp_server.server

# 登录拿 TOKEN 后创建账单
curl -s http://127.0.0.1:8000/api/bills \
  -H "Authorization: Bearer TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"午餐","amount":"32.50","category":"food","spent_at":"2026-08-11"}'

# 分享给 bob
curl -s http://127.0.0.1:8000/api/bills/1/share \
  -H "Authorization: Bearer TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"username":"bob"}'

# 点赞
curl -s http://127.0.0.1:8000/api/bills/1/like \
  -X POST \
  -H "Authorization: Bearer TOKEN"

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

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

# 推荐：一条命令跑 pytest（无需先起服务）
make test
# 或：
# make test-api
# make test-mcp
# make test-e2e   # 只跑 L4 Streamable HTTP 等 e2e 标记

# 测试分层说明（L2 Mock / L4 真传输等）：docs/MCP_L2_L4_EXPLAINED.zh.md

# 手工 E2E 冒烟（需先启动 API；MCP 脚本还需启动 MCP）
python scripts/test_user_client.py
python scripts/test_bill_client.py
python scripts/test_mcp_user_client.py
python scripts/test_mcp_bill_client.py

my-mcp/
├── app/                      # FastAPI REST API
│   ├── __init__.py
│   ├── main.py               # 应用入口
│   ├── config.py             # 配置（端口、数据库、JWT）
│   ├── database.py           # SQLAlchemy / SQLite
│   ├── models.py             # User / Bill / BillShare / BillLike
│   ├── schemas.py            # 请求/响应 Pydantic 模型
│   ├── auth.py               # 密码哈希、JWT、鉴权依赖
│   ├── services.py           # 用户业务逻辑
│   ├── bill_services.py      # 账单业务逻辑
│   └── routers/
│       ├── __init__.py
│       ├── users.py          # /api/users
│       └── bills.py          # /api/bills
├── mcp_server/               # Streamable HTTP MCP Server
│   ├── __init__.py
│   ├── __main__.py           # python -m mcp_server
│   └── server.py             # Tools / Resources / Prompts
├── tests/                        # pytest 套件
│   ├── conftest.py
│   ├── api/
│   │   ├── test_users.py
│   │   └── test_bills.py
│   └── mcp/
│       ├── surface.golden.json   # L1b 表面指纹
│       ├── test_tool_contract.py
│       ├── test_surface_drift.py
│       ├── test_protocol_behavior.py
│       ├── test_resources_prompts.py
│       ├── test_tool_http_wiring.py          # L2 Mock：tool→REST 接线
│       └── test_streamable_http_transport.py # L4：真 Streamable HTTP /mcp
├── scripts/
│   ├── http_helpers.py           # REST 测试公共工具
│   ├── mcp_helpers.py            # MCP 测试公共工具
│   ├── test_user_client.py       # 手工 E2E：用户 REST
│   ├── test_bill_client.py       # 手工 E2E：账单 REST
│   ├── test_mcp_user_client.py   # 手工 E2E：MCP 用户
│   └── test_mcp_bill_client.py   # 手工 E2E：MCP 账单
├── data/
│   └── users.db                  # SQLite 数据库（运行后生成）
├── Makefile
├── pytest.ini
├── requirements.txt
├── requirements-dev.txt
├── TESTING_IMPROVEMENT_PLAN.zh.md
└── README.md