Claude Code MCP 服务器开发：把本地工具推上 Streamable HTTP

mkdir changelog-mcp && cd changelog-mcp
uv init --no-readme
uv add fastmcp

# server.py —— 同一份代码，传输方式由命令行参数决定
import sqlite3, time, uuid
from contextlib import closing
from fastmcp import FastMCP

DB = "/data/changelog.db"  # 容器内持久化路径；本机调试可改 ./changelog.db

def _conn():
    c = sqlite3.connect(DB)
    c.execute("""CREATE TABLE IF NOT EXISTS changes(
        id TEXT PRIMARY KEY, ts INTEGER, title TEXT, author TEXT, detail TEXT)""")
    return c

mcp = FastMCP("changelog")

@mcp.tool()
def add_change(title: str, author: str, detail: str = "") -> str:
    """新增一条团队变更记录。title 简述、author 提交人、detail 可选正文。"""
    cid = uuid.uuid4().hex[:8]
    with closing(_conn()) as c:
        c.execute("INSERT INTO changes VALUES(?,?,?,?,?)",
                  (cid, int(time.time()), title, author, detail))
        c.commit()
    return f"已记录 {cid}: {title}（{author}）"

@mcp.tool()
def list_changes(days: int = 7) -> str:
    """列出近 days 天内的变更，默认 7 天。"""
    cutoff = int(time.time()) - days * 86400
    with closing(_conn()) as c:
        rows = c.execute(
            "SELECT id, ts, title, author FROM changes WHERE ts>=? ORDER BY ts DESC",
            (cutoff,)).fetchall()
    if not rows:
        return f"近 {days} 天无变更记录。"
    return "\n".join(f"[{r[0]}] {time.strftime('%m-%d', time.localtime(r[1]))} {r[2]} @{r[3]}" for r in rows)

@mcp.tool()
def get_change(change_id: str) -> str:
    """按 id 查单条变更详情。"""
    with closing(_conn()) as c:
        r = c.execute("SELECT id, ts, title, author, detail FROM changes WHERE id=?",
                      (change_id,)).fetchone()
    if not r:
        return f"找不到 id={change_id}"
    return f"[{r[0]}] {r[2]}\n提交人: {r[3]}\n时间: {time.strftime('%Y-%m-%d %H:%M', time.localtime(r[1]))}\n详情: {r[4] or '（无）'}"

if __name__ == "__main__":
    mcp.run()  # 默认 stdio；传输由 CLI 参数覆盖

# 方式 A：stdio（本机自用，与 stdio 教程里的写法一致）
fastmcp run server.py

# 方式 B：Streamable HTTP（远程部署，团队共享）
fastmcp run server.py \
  --transport streamable-http \
  --host 0.0.0.0 --port 8000

FastMCP streamable-http server running on http://0.0.0.0:8000/mcp

# Dockerfile
FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir uv
COPY pyproject.toml uv.lock* ./
COPY server.py ./
RUN uv pip install --system --no-cache .
# 持久化目录（数据库落盘处）
RUN mkdir -p /data
EXPOSE 8000
CMD ["fastmcp", "run", "server.py", \
     "--transport", "streamable-http", \
     "--host", "0.0.0.0", "--port", "8000"]

docker build -t changelog-mcp:latest .

# 仅本机访问 → 绑 127.0.0.1；团队访问 → 0.0.0.0 + 反向代理上 TLS
docker run -d --name changelog \
  -p 8000:8000 \
  -v $(pwd)/data:/data \
  changelog-mcp:latest

# 健康探活：发一条 initialize
curl -sS -X POST http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

# 先对比：本地 stdio 接法
claude mcp add --transport stdio changelog-local -- uv run server.py

# 远程 HTTP 接法：注意选项必须在名字和 URL 之前
export MCP_TOKEN="$(openssl rand -hex 24)"   # 与服务器侧约定
claude mcp add \
  --transport http \
  --scope user \
  --header "Authorization: Bearer ${MCP_TOKEN}" \
  changelog https://changelog.internal.corp/mcp

claude mcp list          # 列出所有已配服务器及连接状态
claude mcp get changelog # 看单个服务器详情
claude mcp remove changelog

{
  "mcpServers": {
    "changelog": {
      "type": "http",
      "url": "https://changelog.internal.corp/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

flowchart LR
    subgraph Dev["工程师 A 本机"]
        CC1[Claude Code]
    end
    subgraph CI["CI Runner"]
        CC2[claude -p 无头]
    end
    subgraph Dev2["工程师 B 本机"]
        CC3[Claude Code]
    end

    CC1 -->|"HTTPS + Bearer"| Proxy
    CC2 -->|"HTTPS + Bearer"| Proxy
    CC3 -->|"HTTPS + Bearer"| Proxy

    Proxy["反向代理 nginx/Caddy\nTLS 终结 + Origin 校验"]
    Proxy --> LB["负载均衡\n无状态可水平扩"]
    LB --> S1["FastMCP 容器 1\n/mcp"]
    LB --> S2["FastMCP 容器 2\n/mcp"]
    S1 --> DB[("共享 PostgreSQL\n团队变更日志")]
    S2 --> DB

sequenceDiagram
    participant CC as Claude Code
    participant S as FastMCP /mcp
    CC->>S: POST initialize (protocolVersion, capabilities)
    S-->>CC: 200 + Mcp-Session-Id: abc123 (可选)
    CC->>S: POST notifications/initialized
    CC->>S: POST tools/list
    S-->>CC: [add_change, list_changes, get_change]
    CC->>S: POST tools/call add_change(...)
    S-->>CC: text/event-stream (流式结果) 或 application/json
    Note over CC,S: 长任务时: GET /mcp 开 SSE 收进度推送