从零写一个 MCP Server：用 Python 把内部工具变成 Agent 能调的标准接口

官方 Python SDK 内置了一个高层封装 FastMCP，能把普通 Python 函数直接变成工具，省掉手写 JSON Schema 的活。它需要 Python 3.10+。

# 方式 A：用 uv（推荐，官方脚手架也用这个）
mkdir my-mcp-server && cd my-mcp-server
uv init
uv add "mcp[cli]"

# 方式 B：用传统 venv + pip
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install "mcp[cli]"

# 验证装好了没（不报错即 OK）
python -c "from mcp.server.fastmcp import FastMCP; print('MCP SDK OK')"

新建 server.py，把下面这段原样抄进去。它定义了一个「工单查询」服务，暴露三个工具：

# server.py —— 一个最小可用的 MCP Server
from mcp.server.fastmcp import FastMCP

# ① 创建 Server 实例，名字只是标识，随便起
mcp = FastMCP("ticket-service")

# ② 用装饰器注册工具：函数名=工具名，类型注解=参数 schema，
#    docstring=给模型看的用途说明（非常重要，见下方 warn）
@mcp.tool()
def get_ticket(ticket_id: str) -> dict:
    """根据工单号查询工单详情，返回状态、负责人和更新时间。

    Args:
        ticket_id: 工单编号，例如 "T-10086"。
    """
    # 真实场景这里换成你的数据库/内部 API 调用
    db = {
        "T-10086": {"status": "处理中", "owner": "小王", "updated": "2026-09-12"},
        "T-10087": {"status": "已关闭", "owner": "小李", "updated": "2026-09-10"},
    }
    if ticket_id not in db:
        # 抛异常 → SDK 会转成模型能读懂的 JSON-RPC 错误
        raise ValueError("未找到工单 %s，请确认编号是否正确" % ticket_id)
    return db[ticket_id]

@mcp.tool()
def list_open_tickets(owner: str = "") -> list:
    """列出未关闭的工单；传入 owner 可按负责人过滤。"""
    rows = [
        {"id": "T-10086", "owner": "小王", "status": "处理中"},
        {"id": "T-10088", "owner": "小王", "status": "待受理"},
    ]
    return [r for r in rows if (not owner or r["owner"] == owner)]

# ③ 启动：默认走 stdio（标准输入输出）传输
if __name__ == "__main__":
    mcp.run()

新手最容易犯的错是「一上来就挂进客户端，然后让模型去试错」。正确顺序是：先用官方 Inspector 单独验证工具本身没问题，把「工具坏了」和「模型不会用工具」这两类问题分开。

# 用官方 Inspector 直接连你的 server.py
npx @modelcontextprotocol/inspector python server.py

# 浏览器会打开一个本地 UI（默认 http://localhost:5173）
# 1. 左侧能看到 tools/list 里列出 get_ticket、list_open_tickets
# 2. 选中 get_ticket，参数填 {"ticket_id": "T-10086"}，点 Run
# 3. 右侧看原始 JSON-RPC 返回；再故意传个不存在的编号，看错误长什么样

Tools 是模型主动调用；Resources 是客户端可以按需附加到上下文的数据；Prompts 是可复用的提示词模板。同一套装饰器，写法一样：

# 资源：用 URI 模板寻址，客户端可把它塞进模型上下文
@mcp.resource("ticket://{ticket_id}/history")
def ticket_history(ticket_id: str) -> str:
    """返回某工单最近的处理记录。"""
    return "2026-09-11 已受理；2026-09-12 转技术组"

# 提示词：客户端会把它显示成一条可直接使用的命令
@mcp.prompt()
def triage(ticket_id: str) -> str:
    """生成一段「工单分级」的提示词模板。"""
    return ("请阅读工单 %s 的历史记录，判断它属于"
            "「功能缺陷 / 使用咨询 / 数据问题」中的哪一类，"
            "并给出下一步处理建议。" % ticket_id)

本地 stdio 型 Server 由宿主作为子进程拉起，所以你要在宿主的配置里写清楚「用什么命令启动它」。以 Claude Desktop 为例：

// claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/
// Windows: %APPDATA%\Claude\
{
  "mcpServers": {
    "ticket-service": {
      "command": "python",
      "args": ["C:/absolute/path/to/server.py"],
      "env": { "TICKET_DB_URL": "postgres://..." }
    }
  }
}

三个要点：

1. 路径一律写绝对路径——宿主不会在你以为的目录下启动进程，相对路径是最常见的失败原因。
2. 密钥走 env，不要写死在代码里，也别提交进 git。
3. 改完配置要彻底退出并重启客户端，只关窗口不算重启。

stdio 适合「个人 + 本机」，Server 只服务一个客户端，不暴露网络。一旦要团队共用、或让数据实时来自业务系统，就该换成 Streamable HTTP：一份部署代替每人装一遍，凭证集中管理，调用可审计。传输方式换了，消息格式（JSON-RPC 2.0）不变，工具代码基本不用改。