C++ 组 && py 组 联合授课文档 1： MCP 入门实践

1. 定义#

Agent 是一个由 LLM 驱动的可感知、可思考、可执行的智能体。 它可以：

• 感知环境（理解输入、上下文）
• 规划目标（思考下一步）
• 调用工具（执行外部操作）
• 学习记忆（改进行为）

2. 核心结构#

实际应用场景#

• 代码助理：自动生成、重构并运行测试，必要时调用本地 CLI。
• 企业客服：先规划检索 → 查知识库 → 调用工单系统 → 反馈用户。
• 数据自动化：定时从 API 抓数 → 清洗 → 写入数据库 → 告警。
• 个人助理：管理日程、邮件与文件，跨应用执行动作。

四大能力与常用实现#

• 感知（Perception）

  • 文本/结构化：Transformers、spaCy、Pydantic（入参/出参校验）
  • 语音/图像：Whisper/Vosk（ASR）、PaddleOCR/Tesseract（OCR）、CLIP/SigLIP（图像语义）

• 规划（Planning）

  • ReAct、CoT（Chain-of-Thought）、ToT（Tree-of-Thoughts）
  • LangGraph（图式工作流/有状态代理）、AutoGen、Semantic Kernel Planner

• 调用工具（Action / Tool Use）

  • MCP Server/Client、OpenAI Function/Tool Calling、LangChain Tools、CLI（subprocess）、gRPC/REST
  • 工具描述与注册：JSON Schema、Pydantic、工具白名单与作用域（scope）

• 学习记忆（Memory）

  • 短期：会话缓冲、摘要窗口（summary buffer）
  • 长期：向量数据库（FAISS/Chroma/Milvus/Weaviate）、RAG、事件/语义/程序性记忆

本节要点

• 选择“可观测、可替换”的实现以便排错与演进
• 规划/行动/记忆解耦，避免耦合带来的复杂度

真实世界 Agent 案例#

• GitHub Copilot Workspace（代码工作台）

  • 感知：解析仓库结构、代码语义与现有测试；读取 Issue/PR 上下文
  • 规划：根据任务拆解为“修改点 → 运行测试 → 修复失败 → 提交 PR”的多步流程
  • 执行：自动编辑多文件、运行本地命令（构建/测试/格式化）
  • 记忆：在同一工作空间内持续跟踪历史更改与失败用例，累积上下文

• Cursor AI（IDE 内置 Agent）

  • 感知：理解光标处于文件级语境、项目依赖与类型信息（LSP）
  • 规划：生成重构计划，逐步应用、验证与回滚
  • 执行：批量修改代码、运行命令、插入注释与测试样例
  • 记忆：会话级记忆保持编辑意图与偏好；项目级记忆持久化重要决策

• Devin（全栈软件 Agent）

  • 感知：综合浏览器、终端、编辑器与外部文档的信息
  • 规划：里程碑/任务/子任务分层规划，动态调整路径
  • 执行：自动编写代码、安装依赖、运行脚本与部署
  • 记忆：长期跟踪项目状态、未完成事项与已验证结论

本节要点

• 真实产品普遍具备“感知 → 规划 → 执行 → 记忆”的闭环能力
• 关键差异在于：工具覆盖面、可观测性与对失败的自恢复能力

面临的问题#

Agent 想调用外部系统时，会遇到问题：

• 每个系统接口都不同；
• 工具描述不统一；
• 权限和安全难管控；
• LLM 不知道工具能干什么。

MCP 之前的混乱状况#

在 MCP 协议出现之前，AI Agent 调用外部工具是一个极其混乱的过程：（仅供了解）

1
# 为每个工具写专门的适配代码
2
class GitHubTool:
3
    def __init__(self, token):
4
        self.headers = {"Authorization": f"Bearer {token}"}
5

6
    def create_issue(self, repo, title, body):
7
        # GitHub 特有的 API 调用逻辑
8
        pass
9

10
class SlackTool:
11
    def __init__(self, webhook_url):
