381 lines
12 KiB
Markdown
381 lines
12 KiB
Markdown
---
|
||
tags: [mcp, ai-development, protocol, llm-tools]
|
||
create time: 2026-04-30 14:30
|
||
---
|
||
|
||
# MCP — 模型上下文协议
|
||
|
||
## 概述
|
||
|
||
**Model Context Protocol (MCP)** 是由 Anthropic 开源的开放协议，为 AI 模型与外部数据源、工具之间提供标准化的通信接口。它让大语言模型能够安全、可控地访问文件系统、API、数据库等外部资源，是构建 AI Agent 基础设施的关键组件。
|
||
|
||
> [!question] 为什么需要 MCP？
|
||
> 在 MCP 出现之前，每个 AI 应用集成新数据源都需要写自定义代码——GitHub 一个接口、Slack 一个接口、公司内部 API 又一个接口。MCP 用一套统一协议解决了"重复造轮子"的问题：定义一次 Server，所有兼容 MCP 的 Client 都能使用。
|
||
|
||
---
|
||
|
||
## 核心架构
|
||
|
||
MCP 采用 **Client-Server** 架构，通过 JSON-RPC 2.0 进行通信：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph client["MCP Client（宿主应用）"]
|
||
C1["Claude Desktop"]
|
||
C2["Cursor / IDE"]
|
||
C3["自建应用"]
|
||
end
|
||
|
||
subgraph mcp_layer["MCP 协议层\n(JSON-RPC 2.0)"]
|
||
P1["Tools\n工具调用"]
|
||
P2["Resources\n数据读取"]
|
||
P3["Prompts\n模板预设"]
|
||
P4["Sampling\n子模型调用"]
|
||
end
|
||
|
||
subgraph server["MCP Server（能力提供者）"]
|
||
S1["文件系统 Server"]
|
||
S2["GitHub Server"]
|
||
S3["数据库 Server"]
|
||
S4["自定义 Server"]
|
||
end
|
||
|
||
C1 <-->|"stdio / SSE"| P1
|
||
C1 <-->|"stdio / SSE"| P2
|
||
C1 <-->|"stdio / SSE"| P3
|
||
C2 <-->|"stdio / SSE"| P4
|
||
C3 <-->|"HTTP SSE"| P1
|
||
|
||
P1 --> S1
|
||
P1 --> S2
|
||
P2 --> S3
|
||
P2 --> S4
|
||
P3 --> S1
|
||
P4 --> S2
|
||
|
||
style client fill:#e8f5e9
|
||
style mcp_layer fill:#fff3e0
|
||
style server fill:#e3f2fd
|
||
```
|
||
|
||
**三个核心角色：**
|
||
|
||
| 角色 | 职责 | 类比 |
|
||
|------|------|------|
|
||
| **Client** | 发起请求，连接 Server，将能力提供给 AI 模型 | "插件管理器" |
|
||
| **Server** | 暴露 Tools、Resources、Prompts 等能力 | "插件实现" |
|
||
| **Protocol** | 定义 JSON-RPC 通信格式和消息类型 | "USB 接口标准" |
|
||
|
||
> [!tip] 关键理解
|
||
> MCP **不是**另一个 LLM 框架或 SDK，它是一个**通信协议**。类似 HTTP 之于 Web 开发——你不需要"学 HTTP 框架"，只需要知道如何发起请求和响应。MCP 同理，Server 和 Client 各自用 JSON-RPC 说话。
|
||
|
||
---
|
||
|
||
## 三种核心能力
|
||
|
||
### 1. Tools — 让 AI 执行操作
|
||
|
||
Tools 允许 AI 模型调用函数并获取结果，是 MCP 最常用的能力类型。
|
||
|
||
```go
|
||
// Go 实现：注册一个「查询天气」Tool
|
||
server.AddTool(mcp.Tool{Name: "get_weather", Description: "查询指定地点的天气"},
|
||
func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
|
||
city := req.Arguments["city"].(string)
|
||
weather := queryWeather(city) // 调用实际业务逻辑
|
||
return mcp.SuccessResult(mcp.TextContent(weather)), nil
|
||
})
|
||
```
|
||
|
||
客户端调用流程：
|
||
|
||
```go
|
||
// Client 侧发起 Tool 调用
|
||
result, err := client.CallTool(ctx, "get_weather", map[string]any{
|
||
"city": "Beijing",
|
||
})
|
||
```
|
||
|
||
**典型场景：** 搜索代码仓库、创建 GitHub Issue、发送 Slack 消息、执行数据库查询。
|
||
|
||
### 2. Resources — 让 AI 读取数据
|
||
|
||
Resources 提供结构化的只读数据访问，AI 可以根据 URI 按需读取：
|
||
|
||
```go
|
||
// 注册一个 Resource Template（支持参数化 URI）
|
||
server.AddResourceTemplate(
|
||
mcp.ResourceTemplate{URI: "repo://{owner}/{repo}/file/{path}", Name: "Repository File"},
|
||
func(ctx context.Context, req mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
|
||
// 根据 URI 参数读取文件内容
|
||
content := readFile(req.Arguments["path"].(string))
|
||
return mcp.SuccessResult(mcp.TextContent(content)), nil
|
||
},
|
||
)
|
||
```
|
||
|
||
AI 可以通过 `repo://anthropic/claude-docs/file/README.md` 这样的 URI 读取任意仓库文件。
|
||
|
||
### 3. Prompts — 可复用的对话模板
|
||
|
||
Prompts 允许 Server 预定义结构化提示词模板，Client 加载后自动注入上下文：
|
||
|
||
```go
|
||
server.AddPrompt(mcp.Prompt{Name: "code_review", Description: "代码审查模板"},
|
||
func(ctx context.Context, req mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
|
||
diff := req.Arguments["diff"].(string)
|
||
return &mcp.GetPromptResult{
|
||
Messages: []mcp.PromptMessage{{
|
||
Role: mcp.RoleUser,
|
||
Content: mcp.TextContent(fmt.Sprintf(`请审查以下代码变更：
|
||
|
||
%s
|
||
|
||
重点关注：安全性、性能、可读性。`, diff)),
|
||
}},
|
||
}, nil
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 传输层：连接 Client 与 Server
|
||
|
||
MCP 支持两种传输方式，覆盖从本地到云端的完整场景：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
subgraph stdio_transport["本地进程通信"]
|
||
A["Local MCP Server"] -->|stdin/stdout| B[Host Application]
|
||
end
|
||
|
||
subgraph sse_transport["网络通信"]
|
||
C["Remote MCP Server"] -->|HTTP POST| D[SSE Endpoint]
|
||
D -->|Event Stream| E[Client App]
|
||
end
|
||
|
||
style stdio_transport fill:#e8f5e9
|
||
style sse_transport fill:#e3f2fd
|
||
```
|
||
|
||
| 传输方式 | 适用场景 | 特点 |
|
||
|----------|----------|------|
|
||
| **stdio** | 本地运行的 Server | 零配置，通过标准输入输出通信，适合命令行工具和本地集成 |
|
||
| **SSE (Server-Sent Events)** | 远程 Server | 通过 HTTP 端口暴露，适合云端服务和多客户端共享 |
|
||
|
||
> [!note] 底层原理
|
||
> 无论哪种传输方式，上层使用的都是相同的 **JSON-RPC 2.0** 消息格式。传输层仅负责"把消息送到对方手里"，不关心内容语义。
|
||
|
||
---
|
||
|
||
## JSON-RPC 消息格式
|
||
|
||
MCP 基于 JSON-RPC 2.0，消息结构简洁直观：
|
||
|
||
**初始化握手（Initialize）：**
|
||
|
||
```json
|
||
// Client → Server
|
||
{"jsonrpc":"2.0","id":1,"method":"initialize",
|
||
"params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{}},"clientInfo":{"name":"my-client","version":"1.0.0"}}}
|
||
|
||
// Server → Client 响应
|
||
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{}},"serverInfo":{"name":"weather-server","version":"1.0.0"}}}
|
||
```
|
||
|
||
**列出可用 Tools：**
|
||
|
||
```json
|
||
// Client → Server
|
||
{"jsonrpc":"2.0","method":"tools/list","id":2}
|
||
|
||
// Server → Client
|
||
{"jsonrpc":"2.0","result":{"tools":[{"name":"get_weather","description":"查询天气","inputSchema":{"type":"object","properties":{"city":{"type":"string"}}}}]}}
|
||
```
|
||
|
||
**调用 Tool：**
|
||
|
||
```json
|
||
{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"get_weather","arguments":{"city":"Tokyo"}}}
|
||
```
|
||
|
||
---
|
||
|
||
## 实战：从零搭建 MCP Server
|
||
|
||
以下是一个完整的 Go 实现示例，演示创建一个简单 MCP Server 的最小路径：
|
||
|
||
### Step 1：初始化项目
|
||
|
||
```bash
|
||
mkdir mcp-weather-server && cd mcp-weather-server
|
||
go mod init mcp-weather-server
|
||
go get github.com/modelcontextprotocol/go-sdk/mcp
|
||
```
|
||
|
||
### Step 2：编写 Server 代码
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"context"
|
||
"fmt"
|
||
"log"
|
||
|
||
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||
)
|
||
|
||
func main() {
|
||
// 创建 Stdio 传输（本地模式）
|
||
transport := mcp.NewStdioTransport()
|
||
|
||
// 创建 Server 实例
|
||
server := mcp.NewServer(&mcp.ServerInfo{Name: "weather-server", Version: "1.0.0"})
|
||
|
||
// 注册 Tool：查询天气
|
||
server.AddTool(mcp.Tool{
|
||
Name: "get_weather",
|
||
Description: "Query weather for a given city",
|
||
InputSchema: map[string]any{
|
||
"type": "object",
|
||
"properties": map[string]any{"city": map[string]string{"type": "string"}},
|
||
"required": []string{"city"},
|
||
},
|
||
}, handleGetWeather)
|
||
|
||
// 启动服务
|
||
if err := server.Run(context.Background(), transport); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
}
|
||
|
||
// 处理天气查询的核心逻辑
|
||
func handleGetWeather(ctx context.Context, req *mcp.CallToolRequest) (*mcp.CallToolResult, error) {
|
||
city := req.Arguments["city"].(string)
|
||
|
||
// 此处接入真实天气 API
|
||
response := fetchFromOpenWeather(city)
|
||
|
||
return &mcp.CallToolResult{
|
||
Content: []mcp.Content{mcp.TextContent(response)},
|
||
}, nil
|
||
}
|
||
|
||
func fetchFromOpenWeather(city string) string {
|
||
// TODO: 调用 OpenWeatherMap API
|
||
return fmt.Sprintf("City %s: Sunny, 23°C", city)
|
||
}
|
||
```
|
||
|
||
### Step 3：配置 Claude Desktop 使用
|
||
|
||
在 Claude Desktop 的配置文件中添加 Server：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"weather": {
|
||
"command": "go",
|
||
"args": ["run", "/path/to/mcp-weather-server"],
|
||
"transport": "stdio"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 4：验证效果
|
||
|
||
启动 Claude Desktop 后，在对话中直接告诉 AI "帮我查一下北京的天气"，AI 会自动识别调用 `get_weather` Tool。
|
||
|
||
> [!abstract] 代码说明
|
||
> 以上代码展示了 MCP Server 的三个核心步骤：**创建 Server → 注册 Tool → 启动传输**。实际项目中只需替换 `handleGetWeather` 中的业务逻辑即可。
|
||
|
||
---
|
||
|
||
## 常见开源 MCP Server 参考
|
||
|
||
| Server | 用途 | 技术栈 |
|
||
|--------|------|--------|
|
||
| **Filesystem** | 读写本地文件系统 | TypeScript |
|
||
| **GitHub** | Issue/PR/Code Search | TypeScript |
|
||
| **PostgreSQL** | 数据库查询 | Python |
|
||
| **GitLab** | GitLab 项目管理 | TypeScript |
|
||
| **Slack** | 消息收发 | Python |
|
||
| **Memory** | 向量存储的知识库 | TypeScript |
|
||
|
||
这些参考实现在 MCP 官方仓库的 `servers` 目录下，可以直接编译运行或二次开发。
|
||
|
||
---
|
||
|
||
## 安全考虑
|
||
|
||
MCP 的设计将权限控制交给了 Host Application（宿主应用），这带来了灵活性的同时也需要注意安全风险：
|
||
|
||
> [!warning] 安全最佳实践
|
||
> - **沙箱隔离**：对 Server 的文件/网络访问权限进行限制，避免恶意 Server 读写敏感数据
|
||
> - **权限最小化**：只授予 Server 完成工作所需的最小权限集
|
||
> - **审计日志**：记录所有 Tool 调用和 Resource 访问，便于追踪异常行为
|
||
> - **用户确认**：对破坏性操作（删除、修改）应在 AI 执行前请求用户确认
|
||
> - **依赖安全**：检查 Server 的代码依赖，防止供应链攻击
|
||
|
||
---
|
||
|
||
## MCP 与相关技术的关系
|
||
|
||
```mermaid
|
||
quadrantChart
|
||
title AI 集成生态中的位置
|
||
x-axis "专用集成" --> "通用协议"
|
||
y-axis "运行时绑定" --> "标准化抽象"
|
||
"Custom Integrations": [0.15, 0.1]
|
||
"OpenAI Function Calling": [0.3, 0.2]
|
||
"LangChain Tools": [0.25, 0.15]
|
||
"MCP": [0.7, 0.75]
|
||
"REST APIs": [0.85, 0.85]
|
||
"gRPC": [0.8, 0.9]
|
||
```
|
||
|
||
**核心区别：**
|
||
|
||
| 对比维度 | Function Calling | MCP |
|
||
|----------|------------------|-----|
|
||
| **作用域** | LLM API 内部的能力调用机制 | 跨应用的独立通信协议 |
|
||
| **可复用性** | 每次调用需重新定义 function deffinition | 一次部署，所有兼容 Client 共享 |
|
||
| **生命周期** | 单次请求内有效 | 持久运行的独立进程 |
|
||
| **生态位** | "LLM 怎么调用函数" | "应用之间怎么交换能力和数据" |
|
||
|
||
> [!note] 两者可以共存
|
||
> MCP Server 内部仍然可以使用 Function Calling 调用的方式与 LLM 交互。MCP 解决的是"应用层面的互操作"，Function Calling 解决的是"模型层面的函数感知"——二者在不同层级工作。
|
||
|
||
---
|
||
|
||
## 本章小结
|
||
|
||
| 概念 | 定位 | 一句话理解 |
|
||
|------|------|-----------|
|
||
| **Tools** | 操作型能力 | 让 AI "动手做事" |
|
||
| **Resources** | 数据型能力 | 让 AI "读取数据" |
|
||
| **Prompts** | 模板型能力 | 让 AI "复用话术" |
|
||
| **stdio 传输** | 本地通信 | 进程间 stdin/stdout |
|
||
| **SSE 传输** | 网络通信 | HTTP 流式推送 |
|
||
| **JSON-RPC 2.0** | 消息协议 | 统一的请求-响应格式 |
|
||
|
||
> [!success] 学习成果
|
||
> 完成本章后，你应该能够：
|
||
> - 理解 MCP 的 Client-Server 架构和工作原理
|
||
> - 区分 Tools、Resources、Prompts 三种核心能力的不同场景
|
||
> - 具备从零搭建一个 MCP Server 的能力
|
||
> - 了解 MCP 与传统 Function Calling 的关系与差异
|
||
|
||
---
|
||
|
||
## 扩展阅读
|
||
|
||
- MCP 官方规范：https://modelcontextprotocol.io/specification
|
||
- Go SDK 文档：https://github.com/modelcontextprotocol/go-sdk
|
||
- TypeScript SDK 文档：https://github.com/modelcontextprotocol/sdk
|
||
- 官方参考 Server：https://github.com/modelcontextprotocol/servers
|
||
|
||
## 关联笔记
|