Skip to content
Lv4MCP 协议进度 5 / 6

第 5 章:写一个能用的 Server ​

这一章不写 demo,写一个"小书店"的真实接口:查库存、开工单、读配置、给话术。


学习目标 ​

  • 用 Python SDK 起一个 server,20 行内跑通
  • 加一个工具、一个资源、一个提示词,各自写对
  • 用两种传输启动,并用 Inspector 验证
  • 知道什么样的工具描述"模型才用得对"

5.1 最小可运行 ​

bash
pip install mcp
python
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_stockcreate_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")
一个 server,四类能力,两条传输server.pytool · query_stock(只读)tool · create_ticket(写)resource · config://policiesprompt · handle_complaint同一套定义,两种启动方式stdio宿主拉起,本机使用streamable-http远程、多人、可加鉴权Inspector / 宿主initialize → tools/list → tools/call远程客户端POST /mcp,带 Authorization写 server 的顺序建议:先一个工具跑通 → 再加第二个 → 最后补资源和提示词。

5.6 用 Inspector 自测 ​

bash
npx @modelcontextprotocol/inspector python server.py

按顺序验证四件事:

  1. initialize 返回的能力里有没有 tools、resources、prompts;
  2. tools/list 里两个工具的 inputSchema 是不是你想要的样子;
  3. 调一次 query_stock,看返回 content;
  4. 故意传错参数(比如 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,以及上线后必须面对的安全问题。

本文阅读--次|全站访问--次|访客--人