🍽️ MCP 完全指南：AI 的"万能服务员"协议

第一章：故事开始 —— 一家"没有菜单"的餐厅

想象你开了一家餐厅，请了一个超级聪明但什么都不记得的厨师（这就是 AI 模型）。

厨师：“你要我做什么菜？”
你：“做个红烧肉。”
厨师：“红烧肉是什么？用什么材料？怎么做？我全不知道。”

厨师很聪明，学什么都快，但他完全不了解外面的世界 —— 不知道你的冰箱里有什么、不知道怎么查菜谱、不知道怎么开火。

以前，每个餐厅老板都发明自己的方法来跟厨师沟通：

• 张家用纸条传递
• 李家用对讲机喊话
• 王家自己造了一套手语

结果就是：每个厨师的"外挂"都不通用，换个餐厅就得重新学一套。

直到有一天，整个餐饮界统一了一个协议 —— MCP（Model Context Protocol，模型上下文协议） 。

第二章：核心架构 —— 四个角色各司其职

┌─────────────────────────────────────────────────────────────┐
│                        你的电脑/手机                          │
│                                                             │
│  ┌──────────────┐                                           │
│  │   Host 宿主   │  ← 比如 Claude Desktop、VS Code 插件      │
│  │  (餐厅大堂)   │                                           │
│  └──────┬───────┘                                           │
│         │ 1对1 创建                                           │
│         ▼                                                   │
│  ┌──────────────┐     ┌──────────────┐                      │
│  │ Client 客户端 │────▶│ Server 服务端 │  ← 天气后厨          │
│  │  (服务员A)    │◀────│  (中餐后厨)   │                      │
│  └──────────────┘     └──────────────┘                      │
│         │                                                   │
│  ┌──────────────┐     ┌──────────────┐                      │
│  │ Client 客户端 │────▶│ Server 服务端 │  ← 文件后厨          │
│  │  (服务员B)    │◀────│  (西餐后厨)   │                      │
│  └──────────────┘     └──────────────┘                      │
│         │                                                   │
│  ┌──────────────┐     ┌──────────────┐                      │
│  │ Client 客户端 │────▶│ Server 服务端 │  ← 数据库后厨        │
│  │  (服务员C)    │◀────│  (甜点后厨)   │                      │
│  └──────────────┘     └──────────────┘                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

🏨 用餐厅术语理解

MCP 概念	餐厅比喻	真实角色	举例
Host	餐厅大堂	运行 AI 的主程序	Claude Desktop、Cursor
Client	服务员	协议翻译官（Host 自动创建）	每个 Server 对应一个 Client
Server	后厨	提供能力的程序	天气服务、文件系统、数据库
Tool	厨师技能	模型可调用的函数	get_weather()、read_file()
Resource	食材库	服务器暴露的数据	天气数据、文件内容、数据库记录
Prompt	套餐菜单	预定义的提示模板	“分析天气并给建议”

关键规则：

• 一个 Host 可以有多个 Client
• 一个 Client 只连接一个 Server（一对一）
• Host 负责管理所有 Client 的生命周期（启动、关闭）
• Client 和 Server 之间用 JSON-RPC 2.0 通信（就像服务员用标准格式写点菜单）

第三章：三大能力 —— 后厨能做什么？

🔧 Tool（工具）—— 厨师的"动手能力"

工具就是模型可以主动调用的函数。就像厨师说：“我要炒菜，帮我开火！”

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("kitchen-server")

@mcp.tool()
def stir_fry(ingredient: str, duration: int) -> str:
    """
    炒菜工具
    
    Args:
        ingredient: 食材名称
        duration: 炒制时间（分钟）
    
    Returns:
        炒菜结果描述
    """
    return f"用大火翻炒{ingredient}，{duration}分钟后出锅，香气四溢！"

@mcp.tool()
def check_fridge(item: str) -> str:
    """检查冰箱里有没有某个食材"""
    fridge = ["鸡蛋", "西红柿", "牛肉", "葱姜蒜"]
    if item in fridge:
        return f"冰箱里有{item}，新鲜度良好 ✓"
    return f"冰箱里没有{item} ✗"