12
        self.webhook = webhook_url
13

14
    def send_message(self, channel, text):
15
        # Slack 特有的消息格式
16
        pass
17

18
# 每个工具都需要不同的错误处理、重试逻辑、参数验证...

1
# 方式1：硬编码在提示词里
2
system_prompt = """
3
你可以使用以下工具：
4
- send_email(to, subject, body) - 发送邮件
5
- query_database(sql) - 查询数据库，注意SQL注入
6
- read_file(path) - 读取文件，路径不能包含..
7
"""
8

9
# 方式2：JSON Schema，但每家格式不同
10
github_schema = {
11
    "name": "create_issue",
12
    "description": "Create a GitHub issue",
13
    "parameters": {
14
        "type": "object",
15
        "properties": {
16
            "repo": {"type": "string"},
17
            "title": {"type": "string"}
18
        }
19
    }
20
}
21

22
# 方式3：OpenAI Function Calling 格式
23
openai_function = {
24
    "name": "send_email",
25
    "description": "Send an email",
26
    "parameters": {
27
        "type": "object",
28
        "properties": {
29
            "to": {"type": "string", "description": "Recipient email"}
30
        },
31
        "required": ["to"]
32
    }
33
}

1
# 每个工具都要自己实现权限检查
2
def read_file(path):
3
    # 手动检查路径穿越
4
    if ".." in path or path.startswith("/"):
5
        raise SecurityError("Invalid path")
6

7
    # 手动检查白名单
8
    if not path.startswith("/safe/workspace/"):
9
        raise SecurityError("Path not in whitelist")
10

11
    # 手动检查文件大小
12
    if os.path.getsize(path) > 10 * 1024 * 1024:
13
        raise SecurityError("File too large")
14

15
def run_sql(query):
16
    # 手动 SQL 注入检查
17
    dangerous_keywords = ["DROP", "DELETE", "UPDATE", "INSERT"]
18
    if any(keyword in query.upper() for keyword in dangerous_keywords):
19
        raise SecurityError("Dangerous SQL detected")

1
# 工具A：打印到控制台
2
def tool_a():
3
    print(f"[{datetime.now()}] Tool A called")
4

5
# 工具B：写入文件
6
def tool_b():
7
    with open("tool_b.log", "a") as f:
8
        f.write(f"Tool B executed at {time.time()}\n")
9

10
# 工具C：发送到监控系统
11
def tool_c():
12
    metrics.increment("tool_c.calls")

1
def send_notification(message):
2
    pass
3

4
# v2.0 - 破坏性变更
5
def send_notification(recipient, message, priority="normal"):
6
    pass
7

8
# v3.0 - 又变了
9
def send_notification(config: NotificationConfig):
10
    pass

MCP 横空出世#

这里有一张非常经典而形象的图

就像 USB 接口的发展历程一样：

• USB 1.0/2.0 时代：各种奇形怪状的接口（Mini-USB、Micro-USB、专用接口）
• USB-C 时代：一个接口统一所有设备

MCP 协议就是 AI 工具调用领域的”USB-C”——统一的接口标准。

小结：标准化协议消除了”每接一个系统就写一套适配”的重复劳动，让 LLM 聚焦在规划与决策。没有什么是加一层中间层解决不了的，如果有，那就再加一层！

定义与核心价值#

MCP（Model Context Protocol） 是一种开放协议，定义了 AI 模型如何与外部工具安全、结构化地通信。它解决的核心问题是”Agent 调用工具的标准化”。

核心价值：

• 统一接口：一套协议适配所有工具，告别”每个系统写一套适配器”
• 安全可控：内置权限管理、参数验证和作用域隔离
• 跨平台复用：同一个 MCP Server 可被 Claude、ChatGPT、LangChain 等不同客户端调用
• 自动发现：工具能力可枚举、可描述，模型自动理解可用功能

架构图解#

数据流示例：

MCP Server 能力模型#

一个 MCP Server 可以暴露三种类型的能力：

