MCP Server开发实战：从零搭建工具服务

可视化演示

展示工具定义与注册机制、JSON-RPC请求处理通信流程、以及容器化部署与MCP Inspector调试三大核心开发环节。

开餐厅前的准备：MCP 协议速览

想象你要开一家专门给大模型供餐的“后厨外卖店”。在开店之前，你得先搞清楚三个角色的分工：点餐的顾客（LLM 大模型）、跑堂的传菜员（MCP Client 客户端）、以及后厨你自己（MCP Server 服务端）。顾客不会直接冲进后厨，传菜员负责把顾客的“口头需求”翻译成一张标准化的点餐单（JSON-RPC 消息），后厨按单做菜，再经由传菜员把菜端回去。

MCP 协议就是这套“点餐单”的标准格式。它规定了消息怎么传（stdio 或 HTTP）、有哪些类型的“菜品”（tools、resources、prompts）、以及从开门到打烊的完整流程（initialize 初始化 → 能力协商 → 正常服务 → 关闭）。理解了这个三角色模型，你就拿到了往后厨所有菜谱的“总纲”。

技术上说，一次完整的 MCP 交互长这样：客户端先发一个 initialize 请求表明来意，服务端回传自己支持的能力列表（如支持哪些工具），双方“握手”成功后，客户端就可以通过 tools/call 方法点具体的“菜”了。整个过程中，JSON-RPC 2.0 是唯一的“传菜语言”。

1. initialize 初始化：这是“递名片”环节。客户端告诉服务端“我是谁、我需要什么版本协议”，服务端回复“我支持这些能力”。

$$\text{Client} \xrightarrow{\text{initialize 请求}} \text{Server}$$

2. 能力协商：服务端返回支持的协议版本和工具清单，相当于餐厅展示“今日菜单”。

$$\text{Server} \xrightarrow{\text{capabilities 响应}} \text{Client}$$

3. 请求响应循环：完成握手后，进入点餐循环，双方用请求-响应对完成业务。

$$\text{Client} \xrightarrow{\text{tools/call}} \text{Server} \xrightarrow{\text{result}} \text{Client}$$

把三个角色装进脑子里，后面所有的代码都是给这个“后厨”添砖加瓦。记住：传菜员（Client）不一定是你写的，但后厨（Server）是你的核心资产。

选址装修：开发环境搭建

开店第一步不是炒菜，而是把灶台装好。对 MCP Server 开发来说，“灶台”就是 Python 环境加 MCP SDK。官方推荐用 uv 这个工具来管理项目——它就像一位高效的“装修队长”，能一键创建项目骨架、安装依赖、管理虚拟环境，省去你手工配置的琐碎。

用 uv init mcp-server-demo 初始化项目后，你会得到一个干净的项目骨架。接着执行 uv add "mcp[cli]" 把 MCP Python SDK 装进项目里。这个 SDK 就是你的“后厨设备包”——里面预制了 Server 类、工具注册器、传输层封装等所有基础设备，你不用从零造轮子。

SDK 里最核心的两个导入是 Server 和 stdio_server。前者是后厨的“总操作台”，后者是连接传菜员的“传菜口”——它负责从标准输入读取 JSON-RPC 消息，并把响应写回标准输出。理解了这一进一出，你就理解了 MCP Server 的运行骨架。

环境搭建就像装修：今天装好灶台（Python/uv），明天买齐厨具（SDK）。一旦基础设备到位，你就可以开始设计菜单了。

1. 项目初始化：创建项目文件夹和配置文件，相当于划定后厨区域。

$$\text{uv init} \rightarrow \text{pyproject.toml}$$

2. 安装依赖：把 MCP SDK 装进虚拟环境。

$$\text{uv add mcp[cli]} \rightarrow \text{site-packages/mcp}$$

3. 服务实例化：创建 Server 对象，绑定服务名。

$$\text{Server("name")} \rightarrow \text{App}$$

from mcp.server import Server, stdio_server app = Server("demo-server")  # 总操作台

设计菜单：定义你的工具箱

餐厅的灵魂是菜单。对 MCP Server 来说，“菜单”就是 Tool 工具集——大模型能调用的每一个功能都是一道“菜”。而 MCP Python SDK 提供了最优雅的“写菜方式”：装饰器。