模型的思考过程：

用户: "帮我做个西红柿炒蛋"
模型内心: 我需要：
  1. 先 check_fridge("西红柿") → "冰箱里有西红柿 ✓"
  2. 再 check_fridge("鸡蛋")   → "冰箱里有鸡蛋 ✓"  
  3. 然后 stir_fry("西红柿鸡蛋", 5) → "用大火翻炒..."
  4. 综合以上结果回复用户

📦 Resource（资源）—— 食材库

资源是服务器暴露的静态或动态数据。模型不能修改，只能读取。

@mcp.resource("menu://today")  # URI 格式的资源标识
def get_today_menu() -> str:
    """获取今日菜单"""
    return """
    今日特色菜：
    1. 红烧肉 - ¥68
    2. 清蒸鲈鱼 - ¥88  
    3. 宫保鸡丁 - ¥48
    """

@mcp.resource("recipe://{dish_name}")  # 带参数的资源
def get_recipe(dish_name: str) -> str:
    """获取菜谱"""
    recipes = {
        "红烧肉": "五花肉500g、冰糖30g、酱油2勺、料酒1勺...",
        "宫保鸡丁": "鸡胸肉300g、花生米50g、干辣椒10个..."
    }
    return recipes.get(dish_name, "暂无此菜谱")

Tool 和 Resource 的区别：

┌─────────────────────────────────────────────────────┐
│  Tool（工具）                  Resource（资源）        │
├─────────────────────────────────────────────────────┤
│  🎯 模型主动调用              📖 模型按需读取           │
│  ⚡ 有副作用（改变状态）        🔒 只读（无副作用）       │
│  🔧 执行操作                  📦 提供数据              │
│  📝 需要 Host 批准            📋 直接暴露给模型         │
│  🌰 炒菜、下单、发邮件         🌰 菜单、菜谱、库存清单    │
└─────────────────────────────────────────────────────┘

📋 Prompt（提示模板）—— 固定套餐

Prompt 是服务器预定义的提示词模板，可以带参数。

@mcp.prompt()
def daily_recommendation(preference: str) -> str:
    """每日推荐提示模板"""
    return f"""
    你是一位米其林三星主厨。根据顾客偏好"{preference}"，
    从今日菜单中推荐3道菜，并说明推荐理由。
    请用温暖优雅的语气回答，每道菜配一句诗意的描述。
    """

第四章：通信机制 —— 服务员怎么写点菜单？

MCP 底层使用 JSON-RPC 2.0，这是一种非常简洁的消息格式。

消息有三种类型

// 1️⃣ 请求 —— 服务员向后厨下单
{
    "jsonrpc": "2.0",
    "id": 1,                          // 请求编号，用于匹配响应
    "method": "tools/call",           // 要调用的方法
    "params": {                       // 参数
        "name": "stir_fry",
        "arguments": {
            "ingredient": "西红柿鸡蛋",
            "duration": 5
        }
    }
}

// 2️⃣ 响应 —— 后厨告诉服务员结果
{
    "jsonrpc": "2.0",
    "id": 1,                          // 对应请求的编号
    "result": {
        "content": [{
            "type": "text",
            "text": "用大火翻炒西红柿鸡蛋，5分钟后出锅，香气四溢！"
        }]
    }
}

// 3️⃣ 通知 —— 后厨主动广播（不需要响应）
{
    "jsonrpc": "2.0",
    "method": "notifications/resources/updated",  // 资源更新了
    "params": {
        "uri": "menu://today"
    }
}

传输方式（服务员怎么传单子）

