MCP 协议学习笔记
MCP（Model Context Protocol，模型上下文协议）—— 把 AI 连接到世界的 “USB-C” 接口
1. 什么是 MCP？
| 一句话解释 | 类比 |
|---|---|
| 开放、标准化的协议，让任意 LLM 可以安全、便捷地调用外部工具与数据源 | 就像 USB-C 统一了手机、耳机、显示器的接口，MCP 统一了 AI 与工具的接口 |
- 发起方：最初由 Anthropic 为 Claude 设计
- 现状：完全开放，社区驱动，多家厂商共同推进
- 愿景：成为 AI-工具交互的 通用标准
2. 为什么用 MCP 而不是传统 API？
| 传统 API 集成 | MCP 集成 |
|---|---|
| 每个工具一套 SDK / 鉴权 / 错误处理 → M×N 问题 | 统一协议、统一客户端 → M+N 问题 |
| 代码重复、文档碎片化 | 一次开发，任意 LLM 复用 |
| 难以动态组合工具 | 任意组合 Server，即插即用 |
| 实时性差（轮询） | 长连接、流式推送 |
| 安全模型各异 | 内建权限管控、最小权限原则 |
3. MCP 整体架构
graph TD
A[MCP Host
Claude Desktop / IDE / 机器人] -->|1| B[MCP Client
一对一连接]
B -->|2| C[MCP Server
提供能力]
C -->|3| D[本地数据源
文件/DB/服务]
C -->|4| E[远程服务
SaaS API/Web]
|组件|职责|示例|
| ---------------| --------------------| -------------------------------|
|MCP Host|最终用户应用|Claude Desktop、Cherry Studio|
|MCP Client|管理连接、路由请求|每个 Host 内嵌|
|MCP Server|真正干活的小程序|`filesystem-server`、`github-server`|
|本地/远程资源|被 Server 调用|PDF、数据库、Slack API|
---
## 4. MCP Server 深度解析
### 4.1 基本概念
- **定位**：轻量级插件，专注单一领域（文件、数据库、浏览器…）
- **类比**：ChatGPT 的 “GPTs” / “插件” 体系
- **能力**：同时提供 **Resources**、**Tools**、**Prompts** 三种能力
|能力|作用|LLM 视角|
| -----------| ------------------------------| --------------------|
|Resources|只读数据（文件、配置、日志）|“给我看看…”|
|Tools|可执行函数（发送邮件、写库）|“帮我执行…”|
|Prompts|预置模板（复杂任务分步引导）|“按这个流程做…”|
### 4.2 通信机制
|传输方式|协议版本|场景|特点|未来|
| ----------| -------------------| ----------------| -------------------------------| ---------------|
|**Stdio**|长期支持|本地、隐私数据|零网络、零配置、单进程|✅ 推荐本地|
|**SSE**|2024-11-05 起支持|远程实时通知|长连接、单向推送|⚠️ 计划废弃|
|**Streamable HTTP**|2025-03-26 起支持|云原生、分布式|标准 HTTP、可升级 SSE、无状态|✅ 官方推荐|
> 一句话选择：
> 本地开发 → **Stdio**；云端/远程 → **Streamable HTTP**；SSE 仅用于兼容旧系统。
---
## 5. FastMCP：30 秒写出一个 MCP Server
> Python 生态最活跃的高级封装，官方 SDK 的核心灵感来源。
### 5.1 为什么选择 FastMCP？
- **少写 90% 样板**：自动 JSON Schema、错误处理、协议升级
- **Pythonic**：装饰器即能力
- **完整**：Server + Client + 组合模式 + OpenAPI 一键导入
### 5.2 核心装饰器速查
```python
from fastmcp import FastMCP
mcp = FastMCP("DemoServer")
@mcp.tool() # LLM 可调用的函数
def add(a: int, b: int) -> int: ...
@mcp.resource("config://info") # 只读资源
def get_info() -> dict: ...
@mcp.prompt() # 可复用提示模板
def summarize(text: str) -> str: ...5.3 运行 & 传输
# 默认 stdio
if __name__ == "__main__":
mcp.run()
# 指定传输
mcp.run(transport="streamable-http", host="0.0.0.0", port=8000)6. Client 端：程序化调用
from fastmcp import Client
import asyncio, os
async def main():
async with Client("path/to/server.py") as cli:
print(await cli.list_tools()) # 查看可用工具
result = await cli.call_tool("add", {"a":1,"b":2})
print(result.content) # -> 3
asyncio.run(main())7. MCP Inspector 联调
- 功能：可视化调试 MCP Server（工具/资源/提示）
-
组成
- React Web UI（端口默认 9001）
- Node.js 代理（端口默认 9000）
- 启动
npx @modelcontextprotocol/inspector
# 自定义端口
CLIENT_PORT=9001 SERVER_PORT=9000 npx @modelcontextprotocol/inspector- 协议规范：所有消息遵循 JSON-RPC 2.0
8. 常用客户端 & 配置模板
| 客户端 | 平台 | 特征 |
|---|---|---|
| Claude Desktop | Win / macOS | 官方原生、配置 JSON |
| Cherry Studio | Web / 桌面 | 开箱即用、插件市场 |
| Chatbox AI | 全平台 | 支持多模型、可视化配置 |
| DeepChat | Web | 开源、可嵌入 |
最小配置示例（Claude Desktop）
{
"mcpServers": {
"demo": {
"command": "python",
"args": ["-m", "demo_server"],
"transport": "stdio"
}
}
}9. 数据业务案例快速预览
- 场景：让 LLM 分析本地私有的销售数据
-
Server 能力
- Resource：
sales://daily/{date}.csv读取本地 CSV - Tool：
plot_trend(start, end)生成趋势图并返回图片 URL - Prompt：
deep_dive_metric(metric_name)预置分析模板
- Resource：
- 运行
git clone https://github.com/your-org/sales-mcp
pip install -e .
python -m sales_mcp # 默认 stdio- 体验：打开 Claude Desktop → 选择连接
sales-mcp→ 自然语言提问
“请用 plot_trend 工具画出 2025-07 的销售额趋势，并告诉我哪一周最突出。”