用 @app.tool() 装饰一个普通的 Python 函数，这个函数瞬间就变成了一道“标准菜”。函数名是菜名，函数参数是配菜（输入），返回值是成品（输出）。SDK 会自动把你这个函数翻译成 MCP 协议里的 Tool 定义，包括参数的模式（inputSchema）和函数的描述。

这里最关键的技巧是“把描述写得像菜单文案”。比如“查询用户信息”这个函数，如果你只写 查询用户，大模型可能不知道什么时候该调它；但如果你写 根据用户ID查询用户的姓名、邮箱和注册时间，用户ID是整数，大模型就能精准地“点这道菜”。菜单写得好，大模型才知道什么场合点什么菜。

菜单设计决定了顾客体验。一个清晰的工具列表，让大模型“看菜单就知道点什么”；一个混乱的工具列表，则会让大模型像走进一家没有图片的异国餐厅一样手足无措。

1. 装饰器注册：@app.tool() 把函数注册进服务的工具清单。

$$f \xrightarrow{\text{@tool}} \text{Tool}$$

2. 类型标注转 Schema：Python 类型提示被自动转为 JSON Schema 格式。

$$\text{int} \rightarrow \{\text{type: "integer"}\}$$

3. docstring 转描述：函数文档字符串变成工具描述。

$$\text{docstring} \rightarrow \text{description}$$

@app.tool()def get_user(user_id: int) -> dict:    """根据用户ID查询用户信息"""    return {"id": user_id, "name": "小明", "email": "ming@example.com"}

后厨传菜：JSON-RPC 请求处理

现在后厨设备有了，菜单也写好了，接下来最关键的一环是“传菜流程”——也就是 JSON-RPC 消息处理。如果把 MCP 比作餐厅的传菜系统，那 JSON-RPC 就是传菜员手里的“单子”：每张单子上写着菜名（method）、配菜（params）和单号（id）。