┌──────────────────────────────────────────────────────────────┐
│                                                              │
│  📡 stdio（标准输入输出）                                      │
│  ┌──────────┐    stdin/stdout    ┌──────────┐               │
│  │  Host    │◄═════════════════►│  Server  │               │
│  └──────────┘   （同一台电脑）    └──────────┘               │
│  场景：Claude Desktop 调用本地 MCP Server                     │
│  特点：最简单、最快、最常用                                    │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  🌐 Streamable HTTP（可流式HTTP）                             │
│  ┌──────────┐    HTTP 请求/响应    ┌──────────┐             │
│  │  Host    │◄═══════════════════►│  Server  │             │
│  └──────────┘   （可以跨网络）      └──────────┘             │
│  场景：远程 MCP Server、云服务                               │
│  特点：支持远程、支持流式、支持无状态                           │
│                                                              │
└──────────────────────────────────────────────────────────────┘

第五章：完整时序图 —— 从用户说话到得到结果

下面是一个完整的 MCP 调用时序，用户说  “帮我查一下北京天气，然后给我出行建议” ：

第六章：动手写一个完整的 MCP Server

我们来写一个咖啡店 MCP Server，包含全部三大能力：

项目结构

coffee-mcp-server/
├── pyproject.toml          # 项目配置
└── server.py               # 服务端代码

pyproject.toml

[project]
name = "coffee-mcp-server"
version = "0.1.0"
description = "一个咖啡店 MCP Server 示例"
requires-python = ">=3.10"
dependencies = [
    "mcp[cli]>=1.0.0",
]

[project.scripts]
coffee-server = "server:main"

server.py（完整代码）

"""
☕ 咖啡店 MCP Server
包含：Tools（工具）、Resources（资源）、Prompts（提示模板）
"""
from mcp.server.fastmcp import FastMCP
from datetime import datetime

# ═══════════════════════════════════════
# 🏗️ 创建 Server 实例
# ═══════════════════════════════════════
mcp = FastMCP(
    name="coffee-shop",
    version="0.1.0",
    instructions="你是一家精品咖啡店的智能助手，可以帮顾客点单、查菜单、推荐饮品。"
)

# ═══════════════════════════════════════
# 📦 模拟数据（实际项目中会连接数据库）
# ═══════════════════════════════════════
MENU = {
    "美式咖啡": {"price": 18, "stock": 50, "category": "经典"},
    "拿铁":     {"price": 24, "stock": 30, "category": "经典"},
    "卡布奇诺": {"price": 26, "stock": 25, "category": "经典"},
    "摩卡":     {"price": 28, "stock": 20, "category": "风味"},
    "焦糖玛奇朵": {"price": 32, "stock": 15, "category": "风味"},
    "抹茶拿铁": {"price": 28, "stock": 18, "category": "特调"},
    "冰博克":   {"price": 35, "stock": 10, "category": "特调"},
}

ORDERS = []  # 存储所有订单


# ═══════════════════════════════════════
# 🔧 TOOLS —— 厨师的"动手能力"
# ═══════════════════════════════════════

@mcp.tool()
def order_drink(drink_name: str, size: str = "中杯", quantity: int = 1) -> str:
    """
    下单购买饮品
    
    Args:
        drink_name: 饮品名称，如"拿铁"、"美式咖啡"
        size: 杯型，可选"小杯"、"中杯"、"大杯"
        quantity: 购买数量
    
    Returns:
        下单结果，包含订单号和总价
    """
    # 1. 检查饮品是否存在
    if drink_name not in MENU:
        available = "、".join(MENU.keys())
        return f"❌ 抱歉，我们没有{drink_name}。\n📋 可选饮品：{available}"
    
    # 2. 检查库存
    item = MENU[drink_name]
    if item["stock"] < quantity:
        return f"❌ {drink_name}库存不足，剩余{item['stock']}杯。"
    
    # 3. 计算价格（大杯+4元，小杯-3元）
    size_extra = {"小杯": -3, "中杯": 0, "大杯": 4}
    unit_price = item["price"] + size_extra.get(size, 0)
    total = unit_price * quantity
    
    # 4. 扣减库存
    item["stock"] -= quantity
    
    # 5. 创建订单
    order = {
        "id": f"COF-{len(ORDERS) + 1:04d}",
        "drink": drink_name,
        "size": size,
        "quantity": quantity,
        "unit_price": unit_price,
        "total": total,
        "time": datetime.now().strftime("%H:%M:%S"),
    }
    ORDERS.append(order)
    
    # 6. 返回结果
    return (
        f"✅ 下单成功！\n"
        f"📦 订单号：{order['id']}\n"
        f"☕ {size}{drink_name} x {quantity}\n"
        f"💰 单价：¥{unit_price}  总计：¥{total}\n"
        f"⏰ 时间：{order['time']}\n"
        f"📦 {drink_name}剩余库存：{item['stock']}杯"
    )


