第 5 章:写一个能用的 Server
这一章不写 demo,写一个"小书店"的真实接口:查库存、开工单、读配置、给话术。
学习目标
- 用 Python SDK 起一个 server,20 行内跑通
- 加一个工具、一个资源、一个提示词,各自写对
- 用两种传输启动,并用 Inspector 验证
- 知道什么样的工具描述"模型才用得对"
5.1 最小可运行
bash
pip install mcppython
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("bookstore")
@mcp.tool()
def ping() -> str:
"""连通性检查,返回 pong。"""
return "pong"
if __name__ == "__main__":
mcp.run(transport="stdio")
FastMCP的导入路径、run()的参数在不同版本里可能有差异,装完先看官方 README 的当前示例,别照抄旧教程。
三行关键:创建实例 → 注册能力 → 启动传输。后面所有内容都是在"注册能力"上做文章。
5.2 加工具:一个只读,一个有副作用
python
@mcp.tool()
def query_stock(sku: str, warehouse: str = "main") -> dict:
"""查询某仓库中某个商品的库存。
Args:
sku: 商品编码,如 A100-BLK
warehouse: 仓库名,默认 main(另有 wh2、wh3)
"""
return {"sku": sku, "warehouse": warehouse, "qty": STOCK.get((sku, warehouse), 0)}
@mcp.tool()
def create_ticket(title: str, detail: str, priority: str = "normal") -> dict:
"""为售后问题创建工单。会写入系统,属于有副作用的操作。
Args:
title: 一句话摘要,不超过 40 字
detail: 问题详情
priority: low / normal / high
"""
tid = TICKETS.create(title=title, detail=detail, priority=priority)
return {"ticket_id": tid, "status": "created"}两个工具的差别不止在功能:
query_stock | create_ticket | |
|---|---|---|
| 副作用 | 无 | 有(写数据) |
| 模型该不该随意调 | 可以 | 需要更明确的条件 |
| 描述里要不要强调 | 不必 | 要写"会写入系统" |
一个好习惯:在 description 里把"有副作用"说出来。模型看到"会写入系统"会更谨慎,这比你在提示词里反复叮嘱有效。
5.3 加资源:配置与文档
python
@mcp.resource("config://store/policies")
def policies() -> str:
"""退货与保修政策的只读副本。"""
return open("policies.md", encoding="utf-8").read()
@mcp.resource("config://store/products/{sku}")
def product_info(sku: str) -> str:
"""按 SKU 读取商品资料(URI 模板)。"""
return PRODUCTS.render(sku)URI 模板 {sku} 让"每个商品一份资料"变成可枚举的模式,而不是注册一万个资源。
5.4 加提示词:团队的标准问法
python
@mcp.prompt()
def handle_complaint(order_id: str, issue: str) -> str:
return f"""你是售后专员。请处理以下投诉:
订单号:{order_id}
问题:{issue}
要求:
1. 先判断属于哪类问题(质量 / 物流 / 使用);
2. 给出处理方案,并说明依据的是哪条政策;
3. 如果需要补偿,给出金额区间与理由。
"""它适合"每次都一样的流程",用户点一下就得到一个结构化的开场。
5.5 两种传输
python
import os
if __name__ == "__main__":
if os.getenv("MCP_TRANSPORT") == "http":
mcp.run(transport="streamable-http") # 具体参数以官方文档为准
else:
mcp.run(transport="stdio")5.6 用 Inspector 自测
bash
npx @modelcontextprotocol/inspector python server.py按顺序验证四件事:
initialize返回的能力里有没有tools、resources、prompts;tools/list里两个工具的inputSchema是不是你想要的样子;- 调一次
query_stock,看返回 content; - 故意传错参数(比如
qty传字符串),看是否返回isError。
第 4 步最关键:错误路径没测过,线上一定会出问题。
5.7 让工具"好用"的五个细节
| 细节 | 反例 | 正例 |
|---|---|---|
| 描述写清用途 | "query_stock 函数" | "查询某仓库某 SKU 的库存数量" |
| 参数给默认值 | 三个必填 | 只必填 sku,warehouse 默认 main |
| 枚举写进描述 | "priority 随便传" | "low / normal / high" |
| 返回值别太大 | 返回整张表 | 只返回需要的字段 |
| 错误可读 | raise ValueError | 返回 isError=true + 人话说明 |
还有一条容易忽略:工具数量别太多。50 个工具塞给模型,选择准确率会掉。按场景拆 server,比一个大而全的 server 更好用。
5.8 一次调用的链路
注意中间那一层"业务函数":MCP server 不应该直接写 SQL,它应该调用你已有的服务层。否则同一套逻辑要在 CLI、Web、MCP 里各写一遍。
5.9 常见失败
| 现象 | 原因 |
|---|---|
| 宿主连不上 | 路径不对、依赖没装、stdout 被日志污染 |
| 工具列不出来 | 装饰器没生效、server 没启动到 list 阶段 |
| 参数校验总失败 | schema 太严(additionalProperties: false + 模型爱加字段) |
| 返回被截断 | content 太大,宿主有长度上限 |
| 中文乱码 | 没设 UTF-8,或读文件没指定编码 |
本章小结
| 要点 | 说明 |
|---|---|
| 三步骤 | 建实例、注册能力、启动传输 |
| 工具 | 描述写用途、参数给默认、副作用要说出来 |
| 资源 | URI + 模板,只读 |
| 提示词 | 团队标准问法 |
| 传输 | 同一份代码,两种启动 |
| 自测 | Inspector 四步,必须测错误路径 |
| 架构 | server 调服务层,不直连数据库 |
下一章
server 能跑了,最后一章讲怎么把它接进 Agent,以及上线后必须面对的安全问题。