标准 JSON-RPC 2.0 的消息长这样：{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_user","arguments":{"user_id":123}}}。服务端要做的事情是：解析这张单子，认准菜名（路由到对应 Tool），核对配菜（参数校验），然后下厨做菜（执行函数），最后把成品装盘（返回结果）按原路送回（带同一个 id）。

SDK 已经帮我们封装好了这套“传菜管线”。你在定义 Tool 时，SDK 底层自动注册了 tools/call 的处理逻辑：收到请求后，它根据 params.name 找到对应的 Python 函数，把 params.arguments 解包成函数参数去调用，最后把返回值序列化成 JSON-RPC 响应。你只需要关心“炒菜”，传菜的事交给 SDK。

如果出了问题呢？比如大模型点了一道不存在的菜，SDK 会返回一个 -32602 错误码（无效参数）；如果函数内部抛出异常，则返回 -32603（内部错误）。这些错误码就是后厨的“客诉单”，帮助调用方快速定位问题。

1. 解析请求：把接收到的 JSON 字符串解析为对象。

$$\text{JSON string} \xrightarrow{\text{json.loads}} \text{dict}$$

2. 路由分发：根据 method 字段找到对应的工具处理函数。

$$\text{method} \rightarrow \text{handler}$$

3. 参数绑定：把 arguments 字典解包为函数关键字参数。

$$\{\text{args}\} \rightarrow f(\text{kwargs})$$

4. 错误响应：异常时返回带错误码的响应对象。

$$\text{Error} \rightarrow \{"\text{code}": -32602, "\text{message}": "..."\}$$

后厨传菜流程越标准，翻台率越高。SDK 帮你把传菜管线做好了，你把精力聚焦在“菜品的味道”（业务逻辑）上即可。

试营业：用 MCP Inspector 调试

餐厅开业前，一定要先试营业。MCP 生态里的“试营业工具”就是 MCP Inspector——一个可视化调试面板。它就像一位“神秘顾客”，能模拟大模型的点餐行为，把你后厨的每一个环节都“看”得清清楚楚。

启动 Inspector 的命令是 mcp inspector（在使用 mcp[cli] 安装的前提下）。它会自动拉起一个本地 Web 面板和一个指向你 Server 的连接。在这个面板里，你可以看到工具列表、手动调用某个工具并观察完整请求响应、查看服务端日志——相当于餐厅里装了“后厨直播摄像头”。

调试的核心技巧是“分步观察”：先看 initialize 是否握手成功，再看 tools/list 能否拉到工具清单，最后才测 tools/call 的实际调用。如果某一步出问题，查看 Inspector 捕获的原始 JSON 消息，几乎能立刻定位是协议层问题还是业务逻辑问题。

有了 Inspector 这个“后厨直播”，你不再需要盲猜问题出在哪里。它把你的 Server 变成一个透明的玻璃房：请求怎么进来的、怎么路由的、怎么响应的，一目了然。

正式开业：部署与发布

试营业没问题了，就要正式开业。正式营业意味着你的后厨要“全天候运转”——这个过程就是部署与发布。MCP Server 的部署，核心是“让后厨时刻保持接待状态”。

由于 MCP Server 走的是 stdio 传输，它本质上是“被拉起”的进程：由客户端（如 Claude Desktop）启动并管理。但如果要在服务器上长期运行，你需要考虑三件事：进程守护、环境配置、容器化。

进程管理上，用 systemd 或 supervisor 这类工具守护你的 Server 进程，这样哪怕程序崩溃了，也能自动重启——就像餐厅的“备用发电机”，停电了自动切换。环境配置上，把数据库密码、API Key 之类的敏感信息放进环境变量而不是硬编码在代码里——就像后厨的“配方锁在保险柜”，只给授权的人看。容器化上，用 Docker 打包你的 Server，让它在任何机器上都能以完全一致的方式运行——就像“中央厨房统一配送”，搬到哪家门店味道都一样。

部署是把代码变成服务的关键一跃。守护进程保命、环境变量保安全、容器化保一致——这三板斧砍完，你的 MCP Server 就真的“开业大吉”了。

FROM python:3.12-slimCOPY . /appWORKDIR /appRUN pip install uv && uv sync --frozenCMD ["uv", "run", "python", "server.py"]

AI 应用场景

Python 演示

import jsonimport sqlite3from typing import Anyfrom mcp.server import Server, stdio_server app = Server("db-query-server")DB_PATH = "app.db"  def _get_conn() -> sqlite3.Connection:    """建立数据库连接"""    conn = sqlite3.connect(DB_PATH)    conn.row_factory = sqlite3.Row    return conn  @app.tool()def query_user(user_id: int) -> dict[str, Any]:    """根据用户ID查询用户信息，返回姓名和邮箱"""    conn = _get_conn()    row = conn.execute(        "SELECT name, email FROM users WHERE id = ?", (user_id,)    ).fetchone()    conn.close()    if row is None:        return {"found": False}    return {"found": True, "name": row["name"], "email": row["email"]}  @app.tool()def log_event(event_type: str, message: str) -> dict[str, Any]:    """写一条事件日志到数据库，返回日志ID"""    conn = _get_conn()    cur = conn.execute(        "INSERT INTO logs (event_type, message) VALUES (?, ?)",        (event_type, message),    )    conn.commit()    log_id = cur.lastrowid    conn.close()    return {"log_id": log_id}  async def main() -> None:    """程序入口：通过stdio通道运行服务"""    async with stdio_server() as (read_stream, write_stream):        await app.run(read_stream, write_stream, app.create_initialization_options())  if __name__ == "__main__":    import asyncio     asyncio.run(main())

1. app = Server("db-query-server")创建 MCP 服务实例，相当于“后厨总操作台”
2. def _get_conn() -> sqlite3.Connection封装数据库连接，每个请求独立开合
3. @app.tool()装饰器把函数注册为 MCP 工具
4. def query_user(user_id: int) -> dict[str, Any]定义查询工具，注意类型标注决定参数模式
5. row_factory = sqlite3.Row让查询结果支持按字段名访问
6. async with stdio_server() as (read_stream, write_stream)建立标准输入输出双向通道
7. await app.run(read_stream, write_stream, ...)启动服务，监听请求并自动路由

常见误区

面试题