@mcp.tool()
def check_stock(drink_name: str = "") -> str:
    """
    查询饮品库存
    
    Args:
        drink_name: 可选，指定饮品名称。为空则查询所有。
    
    Returns:
        库存信息
    """
    if drink_name:
        if drink_name not in MENU:
            return f"❌ 没有这款饮品：{drink_name}"
        item = MENU[drink_name]
        status = "🟢 充足" if item["stock"] > 20 else "🟡 偏少" if item["stock"] > 5 else "🔴 紧张"
        return f"☕ {drink_name}：库存 {item['stock']}杯 {status}"
    
    # 查询所有
    lines = ["📋 全部饮品库存：\n"]
    for name, info in MENU.items():
        status = "🟢" if info["stock"] > 20 else "🟡" if info["stock"] > 5 else "🔴"
        lines.append(f"  {status} {name}：{info['stock']}杯 (¥{info['price']})")
    return "\n".join(lines)


@mcp.tool()
def get_daily_sales() -> str:
    """
    获取今日销售统计
    """
    if not ORDERS:
        return "📊 今日暂无订单数据。"
    
    total_orders = len(ORDERS)
    total_revenue = sum(o["total"] for o in ORDERS)
    total_cups = sum(o["quantity"] for o in ORDERS)
    
    # 最畅销
    from collections import Counter
    best_seller = Counter(o["drink"] for o in ORDERS).most_common(1)[0]
    
    return (
        f"📊 今日销售统计\n"
        f"{'─' * 25}\n"
        f"🧾 订单数：{total_orders} 单\n"
        f"☕ 总杯数：{total_cups} 杯\n"
        f"💰 总营收：¥{total_revenue}\n"
        f"🏆 畅销款：{best_seller[0]} ({best_seller[1]}杯)\n"
        f"{'─' * 25}"
    )


# ═══════════════════════════════════════
# 📦 RESOURCES —— 食材库（只读数据）
# ═══════════════════════════════════════

@mcp.resource("coffee://menu")
def get_full_menu() -> str:
    """
    完整菜单（资源）
    URI: coffee://menu
    """
    lines = ["☕ 精品咖啡店 · 完整菜单\n" + "═" * 35]
    
    # 按分类分组
    categories = {}
    for name, info in MENU.items():
        cat = info["category"]
        if cat not in categories:
            categories[cat] = []
        categories[cat].append((name, info))
    
    for cat, items in categories.items():
        lines.append(f"\n【{cat}】")
        for name, info in items:
            lines.append(f"  {name}  ¥{info['price']}  库存:{info['stock']}杯")
    
    lines.append(f"\n{'═' * 35}")
    lines.append(f"共 {len(MENU)} 款饮品")
    return "\n".join(lines)