1
{
2
  "resources": {
3
    "calendar_events": {
4
      "description": "用户的日程事件列表",
5
      "mimeType": "application/json"
6
    },
7
    "project_files": {
8
      "description": "项目文件树结构",
9
      "mimeType": "text/plain"
10
    }
11
  }
12
}

1
{
2
  "tools": {
3
    "add_event": {
4
      "description": "在指定日期新增日程",
5
      "parameters": {
6
        "type": "object",
7
        "properties": {
8
          "date": {"type": "string", "format": "date"},
9
          "title": {"type": "string"},
10
          "time": {"type": "string", "pattern": "^\\d{2}:\\d{2}$"}
11
        },
12
        "required": ["date", "title"]
13
      }
14
    },
15
    "delete_event": {
16
      "description": "删除指定的日程事件",
17
      "parameters": {
18
        "type": "object",
19
        "properties": {
20
          "event_id": {"type": "string"}
21
        },
22
        "required": ["event_id"]
23
      }
24
    }
25
  }
26
}

1
{
2
  "prompts": {
3
    "schedule_conflict_check": {
4
      "description": "检查日程冲突的分析模板",
5
      "template": "分析以下日程是否存在时间冲突：\n{events}\n\n请指出具体的冲突并建议解决方案。"
6
    }
7
  }
8
}

一个完整的 MCP Server（FastMCP 版）#

1
# uv add fastmcp
2
from fastmcp import FastMCP
3

4
# 创建 MCP 服务器实例
5
app = FastMCP("calendar")
6
EVENTS: list[dict] = []
7

8
# 使用实例方法装饰器注册工具
9
@app.tool
10
def add_event(date: str, title: str) -> dict:
11
    """在指定日期新增日程"""
12
    EVENTS.append({"date": date, "title": title})
13
    return {"status": "ok"}
14

15
@app.tool
16
def list_events() -> list:
17
    """列出所有日程"""
18
    return EVENTS
19

20
# 运行服务器
21
if __name__ == "__main__":
22
    app.run()

实际 Server 场景#

• 文件系统访问（filesystem）

  • 工具：list_dir、read_file、write_file、search_in_files
  • 用途：受控地让模型读取/写入工作区文件，生成或修改配置、修复代码
  • 安全：白名单根目录、只读/只写分权、文件大小限制、路径穿越检查

• 数据库查询（database）

  • 工具：list_tables、get_schema、run_sql（带参数化）、explain_sql
  • 用途：生成 SQL、做数据分析/看板快问快答、数据质量巡检
  • 安全：只读 schema、SQL 白名单/模板、结果集行数上限、敏感列脱敏

• 浏览器自动化（browser/automation）

  • 工具：open_url、click、type、extract、screenshot
  • 用途：抓取资料、表单自动化、E2E 验证与回归检查
  • 安全：域名白名单、速率限制、验证码处理与人机分流

本节要点

• MCP Server 将“系统能力”以工具/资源的方式抽象、可枚举、可权限化
• 先做边界再做增强：限制作用域与数据范围，保留审计与回滚手段

消息格式示例（JSON-RPC）#

请求（调用工具）：

1
{
2
  "jsonrpc": "2.0",
3
  "id": "42",
4
  "method": "tools/call",
5
  "params": {
6
    "name": "add_event",
7
    "arguments": { "date": "2025-11-12", "title": "周会" }
8
  }
9
}

响应（成功）：

1
{
2
  "jsonrpc": "2.0",
3
  "id": "42",
4
  "result": { "ok": true, "data": { "date": "2025-11-12", "title": "周会" } }
5
}

响应（错误）：

1
{
2
  "jsonrpc": "2.0",
3
  "id": "42",
4
  "error": { "code": -32602, "message": "invalid params: missing date" }
5
}

关键概念

• JSON-RPC 基于 id 关联请求/响应；error 与 result 互斥
• 工具名、参数对象与返回结构须遵循 Server 公布的 schema

与传统 API / Function Calling 的对比#

