《MCP协议开发实战：从零搭建 AI Agent 工具链（2026最新版）》
前言
2026 年，可以说是真正属于 AI Agent 的一年。
如果说 2025 年大家讨论最多的是：
- Function Calling
- Tool Calling
- RAG
- LangChain
那么 2026 年，几乎所有 AI Agent 平台讨论最多的都是：
MCP（Model Context Protocol）
7 月 28 日最新版 MCP 官方规范发布之后，整个协议已经逐渐稳定。
目前已经有：
- Claude Desktop
- Cursor
- Windsurf
- VSCode AI
- Continue
- OpenHands
- Roo Code
- Cline
- Gemini CLI
- OpenAI Agent SDK
- Koog
- LangGraph
大量产品开始全面支持 MCP。
一句话：
未来 Agent 的工具接口，大概率都会统一成 MCP。
一、什么是 MCP？
很多人第一次看到 MCP，会认为：
它是不是一种 API？
其实不是。
它更像：
USB Type-C。
以前：
每个 AI 都有自己的工具协议。
例如：
OpenAI
↓
Function Calling
Claude
↓
Tool Use
Gemini
↓
Extensions
LangChain
↓
Tool
AutoGen
↓
Skill
CrewAI
↓
Tool
Semantic Kernel
↓
Plugin全部都不一样。
开发者需要：
写五遍工具
维护五套接口
重复开发非常痛苦。
MCP 的目标就是：
统一工具协议。
任何 AI，只要支持 MCP：
AI
↓
MCP
↓
你的工具全部通用。
MCP 架构图
┌─────────────────────────────┐
│ AI Client │
│ Claude Cursor VSCode │
└────────────┬────────────────┘
│
│ JSON-RPC
│
┌────────────▼────────────────┐
│ MCP Server │
│ │
│ Tool │
│ Resource │
│ Prompt │
│ Sampling │
└────────────┬────────────────┘
│
─────────────┼────────────────────
│
数据库
Redis
HTTP API
企业系统
HarmonyOS
GitHubMCP Server 就像：
AI 世界里的 Spring Boot。
二、为什么 MCP 会成为标准？
原因只有一句：
AI 不想再学习各种 Tool API。
例如：
今天：
Claude
↓
tool A明天：
OpenAI
↓
tool B后天：
Gemini
↓
tool C开发者需要不停适配。
而 MCP：
AI
↓
MCP
↓
你的工具永远不用改。
三、MCP 核心组成
MCP 官方定义了几个对象：
Tool
Resource
Prompt
Sampling
Notification
Transport下面逐个讲解。
1、Tool（工具）
这是 MCP 最重要的能力。
例如：
天气查询：
getWeather(city)股票：
getStock(code)地图：
searchPOI(keyword)数据库：
query(sql)Git：
commit()AI 调用：
↓
Tool
↓
返回 JSON例如：
{
"temperature": 32,
"humidity": 68
}AI 自动理解。
Tool 生命周期
初始化
↓
注册
↓
模型发现
↓
模型调用
↓
执行
↓
返回结果全部标准化。
Tool Schema
MCP 使用 JSON Schema。
例如：
{
"name": "getWeather",
"description": "查询天气",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string"
}
}
}
}AI 自动生成参数。
无需 Prompt。
四、Resource（资源）
Resource 是：
AI 可读取的数据。
例如：
README.md
数据库
配置文件
日志
Markdown
PDF
网页AI：
读取
↓
分析
↓
回答而不是 Tool。
二者区别：
Tool：
执行动作Resource：
读取内容五、Prompt
Prompt 也可以注册。
例如：
代码评审
PR分析
日报生成
周报生成AI：
发现 Prompt
↓
调用 Prompt
↓
生成上下文非常方便。
六、Sampling
Sampling 是 MCP 最新的重要能力。
以前：
Client
↓
LLM现在：
Server
↓
请求 Client
↓
再次调用 LLM即：
Server 可以要求：
"请帮我继续推理。"
这是 Agent 能力的重要组成部分。
七、Transport（传输层）
MCP 支持多种通信方式：
stdio
HTTP
SSE
WebSocket（扩展实现）
Streamable HTTP其中：
开发工具：
stdio企业部署：
HTTP云端：
Streamable HTTP已经成为主流。
八、为什么新版 MCP 强调无状态（Stateless）
早期 MCP Server：
Client
↓
Session
↓
Server服务器维护：
Context
Memory
Conversation问题：
扩容困难
负载均衡困难
状态同步复杂新版规范建议：
所有状态
↓
Client 保存Server：
收到请求
↓
执行
↓
返回
↓
结束完全 Stateless。
优势：
- 更容易水平扩容
- 支持 Serverless 部署
- 降低内存占用
- 更适合 Kubernetes 与容器化
- 更容易实现高可用和弹性伸缩
九、开发第一个 MCP Server
下面将进入实战部分，我们会从零开始搭建一个完整的 MCP Server。
项目目标：
- 搭建 MCP Server
- 注册 Tool
- 注册 Resource
- 注册 Prompt
- 对接第三方 HTTP API
- 接入数据库
- 支持 Claude Desktop、Cursor 等客户端
- 实现日志、认证、权限控制
- 最终完成一个企业级 AI Agent 工具链。
第1章 MCP 基础架构与协议解析（上）
——彻底搞懂 MCP 为什么会成为 AI Agent 的基础设施
1.1 MCP 到底解决了什么问题？
在 MCP 出现之前，几乎每一个 AI 平台都有自己的 Tool Calling 规范。
例如：
OpenAI
↓
Function Calling
Claude
↓
Tool Use
Gemini
↓
Extensions
LangChain
↓
Tool
CrewAI
↓
Skill
Semantic Kernel
↓
Plugin如果你开发一个工具：
例如：
查询天气你需要写：
OpenAI版本
Claude版本
Gemini版本
LangChain版本
AutoGen版本接口全部不同。
企业项目通常都会出现这种情况：
天气服务
↓
SpringBoot API
↓
OpenAI
↓
Claude
↓
Cursor
↓
内部Agent同一个能力，需要包装五六层。
维护成本极高。
MCP 的目标
MCP 官方希望做到：
任何模型
↓
统一协议
↓
统一工具
↓
统一资源以后：
AI
↓
MCP
↓
你的系统模型不用适配。
工具不用重复开发。
MCP 不只是 Tool
很多文章介绍 MCP 时，只介绍 Tool。
实际上：
MCP 官方定义的是：
Model Context Protocol注意：
不是：
Tool Protocol为什么叫 Context？
因为 AI 真正需要的是：
上下文(Context)工具只是 Context 的一种。
真正提供给 AI 的内容包括：
Tool
Resource
Prompt
Sampling
Logging
Notification所以：
MCP 管理的是：
AI 能获取的一切上下文。
1.2 MCP 整体架构
完整架构如下：
+----------------------+
| AI Client |
| Claude / Cursor |
+----------+-----------+
|
JSON-RPC 2.0
|
+------------------+------------------+
| |
+-------v-------+ +-------v-------+
| MCP Server A | | MCP Server B |
| Weather | | GitHub |
+-------+-------+ +-------+-------+
| |
| |
+-------v-------+ +-------v-------+
| Weather API | | GitHub API |
+---------------+ +---------------+一个 AI 可以连接：
天气服务器
Git服务器
数据库服务器
文件服务器
搜索服务器全部通过 MCP。
这就是：
AI Tool Chain（工具链）
为什么要拆成多个 Server？
很多人第一次开发 MCP 都喜欢：
一个Server
里面放100个Tool实际上并不推荐。
企业一般这样拆：
Finance MCP
CRM MCP
OA MCP
Git MCP
Wiki MCP
DevOps MCP
HR MCP原因：
权限不同。
生命周期不同。
部署不同。
维护团队不同。
所以：
MCP 天然支持：
多个 Server
↓
一个 Client1.3 MCP 通信流程
AI 调用一次 Tool，
到底发生了什么？
例如：
用户说：
今天北京天气怎么样？整个流程：
用户
↓
AI
↓
判断需要天气
↓
查询Tool列表
↓
找到getWeather
↓
调用Tool
↓
返回JSON
↓
AI组织自然语言
↓
回答用户注意：
AI 并不知道：
getWeather()如何实现。
AI 只知道：
名字
描述
参数
返回结果因此：
Tool 永远都是：
黑盒。Tool Discovery（工具发现）
AI 第一次连接 Server：
首先发送：
initializeServer 返回：
我支持：
Tool
Prompt
Resource
Sampling然后：
AI 会请求：
tools/listServer 返回：
Tool A
Tool B
Tool CAI：
全部缓存。
所以：
用户第一次提问：
AI 已经知道：
有哪些工具整个时序图：
Client
↓
initialize
↓
Server
↓
返回Capability
↓
Client
↓
tools/list
↓
Server
↓
返回Tool列表
↓
Client缓存以后：
无需再次获取。
除非：
Tool更新1.4 JSON-RPC 通信协议
MCP 底层采用：
JSON-RPC 2.0很多后端同学都很熟悉。
例如：
请求：
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}Server：
{
"jsonrpc":"2.0",
"id":1,
"result":{
...
}
}调用 Tool：
{
"jsonrpc":"2.0",
"id":2,
"method":"tools/call",
"params":{
"name":"getWeather",
"arguments":{
"city":"北京"
}
}
}Server：
{
"jsonrpc":"2.0",
"id":2,
"result":{
"content":[
{
"type":"text",
"text":"32℃"
}
]
}
}是不是很简单？
实际上：
整个 MCP 通信，
都是：
JSON
+
JSON-RPC没有任何神秘的地方。
1.5 initialize 生命周期
所有 MCP Server，
第一步都是：
initialize流程：
Client
↓
initialize
↓
Server
↓
返回：
协议版本
Server名称
Capability
↓
Client
↓
initialized例如：
Client
↓
initialize
↓
{
protocolVersion
capabilities
clientInfo
}Server：
{
protocolVersion
serverInfo
capabilities
}其中：
ServerInfo：
{
name
version
}例如：
HarmonyOS MCP
v1.0.0Capability（能力协商）
这是 MCP 最大特点。
Client：
不会假设：
Server支持全部功能而是：
询问：
你支持什么？例如：
Server：
支持：
Tool
Prompt
Resource
Sampling另一个：
Server：
只有ToolAI：
自动适配。
所以：
MCP：
非常灵活。
Capability 示例：
{
"capabilities": {
"tools": {},
"resources": {},
"prompts": {},
"sampling": {}
}
}AI：
看到：
sampling就知道：
这个 Server：
可以请求模型继续推理。
1.6 Tool 为什么不用 Prompt？
很多人第一次看到：
description会疑惑：
为什么：
没有 Prompt？
实际上：
AI 自动理解：
例如：
{
"name":"getWeather",
"description":"获取指定城市天气"
}LLM 会理解：
天气
↓
城市
↓
调用如果：
用户：
杭州今天多少度？AI：
自动：
city=杭州无需：
Prompt。
再例如：
Git Commit描述：
提交Git代码用户：
帮我提交代码AI：
自动调用。
这就是：
Schema 驱动。
而不是：
Prompt 驱动。
1.7 为什么 Tool 一定要有 Schema？
如果：
没有 Schema：
AI：
不知道：
需要几个参数？
参数叫什么？
参数类型？
哪些必填？例如：
Tool：
createUserSchema：
{
"type":"object",
"properties":{
"name":{
"type":"string"
},
"age":{
"type":"integer"
}
},
"required":[
"name"
]
}AI：
立即知道：
需要：
name
可选：
age甚至：
还能自动：
追问用户：
请告诉我姓名。这就是 Schema 的价值。
第1章 MCP 基础架构与协议解析（下）
1.8 MCP 消息格式与 JSON-RPC 全流程解析
1.8 为什么 MCP 选择 JSON-RPC？
很多人都会问：
为什么不用 REST？
为什么不用 GraphQL？
为什么不用 gRPC？
官方最终选择了：
JSON-RPC 2.0主要原因有五个。
原因一：天然支持 Request / Response
REST：
GET
POST
PUT
DELETE而 AI Tool 调用其实只有一种：
调用一个方法JSON-RPC 天然就是：
method
↓
params
↓
result十分契合。
原因二：支持双向通信
REST：
一般都是：
Client
↓
Server而 MCP：
Client
↓
Server
↓
Client
↓
Server例如 Sampling：
Server
↓
请 Client 再调用一次 LLM
↓
Client 返回结果REST 很难表达这种模式。
原因三：天然支持通知（Notification）
例如：
日志
进度
事件JSON-RPC：
可以没有 id。
例如：
{
"jsonrpc":"2.0",
"method":"notifications/message",
"params":{
"level":"info",
"message":"开始分析仓库..."
}
}Client：
收到即可。
无需回复。
原因四：跨语言成本极低
任何语言都有：
JSON
Socket
stdin/stdout因此：
Java
↓
Python
↓
Node
↓
Go
↓
Rust
↓
Kotlin
全部可以实现。
原因五：协议十分轻量
整个 MCP：
实际上只有：
JSON
+
JSON-RPC
+
Schema没有：
HTTP框架
Session
Cookie
数据库因此：
学习成本极低。
1.9 一次完整 MCP 会话
下面模拟一次真实通信。
假设：
Cursor 连接 Weather MCP。
第一步
建立连接。
如果是 stdio：
Cursor
↓
启动：
weather-server.exe如果：
HTTP：
POST
/mcp如果：
Streamable HTTP：
建立长连接第二步
initialize
Client：
{
"jsonrpc":"2.0",
"id":1,
"method":"initialize",
"params":{
"protocolVersion":"2026-07-28",
"capabilities":{
"sampling":{}
},
"clientInfo":{
"name":"Cursor",
"version":"1.2"
}
}
}这里：
包含：
协议版本
客户端信息
客户端能力Server：
{
"jsonrpc":"2.0",
"id":1,
"result":{
"protocolVersion":"2026-07-28",
"serverInfo":{
"name":"Weather MCP",
"version":"1.0"
},
"capabilities":{
"tools":{},
"resources":{},
"prompts":{}
}
}
}至此：
双方知道：
彼此支持什么能力。这就是：
Capability Negotiation（能力协商）。
第三步
Client：
发送：
initialized注意：
很多新人容易忽略这一条。
例如：
{
"jsonrpc":"2.0",
"method":"notifications/initialized"
}为什么需要？
因为：
initialize
只是：
能力协商initialized
表示：
可以正式开始工作。很多 SDK 都会自动发送。
第四步
获取 Tool。
Client：
{
"jsonrpc":"2.0",
"id":2,
"method":"tools/list"
}Server：
返回：
{
"jsonrpc":"2.0",
"id":2,
"result":{
"tools":[
{
"name":"getWeather",
"description":"查询天气",
"inputSchema":{
...
}
},
{
"name":"getAQI",
"description":"空气质量"
}
]
}
}Cursor：
缓存。
Claude：
缓存。
VS Code：
缓存。
后面：
不用重复请求。
第五步
用户：
杭州今天多少度？LLM：
推理：
需要：
getWeather于是：
Client：
发送：
{
"jsonrpc":"2.0",
"id":3,
"method":"tools/call",
"params":{
"name":"getWeather",
"arguments":{
"city":"杭州"
}
}
}Server：
执行：
HTTP API
↓
天气平台返回：
{
"jsonrpc":"2.0",
"id":3,
"result":{
"content":[
{
"type":"text",
"text":"杭州今天32℃，晴。"
}
]
}
}随后：
LLM：
组织自然语言：
今天杭州天气晴，
最高32℃，
适合出行。整个调用结束。
1.10 Tool Call 生命周期
完整流程：
User
↓
LLM 推理
↓
选择 Tool
↓
参数补全
↓
Client
↓
tools/call
↓
Server
↓
执行业务
↓
返回 JSON
↓
LLM 生成回答
↓
User整个过程：
AI：
并不会：
直接访问数据库。所有能力：
都来自：
MCP。
1.11 Resource 生命周期
Tool：
执行动作。
而：
Resource：
读取内容。
例如：
README
PDF
Markdown
日志
数据库Client：
请求：
{
"jsonrpc":"2.0",
"id":5,
"method":"resources/list"
}Server：
返回：
README
API文档
用户手册
数据库随后：
Client：
读取：
{
"method":"resources/read",
"params":{
"uri":"docs://readme"
}
}Server：
返回：
MarkdownAI：
分析。
1.12 Prompt 生命周期
Prompt：
也是一种资源。
例如：
Code Review
日报
SQL优化
周报Client：
prompts/listServer：
返回：
日报模板
↓
PR模板
↓
代码Review模板随后：
AI：
prompts/getServer：
返回：
Prompt内容AI：
直接拼接上下文。
1.13 Sampling 生命周期
Sampling：
新版 MCP 最有意思的能力。
例如：
AI：
调用：
Git ToolServer：
发现：
需要总结：
Git Diff但是：
Server：
没有：
LLM。
怎么办？
Server：
发送：
sampling/createMessageClient：
收到：
请调用模型：
总结以下Diff...LLM：
完成。
结果：
再返回：
Server。
整个过程：
Server
↓
Client
↓
LLM
↓
Client
↓
Server这就是：
Server 借用 Client 模型能力。
1.14 Notification（通知）
除了：
Request。
还有：
Notification。
例如：
日志。
Server：
开始读取Git仓库...发送：
{
"jsonrpc":"2.0",
"method":"notifications/message",
"params":{
"level":"info",
"message":"开始扫描..."
}
}没有：
id。
因为：
无需回复。同理：
还有：
Progress
Warning
Error
Log全部属于：
Notification。
1.15 Progress（进度）
假设：
工具：
扫描：
10000
个文件如果：
一分钟：
没有任何输出。
用户：
会认为：
卡死。因此：
Server：
可以发送：
{
"jsonrpc":"2.0",
"method":"notifications/progress",
"params":{
"progress":45,
"total":100
}
}Cursor：
显示：
45%用户体验：
大幅提升。
1.16 Error（错误）
JSON-RPC：
统一错误格式。
例如：
{
"jsonrpc":"2.0",
"id":3,
"error":{
"code":-32602,
"message":"Invalid params"
}
}常见错误：
| 错误码 | 含义 |
|---|---|
| -32700 | JSON 解析失败 |
| -32600 | 非法请求 |
| -32601 | 方法不存在 |
| -32602 | 参数错误 |
| -32603 | 内部错误 |
建议：
业务错误：
不要：
直接：
throw Exception而应该：
包装：
错误码
错误描述
可恢复建议例如：
Git仓库不存在
↓
建议：
请确认仓库路径。AI：
还能：
自动解释给用户。
1.17 MCP 为什么强调无状态？
这是最新版规范最大的变化之一。
以前：
很多 MCP Server：
都会保存：
Conversation
Memory
Session后来发现：
扩容困难。
因此：
新版：
推荐：
所有状态：
Client 保存。Server：
每一次：
收到请求
↓
执行
↓
返回
↓
释放资源因此：
Server：
可以：
无限水平扩容。这也是为什么：
MCP 非常适合：
Docker
Kubernetes
Serverless
云原生部署。
1.18 一张图理解整个协议
User
│
▼
+------------------+
| Client |
| Claude / Cursor |
+------------------+
│
initialize / tools/list
│
▼
+------------------+
| MCP Server |
+------------------+
│ │ │
│ │ │
Tool Resource Prompt
│
▼
HTTP API / DB / Git / 企业系统可以看到，MCP Server 更像是 AI 与企业系统之间的一层标准化适配层。它屏蔽了底层业务实现细节，对外只暴露统一的协议接口，让任何支持 MCP 的 AI Client 都能够安全、规范地调用企业能力。
第2章 开发环境搭建（2026最新版）
——30分钟搭建属于自己的第一个 MCP Server
2.1 MCP 官方 SDK 介绍
很多人第一次开发 MCP 时都会问：
是不是必须自己实现 JSON-RPC？
答案：
完全不用。
官方已经提供了多种语言 SDK。
目前主流包括：
| SDK | 推荐指数 | 企业使用 |
|---|---|---|
| Node.js SDK | ⭐⭐⭐⭐⭐ | 非常多 |
| Python SDK | ⭐⭐⭐⭐⭐ | AI项目最多 |
| Kotlin SDK（Koog） | ⭐⭐⭐⭐☆ | 增长很快 |
| Java SDK | ⭐⭐⭐⭐☆ | 企业后台 |
| Go SDK | ⭐⭐⭐⭐☆ | 云原生 |
| Rust SDK | ⭐⭐⭐☆☆ | 高性能 |
为什么推荐 SDK？
如果自己实现：
你需要处理：
JSON-RPC
initialize
Capability
Tool
Prompt
Resource
Sampling
Error
Notification
Progress工作量非常大。
SDK 已经帮你完成：
协议解析
Tool注册
Schema生成
生命周期
Transport开发者：
只需要：
写业务代码。2.2 一个 MCP Server 到底有多简单？
很多人以为：
MCP Server：
至少几百行代码。
实际上：
真正的 Server：
通常只有几十行。
例如：
创建Server
↓
注册Tool
↓
启动Server结束。
是不是很像：
Spring Boot：
@SpringBootApplication
public class Application{
public static void main(String[] args){
}
}MCP：
也是如此。
2.3 推荐目录结构
企业项目：
推荐如下：
weather-mcp/
│
├── src/
│
├── tools/
│ weatherTool
│ searchTool
│ gitTool
│
├── resources/
│ readme
│ docs
│
├── prompts/
│ review
│ summary
│
├── services/
│ weatherService
│ httpService
│
├── config/
│
├── utils/
│
└── main为什么不要：
main.js
weather.js
tool.js
util.js因为：
后期：
Tool：
可能：
几十个
甚至几百个。2.4 Tool 如何划分？
很多新人喜欢：
一个Tool：
什么都做。例如：
GitTool里面：
commit()
push()
pull()
clone()
branch()
merge()
tag()
checkout()几千行。
实际上：
推荐：
一个 Tool：
只做：
一件事情。
例如：
GitCommitTool
GitPushTool
GitPullTool
GitCloneTool优势：
- 更容易维护
- AI 更容易选择
- Schema 更简单
- 参数更少
2.5 Tool Description 编写原则
AI：
选择 Tool：
主要依赖：
name
description因此：
Description：
非常重要。
例如：
错误：
天气AI：
不知道：
什么意思。
正确：
查询指定城市实时天气再例如：
错误：
Git正确：
提交当前工作区修改到Git仓库越具体：
AI：
越容易：
调用正确。
2.6 Tool Name 命名规范
推荐：
使用：
camelCase例如：
getWeather
searchHotel
createIssue
queryDatabase
sendEmail不要：
weather
tool1
aaa
testAI：
无法理解。
2.7 Schema 编写规范
一个优秀 Schema：
应该做到：
参数明确
类型明确
必填明确
描述明确例如：
{
"type":"object",
"properties":{
"city":{
"type":"string",
"description":"需要查询天气的城市"
}
},
"required":[
"city"
]
}AI：
看到：
城市即可：
自动：
提取：
杭州
北京
上海无需：
Prompt。
2.8 一个好的 Tool 应该满足什么？
官方推荐：
一个 Tool：
最好：
满足：
第一：
职责单一。
不要：
查询天气
↓
顺便查空气
↓
顺便查酒店
↓
顺便订酒店拆开。
第二：
返回结构稳定。
例如：
始终：
{
"temperature":32,
"humidity":68
}不要：
今天：
字符串明天：
HTML后天：
MarkdownAI：
会困惑。
第三：
返回机器可理解数据。
错误：
今天天气不错。正确：
{
"temperature":32,
"condition":"Sunny"
}自然语言：
留给：
LLM。
2.9 Resource 如何组织？
很多人：
第一次开发：
把：
所有文件：
都注册：
Resource。
实际上：
推荐：
产品文档
API文档
README
FAQ
帮助中心
知识库不要：
node_modules
build
cache
tmp否则：
AI：
上下文：
污染。
2.10 Prompt 如何组织？
企业项目：
Prompt：
推荐：
分类。
例如：
prompts/
code/
report/
qa/
translate/
sql/不要：
几十个 Prompt：
放一起。
2.11 企业级项目目录
真正的大型 MCP：
通常：
如下：
src
├── controller
├── tool
│ git
│ weather
│ email
│ db
│
├── prompt
├── resource
├── service
├── repository
├── dto
├── model
├── config
├── middleware
├── auth
├── cache
├── logger
├── metrics
└── transport是不是：
已经：
很像：
Spring Boot？
实际上：
企业 MCP：
就是：
一个：
轻量级：
微服务。
2.12 Transport 如何选择？
很多新人：
容易纠结：
到底：
选择：
stdio？
还是：
HTTP？
还是：
SSE？
建议：
| 场景 | 推荐 |
|---|---|
| Claude Desktop | stdio |
| Cursor | stdio |
| VS Code | stdio |
| 本地开发 | stdio |
| 企业网关 | HTTP |
| 云端服务 | Streamable HTTP |
| Kubernetes | HTTP |
一句话：
开发：
stdio。
部署：
HTTP。
2.13 日志系统
建议：
不要：
console.log()推荐：
统一：
Logger
↓
INFO
WARN
ERROR
DEBUG例如：
INFO：
开始调用天气接口
↓
INFO：
返回成功
↓
ERROR：
超时方便：
Cursor：
显示：
Notification。
2.14 配置管理
不要：
写死：
API Key
URL
Token推荐：
.env
config
yaml例如：
WEATHER_API_KEY=
DB_URL=
REDIS_URL=这样：
部署：
更加方便。
第3章 编写第一个 MCP Server（上）
——从零实现一个可以被 Cursor / Claude Desktop 调用的 AI Agent 工具
前面两章，我们已经学习了：
- MCP 的协议原理
- JSON-RPC 通信流程
- Tool / Resource / Prompt 模型
- Stateless 无状态架构
- 企业级项目结构
现在开始真正写代码。
本章目标：
我们实现一个：
天气查询 MCP Server
最终效果：
用户：
查询一下北京今天的天气AI：
自动发现：
getWeather调用：
MCP Server
↓
天气接口
↓
返回结果最终：
AI 输出：
北京今天晴天，
温度 32℃，
湿度 45%3.1 技术选型
本章使用：
方案一：Node.js
原因：
目前 MCP 生态最成熟。
适合：
- Cursor
- Claude Desktop
- VS Code Extension
- 快速原型开发
技术：
Node.js
+
TypeScript
+
MCP SDK项目：
weather-mcp-server3.2 环境准备
安装 Node.js
推荐：
Node.js 22+
检查：
node -v输出：
例如：
v22.12.0npm：
npm -v例如：
10.x3.3 创建项目
创建目录：
mkdir weather-mcp-server
cd weather-mcp-server初始化：
npm init -y生成：
package.json安装 TypeScript：
npm install typescript ts-node @types/node --save-dev初始化：
npx tsc --init生成：
tsconfig.json3.4 安装 MCP SDK
安装：
npm install @modelcontextprotocol/sdk安装完成：
package.json：
{
"dependencies":{
"@modelcontextprotocol/sdk":"latest"
}
}3.5 创建项目结构
最终：
weather-mcp-server
├── src
│ ├── index.ts
│ ├── tools
│ │ └── weather.ts
│ │
│ └── services
│ └── weatherService.ts
├── package.json
└── tsconfig.json
为什么拆？
因为：
MCP Server：
不要：
全部写：
index.ts。
推荐：
index
↓
tool
↓
service
↓
API类似：
Spring Boot：
Controller
↓
Service
↓
Repository3.6 创建 MCP Server
创建：
src/index.ts代码：
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
StdioServerTransport
} from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server(
{
name:"weather-mcp",
version:"1.0.0"
},
{
capabilities:{
tools:{}
}
}
);
const transport =
new StdioServerTransport();
await server.connect(
transport
);运行：
node index.js现在：
你的 MCP Server：
已经启动。
但是：
还没有 Tool。
AI：
连接以后：
发现：
tools=[]没有任何能力。
3.7 添加第一个 Tool
创建：
src/tools/weather.ts代码：
export const weatherTool = {
name:"getWeather",
description:
"查询指定城市当前天气信息",
inputSchema:{
type:"object",
properties:{
city:{
type:"string",
description:
"城市名称"
}
},
required:[
"city"
]
}
};这里：
最重要：
三个字段：
name
工具名字：
getWeatherAI：
看到：
知道：
调用它。
description
工具描述：
例如：
查询天气不推荐。
推荐：
查询指定城市当前天气信息更加准确。
inputSchema
告诉 AI：
参数。
例如：
用户：
上海天气AI：
生成：
{
"city":"上海"
}3.8 注册 Tool
修改：
index.ts增加：
import {
weatherTool
}
from "./tools/weather.js";注册：
server.setRequestHandler(
"tools/list",
async()=>{
return {
tools:[
weatherTool
]
};
}
);现在：
Client 请求：
tools/list返回：
{
"tools":[
{
"name":"getWeather"
}
]
}AI：
发现：
有工具。
3.9 实现 Tool 调用
继续：
添加：
server.setRequestHandler(
"tools/call",
async(request)=>{
const name =
request.params.name;
if(name==="getWeather"){
const city =
request.params.arguments.city;
return {
content:[
{
type:"text",
text:
`${city}今天晴天，32℃`
}
]
};
}
throw new Error(
"Tool不存在"
);
}
);现在：
完整流程：
用户
↓
AI
↓
getWeather
↓
city=北京
↓
MCP Server
↓
返回天气3.10 完整 index.ts
最终：
import { Server }
from "@modelcontextprotocol/sdk/server/index.js";
import {
StdioServerTransport
}
from "@modelcontextprotocol/sdk/server/stdio.js";
const server =
new Server(
{
name:"weather-mcp",
version:"1.0.0"
},
{
capabilities:{
tools:{}
}
});
server.setRequestHandler(
"tools/list",
async()=>{
return {
tools:[
{
name:"getWeather",
description:
"查询指定城市当前天气",
inputSchema:{
type:"object",
properties:{
city:{
type:"string"
}
},
required:[
"city"
]
}
}
]
};
}
);
server.setRequestHandler(
"tools/call",
async(request)=>{
if(
request.params.name
==="getWeather"
){
const city =
request.params.arguments.city;
return {
content:[
{
type:"text",
text:
`${city}今天晴天，32℃`
}
]
};
}
throw new Error(
"Unknown Tool"
);
}
);
const transport =
new StdioServerTransport();
await server.connect(
transport
);3.11 启动测试
修改：
package.json：
增加：
{
"scripts":{
"start":
"node src/index.ts"
}
}运行：
npm start如果没有错误：
说明：
MCP Server：
启动成功。
3.12 使用 MCP Inspector 调试
官方提供：
MCP Inspector。
安装：
npm install -g @modelcontextprotocol/inspector启动：
mcp-inspector连接：
你的 Server。
可以看到：
Tools
↓
getWeather点击：
测试：
输入：
{
"city":"北京"
}返回：
北京今天晴天，32℃3.13 接入 Cursor
Cursor：
打开：
Settings
↓
MCP
↓
Add Server
配置：
{
"mcpServers":{
"weather":{
"command":
"node",
"args":[
"/path/weather-mcp-server/src/index.ts"
]
}
}
}重新启动 Cursor。
输入：
北京天气Cursor：
显示：
Calling getWeather然后：
返回：
北京今天晴天，32℃3.14 到这里完成了什么？
我们已经实现：
✅ MCP Server
✅ initialize
✅ Capability
✅ tools/list
✅ tools/call
✅ Tool Schema
✅ stdio Transport
✅ AI Client 调用
这已经是一个完整 MCP Server。
但是：
现在还有几个问题：
问题1
天气数据是假数据。
需要：
接入真实 API。
问题2
Tool 全部写在：
index.ts
后期无法维护。
问题3
没有：
- 日志
- 异常处理
- 超时
- 重试
- 权限控制
企业项目：
必须完善。
第3章 编写第一个 MCP Server（下）
——从 Demo 升级到企业级 MCP Agent 服务
上一节，我们已经完成了一个最简单的 MCP Server：
AI Client
↓
MCP Server
↓
getWeather Tool
↓
返回天气但是，这个版本距离生产环境还有很大距离。
真实企业项目中，一个 MCP Server 通常需要：
- 调用外部 API
- 访问数据库
- 权限校验
- 日志追踪
- 异常恢复
- 超时控制
- 缓存
- 监控
- Docker 部署
这一节，我们开始进行工程化改造。
3.15 为什么不能把业务全部写在 MCP Server？
上一节：
tools/call
{
if(name==="getWeather"){
调天气接口
}
}这种方式：
Demo 可以。
生产不行。
原因：
假设未来增加：
getWeather
getAirQuality
getWeatherHistory
getWeatherWarning
getCityInfo最后：
index.ts：
变成：
2000行代码维护灾难。
正确架构：
MCP Client
|
|
MCP Server
|
+-----------+------------+
| |
Tool层 Resource层
|
|
Service层
|
|
外部系统
API / DB / Redis类似 Spring Boot：
Controller
↓
Service
↓
Repository3.16 重构项目结构
调整：
weather-mcp-server
src
├── index.ts
├── server
│ └── mcpServer.ts
├── tools
│ └── weatherTool.ts
├── services
│ └── weatherService.ts
├── clients
│ └── httpClient.ts
├── models
│ └── weather.ts
├── utils
│ └── logger.ts
└── config
└── env.ts
职责：
| 模块 | 作用 |
|---|---|
| server | MCP生命周期 |
| tools | AI工具定义 |
| services | 业务逻辑 |
| clients | 外部接口 |
| models | 数据模型 |
| utils | 公共能力 |
| config | 配置 |
3.17 创建 Service 层
创建：
services/weatherService.ts代码：
export class WeatherService {
async getWeather(city:string){
// 模拟调用接口
return {
city,
temperature:32,
condition:"Sunny",
humidity:45
};
}
}注意：
这里不关心：
MCP。
它只是普通业务代码。
未来：
可以：
Web调用
App调用
Agent调用
MCP调用全部复用。
3.18 创建 Tool 层
创建：
tools/weatherTool.ts代码：
import {
WeatherService
}
from "../services/weatherService.js";
const service =
new WeatherService();
export const weatherTool = {
name:"getWeather",
description:
"查询指定城市实时天气信息",
inputSchema:{
type:"object",
properties:{
city:{
type:"string",
description:
"城市名称"
}
},
required:[
"city"
]
}
};
export async function executeWeatherTool(
args:any
){
const result =
await service.getWeather(
args.city
);
return {
content:[
{
type:"text",
text:
JSON.stringify(
result
)
}
]
};
}现在：
Tool：
只负责：
AI输入
↓
参数转换
↓
调用Service业务：
全部：
在Service。
3.19 创建 MCP Server 管理类
创建：
server/mcpServer.ts代码：
import {
Server
}
from "@modelcontextprotocol/sdk/server/index.js";
import {
weatherTool,
executeWeatherTool
}
from "../tools/weatherTool.js";
export function createServer(){
const server =
new Server(
{
name:"weather-mcp",
version:"1.0.0"
},
{
capabilities:{
tools:{}
}
}
);
server.setRequestHandler(
"tools/list",
async()=>{
return {
tools:[
weatherTool
]
};
}
);
server.setRequestHandler(
"tools/call",
async(request)=>{
if(
request.params.name
==="getWeather"
){
return await executeWeatherTool(
request.params.arguments
);
}
throw new Error(
"Unknown tool"
);
}
);
return server;
}优势：
以后增加 Tool：
只需要：
tools/
weatherTool
gitTool
emailTool
dbTool3.20 入口文件简化
现在：
index.ts：
只剩：
import {
createServer
}
from "./server/mcpServer.js";
import {
StdioServerTransport
}
from "@modelcontextprotocol/sdk/server/stdio.js";
const server =
createServer();
const transport =
new StdioServerTransport();
await server.connect(
transport
);是不是很像：
Spring Boot：
main：
只负责启动。
3.21 接入真实天气 API
生产：
不能：
return {
temperature:32
}需要：
调用：
例如：
天气平台
↓
HTTP API
↓
JSON创建：
clients/httpClient.ts封装：
export async function get(
url:string
){
const response =
await fetch(url);
if(!response.ok){
throw new Error(
"HTTP Error"
);
}
return response.json();
}以后：
所有 HTTP：
统一管理。
3.22 Weather Client
创建：
clients/weatherClient.ts代码：
import {
get
}
from "./httpClient.js";
export async function queryWeather(
city:string
){
const url =
`https://api.weather.com/${city}`;
return await get(url);
}Service：
修改：
import {
queryWeather
}
from "../clients/weatherClient.js";
export class WeatherService{
async getWeather(city:string){
return await queryWeather(city);
}
}现在：
结构：
变成：
Tool
↓
Service
↓
Client
↓
HTTP API3.23 参数校验
AI 生成参数：
虽然很智能。
但是：
不能完全相信。
例如：
AI：
可能传：
{
"city":123
}或者：
{}所以：
必须校验。
安装：
npm install zod定义：
import {
z
}
from "zod";
export const WeatherSchema =
z.object({
city:
z.string()
.min(1)
});调用：
const data =
WeatherSchema.parse(args);错误：
自动：
抛出。
3.24 错误处理
不要：
直接：
throw Error()推荐：
统一：
class MCPError extends Error{
code:string;
constructor(
code:string,
message:string
){
super(message);
this.code=code;
}
}例如：
throw new MCPError(
"CITY_NOT_FOUND",
"城市不存在"
);AI：
可以理解：
城市不存在
↓
请重新输入城市3.25 日志系统
生产必须：
记录：
用户请求
Tool调用
参数
耗时
异常创建：
utils/logger.ts代码：
export const logger={
info(
message:string
){
console.error(
"[INFO]",
message
);
},
error(
message:string
){
console.error(
"[ERROR]",
message
);
}
};为什么：
console.error？
因为：
MCP stdio 模式：
stdout：
用于协议通信。
如果：
console.log：
会污染：
JSON-RPC。
这是很多新人踩坑。
3.26 MCP Notification 日志
MCP 支持：
主动通知 Client。
例如：
工具执行：
开始查询天气
↓
调用API
↓
完成发送：
{
"method":
"notifications/message",
"params":{
"level":"info",
"message":
"正在查询天气"
}
}Cursor：
可以展示。
3.27 超时控制
外部 API：
可能：
10秒。
30秒。
甚至：
一直等待。
必须：
限制。
例如：
const controller =
new AbortController();
setTimeout(()=>{
controller.abort();
},5000);超过：
5秒：
取消。
3.28 重试机制
网络：
偶尔失败。
例如：
第一次：
503第二次：
成功。
推荐：
指数退避：
第一次
1秒
第二次
2秒
第三次
4秒公式：
delay = 2^retry3.29 Docker 部署 MCP Server
Dockerfile：
FROM node:22
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
CMD [
"node",
"src/index.ts"
]构建：
docker build -t weather-mcp .运行：
docker run weather-mcp企业环境：
通常：
Kubernetes
↓
Service
↓
MCP Server Pod3.30 本章完成效果
现在我们的 MCP Server：
已经具备：
✅ 标准 MCP 协议
✅ Tool 注册
✅ Service 分层
✅ HTTP 调用
✅ 参数校验
✅ 错误处理
✅ 日志系统
✅ 超时控制
✅ Docker部署能力
已经接近：
生产级 MCP 服务。
第4章 MCP Tool 开发实战（上）
——从简单函数到企业级 AI Agent 工具设计
前面三章，我们已经完成：
- MCP 协议理解
- MCP Server 搭建
- 第一个 Tool 实现
- 企业级项目结构改造
但是很多开发者真正开始做 Agent 时，会遇到一个核心问题：
为什么我的 Tool 明明注册成功了，AI 却不会调用？
或者：
为什么 AI 经常选择错误的 Tool？
原因：
大部分问题不是 MCP 协议问题。
而是：
Tool 设计问题。
4.1 什么是 MCP Tool？
简单理解：
MCP Tool：
就是：
暴露给 AI 调用的函数。
传统开发：
函数：
function getWeather(city){
}调用者：
程序员决定：
什么时候调用。
AI Agent：
不同。
调用者：
LLM它需要：
自己判断：
什么时候调用。
例如：
用户：
上海今天温度多少？AI：
思考：
我需要天气工具然后：
调用：
getWeather所以：
普通函数：
关注：
怎么执行AI Tool：
还必须关注：
AI什么时候调用4.2 MCP Tool 四大组成
一个标准 Tool：
包含：
name
description
inputSchema
handler例如：
{
"name":"searchUser",
"description":"根据用户ID查询用户信息",
"inputSchema":{
"type":"object",
"properties":{
"userId":{
"type":"string"
}
}
}
}然后：
handler：
执行：
async function handler(args){
}4.3 Tool Name 设计
很多人：
随便命名。
例如：
tool1
search
query
data这是错误的。
因为：
LLM 看到：
名字。
它需要理解含义。
推荐规则
格式：
动词 + 名词例如：
查询：
getUser创建：
createOrder搜索：
searchProduct删除：
deleteFile更新：
updateProfile不要：
user因为：
它不知道：
这是：
查询？
创建？
删除？
4.4 Tool Description 是最重要字段
很多 MCP 项目失败：
原因：
description 写得太差。
错误：
{
"name":"weather",
"description":"天气"
}AI：
不知道：
什么时候使用。
正确：
{
"name":"getWeather",
"description":
"查询指定城市当前天气情况，包括温度、湿度、天气状态"
}为什么？
因为：
LLM 判断 Tool：
主要依靠：
name
description
schema4.5 Description 编写公式
推荐：
使用：
动作 + 对象 + 范围
公式：
[做什么]
+
[针对什么]
+
[返回什么]例如：
数据库：
不好：
数据库查询好：
执行只读SQL查询，返回指定表的数据记录Git：
不好：
Git工具好：
获取Git仓库当前状态，包括修改文件、分支信息和提交状态文件：
不好：
读取文件好：
读取指定路径文本文件内容，用于代码分析和文档理解4.6 Input Schema 设计
Schema：
决定：
AI 如何生成参数。
例如：
查询订单：
错误：
{
"param":"订单"
}正确：
{
"type":"object",
"properties":{
"orderId":{
"type":"string",
"description":
"订单唯一编号"
}
},
"required":[
"orderId"
]
}AI：
知道：
需要：
orderId4.7 必填参数设计
原则：
能少不要多。
错误：
{
"country":"",
"province":"",
"city":"",
"district":"",
"street":"",
"number":""
}用户：
说：
北京天气AI：
无法补全。
优化：
{
"city":"北京"
}让：
LLM：
发挥优势。
4.8 参数默认值
很多 Tool：
需要：
默认值。
例如：
查询列表：
limit
page
sort不要：
全部要求。
例如：
{
"page":{
"type":"number",
"default":1
},
"limit":{
"type":"number",
"default":20
}
}AI：
自动：
填充。
4.9 返回结果设计
这是非常关键。
很多人：
Tool 返回：
一句话：
查询成功这是错误。
AI Tool：
应该返回：
结构化数据。
例如：
天气：
错误：
今天32度正确：
{
"city":"北京",
"temperature":32,
"condition":"晴",
"humidity":40
}为什么？
因为：
后面可能：
继续：
根据天气推荐穿衣AI：
需要字段。
4.10 Tool 返回格式
MCP 推荐：
Content：
例如：
{
"content":[
{
"type":"text",
"text":"天气信息"
}
]
}除了 text：
还可以：
{
"type":"image"
}或者：
{
"type":"resource"
}例如：
图片分析：
返回：
{
"type":"image",
"data":"base64"
}AI：
直接理解。
4.11 Tool 错误设计
错误：
throw Error(
"失败"
)AI：
不知道：
怎么办。
正确：
{
"error":{
"code":
"USER_NOT_FOUND",
"message":
"用户不存在"
}
}AI：
可以：
告诉用户：
没有找到该用户，请确认ID。4.12 Tool 粒度设计
这是 Agent 设计核心。
问题：
一个 Tool：
到底做多少事情？
过细
例如：
getUserName
getUserAge
getUserPhone问题：
Tool数量爆炸。
过粗
例如：
manageUser里面：
查询
新增
修改
删除AI：
容易误调用。
推荐：
中等粒度。
例如：
getUserInfo
createUser
updateUser
deleteUser4.13 一个企业 CRM MCP 示例
假设：
CRM系统。
不要：
一个：
crmTool拆：
CRM MCP Server
Tools:
getCustomer
searchCustomer
createCustomer
updateCustomer
getOrder
createOrder
AI：
看到：
用户：
查询张三客户资料选择：
searchCustomer用户：
新增一个客户选择：
createCustomer4.14 多 Tool 冲突问题
企业经常遇到：
两个 Tool：
功能相似。
例如：
searchUser
findUserAI：
不知道：
选哪个。
解决：
方法1
合并。
方法2
明确描述。
例如：
searchUser:
通过关键词模糊搜索用户findUser:
通过唯一ID精确查询用户4.15 Tool 分类
大型 MCP：
推荐：
分类。
例如：
tools
├── user
│ getUser
│ createUser
├── order
│ getOrder
│ createOrder
├── payment
│ refund
├── system
│ healthCheck
虽然 MCP：
没有强制 Namespace。
但是：
工程上：
必须管理。
4.16 Tool 权限设计
企业环境：
不能：
所有 AI：
访问所有 Tool。
例如：
普通员工：
不能：
deleteUser财务：
不能：
approvePayment因此：
需要：
用户
↓
Agent
↓
MCP
↓
权限系统
↓
Tool例如：
调用：
{
"name":"deleteUser"
}Server：
检查：
role != admin
拒绝4.17 Tool 安全原则
永远不要：
相信 AI 参数。
例如：
SQL Tool：
收到：
DROP TABLE user怎么办？
必须：
限制。
数据库 Tool：
推荐：
只读：
SELECT禁止：
UPDATE
DELETE
DROP文件 Tool：
限制：
目录：
例如：
允许：
/workspace禁止：
/etc第4章 MCP Tool 开发实战（下）
——高级 Tool 架构：从单工具到企业级 AI Agent 工具链
上一节我们学习了：
- Tool 命名设计
- Description 编写
- Schema 设计
- 返回值设计
- 权限控制
但是企业级 Agent 面临的问题更加复杂：
例如：
一个代码开发 Agent：
用户：
帮我修复订单模块 Bug，并提交代码。
AI 需要：
读取代码
↓
分析问题
↓
修改文件
↓
执行测试
↓
生成提交信息
↓
Git Commit这不是一个 Tool 可以完成的。
而是：
多个 Tool 协同形成 Tool Chain。
本章进入高级阶段。
4.19 Tool 自动注册机制
前面：
我们手动：
server.setRequestHandler()注册。
例如：
tools:[
weatherTool,
gitTool
]问题：
几十个 Tool：
怎么办？
企业项目：
通常：
自动扫描。
结构：
tools/
weather/
index.ts
git/
index.ts
database/
index.ts启动时：
自动加载：
扫描目录
↓
发现Tool
↓
注册MCPTool Registry（工具注册中心）
设计：
class ToolRegistry{
private tools=[];
register(tool){
this.tools.push(tool);
}
list(){
return this.tools;
}
}使用：
registry.register(
weatherTool
);
registry.register(
gitTool
);MCP：
统一：
tools:list
↓
registry.list()优势：
新增 Tool：
只增加文件。
不用修改：
Server。
4.20 Tool Factory 工厂模式
大型系统：
不要：
直接创建 Tool。
例如：
new WeatherTool()推荐：
Factory。
结构：
ToolFactory
↓
根据配置
↓
创建Tool例如：
配置：
{
"tools":[
"weather",
"github",
"database"
]
}启动：
读取配置
↓
加载对应Tool
↓
注册优势：
动态启停。
例如：
生产环境：
开启：
Git
Database测试环境：
开启：
MockWeather4.21 动态 Tool 加载
MCP 最大优势：
Server 可以：
动态暴露能力。
例如：
企业系统：
100个业务模块。
用户：
登录之后：
权限不同。
管理员：
看到：
createUser
deleteUser
manageRole普通员工：
看到：
queryUser流程：
User Login
↓
获取权限
↓
生成Tool列表
↓
返回tools/list因此：
Tool：
不是固定的。
而是：
动态能力。
4.22 Tool Chain（工具链）
Agent 最核心能力：
不是调用一个 Tool。
而是：
多个 Tool 组合。
案例：
自动处理工单
用户：
帮我处理这个客户投诉Agent：
步骤：
第一步：
查询客户。
调用：
searchCustomer第二步：
查询订单。
调用：
getOrder第三步：
分析问题。
调用：
analysisComplaint第四步：
发送邮件。
调用：
sendEmail最终：
用户
↓
Agent
↓
Tool1
↓
Tool2
↓
Tool3
↓
Tool4
↓
结果4.23 Tool Chain 不应该写死
错误：
await searchCustomer();
await getOrder();
await sendEmail();这是传统程序。
不是 Agent。
Agent 模式：
由 LLM 决定：
当前状态
↓
选择下一步Tool
↓
观察结果
↓
继续规划这就是：
ReAct Agent。
4.24 ReAct 模式
ReAct：
Reason + Act。
即：
推理 + 行动。
流程：
Thought
↓
Action
↓
Observation
↓
Thought
↓
Action
↓
Answer例如：
用户：
帮我找一下北京销量最高的商品AI：
Thought:
需要查询商品数据Action:
searchProductObservation:
销量数据Thought:
需要排序Action:
sortProductAnswer:
返回结果。
MCP：
非常适合：
ReAct。
4.25 数据库 MCP Tool 实战设计
数据库：
是企业最常见 Tool。
例如：
自然语言：
查询本月订单金额AI：
调用：
queryDatabase设计：
不要：
直接暴露：
executeSQL危险。
推荐：
业务化 Tool。
例如：
错误：
runSQL正确：
getMonthlySales为什么？
AI：
容易生成：
危险 SQL。
数据库 Tool
Schema：
{
"name":"getOrderStatistics",
"description":
"查询订单销售统计数据",
"inputSchema":{
"type":"object",
"properties":{
"month":{
"type":"string"
}
}
}
}内部：
固定 SQL：
SELECT
sum(amount)
FROM orders
WHERE month=?安全：
提升。
4.26 Git MCP Tool 实战
开发 Agent：
非常需要 Git。
常见 Tool：
gitStatus
gitDiff
gitCommit
gitBranch
gitLog例如：
用户：
分析我的代码修改流程：
gitDiff
↓
LLM分析
↓
返回建议用户：
帮我提交代码流程：
gitStatus
↓
gitCommit注意：
Git Tool：
必须：
权限限制。
禁止：
AI：
随便：
rm -rf4.27 文件系统 MCP Tool
文件 Tool：
非常常见。
例如：
代码 Agent：
需要：
读取：
src/main.tsTool：
readFile
writeFile
listDirectory
searchFile但是：
安全：
非常重要。
必须限制：
Root目录。
例如：
允许：
/project禁止：
/etc/passwd代码：
function checkPath(path){
if(
!path.startsWith(
"/project"
)
){
throw Error(
"禁止访问"
);
}
}4.28 浏览器 MCP Tool
Browser Agent：
需要：
网页操作。
常见：
openPage
click
input
screenshot
extractText例如：
用户：
帮我查一下某商品价格Agent：
调用：
openPage
↓
extractText
↓
analysis典型：
Computer Use Agent。
4.29 Tool 返回中间状态
复杂任务：
不能：
一直等待。
例如：
AI：
执行：
扫描10000文件需要：
进度。
使用：
Progress Notification。
例如：
{
"method":
"notifications/progress",
"params":{
"progress":500,
"total":10000
}
}用户：
看到：
5%
50%
100%体验接近传统软件。
4.30 Tool 并发执行
例如：
查询：
三个系统：
订单
库存
物流互不依赖。
可以：
并行。
传统：
订单
↓
库存
↓
物流耗时：
3秒。
并发：
订单
库存
物流
同时执行耗时：
1秒。
代码：
await Promise.all([
getOrder(),
getStock(),
getDelivery()
]);4.31 Tool 超时管理
任何外部 Tool：
必须：
设置：
Timeout。
例如：
const timeout =
5000;超过：
返回：
{
"code":
"TIMEOUT",
"message":
"服务响应超时"
}AI：
可以：
换方案。
4.32 Tool 缓存设计
很多查询：
重复。
例如：
天气：
用户连续问：
北京天气不用：
每次调用 API。
架构：
Tool
↓
Cache
↓
API例如：
Redis：
保存：
weather:beijing
TTL=10分钟4.33 Tool 监控
企业必须知道：
AI：
调用了什么。
例如：
指标：
Tool调用次数
成功率
平均耗时
错误率
Token消耗推荐：
接入：
OpenTelemetry。
链路：
User Request
↓
Agent Trace
↓
MCP Tool
↓
API4.34 一个完整企业 Agent 架构
最终：
用户
|
v
AI Agent
|
+---------+---------+
| |
MCP Client Memory
|
|
MCP Server
|
+-------+--------+
| | |
Tool Resource Prompt
|
+----------------+
|
企业系统
|
CRM
ERP
Git
DB
API第5章 MCP Resource 开发实战（上）
——从文件读取到企业知识库：打造 AI 可访问的数据资源层
前面章节我们重点学习了 MCP 的 Tool。
Tool 解决的问题：
AI 如何执行动作？
例如：
查询天气
创建订单
提交代码
发送邮件但是企业 AI Agent 还有一个巨大需求：
AI 如何读取企业已有的数据？
例如：
- 产品文档
- API 文档
- 数据库数据
- Git代码
- PDF 文件
- Wiki知识库
- 用户手册
- 业务规则
这些内容：
不是动作。
而是：
上下文资源（Context Resource）。
这就是 MCP Resource。
5.1 什么是 MCP Resource？
简单理解：
Resource：
就是：
MCP Server 暴露给 AI 的可读取数据。
例如：
AI
↓
MCP Resource
↓
企业数据举例：
你的公司：
有：
docs/
├── payment.md
├── user.md
├── api.md
└── order.md以前：
AI：
不知道。
现在：
MCP Resource：
暴露：
docs://payment
docs://user
docs://api
docs://orderAI：
可以读取。
5.2 Tool 和 Resource 的区别
这是很多新人最容易混淆的地方。
Tool
关键词：
做事情
例如：
发送邮件
创建订单
查询天气
执行代码流程：
AI
↓
调用Tool
↓
产生动作Resource
关键词：
提供信息
例如：
产品文档
用户协议
数据库记录
代码文件流程：
AI
↓
读取Resource
↓
获得上下文对比：
| Tool | Resource | |
|---|---|---|
| 作用 | 执行动作 | 提供数据 |
| 是否改变系统 | 可能改变 | 通常只读 |
| 调用方式 | tools/call | resources/read |
| 示例 | 创建订单 | 读取订单规则 |
5.3 为什么 MCP 需要 Resource？
很多 AI 应用：
早期采用：
RAG。
架构：
用户
↓
Embedding
↓
Vector DB
↓
检索
↓
LLM问题：
企业数据：
越来越复杂。
例如：
实时数据库
文件系统
代码仓库
API文档
业务系统全部需要：
统一访问。
MCP Resource：
提供：
统一入口：
任何数据
↓
MCP Resource
↓
AI5.4 Resource URI 设计
Resource：
通过 URI 标识。
类似：
URL。
例如：
文件：
file:///project/readme.md数据库：
mysql://users/10001文档：
docs://payment/api代码：
git://repo/src/main.ts推荐：
企业统一设计：
例如：
company://
├── docs/
├── database/
├── git/
├── knowledge/
5.5 第一个 Resource 示例
目标：
让 AI 读取：
README.md目录：
project
├── src
│ index.ts
└── docs
README.md内容：
README.md
# 商品系统
支持：
- 商品管理
- 库存管理
- 订单管理
创建 Resource：
const resource = {
uri:
"docs://readme",
name:
"项目说明文档",
description:
"商品系统项目介绍"
};5.6 注册 Resource
Server：
添加：
server.setRequestHandler(
"resources/list",
async()=>{
return {
resources:[
{
uri:"docs://readme",
name:"项目说明文档",
description:
"商品系统说明"
}
]
};
}
);Client：
请求：
resources/list返回：
{
"resources":[
{
"uri":"docs://readme"
}
]
}AI：
知道：
存在这个资源。
5.7 读取 Resource
Client：
发送：
{
"method":
"resources/read",
"params":{
"uri":
"docs://readme"
}
}Server：
读取：
server.setRequestHandler(
"resources/read",
async(request)=>{
return {
contents:[
{
uri:
"docs://readme",
mimeType:
"text/markdown",
text:
"# 商品系统..."
}
]
};
}
);AI：
获得：
Markdown。
5.8 文件系统 Resource 实战
企业最常见：
文件资源。
例如：
代码 Agent。
需要：
读取：
src/UserService.java设计：
Resource：
file://src/UserService.java读取：
import fs from "fs/promises";
async function readFileResource(path){
return await fs.readFile(
path,
"utf-8"
);
}但是：
这里有巨大安全问题。
5.9 文件 Resource 安全设计
不能：
允许：
file:///etc/passwd否则：
AI：
可能读取：
服务器敏感文件。
必须：
限制：
Root目录。
例如：
/workspace检查：
function checkPath(path:string){
if(
!path.startsWith(
"/workspace"
)
){
throw Error(
"非法路径"
);
}
}企业必须：
做：
路径沙箱。
5.10 数据库 Resource
数据库也是 Resource。
例如：
用户信息。
URI：
mysql://user/10001读取：
流程：
AI
↓
resources/read
↓
MCP Server
↓
Database
↓
返回JSON例如：
返回：
{
"id":10001,
"name":"张三",
"level":"VIP"
}注意：
数据库 Resource：
通常：
只读。
5.11 为什么数据库不要直接给 SQL Resource？
错误设计：
mysql://executeSQL然后：
AI：
传：
DELETE FROM user危险。
推荐：
业务资源。
例如：
customer://10001
order://88888
product://100AI：
看到：
业务含义。
5.12 Git Resource
代码 Agent：
非常需要。
例如：
Resource：
git://repo/file/src/main.ts读取：
git show HEAD:path返回：
代码内容。
然后：
AI：
可以：
分析：
Bug
优化
重构5.13 Resource + RAG 架构
MCP 和 RAG：
不是竞争。
而是结合。
传统：
用户
↓
Embedding
↓
Vector DB
↓
LLMMCP：
升级：
用户
↓
AI Agent
↓
MCP Resource
↓
数据源
↓
Embedding/RAG
↓
LLM例如：
企业知识库：
MCP Server
|
|
Knowledge Resource
|
Vector DB
|
Documents5.14 动态 Resource
Resource：
不一定固定。
例如：
用户：
登录之后：
看到：
自己的数据。
流程：
User Login
↓
权限查询
↓
生成Resource列表
↓
resources/list管理员：
看到：
company://all/users普通员工：
看到：
company://my/profile5.15 Resource 分页
企业数据：
可能：
百万级。
不能：
一次返回：
全部。
例如：
错误：
resources/list
返回100万个文件推荐：
分页：
{
"cursor":
"page2"
}类似：
数据库分页。
5.16 Resource 缓存
资源：
很多：
不会变化。
例如：
API文档。
可以缓存：
Resource
↓
Cache
↓
File/DB例如：
Redis：
docs:api
TTL=1小时5.17 Resource 权限控制
企业：
必须。
例如：
HR 文档：
普通员工不能看。
流程：
AI
↓
Resource请求
↓
权限检查
↓
允许
↓
读取例如：
if(
!user.hasPermission(
"HR_READ"
)
){
throw Error(
"Forbidden"
)
}5.18 Resource 和 Context Window
一个重要问题：
AI 上下文有限。
不能：
把：
100MB 文档：
全部塞进去。
正确：
流程：
Resource
↓
选择
↓
摘要
↓
相关片段
↓
LLM这就是：
MCP + RAG。
第5章 MCP Resource 开发实战（下）
——构建企业级知识库 MCP Server：MCP + RAG + Vector Database 实战
上一节我们学习了：
- Resource 基础概念
- Tool 与 Resource 区别
- 文件 Resource
- 数据库 Resource
- Git Resource
- 权限控制
但是企业真正落地 AI Agent 时，最常见的场景是：
让 AI 理解公司的所有知识。
例如：
员工问：
退款流程是什么？AI 自动：
查询知识库
↓
找到退款规则
↓
结合上下文回答这就是：
企业知识库 Agent。
5.20 企业知识库为什么需要 MCP？
传统知识库：
架构：
用户
↓
搜索系统
↓
关键词匹配
↓
返回文档问题：
理解能力弱。
例如：
用户：
客户取消订单后多久退款？文档：
订单关闭后的资金原路退回周期关键词：
完全不同。
RAG：
解决：
用户问题
↓
Embedding
↓
向量搜索
↓
相关文档
↓
LLM但是：
企业数据来源很多：
Confluence
Git
数据库
PDF
Word
内部系统
OSS如何统一？
答案：
MCP Resource。
5.21 MCP + RAG 总体架构
完整架构：
用户
|
v
AI Agent
|
MCP Client
|
MCP Knowledge Server
|
+-----------+------------+
| |
Resource Tool
|
|
Knowledge Layer
|
+-----+------+
文件
数据库
Git
Wiki
|
|
Embedding
|
Vector Database
|
文档片段5.22 知识库 Resource 设计
假设：
公司：
支付系统。
文档：
payment/
├── refund.md
├── payment_api.md
├── error_code.md
└── settlement.md设计 URI：
knowledge://payment/refund例如：
knowledge://payment/api
knowledge://payment/error为什么不用：
file:///xxx/refund.md？
因为：
业务语义更强。
AI：
更容易理解。
5.23 Markdown Resource 实现
创建：
resources/documentResource.ts代码：
import fs from "fs/promises";
export async function readDocument(
path:string
){
const content =
await fs.readFile(
path,
"utf-8"
);
return {
uri:
`knowledge://${path}`,
mimeType:
"text/markdown",
text:
content
};
}注册：
server.setRequestHandler(
"resources/read",
async(req)=>{
if(
req.params.uri
==="knowledge://payment/refund"
){
return {
contents:[
await readDocument(
"./docs/refund.md"
)
]
};
}
}
);现在：
AI：
可以读取：
退款规则文档5.24 PDF Resource 实现
企业文档：
大量 PDF。
例如：
产品手册.pdf
合同模板.pdf
技术规范.pdf流程：
PDF
↓
文本提取
↓
Resource
↓
AINode：
常用：
pdf-parse安装：
npm install pdf-parse代码：
import pdf from "pdf-parse";
async function readPDF(
file
){
const buffer =
await fs.readFile(file);
const data =
await pdf(buffer);
return {
mimeType:
"text/plain",
text:
data.text
};
}AI：
读取：
PDF内容。
5.25 Word 文档 Resource
企业：
大量：
.docx流程：
docx
↓
文本
↓
Resource使用：
mammoth代码：
import mammoth
from "mammoth";
const result =
await mammoth.extractRawText({
path:"contract.docx"
});
return result.value;5.26 Excel Resource
企业：
大量：
销售报表.xlsx
库存表.xlsx
财务表.xlsx不要：
直接返回：
Excel。
转换：
Excel
↓
JSON
↓
Resource例如：
原表：
| 商品 | 销量 |
|---|---|
| 手机 | 100 |
转换：
{
"product":"手机",
"sales":100
}AI：
更容易理解。
5.27 数据库 Resource 实战
例如：
订单数据库。
表：
orders字段：
id
amount
status
create_timeResource：
设计：
order://88888读取：
async function getOrder(id){
return await db.query(
`
SELECT *
FROM orders
WHERE id=?
`
,[id]
);
}返回：
{
"id":88888,
"amount":199,
"status":"paid"
}5.28 Elasticsearch Resource
企业搜索：
经常使用：
Elasticsearch架构：
MCP Resource
↓
ES
↓
全文搜索
↓
返回文档例如：
用户：
查询支付失败原因Resource：
调用：
search:
payment failed返回：
相关文档。
5.29 Vector Database Resource
真正 RAG：
核心：
向量数据库。
常见：
Milvus
Qdrant
Chroma
Pinecone
Weaviate流程：
用户问题
↓
Embedding
↓
Vector Search
↓
Top K 文档
↓
Resource
↓
LLM例如：
问题：
退款多久到账？Embedding：
↓
找到：
refund.md5.30 文档切片 Chunk
大文档：
不能：
一次 Embedding。
例如：
100页 PDF。
需要：
切片。
例如：
文档
↓
Chunk
↓
Embedding常见：
chunk size：
500~1000 tokens例如：
原文：
退款规则全文切：
chunk1:
退款申请流程
chunk2:
退款到账时间
chunk3:
异常处理5.31 Metadata 设计
每个 Chunk：
保存：
元数据。
例如：
{
"text":
"退款到账时间",
"source":
"refund.md",
"department":
"finance",
"version":
"2026"
}为什么？
过滤。
例如：
用户：
财务部门。
只搜索：
department=finance5.32 MCP Resource + RAG 查询流程
完整：
用户:
退款多久到账？
↓
AI Agent
↓
判断需要知识
↓
调用 Resource
↓
knowledge://refund
↓
Vector Search
↓
找到相关Chunk
↓
LLM总结
↓
回答5.33 企业知识库权限
这是重点。
企业不能：
所有人：
看到所有文档。
例如：
HR：
薪资制度普通员工：
不能。
权限模型：
User
↓
Role
↓
Permission
↓
Resource例如：
Resource:
hr://salary检查：
if(
!user.hasRole(
"HR"
)
){
deny();
}5.34 多租户知识库
SaaS 场景：
非常重要。
例如：
公司A：
company_a://docs公司B：
company_b://docsVector：
必须隔离：
tenant_id例如：
Metadata：
{
"tenant":"company_a"
}查询：
自动过滤。
5.35 Resource 缓存策略
文档：
不会频繁变化。
可以缓存。
架构：
Resource
↓
Redis
↓
Storage例如：
payment_api.md
缓存:
1小时5.36 Resource 更新通知
企业文档：
会变化。
例如：
产品规则更新。
需要通知 AI。
流程：
文档更新
↓
MCP Server
↓
Resource Changed
↓
Client刷新例如：
notifications/resources/list_changed5.37 MCP Resource 与 Memory
很多 Agent：
还有 Memory。
区别：
Resource：
企业知识Memory：
用户历史例如：
Resource：
公司退款规则Memory：
用户喜欢中文回答完整 Agent：
Context
=
Resource
+
Memory
+
Tool Result
+
Prompt5.38 企业知识助手案例
最终效果：
用户：
我们公司的退款政策是什么？Agent：
执行：
1. 查询知识库
2. 找退款文档
3. 获取最新版本
4. 总结回答返回：
根据2026年退款政策：
普通订单:
3-7个工作日
信用卡:
7-15个工作日第6章 MCP Prompt 开发实战（上）
——让 AI Agent 拥有企业级工作模板能力
前面章节，我们已经掌握 MCP 的两个核心能力：
Tool
解决：
AI 能不能执行任务？
例如：
创建订单
发送邮件
执行代码
查询数据库Resource
解决：
AI 能不能获取知识？
例如：
产品文档
业务规则
数据库记录
代码文件但是企业 Agent 还有一个问题：
AI 每次执行任务，都需要重新理解流程吗？
例如：
代码审查：
每次告诉 AI：
请检查代码质量
请检查安全问题
请检查性能问题
请给优化建议非常浪费。
于是 MCP 提供第三种能力：
Prompt
它解决：
给 AI 提供标准化任务模板。
6.1 MCP 三大核心能力关系
完整 MCP：
MCP
|
+-------------+--------------+
| | |
Tool Resource Prompt
执行动作 提供数据 指导行为举例：
开发 Agent：
用户：
帮我优化这段代码Agent：
需要：
Resource：
读取代码：
git://src/UserService.tsTool：
执行测试：
runTest()Prompt：
告诉 AI：
按照代码审查规范分析：
1. 性能
2. 安全
3. 可维护性
4. 最佳实践三者组合：
形成完整 Agent。
6.2 什么是 MCP Prompt？
简单理解：
Prompt：
就是：
MCP Server 提供给 AI 的可复用提示模板。
例如：
定义：
code-review内容：
你是一名高级代码审查工程师。
请检查：
1. Bug
2. 性能
3. 安全
4. 架构问题
输出详细报告。AI：
调用：
prompts/get获得模板。
6.3 Prompt 与普通 Prompt 区别
普通开发：
Prompt 写死：
const prompt=
"你是客服机器人"问题：
不可管理。
MCP Prompt：
变成：
资源化能力：
MCP Server
↓
Prompt Repository
↓
AI Client优势：
- 统一管理
- 动态更新
- 权限控制
- 版本管理
- 企业复用
6.4 第一个 MCP Prompt
目标：
创建：
代码审查 Prompt。
目录：
src
├── prompts
│ └── codeReviewPrompt.ts
└── index.ts创建：
export const codeReviewPrompt = {
name:
"code-review",
description:
"用于代码质量审查的专业分析模板",
arguments:[
{
name:"language",
description:
"代码语言",
required:true
}
]
};这里：
定义：
Prompt 名称。
6.5 注册 Prompt
Server：
添加：
server.setRequestHandler(
"prompts/list",
async()=>{
return {
prompts:[
codeReviewPrompt
]
};
}
);Client：
请求：
{
"method":
"prompts/list"
}返回：
{
"prompts":[
{
"name":
"code-review"
}
]
}AI：
知道：
存在这个模板。
6.6 获取 Prompt 内容
定义：
server.setRequestHandler(
"prompts/get",
async(request)=>{
if(
request.params.name
==="code-review"
){
return {
messages:[
{
role:"user",
content:{
type:"text",
text:
`
你是一名高级软件工程师。
请审查${request.params.arguments.language}代码。
关注：
1.Bug
2.安全
3.性能
4.可维护性
`
}
}
]
};
}
}
);调用：
参数：
{
"name":
"code-review",
"arguments":{
"language":"TypeScript"
}
}返回：
完整 Prompt。
6.7 参数化 Prompt
企业场景：
不能写死。
例如：
客服 Prompt。
错误：
你是客服。正确：
参数：
行业
产品
语气
用户类型定义：
arguments:[
{
name:"industry",
required:true
},
{
name:"tone",
required:true
}
]调用：
{
"industry":"电商",
"tone":"专业友好"
}生成：
你是一名电商客服。
回答风格：
专业友好。6.8 企业 Prompt 模板库
大型企业：
通常：
建立：
Prompt Center。
结构：
prompts
├── customer-service
│ v1
│ v2
├── code-review
│ v1
├── data-analysis
├── report-generation
类似：
代码仓库。
6.9 Prompt 版本管理
Prompt：
也需要版本。
例如：
客服：
v1：
简单回答问题v2：
增加投诉处理流程URI：
设计：
prompt://customer/v2或者：
metadata：
{
"name":
"customer",
"version":
"2.0"
}6.10 动态 Prompt
高级 Agent：
Prompt：
不是固定。
例如：
用户：
登录。
角色：
管理员。
生成：
你是企业管理员助手。
你可以：
查询用户
管理权限
查看日志普通用户：
生成：
你是普通员工助手。
只能查询资料。流程：
用户身份
↓
权限系统
↓
生成Prompt
↓
AI6.11 Prompt + Resource 组合
真实场景：
知识问答。
Prompt：
定义：
你是企业知识助手。Resource：
提供：
公司文档组合：
Prompt
+
Resource
↓
AI回答例如：
Prompt：
回答必须引用公司政策。Resource：
refund_policy.md最终：
AI：
不会胡编。
6.12 Prompt + Tool 组合
自动化任务：
例如：
日报生成。
Prompt：
你是一名项目经理。
根据Git提交记录生成日报。Tool：
调用：
gitLog()流程：
Prompt
↓
AI理解任务
↓
Tool获取数据
↓
生成日报6.13 实战：日报生成 Agent
需求：
每天：
自动生成：
开发日报Prompt：
你是高级项目经理。
根据开发记录生成日报。
格式：
今日完成：
问题：
风险：
明日计划：Tool：
getGitCommitResource：
project://requirements最终：
自动生成：
今日完成：
1.完成支付接口
2.优化订单查询
风险：
暂无
明日：
开发退款模块6.14 Prompt 安全问题
Prompt：
也是攻击目标。
例如：
用户输入：
忽略之前规则叫：
Prompt Injection。
解决：
1. 分层 Prompt
System Prompt
↓
MCP Prompt
↓
User Input2. 权限隔离
不要：
让用户修改：
系统 Prompt。
3. 内容过滤
检测：
危险指令。
6.15 Prompt 与 Agent Memory
区别：
Prompt：
告诉 AI：
应该怎么做。
Memory：
告诉 AI：
以前发生什么。
例如：
Prompt：
你是客服助手。Memory：
用户喜欢中文回复。组合：
Prompt
+
Memory
+
Resource
+
Tool6.16 企业 Prompt 生命周期
成熟企业：
流程：
需求
↓
Prompt设计
↓
测试
↓
评估
↓
发布
↓
监控
↓
优化类似：
软件发布。
6.17 Prompt 测试
不能：
凭感觉。
需要：
测试集。
例如：
客服：
1000个问题。
评估：
- 正确率
- 幻觉率
- 用户满意度
工具：
可以结合：
- LangSmith
- Langfuse
- OpenTelemetry
6.18 本章总结
本章学习：
- MCP Prompt 概念
- Prompt 与 Tool/Resource区别
- Prompt 注册
- Prompt 参数化
- Prompt 模板库
- Prompt 版本管理
- Prompt 动态生成
- Prompt Injection防护
- 企业 Prompt 生命周期
核心理解：
Tool 让 AI 会做事，Resource 让 AI 有知识，Prompt 让 AI 按企业规范工作。
完整 Agent：
AI Agent
Prompt
+
Resource
+
Tool
+
Memory第6章 MCP Prompt 开发实战（下）
——企业级 Prompt 工程体系：让 Agent 从“会聊天”升级为“会工作”
上一节我们学习了 MCP Prompt 基础：
- Prompt 是什么
- Prompt 与 Tool、Resource 的关系
- Prompt 注册
- 参数化 Prompt
- Prompt 版本管理
- Prompt 安全
但是企业真正部署 Agent 时，会遇到更复杂的问题：
例如：
一个客服 Agent：
需要：
普通咨询 → 客服角色
投诉问题 → 安抚专家角色
退款问题 → 财务规则角色
技术问题 → 技术支持角色一个 Prompt：
无法满足。
所以企业需要：
Prompt 工程体系。
6.19 企业为什么需要 Prompt 工程？
很多团队初期：
直接：
system prompt:
你是一个AI助手。然后：
不断追加：
不要骗人。
回答详细一点。
注意安全。
遵守规则。
最后：
Prompt：
几千行。
问题：
1. 无法维护
没人知道：
哪句话影响效果。
2. 无法测试
修改一句：
不知道：
效果提升还是下降。
3. 无法复用
客服团队：
一套。
销售团队：
一套。
开发团队：
一套。
因此：
需要：
Prompt Engineering。
6.20 企业 Prompt 分层架构
推荐：
五层模型：
Agent Prompt
Role Layer
|
Rule Layer
|
Knowledge Layer
|
Tool Layer
|
Output Layer
第一层：Role（角色）
定义：
AI是谁。
例如：
你是一名资深Java架构师。第二层：Rule（规则）
定义：
行为约束。
例如：
不要编造不存在的信息。
发现不确定时明确说明。第三层：Knowledge（知识）
来自：
Resource。
例如：
公司退款政策。第四层：Tool
定义：
可使用能力。
例如：
查询订单。
发送邮件。第五层：Output
输出格式。
例如：
{
"summary":"",
"solution":""
}6.21 Prompt Factory 设计
企业：
不应该：
到处写字符串。
例如：
错误：
const prompt =
"你是客服..."应该：
创建：
Prompt Factory。
结构：
prompt
├── factory
│ PromptFactory.ts
├── templates
│ customer.ts
│ developer.ts
│ analyst.ts
6.22 Prompt 模板
例如：
export const customerPrompt = {
role:
"你是一名专业客服",
rules:[
"保持友好",
"不要承诺无法完成的事情"
],
output:
"使用Markdown格式"
};Factory：
class PromptFactory{
create(type){
switch(type){
case "customer":
return customerPrompt;
case "developer":
return developerPrompt;
}
}
}调用：
factory.create(
"customer"
);6.23 Prompt 模板变量
企业：
大量动态信息。
例如：
客服：
需要：
用户姓名
会员等级
订单状态模板：
你是客服助手。
用户:
{{username}}
会员等级:
{{level}}运行：
输入：
{
"username":"张三",
"level":"VIP"
}生成：
你是客服助手。
用户:
张三
会员等级:
VIP6.24 Prompt Template Engine
类似：
前端模板。
例如：
使用：
Handlebars。
模板：
你好 {{name}}
你的订单:
{{orderId}}渲染：
template.render({
name:"李四",
orderId:"8888"
});输出：
你好 李四
你的订单:
88886.25 多角色 Agent Prompt
企业复杂任务：
通常：
不是一个 Agent。
而是：
多个角色。
例如：
软件开发 Agent。
包含：
Planner
规划。
Prompt：
你是项目规划专家。
负责拆解任务。Coder
编码。
Prompt：
你是高级开发工程师。
负责实现代码。Reviewer
审查。
Prompt：
你是代码审查专家。
寻找问题。架构：
User
|
Planner Agent
|
+------+------+
| |
Coder Reviewer
6.26 Planner Prompt 设计
Planner：
不能直接写代码。
职责：
拆任务。
Prompt：
你是任务规划Agent。
你的职责：
1.分析需求
2.拆分步骤
3.选择工具
4.制定执行计划
不要直接执行。输出：
{
"steps":[
"查询用户信息",
"检查订单",
"生成方案"
]
}6.27 Executor Prompt
Executor：
执行。
Prompt：
你是执行Agent。
根据计划调用工具。
每一步必须确认结果。调用：
Tool
↓
Observation
↓
Next Step6.28 Reviewer Prompt
Reviewer：
负责质量。
例如：
代码：
检查：
安全漏洞
性能问题
代码规范
测试覆盖输出：
{
"issues":[
{
"type":"security",
"level":"high"
}
]
}6.29 Prompt Chain
多个 Prompt：
串联。
例如：
文章生成：
主题
↓
Research Prompt
↓
Writer Prompt
↓
Editor Prompt
↓
SEO Prompt
每一步：
不同角色。
6.30 Prompt A/B 测试
企业优化：
不能靠感觉。
例如：
客服 Prompt：
版本A：
简短回答。版本B：
详细解释。比较：
指标：
用户满意度
解决率
平均响应时间最终：
选择：
效果更好的版本。
6.31 Prompt 评估体系
推荐指标：
准确率
回答是否正确。
幻觉率
是否编造。
完成率
任务是否完成。
成本
Token消耗。
延迟
响应时间。
6.32 Prompt 自动优化
高级：
让 AI 优化 Prompt。
流程：
旧Prompt
↓
测试集
↓
分析失败案例
↓
生成优化Prompt
↓
人工审核
↓
上线类似：
代码持续优化。
6.33 Prompt 管理平台设计
企业：
可以建立：
Prompt Hub。
架构：
Web UI
|
Prompt Service
|
Database
|
MCP Prompt Server
功能：
- 创建 Prompt
- 编辑
- 发布
- 回滚
- 测试
- 统计
数据库：
例如：
prompt表：
CREATE TABLE prompt(
id bigint,
name varchar(100),
version varchar(20),
content text,
status varchar(20)
);6.34 Prompt 权限管理
不是所有人：
可以修改。
例如：
开发：
可以测试。
产品：
可以编辑。
管理员：
可以发布。
权限：
User
↓
Role
↓
Permission
↓
Prompt6.35 Prompt 与 MCP 集成
最终：
MCP Server：
提供：
prompts/list返回：
[
{
"name":
"code-review"
},
{
"name":
"customer-service"
}
]AI Client：
动态获取。
6.36 企业 Agent 完整架构
最终：
用户
|
AI Agent
|
+------------+------------+
| | |
Prompt Resource Tool
| | |
角色规范 企业知识 系统能力
|
Enterprise System第7章 MCP Client 开发实战（上）
——自己实现一个 AI Agent 客户端：从协议连接到智能调用
前面章节，我们一直在开发：
- MCP Server
- Tool
- Resource
- Prompt
但是有一个关键角色还没有深入：
谁来连接 MCP Server？
答案：
MCP Client。
很多人理解 MCP：
认为：
AI模型
↓
MCP Server实际上：
中间还有：
AI Agent Runtime也就是：
MCP Client。
7.1 MCP 完整通信架构
完整链路：
用户
|
v
AI Agent
|
v
MCP Client
|
v
MCP Server
+---------+---------+
| | |
Tool Resource Prompt
|
v
企业业务系统
角色说明：
| 组件 | 职责 |
|---|---|
| LLM | 理解需求、规划 |
| MCP Client | 连接管理、协议调用 |
| MCP Server | 提供能力 |
| Tool | 执行动作 |
| Resource | 提供数据 |
| Prompt | 提供模板 |
7.2 MCP Client 是什么？
简单理解：
MCP Client：
就是：
一个懂 MCP 协议的 AI Agent 运行环境。
它负责：
- 连接 Server
- 获取能力
- 调用 Tool
- 读取 Resource
- 获取 Prompt
- 管理上下文
类似：
浏览器：
访问：
HTTP Server。
MCP Client：
访问：
MCP Server。
7.3 为什么要自己实现 MCP Client？
现有客户端：
例如：
- Claude Desktop
- Cursor
- VS Code Agent
已经支持 MCP。
但是企业经常需要：
自己的 Agent 平台。
例如：
客服机器人：
用户
↓
企业Agent
↓
MCP Client
↓
CRM MCP Server
↓
CRM系统所以：
需要：
自己实现 Runtime。
7.4 MCP Client 项目结构
创建：
mcp-agent-client
src
├── index.ts
├── client
│ └── mcpClient.ts
├── llm
│ └── agent.ts
├── tools
│ └── toolManager.ts
├── memory
│ └── memory.ts
└── config
└── server.json
架构：
Agent
|
MCP Client
|
MCP Server7.5 创建 MCP Client
安装 SDK：
npm install @modelcontextprotocol/sdk创建：
src/client/mcpClient.ts代码：
import {
Client
}
from "@modelcontextprotocol/sdk/client/index.js";
export class MCPClient{
client:Client;
constructor(){
this.client =
new Client(
{
name:"my-agent",
version:"1.0.0"
}
);
}
}现在：
拥有：
一个 MCP Client。
7.6 连接 MCP Server
MCP 支持多种 Transport：
常见：
stdio
本地进程：
Client
↓
启动Server进程
HTTP/SSE
远程：
Client
↓
Network
↓
Server本章：
使用：
stdio。
代码：
import {
StdioClientTransport
}
from "@modelcontextprotocol/sdk/client/stdio.js";
async connect(){
const transport =
new StdioClientTransport({
command:"node",
args:[
"../weather-server/index.js"
]
});
await this.client.connect(
transport
);
}连接：
成功。
7.7 MCP 初始化流程
连接后：
第一步：
initialize。
流程：
Client
initialize
↓
Server
返回能力
Client
保存能力
例如：
Client发送：
{
"method":"initialize",
"params":{
"clientInfo":{
"name":"my-agent"
}
}
}Server：
返回：
{
"serverInfo":{
"name":"weather-mcp"
},
"capabilities":{
"tools":{}
}
}这一步：
类似：
HTTP握手。
7.8 获取 Tool 列表
连接后：
Client：
调用：
tools/list代码：
async listTools(){
const result =
await this.client.listTools();
return result.tools;
}返回：
例如：
[
{
"name":
"getWeather",
"description":
"查询天气"
}
]现在：
Agent：
知道：
有什么能力。
7.9 获取 Resource 列表
同理：
async listResources(){
return await this.client.listResources();
}返回：
[
{
"uri":
"docs://payment"
}
]7.10 获取 Prompt 列表
调用：
listPrompts()返回：
[
{
"name":
"code-review"
}
]现在：
Client：
拥有：
完整能力地图。
7.11 Agent Runtime 核心循环
真正 Agent：
不是：
一次调用。
而是：
循环。
核心：
用户问题
↓
LLM分析
↓
需要Tool?
↓
调用MCP
↓
获得结果
↓
继续思考
↓
最终回答
这叫：
Agent Loop。
7.12 实现 Agent Loop
伪代码：
while(true){
response =
llm.chat(messages);
if(response.toolCall){
result =
mcp.callTool(
response.tool
);
messages.push(result);
continue;
}
return response.text;
}这就是：
ChatGPT Agent 工作方式。
7.13 Tool 自动发现
传统：
写死：
if(tool==="weather")不好。
企业：
动态：
启动：
连接Server
↓
tools/list
↓
注册Tool
↓
提供给LLM
例如：
获得：
[
{
name:"getWeather"
},
{
name:"searchCustomer"
}
]转换：
LLM Function Calling 格式。
7.14 MCP Tool 转 OpenAI Function
很多模型：
使用：
Function Calling。
例如：
OpenAI格式：
{
"name":
"getWeather",
"parameters":{
"type":"object"
}
}MCP：
转换：
MCP Tool Schema
↓
LLM Function Schema这样：
任何支持 Function Calling 的模型：
都可以使用 MCP。
7.15 Tool 调用流程
完整：
用户：
北京天气LLM：
返回：
{
"tool":
"getWeather",
"arguments":{
"city":"北京"
}
}Client：
调用：
MCP tools/callServer：
返回：
{
"temperature":
32
}Client：
追加：
Tool Result再次请求：
LLM。
最终：
回答。
7.16 多 MCP Server 管理
企业：
通常：
不是一个 Server。
例如：
Agent
|
+----------------+
|
天气MCP
|
CRM MCP
|
Git MCP
|
数据库MCP
Client：
需要：
Server Manager。
结构：
servers
├── weather
├── crm
├── git
└── database
配置：
{
"servers":[
{
"name":"crm",
"command":"node crm.js"
},
{
"name":"git",
"command":"node git.js"
}
]
}启动：
自动连接。
7.17 MCP Client 状态管理
需要保存：
连接状态
能力列表
Tool缓存
Resource缓存
Session信息
例如：
class ServerSession{
serverName:string;
tools=[];
resources=[];
status:"connected";
}7.18 MCP Client 错误处理
常见：
Server关闭
处理：
自动重连。
Tool失败
返回：
错误上下文。
网络超时
切换备用Server。
类似：
微服务治理。
7.19 MCP Client 安全
Client：
也需要安全。
例如：
不要允许：
任意 MCP Server。
需要：
Server 白名单：
{
"allowed":[
"company-crm",
"company-git"
]
}7.20 本章总结
本章完成：
✅ MCP Client 原理
✅ Client 创建
✅ Server连接
✅ initialize流程
✅ Tool发现
✅ Resource发现
✅ Prompt发现
✅ Agent Loop
✅ Function Calling转换
✅ 多Server管理
核心理解：
MCP Server 提供能力，MCP Client 负责把这些能力变成 AI 可以使用的行动。
完整链路：
User
↓
LLM
↓
MCP Client
↓
MCP Server
↓
Tool / Resource / Prompt
↓
Enterprise System第7章 MCP Client 开发实战（下）
——打造类似 Cursor 的企业级 Agent Runtime
上一节我们完成了：
- MCP Client 创建
- Server 连接
- initialize 握手
- Tool/Resource/Prompt 发现
- Agent Loop 基础流程
但是：
真正的 AI Agent 平台还需要：
- 自动规划
- 多工具调度
- 上下文管理
- 记忆系统
- 长任务执行
- 人工确认
- 任务恢复
这一章开始：
我们实现一个接近 Cursor / Claude Agent 的 Runtime。
7.21 什么是 Agent Runtime？
很多人认为：
Agent = 大模型。
这是错误的。
LLM：
只是“大脑”。
完整 Agent：
实际上：
id="m3x0z1"
Agent Runtime
+---------------------+
| |
Planner Executor
| |
+----------+----------+
|
MCP Client
|
MCP Server
|
Tools / Resources
Runtime 负责：
- 调度模型
- 管理状态
- 调用工具
- 保存上下文
- 控制流程
7.22 Agent Runtime 核心模块
企业级：
通常：
包含：
src
├── agent
│ ├── planner.ts
│ ├── executor.ts
│ └── loop.ts
├── context
│ └── contextManager.ts
├── memory
│ └── memoryStore.ts
├── mcp
│ └── mcpClient.ts
└── tools
└── toolRegistry.ts
7.23 Planner Agent
Planner：
负责：
思考：
下一步做什么。
例如：
用户：
帮我分析订单异常原因Planner：
生成：
{
"steps":[
"查询订单",
"检查支付状态",
"查询日志",
"生成分析报告"
]
}Planner 不执行。
只规划。
代码：
class Planner{
async plan(task:string){
return {
steps:[
"collect_data",
"analysis",
"report"
]
};
}
}7.24 Executor Agent
Executor：
负责：
执行计划。
流程：
Planner
↓
Step1
↓
Tool
↓
Result
↓
Step2
↓
Tool
↓
Result
代码：
class Executor{
async execute(plan){
for(
const step of plan.steps
){
await this.runStep(step);
}
}
}7.25 Agent Loop 完整实现
核心：
async function runAgent(
input
){
while(true){
const response =
await llm.chat(
messages
);
if(response.finish){
return response.text;
}
if(response.toolCall){
const result =
await mcp.callTool(
response.toolCall.name,
response.toolCall.args
);
messages.push({
role:"tool",
content:
result
});
}
}
}这就是：
现代 Agent 核心。
7.26 Tool 自动选择
传统：
代码决定：
if(weather)
调用天气Agent：
让模型决定。
流程：
启动：
获取：
tools/list得到：
[
{
"name":
"getWeather"
},
{
"name":
"searchCustomer"
}
]转换：
给 LLM：
{
"functions":[
{
"name":
"getWeather"
}
]
}模型：
自主选择。
7.27 多 Tool 冲突解决
问题：
例如：
有：
searchCustomer
searchUser
findCustomer
AI：
可能混乱。
解决：
增加：
Tool Router。
架构：
User
↓
Router Agent
↓
选择领域
↓
CRM Agent
↓
Tool例如：
问题：
查询客户资料Router：
判断：
{
"domain":"CRM"
}进入：
CRM Agent。
7.28 MCP Server 动态发现
大型企业：
Server 很多。
不能：
全部配置。
可以：
建立：
MCP Registry。
结构：
MCP Registry
|
+-- CRM Server
+-- Git Server
+-- Database Server
+-- Knowledge Server
Client：
启动：
查询：
有哪些 MCP Server？返回：
[
{
"name":"crm",
"url":"xxx"
}
]动态连接。
7.29 Session 管理
MCP Client：
需要管理会话。
例如：
用户：
连续聊天。
Session：
保存：
{
id:"abc123",
userId:"10001",
messages:[],
tools:[],
memory:[]
}生命周期：
创建Session
↓
用户交互
↓
保存状态
↓
结束
7.30 Context Manager
Agent 最大问题：
上下文爆炸。
例如：
聊天100轮。
全部发送：
成本巨大。
需要：
Context Manager。
功能：
压缩历史
例如：
旧消息：
50轮聊天总结：
用户目标：
开发支付模块。
当前状态：
接口已完成。
保留关键内容
保留：
- 当前任务
- Tool结果
- 用户偏好
7.31 Memory 系统设计
Agent Memory：
分：
Short Memory
短期。
当前会话。
例如：
正在开发订单模块Long Memory
长期。
用户习惯。
例如：
用户喜欢Java代码示例架构：
Memory
|
+-------------+
|
Redis Vector DB
7.32 Memory + MCP Resource
结合：
例如：
用户：
继续之前的项目Agent：
查询：
Memory：
之前开发商城系统Resource：
项目代码Tool：
Git操作形成：
连续工作能力。
7.33 长任务执行
企业任务：
可能：
几小时。
例如：
自动迁移数据库。
不能：
一个请求完成。
需要：
Task Manager。
架构：
User
↓
Task Queue
↓
Agent Worker
↓
MCP Tool
↓
Result
类似：
后台任务系统。
7.34 Task 状态机
任务：
不要：
简单：
成功/失败。
设计：
CREATED
↓
PLANNING
↓
RUNNING
↓
WAITING_CONFIRM
↓
COMPLETED
例如：
删除数据库：
进入：
WAITING_CONFIRM等待用户。
7.35 Human-in-the-loop
企业非常重要。
AI：
不能：
完全自主。
危险操作：
例如：
删除数据
发布代码
付款
需要：
人工确认。
流程：
AI
↓
生成计划
↓
请求确认
↓
用户批准
↓
执行
例如：
AI：
准备删除1000条测试数据。
是否继续？7.36 Agent Observability
生产环境：
必须知道：
AI 做了什么。
记录：
Trace:
用户输入
↓
Prompt
↓
LLM响应
↓
Tool调用
↓
Tool结果
↓
最终输出
类似：
分布式链路追踪。
推荐：
OpenTelemetry。
7.37 Agent Cost Control
企业：
必须控制成本。
指标：
Token
调用次数
响应时间
模型费用
策略：
模型路由
简单任务：
小模型。
复杂任务：
大模型。
例如：
分类
↓
小模型
代码分析
↓
大模型7.38 Agent 安全边界
必须限制：
Tool 权限
例如：
AI：
不能：
生产删除。
Resource 权限
例如：
AI：
不能：
读取工资文件。
Prompt 防护
防止：
Prompt Injection。
7.39 一个完整企业 Agent Runtime
最终：
User
|
v
Agent Runtime
+---------------+---------------+
| |
Planner Memory
| |
+---------------+---------------+
|
MCP Client
|
+---------------+---------------+
| | |
CRM MCP Git MCP Knowledge MCP
| | |
CRM Git RAG第8章 MCP 企业实战项目（上）
——从零搭建一个完整 AI Agent 助手平台
前面 7 章，我们已经掌握：
- MCP Server
- Tool
- Resource
- Prompt
- MCP Client
- Agent Runtime
现在进入真正项目阶段：
从 0 搭建一个企业级 AI Agent 平台。
目标：
打造一个类似：
- Cursor
- Claude Desktop
- 企业 Copilot
的智能助手系统。
8.1 项目目标
我们实现：
一个企业 AI 助手：
名字：
Enterprise Agent能力：
1. 企业知识问答
例如：
用户：
公司的退款规则是什么？AI：
自动查询：
- 产品文档
- 业务规则
- PDF资料
2. CRM 客户管理
用户：
查询客户张三的信息AI：
调用：
CRM MCP Server。
3. Git 代码助手
用户：
帮我分析最近提交的问题AI：
调用：
Git MCP Server。
4. 数据分析助手
用户：
统计本月销售额AI：
查询数据库。
最终架构：
用户
|
v
Enterprise Agent
|
+-----------+-----------+
| |
Agent Runtime Memory
|
MCP Client
|
+------------+------------+-------------+
| | | |
CRM MCP Git MCP DB MCP Knowledge MCP
| | | |
CRM Git仓库 数据库 RAG知识库
8.2 技术选型
后端：
Node.js
TypeScript
MCP SDKAI：
支持：
- GPT
- Claude
- Gemini
- 本地模型
数据库：
业务：
PostgreSQL向量：
Qdrant
Milvus
Chroma缓存：
Redis部署：
Docker
Kubernetes8.3 项目目录设计
企业项目：
推荐：
Monorepo。
结构：
enterprise-agent
├── apps
│
├── agent-runtime
│
├── web-console
├── servers
│
├── crm-server
├── git-server
├── database-server
├── knowledge-server
├── packages
│
├── mcp-client
├── prompt-engine
├── memory
├── shared
└── docker
说明：
apps
应用。
servers
MCP Server。
packages
公共能力。
8.4 Agent Runtime 核心
Runtime：
负责：
调度。
目录：
agent-runtime
src
├── Agent.ts
├── Planner.ts
├── Executor.ts
├── Context.ts
└── Router.ts
入口：
class Agent{
async run(input){
const plan =
await this.planner.create(input);
const result =
await this.executor.run(plan);
return result;
}
}8.5 MCP Client 管理层
创建：
packages/mcp-client核心：
class MCPManager{
servers = [];
async connect(server){
const client =
new Client();
await client.connect(
server
);
this.servers.push(
client
);
}
}作用：
统一管理：
多个 MCP Server。
8.6 CRM MCP Server
第一个业务 Server：
客户系统。
目录：
servers/crm-server
src
├── index.ts
├── tools
│ customer.ts
└── database.ts
提供 Tool：
id="d2o8sy"
get_customer
create_customer
update_customer
例如：
Tool：
{
name:
"get_customer",
description:
"查询客户信息",
inputSchema:{
customerId:"string"
}
}AI：
看到：
知道：
可以查询客户。
8.7 CRM Resource
除了 Tool：
还提供：
客户资料。
Resource：
设计：
crm://customer/{id}例如：
crm://customer/10001返回：
{
"id":10001,
"name":"张三",
"level":"VIP",
"orders":20
}区别：
Tool：
主动查询。
Resource：
提供上下文。
8.8 Git MCP Server
代码 Agent：
核心。
目录：
git-server
src
├── tools
│ commit.ts
│ diff.ts
│ branch.ts
提供：
Tool：
get_commit
get_diff
create_branch
例如：
用户：
分析最近提交Agent：
调用：
git.get_commit获得：
commit abc123
修改:
payment.ts
8.9 Database MCP Server
数据分析：
必须。
提供：
Tool：
query_database但是：
不能：
直接 SQL。
危险：
DROP TABLE user;设计：
业务 API。
例如：
sales_report
user_statistics
order_summary安全：
限制：
只读账号。
8.10 Knowledge MCP Server
企业最核心。
目录：
knowledge-server
src
├── loader
├── embedding
├── vector
└── resource
流程：
PDF
Word
Markdown
网页
↓
解析
↓
Chunk
↓
Embedding
↓
Vector DB
↓
MCP Resource
8.11 Knowledge Resource设计
URI：
knowledge://document/{id}例如：
knowledge://document/payment-policy返回：
{
"title":
"退款政策",
"content":
"退款7个工作日内到账"
}8.12 Prompt Center
企业：
不要写死 Prompt。
单独：
服务。
结构：
prompt-center
├── customer
├── coder
├── analyst
└── manager
MCP：
提供：
prompts/list
prompts/get例如：
获取：
code-review-v2返回：
你是一名高级代码审查工程师...8.13 Agent Router
企业：
多个 Agent。
例如：
用户：
帮我查订单进入：
订单 Agent。
用户：
分析代码进入：
Coding Agent。
Router：
负责：
分类。
流程：
用户输入
↓
Router
↓
选择Agent
↓
执行
代码：
switch(domain){
case "crm":
return crmAgent;
case "coding":
return codingAgent;
}8.14 多 Agent 协作
复杂任务：
多个 Agent。
例如：
上线新功能：
需要：
产品Agent
↓
开发Agent
↓
测试Agent
↓
发布Agent
架构：
Supervisor
|
+--------------+--------------+
| | |
Product Dev Test
Supervisor：
协调。
8.15 用户请求完整流程
用户：
分析支付失败原因步骤：
第一步
Router：
判断：
支付领域第二步
Planner：
制定：
1 查询订单
2 查询日志
3 分析错误码
第三步
MCP Client：
调用：
CRM Tool
Database Tool
Knowledge Resource
第四步
LLM：
生成：
分析报告。
最终：
支付失败原因：
银行卡渠道超时。
建议：
切换备用渠道。
8.16 企业安全设计
必须考虑：
身份认证
例如：
OAuth2。
权限控制
RBAC：
用户
↓
角色
↓
权限
↓
Tool/Resource
审计日志
记录：
谁
什么时候
调用什么Tool
参数是什么
结果是什么第8章 MCP 企业实战项目（下）
——完整实现、Docker 部署与生产级 AI Agent 架构
上一节我们完成了企业 AI Agent 平台的整体设计：
- Agent Runtime
- MCP Client
- CRM MCP Server
- Git MCP Server
- Database MCP Server
- Knowledge MCP Server
- Prompt Center
- Multi-Agent 架构
这一节进入真正生产部署：
目标：
将 MCP Agent 从 Demo 变成企业可运行的平台。
8.18 生产环境整体架构
最终生产架构：
用户
|
Web / App / API
|
API Gateway
|
Enterprise Agent Runtime
|
+-----------+-----------+
| |
MCP Client Memory System
| |
| Redis
|
+-------+--------+--------+---------+
| | | |
CRM MCP Git MCP DB MCP Knowledge MCP
| | | |
CRM系统 Git仓库 数据库 Vector DB
8.19 Docker 化 MCP Server
企业中：
每个 MCP Server：
独立部署。
例如：
crm-server
git-server
database-server
knowledge-server
目录：
crm-server
├── Dockerfile
├── package.json
└── src
Dockerfile：
FROM node:22
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
CMD [
"node",
"dist/index.js"
]
构建：
docker build -t crm-mcp-server .运行：
docker run \
-p 8080:8080 \
crm-mcp-server8.20 MCP Server 容器化原则
生产环境：
不要：
一个容器：
所有能力。
错误：
Agent
+
CRM
+
Git
+
Database
全部一起。
正确：
微服务：
Agent Runtime
|
|
MCP Server 集群
+---------+
CRM
+---------+
Git
+---------+
Knowledge
优势：
- 独立扩容
- 独立升级
- 故障隔离
8.21 Docker Compose 本地环境
开发阶段：
使用：
docker-compose。
结构：
docker-compose.yml示例：
version: "3"
services:
agent:
image:
enterprise-agent
crm-mcp:
image:
crm-server
git-mcp:
image:
git-server
redis:
image:
redis
启动：
docker compose up本地：
完整环境启动。
8.22 MCP Server 服务发现
生产：
MCP Server：
动态变化。
需要：
Service Registry。
例如：
MCP Registry
crm-server
git-server
database-server
注册：
{
"name":
"crm-server",
"url":
"http://crm:8080",
"capabilities":[
"tools",
"resources"
]
}
Agent：
启动：
查询 Registry。
8.23 Kubernetes 部署
企业：
通常：
K8S。
架构：
Kubernetes Cluster
namespace: ai-agent
|
+----------------+
Agent Deployment
+----------------+
CRM MCP Deployment
+----------------+
Knowledge MCP Deployment
8.24 Agent Runtime Deployment
Deployment：
apiVersion:
apps/v1
kind:
Deployment
metadata:
name:
agent-runtime
spec:
replicas:
3
为什么：
3？
因为：
高可用。
如果：
一个挂掉：
自动恢复。
8.25 MCP Server 自动扩容
例如：
知识库查询：
高峰：
10000请求。
增加：
knowledge-mcp
replicas:
10
Kubernetes：
自动负载。
8.26 MCP 通信方式选择
MCP：
支持：
本地
stdio：
Client
|
Process
|
Server
适合：
桌面 Agent。
企业
HTTP：
Client
|
HTTP
|
Server
适合：
云端。
大规模
Streaming：
Client
|
SSE/WebSocket
|
Server
适合：
实时 Agent。
8.27 Redis Memory 系统
Agent Memory：
不能：
存在进程内。
原因：
多实例：
数据不共享。
错误：
Agent1
memory[]
Agent2
memory[]
正确：
Agent
|
Redis
存储：
短期记忆：
{
session:
"10001",
messages:[
]
}
8.28 Vector Database 部署
知识库：
需要：
向量数据库。
选择：
Qdrant
适合：
轻量。
Milvus
适合：
大型企业。
Elasticsearch
适合：
搜索融合。
架构：
Document
|
Embedding
|
Vector DB
|
MCP Resource
8.29 Knowledge Pipeline
企业文档：
自动同步。
流程：
文件上传
↓
Parser
↓
Chunk
↓
Embedding
↓
Vector DB
↓
Knowledge MCP
例如：
新增：
payment.pdf。
自动：
生成：
payment chunk1
payment chunk2
payment chunk3
8.30 Agent 可观测性
生产最大问题：
不知道 AI 为什么这么回答。
必须记录：
Trace。
例如：
一次请求：
User Question
↓
Prompt
↓
LLM
↓
Tool Call
↓
Tool Result
↓
Final Answer
类似：
后端链路追踪。
8.31 OpenTelemetry 接入
架构：
Agent Runtime
|
OpenTelemetry
|
Trace Collector
|
Monitoring System
记录：
例如：
{
traceId:
"abc123",
tool:
"query_order",
duration:
1200
}
8.32 Agent 日志体系
日志：
分：
应用日志
例如：
Agent started
推理日志
例如：
调用CRM Tool
审计日志
例如：
用户A查询客户B
8.33 Agent 成本控制
企业最关注：
费用。
主要来源：
Token。
优化：
1. Prompt压缩
减少：
无用内容。
2. Context窗口管理
历史：
摘要。
3. 模型路由
简单：
小模型。
复杂：
大模型。
架构：
Request
|
Classifier
|
+-------+
|
Small LLM
|
Large LLM
8.34 Agent 限流
防止：
恶意调用。
例如：
用户：
一分钟：
1000次。
限制：
user:
100 requests/min
Tool：
限制：
delete_user
10/day
8.35 MCP 安全网关
大型企业：
建议：
增加：
MCP Gateway。
架构：
Agent
|
MCP Gateway
|
MCP Servers
Gateway：
负责：
- 身份认证
- 权限
- 审计
- 限流
- 路由
8.36 Agent 发布流程
类似软件：
开发
↓
测试
↓
Prompt评估
↓
灰度
↓
上线
灰度：
例如：
10% 用户。
观察：
指标：
- 成功率
- 成本
- 延迟
8.37 企业级 Agent 测试
测试：
不能只测接口。
需要：
Prompt测试
输入：
1000问题。
Tool测试
模拟：
异常。
Agent测试
完整流程。
例如：
测试：
用户:
退款多久到账？
期望:
返回退款规则
8.38 MCP Agent 高可用设计
核心：
避免单点。
设计：
Load Balancer
|
+-------+-------+
| | |
Agent Agent Agent
|
MCP Pool
数据库：
主从。
Redis：
Cluster。
Vector：
集群。
8.39 最终企业架构图
完整：
用户
|
Web / Mobile
|
API Gateway
|
Enterprise Agent Platform
+-----------------+-----------------+
| |
Agent Runtime Observability
|
MCP Client
|
+-------+--------+---------+------------+
| | | |
CRM MCP Git MCP DB MCP Knowledge MCP
| | | |
CRM系统 GitLab SQL DB Vector DB
8.40 MCP 企业落地路线
推荐路线：
第一阶段
单 Agent。
实现：
- MCP Client
- 一个 Server
- 一个 Tool
第二阶段
知识库。
增加：
- Resource
- RAG
第三阶段
多 Agent。
增加：
- Planner
- Executor
第四阶段
生产化。
增加：
- Kubernetes
- Monitoring
- Security
8.41 本系列总结
经过 8 章：
我们完整学习：
MCP基础
- MCP协议
- 架构
- 生命周期
Server开发
- Tool
- Resource
- Prompt
Client开发
- MCP Client
- Agent Runtime
企业实践
- RAG
- Memory
- Multi Agent
- Docker
- Kubernetes
最终理解：
MCP 不是一个简单协议。
它正在成为：
AI Agent 连接现实世界能力的标准接口。
未来企业 AI 架构：
很可能：
AI Model
+
Agent Runtime
+
MCP Protocol
+
Enterprise Capability第9章 MCP 高级开发篇（上）
——深入理解 MCP 协议底层原理：从 JSON-RPC 到 Agent 通信模型
前面 8 章，我们完成了：
- MCP 基础概念
- Server 开发
- Tool / Resource / Prompt
- Client 开发
- Agent Runtime
- 企业部署
现在进入 MCP 深层原理。
本章目标：
不只是会用 MCP，而是理解 MCP 为什么这样设计，以及如何打造自己的 MCP 基础设施。
9.1 MCP 的本质是什么？
很多人认为：
MCP：
=
“给 AI 调工具的协议”。
这个理解：
不完整。
MCP 本质：
是一套：
AI 应用与外部能力之间的标准通信协议。
类似：
过去：
Web
解决：
浏览器 ↔ 服务端通信。
JDBC
解决：
Java ↔ 数据库通信。
MCP
解决：
AI Agent ↔ 外部世界通信。
架构：
传统互联网：
Browser
|
HTTP
|
Server
AI时代：
Agent
|
MCP
|
Capability Server
9.2 为什么 MCP 不直接调用 API？
很多人问：
已经有 REST API：
为什么需要 MCP？
例如：
CRM：
已有：
GET /customer/10001为什么还需要：
MCP Tool？
原因：
API：
面向程序。
例如：
开发者知道：
/customer/{id}但是 AI：
不知道：
- 哪个接口适合
- 参数是什么
- 什么情况下调用
MCP 增加：
语义描述。
例如：
Tool：
{
"name":
"get_customer",
"description":
"根据客户编号查询客户资料"
}AI：
理解：
用途。
9.3 MCP 协议分层模型
MCP：
类似网络协议栈。
五层：
Application Layer
Tool Resource Prompt
|
Protocol Layer
JSON-RPC
|
Transport Layer
stdio HTTP SSE
|
Session Layer
|
Runtime Layer
9.4 MCP 基于 JSON-RPC
核心：
JSON-RPC 2.0。
为什么选择？
因为：
简单。
跨语言。
一个请求：
{
"jsonrpc":
"2.0",
"id":
1,
"method":
"tools/list",
"params":{}
}
解释：
jsonrpc
协议版本。
id
请求编号。
method
调用方法。
params
参数。
9.5 MCP 请求生命周期
一次 Tool 调用：
完整流程：
Client
|
| tools/call
|
v
Server
|
| 执行业务
|
v
返回Result
|
Client
|
LLM继续推理
例如：
用户：
查询天气。
第一步：
LLM：
决定：
调用：
getWeather第二步：
MCP Client：
发送：
{
"method":
"tools/call",
"params":{
"name":
"getWeather"
}
}
第三步：
Server：
执行。
第四步：
返回。
9.6 MCP Initialize 握手原理
连接不是：
直接调用。
第一步：
必须：
初始化。
Client：
发送：
{
"method":
"initialize",
"params":{
"clientInfo":{
"name":
"agent"
}
}
}
Server：
返回：
{
"serverInfo":{
"name":
"crm-server"
},
"capabilities":{
"tools":{}
}
}
作用：
双方确认：
能力。
类似：
TCP Handshake。
9.7 Capability 协商
MCP：
不是所有 Server：
都支持全部能力。
例如：
Server A：
支持：
{
"tools":{}
}
Server B：
支持：
{
"resources":{}
}
Client：
根据能力：
决定：
调用什么。
9.8 MCP Method 分类
主要：
三类。
Tool
方法：
tools/list
tools/call
Resource
方法：
resources/list
resources/read
Prompt
方法：
prompts/list
prompts/get
9.9 Tool Schema 设计原理
Tool：
核心：
Schema。
例如：
{
"name":
"create_order",
"inputSchema":{
"type":
"object",
"properties":{
"userId":{
"type":"string"
}
}
}
}
为什么重要？
因为：
LLM 根据 Schema：
决定：
怎么调用。
9.10 Tool 描述设计原则
错误：
{
"name":
"query"
}
AI：
不知道：
查什么。
正确：
{
"name":
"get_customer_orders",
"description":
"查询指定客户最近订单列表"
}
原则：
名称
动词 + 对象。
例如：
good：
search_customer
create_invoice
bad：
data1
api2
9.11 Tool 参数设计
错误：
一个参数：
{
"input":
"string"
}
问题：
AI不知道格式。
正确：
{
"customerId":
{
"type":
"string",
"description":
"客户编号"
}
}
描述：
非常重要。
9.12 Tool 返回值设计
不要：
返回：
巨大 JSON。
错误：
{
100个字段
}
推荐：
结构化：
{
"success":
true,
"data":{
"name":
"张三"
}
}
方便 AI 理解。
9.13 MCP Resource 深层设计
Resource：
不是简单文件。
它代表：
知识对象。
例如：
错误：
file:///a/b/c.pdf正确：
customer://10001/profile
order://8888/detail
policy://refund为什么？
因为：
AI 理解业务语义。
9.14 MCP Prompt 本质
Prompt：
不是字符串。
而是：
企业行为规范。
例如：
代码审查：
code-review-v2包含：
- 角色
- 规则
- 输出格式
- 安全限制
类似：
“AI工作流程模板”。
9.15 MCP Transport 原理
MCP：
支持不同传输。
stdio
流程：
Client
|
stdin/stdout
|
Server Process
特点：
简单。
适合：
桌面应用。
HTTP
流程：
Client
|
HTTP Request
|
Server
适合：
云服务。
SSE
支持：
服务器推送。
例如：
任务执行进度。
9.16 为什么 MCP 选择 JSON-RPC？
原因：
1. 双向通信
客户端：
调用服务器。
服务器：
也可以通知客户端。
例如：
资源更新：
resources/list_changed2. 简单
容易：
跨语言。
3. 适合 Agent
Agent：
大量：
动态调用。
9.17 MCP 与微服务区别
很多人混淆。
微服务：
解决：
服务拆分。
MCP：
解决：
AI访问能力。
对比：
| 微服务 | MCP | |
|---|---|---|
| 调用者 | 程序 | AI |
| 接口 | API | Tool/Resource |
| 描述 | 文档 | Schema |
| 目标 | 业务通信 | 智能调用 |
9.18 MCP 与 OpenAPI 区别
OpenAPI：
描述：
HTTP API。
MCP：
描述：
AI Capability。
可以：
OpenAPI 转 MCP。
流程：
OpenAPI
↓
Schema转换
↓
MCP Tool
↓
Agent调用
9.19 MCP Server 设计最佳实践
一个 Server 一个领域
推荐：
crm-server
payment-server
knowledge-server不要：
everything-server第9章 MCP 高级开发篇（下）
——MCP SDK 源码解析与高级 Server 设计
上一节我们从协议层理解了 MCP：
- JSON-RPC
- initialize
- Capability
- Tool / Resource / Prompt
- Transport
这一节进入 SDK 和框架层。
目标：
不只是调用 MCP SDK，而是理解 SDK 如何工作，并设计自己的企业级 MCP Framework。
9.21 MCP SDK 整体结构分析
以 TypeScript MCP SDK 为例。
整体结构：
@mcp/sdk
├── client
│ ├── Client
│ ├── Session
├── server
│ ├── Server
│ ├── RequestHandler
├── transport
│ ├── Stdio
│ ├── HTTP
├── types
│ ├── Tool
│ ├── Resource
│ └── Prompt
└── protocol
└── JSON-RPC
核心：
其实只有三个部分：
Protocol
Transport
Capability
9.22 MCP Server 内部运行模型
一个 Server：
启动后：
执行：
创建Server
↓
注册能力
↓
监听Transport
↓
接收Request
↓
匹配Handler
↓
执行业务
↓
返回Result
代码结构：
const server =
new MCPServer();
server.registerTool();
server.start();
9.23 Server 初始化过程
例如：
const server =
new Server({
name:"crm",
version:"1.0"
});
内部：
创建：
{
name,
version,
capabilities,
handlers
}
其中：
handlers：
保存：
所有请求处理函数。
9.24 Tool 注册机制源码思想
调用：
server.tool(
"get_customer",
schema,
handler
)
实际上：
类似：
tools.set(
"get_customer",
{
schema,
handler
}
)
内部：
维护：
Map。
结构：
ToolRegistry
{
get_customer:
handler
create_order:
handler
}
9.25 Request Handler 工作流程
收到：
{
method:
"tools/call"
}
进入：
Router：
switch(method){
case "tools/call":
handleToolCall();
}
然后：
找到：
Tool。
执行：
tool.handler(args)
返回：
Result。
9.26 自己实现一个 MCP Mini Framework
理解原理后：
可以自己封装。
目录：
mini-mcp
src
├── server.ts
├── registry.ts
├── transport.ts
└── protocol.ts
9.27 Tool Registry设计
核心：
工具注册中心。
代码：
class ToolRegistry{
private tools =
new Map();
register(
tool
){
this.tools.set(
tool.name,
tool
);
}
get(name){
return this.tools.get(name);
}
}
使用：
registry.register({
name:"weather",
handler:getWeather
})
9.28 Request Router设计
所有请求：
进入 Router。
class Router{
async dispatch(request){
const method =
request.method;
if(method==="tools/list"){
return this.listTools();
}
if(method==="tools/call"){
return this.callTool(
request
);
}
}
}
类似：
Web Router。
9.29 Schema 校验系统
企业环境：
参数必须安全。
例如：
Tool：
要求：
{
age:
number
}
用户：
传：
{
age:
"abc"
}
必须拒绝。
使用：
Schema Validator。
例如：
validate(
schema,
params
)
流程：
Request
↓
Schema验证
↓
Handler
↓
Result
9.30 MCP Middleware设计
类似：
Express。
例如：
Request
↓
Auth Middleware
↓
Logging Middleware
↓
Permission Middleware
↓
Tool Handler
代码：
server.use(
middleware
)
用途：
- 权限
- 审计
- 限流
9.31 MCP 权限系统设计
企业：
不能：
所有 Tool：
全部开放。
设计：
Permission Matrix。
例如：
Tool
User query delete
Admin √ √
Operator √ ×
Guest √ ×
实现：
checkPermission(
user,
tool
)
9.32 MCP Gateway设计
大型企业：
不会：
Agent直接连接几十个Server。
中间：
增加 Gateway。
架构：
Agent
|
MCP Gateway
+--------+---------+
| | |
CRM Git DB
Gateway职责：
- 路由
- 鉴权
- 监控
- 限流
9.33 Gateway Tool 聚合
例如：
三个 Server：
CRM：
get_customerOrder：
get_orderPayment：
get_paymentGateway：
统一暴露：
enterprise.tools
Agent：
只连接一个入口。
9.34 Tool 动态注册
企业：
新系统上线：
不希望：
重启 Agent。
动态：
新Tool上线
↓
注册中心
↓
Gateway发现
↓
Agent刷新能力
类似：
服务发现。
9.35 MCP Server 热更新
需求：
修改 Tool：
无需停机。
方案：
Tool版本管理。
例如：
customer-search-v1
customer-search-v2
灰度：
10%
↓
50%
↓
100%
9.36 MCP Server 集群
生产：
单 Server：
不够。
架构：
Load Balancer
|
+-----------+-----------+
| | |
MCP1 MCP2 MCP3
注意：
MCP Server：
最好：
无状态。
为什么？
方便扩容。
9.37 无状态 MCP 架构
推荐：
不要保存：
用户状态。
错误：
Server
{
session:{}
}
正确：
Server
|
Redis
|
Database
优势：
任意节点处理请求。
9.38 MCP Event机制
高级场景：
需要：
事件通知。
例如：
数据更新。
流程：
Database变化
↓
Event
↓
MCP Server
↓
通知Agent
例如：
Resource变化：
resources/list_changed
9.39 MCP 长任务设计
例如：
生成报告：
需要30分钟。
不能：
HTTP一直等待。
设计：
异步任务。
流程：
Tool Call
↓
Create Task
↓
Return taskId
↓
后台执行
↓
Notify Result
返回：
{
taskId:
"123456",
status:
"running"
}
9.40 MCP Framework 企业封装
最终：
企业可以封装：
自己的 MCP Framework。
结构：
Enterprise MCP Framework
├── Tool SDK
├── Auth SDK
├── Registry
├── Gateway
├── Monitor
└── Deployment
开发者：
只需要：
@mcpTool({
name:"queryOrder"
})
class OrderService{
}
自动生成：
MCP Tool。
9.41 MCP 未来演进方向
未来 MCP：
可能发展：
1. Capability Marketplace
能力市场。
类似：
App Store。
2. Agent Operating System
AI操作系统。
3. Enterprise AI Bus
企业AI总线。
架构：
AI Agents
|
MCP Bus
|
Enterprise Systems
中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。
更多推荐
4
0- 0
已为社区贡献5条内容
所有评论(0)