@mcp.resource("coffee://drink/{drink_name}")
def get_drink_detail(drink_name: str) -> str:
    """
    单个饮品详情（带参数的资源）
    URI: coffee://drink/拿铁
    """
    if drink_name not in MENU:
        return f"未找到饮品：{drink_name}"
    
    info = MENU[drink_name]
    
    # 模拟详细描述
    descriptions = {
        "美式咖啡": "浓缩咖啡加热水，口感醇厚，苦味明显，适合喜欢纯粹咖啡味的人。",
        "拿铁": "浓缩咖啡加大量蒸汽牛奶，奶香浓郁，口感柔和，入门首选。",
        "卡布奇诺": "浓缩咖啡加等量奶泡和牛奶，层次分明，口感绵密。",
        "摩卡": "浓缩咖啡加巧克力酱和牛奶，甜美浓郁，像液体巧克力蛋糕。",
        "焦糖玛奇朵": "浓缩咖啡加香草糖浆和焦糖酱，甜蜜浪漫，颜值担当。",
        "抹茶拿铁": "日本抹茶加蒸汽牛奶，清新回甘，不喝咖啡也能选。",
        "冰博克": "冷冻提纯牛奶加浓缩咖啡，奶味超级浓郁，咖啡界的爱马仕。",
    }
    
    desc = descriptions.get(drink_name, "一款精选饮品。")
    
    return (
        f"☕ {drink_name}\n"
        f"{'─' * 30}\n"
        f"💰 价格：¥{info['price']}\n"
        f"📂 分类：{info['category']}\n"
        f"📦 库存：{info['stock']}杯\n"
        f"📝 描述：{desc}\n"
        f"{'─' * 30}\n"
        f"杯型加价：小杯 -3元 / 大杯 +4元"
    )


@mcp.resource("coffee://orders/today")
def get_today_orders() -> str:
    """
    今日订单记录
    URI: coffee://orders/today
    """
    if not ORDERS:
        return "今日暂无订单。"
    
    lines = [f"📋 今日订单记录 ({len(ORDERS)}单)\n" + "═" * 50]
    for o in ORDERS:
        lines.append(
            f"  {o['id']}  {o['time']}  "
            f"{o['size']}{o['drink']} x{o['quantity']}  "
            f"¥{o['total']}"
        )
    return "\n".join(lines)


# ═══════════════════════════════════════
# 📋 PROMPTS —— 固定套餐（提示模板）
# ═══════════════════════════════════════

@mcp.prompt()
def recommend_drink(preference: str = "", budget: int = 0) -> str:
    """
    饮品推荐提示模板
    
    Args:
        preference: 顾客口味偏好，如"喜欢甜的"、"不要太苦"
        budget: 预算上限，0表示不限
    """
    prompt = "你是一位专业的咖啡师，请根据顾客需求推荐饮品。\n\n"
    prompt += "顾客需求：\n"
    if preference:
        prompt += f"- 口味偏好：{preference}\n"
    if budget > 0:
        prompt += f"- 预算上限：¥{budget}\n"
    if not preference and budget == 0:
        prompt += "- 没有特殊要求，请推荐最受欢迎的\n"
    
    prompt += "\n请先查看完整菜单(coffee://menu)，然后推荐2-3款合适的饮品，"
    prompt += "说明推荐理由，用温暖亲切的语气。"
    
    return prompt


@mcp.prompt()
def barista_guide(drink_name: str) -> str:
    """
    咖啡制作指南提示模板
    
    Args:
        drink_name: 饮品名称
    """
    return f"""
    请以专业咖啡师的身份，详细介绍如何制作一杯完美的{drink_name}。
    
    要求：
    1. 先查看该饮品的详情(coffee://drink/{drink_name})
    2. 列出所需材料和工具
    3. 分步骤讲解制作过程
    4. 给出专业小技巧
    5. 用优雅但易懂的语言
    """


# ═══════════════════════════════════════
# 🚀 启动 Server
# ═══════════════════════════════════════
def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

第七章：让 Claude Desktop 连接你的 Server

在 Claude Desktop 的配置文件中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "coffee-shop": {
            "command": "python",
            "args": ["/path/to/coffee-mcp-server/server.py"],
            "env": {}
        }
    }
}

如果是 npm 包（比如社区已有的 Server）：

{
    "mcpServers": {
        "filesystem": {
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "/Users/you/documents"
            ]
        },
        "github": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-github"],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
            }
        },
        "postgres": {
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-postgres",
                "postgresql://localhost:5432/mydb"
            ]
        }
    }
}

第八章：最佳实践（资深架构师的经验之谈）

✅ DO —— 应该做的