适用建议

• 已有成熟后端服务：继续提供 REST/gRPC；对 Agent 开放时可加一层 MCP 以复用
• 仅在单模型内少量工具：Function Calling 足够
• 需要跨客户端/团队复用工具、强调权限与可观测：优先 MCP

MCP 生态#

随着 MCP 生态的快速发展，专门的工具市场和分发平台开始涌现，为开发者提供发现、安装和管理 MCP Server 的便捷方式。这些平台正在成为 MCP 生态的重要基础设施。

1
# 1. 安装 Smithery CLI
2
npm install -g @smithery/cli
3

4
# 2. 搜索工具
5
smithery search "database"
6

7
# 3. 安装工具
8
smithery install sqlite-explorer
9

10
# 4. 配置到 Claude Desktop
11
smithery configure claude-desktop

1
{
2
  "mcpServers": {
3
    "sqlite-explorer": {
4
      "command": "npx",
5
      "args": ["@smithery/sqlite-explorer"],
6
      "env": {
7
        "DATABASE_PATH": "./data"
8
      }
9
    },
10
    "github-integration": {
11
      "command": "python",
12
      "args": ["-m", "mcp_github"],
13
      "env": {
14
        "GITHUB_TOKEN": "your_token_here"
15
      }
16
    }
17
  }
18
}

如何自己实现 MCP / Agent#

下面进入实践部分：使用 FastMCP 与 LangChain。

1
# 1. 进入示例目录
2
cd examples/
3

4
# 2. 安装依赖
5
uv add fastmcp langchain langchain-openai
6

7
# 3. 设置 API 密钥（示例 2 和 3 需要）
8
# Windows (CMD)
9
set OPENAI_API_KEY=your_key_here
10
set OPENAI_BASE_URL=https://api.openai.com/v1
11

12
# Windows (PowerShell)
13
$env:OPENAI_API_KEY="your_key_here"
14
$env:OPENAI_BASE_URL="https://api.openai.com/v1"
15

16
# Linux/macOS
17
export OPENAI_API_KEY=your_key_here
18
export OPENAI_BASE_URL=https://api.openai.com/v1
19

20
# 4. 运行任意示例
21
uv run 01_calendar_server.py
22
uv run 02_langchain_basic_agent.py
23
uv run 03_code_agent_with_planning.py
24
uv run 04_integrated_mcp_langchain.py

开发 MCP Server 的最佳实践#

• 工具命名规范：动词_名词（如 add_event），避免歧义
• 参数校验：使用 Pydantic/JSON Schema；对日期/邮箱等做格式校验
• 安全性：最小权限原则、作用域（scope）隔离；不把机密直接暴露给模型；必要时审计日志
• 超时与失败策略：为外部调用设置超时、重试、熔断；保证幂等（如使用去重键）
• 可观测性：记录请求/响应摘要、错误码、耗时；避免记录敏感原文
• 文档与自描述：为每个工具写清楚 docstring、示例与边界，便于模型理解

本节要点

• “清晰的 schema + 最小权限 + 可观测”是生产可用的三件套
• 同一个工具不要“既做这又做那”，保持单一职责

Agent 开发常见问题与解决方案#

• 工具调用死循环

  • 症状：模型在“思考 → 行动”之间反复横跳
  • 解决：设置 max_iterations/early_stopping；添加反思/reflection 步骤；为工具增加冷却时间与重试上限

• 上下文溢出/对话太长

  • 解决：对历史做摘要（summary）、基于检索的拼接（RAG），限制窗口长度，压缩中间推理链条

• 成本与延迟过高

  • 解决：缓存（prompt/检索/工具调用）；优先使用小模型 + 升级策略；并发/批量化；合理的温度与 top-p

• 工具选择错误

  • 解决：为工具写清楚“何时使用/不该使用”；给出正反例；在提示词加入强约束

• 非确定性导致结果不稳定

  • 解决：Self-Consistency 多样本投票、约束解码、规则校验与回退策略