# ═══ 1. 工具描述要像给人看的一样写清楚 ═══
# ❌ 坏示范
@mcp.tool()
def calc(a: int, b: int) -> int:
    """计算"""
    return a + b

# ✅ 好示范
@mcp.tool()
def calculate_order_total(
    subtotal: float,
    discount_code: str = "",
    tax_rate: float = 0.06
) -> float:
    """
    计算订单最终总价（含税和折扣）
    
    Args:
        subtotal: 商品小计金额（税前，单位：元）
        discount_code: 折扣码，可选。空字符串表示无折扣。
                      支持的折扣码：SAVE10(9折)、SAVE20(8折)、NEWUSER(7折)
        tax_rate: 税率，默认6%（中国餐饮增值税）
    
    Returns:
        最终应付金额（四舍五入到分）
    
    Examples:
        calculate_order_total(100, "SAVE10") → 95.4
        calculate_order_total(100) → 106.0
    """
    discount_map = {"SAVE10": 0.9, "SAVE20": 0.8, "NEWUSER": 0.7}
    rate = discount_map.get(discount_code, 1.0)
    return round(subtotal * rate * (1 + tax_rate), 2)


# ═══ 2. 用 JSON Schema 约束参数 ═══
from pydantic import BaseModel, Field

class OrderRequest(BaseModel):
    drink_name: str = Field(
        ..., 
        description="饮品名称",
        pattern=r"^[\u4e00-\u9fa5a-zA-Z]+$"  # 只允许中英文
    )
    size: str = Field(
        default="中杯",
        description="杯型",
        json_schema_extra={"enum": ["小杯", "中杯", "大杯"]}
    )
    quantity: int = Field(
        default=1,
        ge=1,           # 最小值 1
        le=20,          # 最大值 20
        description="购买数量，1-20杯"
    )

@mcp.tool()
def place_order(req: OrderRequest) -> str:
    """下单购买饮品"""
    # req 已经经过 Pydantic 验证，类型安全
    ...


# ═══ 3. 返回结构化内容 ═══
@mcp.tool()
def search_drinks(keyword: str) -> list[dict]:
    """
    搜索饮品（返回结构化数据，方便模型解析）
    """
    results = []
    for name, info in MENU.items():
        if keyword in name:
            results.append({
                "name": name,
                "price": info["price"],
                "stock": info["stock"],
                "available": info["stock"] > 0
            })
    return results


# ═══ 4. 错误处理要友好 ═══
@mcp.tool()
def cancel_order(order_id: str) -> str:
    """
    取消订单
    """
    # 找不到订单
    order = next((o for o in ORDERS if o["id"] == order_id), None)
    if not order:
        return f"❌ 未找到订单 {order_id}。请检查订单号是否正确。"
    
    # 超时不可取消
    if datetime.now().minute - int(order["time"].split(":")[1]) > 5:
        return f"❌ 订单 {order_id} 已超过5分钟，无法取消。请联系门店。"
    
    # 正常取消
    MENU[order["drink"]]["stock"] += order["quantity"]
    ORDERS.remove(order)
    return f"✅ 订单 {order_id} 已取消，{order['quantity']}杯{order['drink']}已退回库存。"


# ═══ 5. 资源 URI 要有语义 ═══
# ✅ 好的 URI 设计
@mcp.resource("coffee://menu")                    # 菜单
@mcp.resource("coffee://drink/{name}")            # 单个饮品
@mcp.resource("coffee://orders/{date}")           # 某天订单
@mcp.resource("coffee://stats/sales/{period}")    # 销售统计

# ❌ 坏的 URI 设计
@mcp.resource("data/1")          # 无语义
@mcp.resource("api/get-all")     # 像 REST 而不像资源
@mcp.resource("test")            # 无意义

❌ DON’T —— 千万别做的

# ═══ 1. 不要在工具里做大模型的工作 ═══
# ❌ 坏示范：工具自己做总结
@mcp.tool()
def get_weather_with_analysis(city: str) -> str:
    """获取天气并分析"""
    weather = fetch_weather(city)
    analysis = f"天气是{weather}，建议{'带伞' if '雨' in weather else '出行'}"
    return analysis  # 模型应该自己分析，你剥夺了它的能力

# ✅ 好示范：只返回原始数据
@mcp.tool()
def get_weather(city: str) -> dict:
    """获取城市天气原始数据"""
    return fetch_weather(city)  # 让模型来分析和建议


# ═══ 2. 不要让工具做太多事 ═══
# ❌ 坏示范：一个工具干所有事
@mcp.tool()
def coffee_operation(
    action: str,  # "order" / "cancel" / "check" / "recommend"
    **kwargs
) -> str:
    """咖啡操作（万能工具）"""
    if action == "order": ...
    elif action == "cancel": ...
    elif action == "check": ...
    # 模型很难准确选择 action

# ✅ 好示范：每个操作一个工具
@mcp.tool()
def order_drink(...): ...
@mcp.tool()
def cancel_order(...): ...
@mcp.tool()
def check_stock(...): ...


# ═══ 3. 不要忽略安全性 ═══
# ❌ 坏示范：直接执行任意 SQL
@mcp.tool()
def query_database(sql: str) -> str:
    """执行SQL查询"""
    return db.execute(sql)  # 危险！模型可能发送 DROP TABLE

# ✅ 好示范：限制查询范围
@mcp.tool()
def query_orders(
    date_from: str,
    date_to: str,
    status: str = ""
) -> str:
    """查询订单记录（只读，限定范围）"""
    # 使用参数化查询，只允许查询 orders 表
    return db.query_orders(date_from, date_to, status)


# ═══ 4. 不要返回海量数据 ═══
# ❌ 坏示范
@mcp.tool()
def get_all_logs() -> str:
    """获取所有日志"""  # 可能返回 100MB 数据，模型直接崩溃
    return open("/var/log/everything.log").read()

# ✅ 好示范
@mcp.tool()
def search_logs(
    keyword: str,
    limit: int = Field(default=20, le=100),
    start_time: str = "",
) -> str:
    """搜索日志（最多返回100条）"""
    ...

第九章：高级技巧 —— 资源订阅与进度通知

# ═══ 资源订阅（后厨食材变了，主动通知） ═══

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("smart-kitchen")

# 定义一个可更新的资源
@mcp.resource("kitchen://stock/{ingredient}")
async def get_stock(ingredient: str) -> str:
    """获取食材库存"""
    stock = await db.get_stock(ingredient)
    return f"{ingredient}: 剩余 {stock} 份"


# 当库存变化时，通知所有订阅者
async def on_stock_changed(ingredient: str, new_stock: int):
    """库存变化回调"""
    if new_stock < 10:
        # 通知资源更新了
        await mcp.request_context.session.send_resource_updated(
            "kitchen://stock/" + ingredient
        )
        # 还可以主动发日志通知
        await mcp.request_context.session.send_log_message(
            level="warning",
            data=f"⚠️ {ingredient} 库存不足，仅剩 {new_stock} 份！"
        )


# ═══ 进度通知（长时间操作，报告进度） ═══
import asyncio

@mcp.tool()
async def batch_brew(drinks: list[str]) -> str:
    """
    批量制作饮品（耗时操作，会报告进度）
    """
    total = len(drinks)
    for i, drink in enumerate(drinks):
        # 模拟制作过程
        await asyncio.sleep(1)
        
        # 发送进度通知
        await mcp.request_context.session.send_progress(
            progress_token="batch-brew-001",
            progress=i + 1,
            total=total,
            message=f"正在制作 {drink} ({i+1}/{total})"
        )
    
    return f"✅ {total}杯饮品全部制作完成！"

第十章：调试技巧 —— MCP Inspector

MCP 官方提供了一个超好用的调试工具 MCP Inspector：

# 直接启动，会打开一个 Web 界面
npx @modelcontextprotocol/inspector python server.py

# 或者调试远程 Server
npx @modelcontextprotocol/inspector --transport streamable-http http://localhost:8080/mcp

Inspector 界面可以：

• 📋 查看所有 Tools / Resources / Prompts
• 🧪 手动调用任意工具（填参数 → 看结果）
• 📡 实时查看所有 JSON-RPC 消息（像抓包一样）
• 🔍 调试连接问题

第十一章：常见问题排查

┌─────────────────────────────────────────────────────────────┐
│  问题现象                    │  可能原因        │  解决方案    │
├─────────────────────────────┼────────────────┼─────────────┤
│  Claude 看不到工具           │  Server没启动    │  检查配置JSON │
│                              │  初始化失败      │  看stderr日志│
├─────────────────────────────┼────────────────┼─────────────┤
│  模型不调用工具               │  描述不清楚      │  优化docstring│
│                              │  参数名模糊      │  加enum约束  │
├─────────────────────────────┼────────────────┼─────────────┤
│  工具调用报错                 │  参数类型错误    │  加Pydantic  │
│                              │  缺少必填参数    │  设默认值    │
├─────────────────────────────┼────────────────┼─────────────┤
│  连接超时                    │  stdio阻塞      │  不要用input()│
│                              │  启动太慢       │  懒加载资源  │
├─────────────────────────────┼────────────────┼─────────────┤
│  返回数据被截断               │  超过token限制   │  分页/摘要   │
│                              │  格式错误       │  返回纯文本  │
└─────────────────────────────────────────────────────────────┘

终章：一张图总结 MCP 全貌

┌─────────────────────────────────────────────────────────────────┐
│                      MCP 协议全景图                              │
│                                                                 │
│  用户 ──▶ Host ──▶ AI模型 ──┐                                   │
│                           │                                    │
│                    ┌──────┴──────┐                               │
│                    │ 需要外部能力？│                               │
│                    └──────┬──────┘                               │
│                    Yes     │     No                              │
│                   ┌────────┴────────┐                            │
│                   ▼                 ▼                            │
│            ┌─────────────┐   直接回答用户                       │
│            │ 选择工具/资源 │                                     │
│            └──────┬──────┘                                     │
│                   │                                             │
│         ┌─────────┼─────────┐                                   │
│         ▼         ▼         ▼                                   │
│      ┌──────┐ ┌──────┐ ┌──────┐                                │
│      │Tool  │ │Resrc │ │Prompt│  ← 三大能力                     │
│      │动手做│ │读数据│ │模板化│                                │
│      └──┬───┘ └──┬───┘ └──┬───┘                                │
│         │        │        │                                     │
│         └────────┼────────┘                                     │
│                  ▼                                              │
│           ┌─────────────┐                                       │
│           │  Client     │  ← JSON-RPC 2.0                      │
│           │  (协议翻译)  │                                       │
│           └──────┬──────┘                                       │
│                  │                                              │
│         ┌────────┼────────┐                                      │
│         ▼        ▼        ▼                                      │
│      stdio    HTTP    (未来更多)   ← 传输层                      │
│         │        │                                              │
│         ▼        ▼                                              │
│      ┌─────────────────┐                                        │
│      │    Server       │  ← 你的代码运行在这里                   │
│      │  (能力提供者)    │                                        │
│      └─────────────────┘                                        │
│                                                                 │
│  ═══════════════════════════════════════════════════════════    │
│  核心价值：一次编写，到处使用（任何 MCP Host 都能调用你的Server） │
└─────────────────────────────────────────────────────────────────┘

最后的一句话总结

MCP 就是 AI 世界里的 USB 接口标准。

以前每个 AI 应用要连接外部工具，都得自己写一套"驱动程序"。MCP 出现后，工具开发者只要按标准写一个 Server，所有支持 MCP 的 AI 应用都能直接用 —— 就像 U 盘插上任何电脑都能用一样简单。

希望这个故事和代码能让你彻底理解 MCP！如果你想把咖啡店 Server 跑起来，或者想了解更高级的用法（比如多 Server 协作、远程部署），随时问我 ☕