513 lines
13 KiB
Markdown
513 lines
13 KiB
Markdown
# MCP 工具调用完整示例
|
||
|
||
## 概述
|
||
|
||
本文档展示 Cherry Studio 架构风格的 MCP 工具调用流程，通过"发布小红书文章"的实际例子，详细说明 AI 如何理解用户意图、生成内容、并自动调用 MCP 工具。
|
||
|
||
## 实现架构
|
||
|
||
### 核心流程
|
||
|
||
```
|
||
用户输入
|
||
↓
|
||
获取 MCP 工具 (带服务器名称前缀)
|
||
↓
|
||
添加 System Prompt (指导 AI 使用工具)
|
||
↓
|
||
AI 理解意图 + 生成内容
|
||
↓
|
||
AI 调用工具 (OpenAI Function Calling)
|
||
↓
|
||
解析工具名称 (serverName__toolName)
|
||
↓
|
||
执行 MCP 工具
|
||
↓
|
||
工具结果返回
|
||
↓
|
||
AI 生成友好回复
|
||
```
|
||
|
||
### 关键创新点
|
||
|
||
1. **工具名称前缀**: `serverName__toolName` 格式避免多服务器工具名冲突
|
||
2. **System Prompt**: 详细的工具使用指南，让 AI 理解如何创作和调用
|
||
3. **参数自动注入**: AI 根据用户意图自动生成完整参数
|
||
4. **多轮对话**: 支持工具结果继续对话
|
||
|
||
## 完整示例：发布小红书文章
|
||
|
||
### 用户输入
|
||
|
||
```
|
||
用户: 帮我发布小红书文章，内容是：如何制作一道酸菜鱼
|
||
```
|
||
|
||
### 步骤 1: 获取 MCP 工具
|
||
|
||
假设连接了名为 `xiaohongshu` 的 MCP 服务器，提供以下工具：
|
||
|
||
```json
|
||
{
|
||
"name": "public_content",
|
||
"description": "发布内容到小红书平台",
|
||
"inputSchema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"title": {
|
||
"type": "string",
|
||
"description": "文章标题，吸引眼球且相关"
|
||
},
|
||
"content": {
|
||
"type": "string",
|
||
"description": "文章正文，Markdown 格式"
|
||
},
|
||
"tags": {
|
||
"type": "array",
|
||
"description": "标签列表，3-5个",
|
||
"items": { "type": "string" }
|
||
},
|
||
"category": {
|
||
"type": "string",
|
||
"description": "分类，如美食、生活、旅游等"
|
||
}
|
||
},
|
||
"required": ["title", "content", "tags", "category"]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 步骤 2: 转换为 OpenAI 格式（带前缀）
|
||
|
||
```typescript
|
||
// chatService.ts - convertToolsToOpenAIFormat()
|
||
{
|
||
type: 'function',
|
||
function: {
|
||
name: 'xiaohongshu__public_content', // 添加服务器前缀
|
||
description: '发布内容到小红书平台',
|
||
parameters: { ...inputSchema }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 步骤 3: 生成 System Prompt
|
||
|
||
```typescript
|
||
// chatService.ts - createSystemPromptWithTools()
|
||
你是一个智能助手，可以使用以下工具完成任务：
|
||
|
||
• xiaohongshu__public_content
|
||
描述: 发布内容到小红书平台
|
||
参数:
|
||
- title [必填]: 文章标题，吸引眼球且相关
|
||
- content [必填]: 文章正文，Markdown 格式
|
||
- tags [必填]: 标签列表，3-5个
|
||
- category [必填]: 分类，如美食、生活、旅游等
|
||
|
||
使用指南：
|
||
1. 当用户需要完成某个任务时，请分析哪个工具最合适
|
||
2. 如果需要发布内容（如文章、笔记等），请根据用户意图创作完整的内容
|
||
3. 为内容生成合适的标题、正文、标签等所有必需参数
|
||
4. 自动调用相应工具，将生成的内容作为参数传递
|
||
5. 根据工具执行结果，给用户友好的反馈
|
||
|
||
注意事项：
|
||
- 保持内容质量和平台特色
|
||
- 标签要相关且有吸引力
|
||
- 分类要准确
|
||
- 如果工具执行失败，给出明确的错误说明和建议
|
||
|
||
当前连接的 MCP 服务器: xiaohongshu
|
||
```
|
||
|
||
### 步骤 4: 发送请求到 LLM
|
||
|
||
```typescript
|
||
// modelServiceManager.ts - sendChatRequestStream()
|
||
const request = {
|
||
model: 'gpt-4',
|
||
messages: [
|
||
{
|
||
role: 'system',
|
||
content: '你是一个智能助手，可以使用以下工具...' // System Prompt
|
||
},
|
||
{
|
||
role: 'user',
|
||
content: '帮我发布小红书文章，内容是：如何制作一道酸菜鱼'
|
||
}
|
||
],
|
||
tools: [
|
||
{
|
||
type: 'function',
|
||
function: {
|
||
name: 'xiaohongshu__public_content',
|
||
description: '发布内容到小红书平台',
|
||
parameters: { ... }
|
||
}
|
||
}
|
||
],
|
||
tool_choice: 'auto',
|
||
stream: true
|
||
}
|
||
```
|
||
|
||
### 步骤 5: AI 理解 + 生成内容 + 调用工具
|
||
|
||
AI 响应（SSE 流式返回）:
|
||
|
||
```json
|
||
// 第一部分：AI 思考过程（可选）
|
||
{
|
||
"choices": [{
|
||
"delta": {
|
||
"content": "好的，我来帮你创作一篇关于酸菜鱼制作的小红书文章并发布。"
|
||
}
|
||
}]
|
||
}
|
||
|
||
// 第二部分：工具调用
|
||
{
|
||
"choices": [{
|
||
"delta": {
|
||
"tool_calls": [
|
||
{
|
||
"id": "call_abc123",
|
||
"type": "function",
|
||
"function": {
|
||
"name": "xiaohongshu__public_content",
|
||
"arguments": {
|
||
"title": "🐟 超详细！家常酸菜鱼做法，10分钟学会！",
|
||
"content": "# 酸菜鱼制作教程\n\n## 所需食材\n- 草鱼1条(约1.5kg)\n- 酸菜200g\n- 姜片、蒜瓣适量...\n\n## 制作步骤\n\n### 1. 处理鱼肉\n...",
|
||
"tags": ["美食教程", "酸菜鱼", "家常菜", "川菜", "烹饪技巧"],
|
||
"category": "美食"
|
||
}
|
||
}
|
||
}
|
||
]
|
||
},
|
||
"finish_reason": "tool_calls"
|
||
}]
|
||
}
|
||
```
|
||
|
||
### 步骤 6: 解析工具名称
|
||
|
||
```typescript
|
||
// chatService.ts - executeToolCalls()
|
||
const fullFunctionName = 'xiaohongshu__public_content'
|
||
const parts = fullFunctionName.split('__')
|
||
|
||
if (parts.length !== 2) {
|
||
console.error('工具名称格式错误')
|
||
return
|
||
}
|
||
|
||
const [serverName, toolName] = parts
|
||
// serverName = 'xiaohongshu'
|
||
// toolName = 'public_content'
|
||
```
|
||
|
||
### 步骤 7: 执行 MCP 工具
|
||
|
||
```typescript
|
||
// MCPClientService.ts - callTool()
|
||
const result = await mcpClient.callTool(
|
||
'xiaohongshu', // serverId
|
||
'public_content', // toolName (不带前缀)
|
||
{
|
||
title: '🐟 超详细！家常酸菜鱼做法，10分钟学会！',
|
||
content: '# 酸菜鱼制作教程\n\n## 所需食材...',
|
||
tags: ['美食教程', '酸菜鱼', '家常菜', '川菜', '烹饪技巧'],
|
||
category: '美食'
|
||
}
|
||
)
|
||
|
||
// MCP Server 响应:
|
||
{
|
||
"success": true,
|
||
"article_id": "xhs_2024_001",
|
||
"url": "https://www.xiaohongshu.com/discovery/item/xhs_2024_001",
|
||
"views": 0,
|
||
"likes": 0
|
||
}
|
||
```
|
||
|
||
### 步骤 8: 工具结果返回 AI
|
||
|
||
```typescript
|
||
// chatService.ts - 继续对话
|
||
const messages = [
|
||
{
|
||
role: 'system',
|
||
content: '...' // System Prompt
|
||
},
|
||
{
|
||
role: 'user',
|
||
content: '帮我发布小红书文章，内容是：如何制作一道酸菜鱼'
|
||
},
|
||
{
|
||
role: 'assistant',
|
||
tool_calls: [{
|
||
id: 'call_abc123',
|
||
type: 'function',
|
||
function: {
|
||
name: 'xiaohongshu__public_content',
|
||
arguments: '{"title":"🐟 超详细！家常酸菜鱼做法，10分钟学会！",...}'
|
||
}
|
||
}]
|
||
},
|
||
{
|
||
role: 'tool',
|
||
tool_call_id: 'call_abc123',
|
||
name: 'xiaohongshu__public_content', // 保持原名称（带前缀）
|
||
content: JSON.stringify({
|
||
success: true,
|
||
article_id: 'xhs_2024_001',
|
||
url: 'https://www.xiaohongshu.com/discovery/item/xhs_2024_001'
|
||
})
|
||
}
|
||
]
|
||
|
||
// 再次调用 LLM
|
||
```
|
||
|
||
### 步骤 9: AI 生成友好回复
|
||
|
||
```json
|
||
{
|
||
"choices": [{
|
||
"delta": {
|
||
"content": "✅ 文章已成功发布到小红书！\n\n📝 标题：🐟 超详细！家常酸菜鱼做法，10分钟学会！\n🔗 链接：https://www.xiaohongshu.com/discovery/item/xhs_2024_001\n\n你的酸菜鱼教程已经上线啦！记得定期查看浏览和点赞数据哦~ 🎉"
|
||
},
|
||
"finish_reason": "stop"
|
||
}]
|
||
}
|
||
```
|
||
|
||
## 关键代码实现
|
||
|
||
### 1. System Prompt 生成 (chatService.ts)
|
||
|
||
```typescript
|
||
private createSystemPromptWithTools(tools: any[], serverName: string): string {
|
||
const toolDescriptions = tools.map(tool => {
|
||
const func = tool.function
|
||
const params = func.parameters?.properties || {}
|
||
const required = func.parameters?.required || []
|
||
|
||
const paramDesc = Object.entries(params).map(([name, schema]: [string, any]) => {
|
||
const isRequired = required.includes(name)
|
||
const requiredMark = isRequired ? '[必填]' : '[可选]'
|
||
return ` - ${name} ${requiredMark}: ${schema.description || schema.type}`
|
||
}).join('\n')
|
||
|
||
return `• ${func.name}\n 描述: ${func.description}\n 参数:\n${paramDesc || ' 无参数'}`
|
||
}).join('\n\n')
|
||
|
||
return `你是一个智能助手，可以使用以下工具完成任务：
|
||
|
||
${toolDescriptions}
|
||
|
||
使用指南：
|
||
1. 当用户需要完成某个任务时，请分析哪个工具最合适
|
||
2. 如果需要发布内容（如文章、笔记等），请根据用户意图创作完整的内容
|
||
3. 为内容生成合适的标题、正文、标签等所有必需参数
|
||
4. 自动调用相应工具，将生成的内容作为参数传递
|
||
5. 根据工具执行结果，给用户友好的反馈
|
||
|
||
注意事项：
|
||
- 保持内容质量和平台特色
|
||
- 标签要相关且有吸引力
|
||
- 分类要准确
|
||
- 如果工具执行失败，给出明确的错误说明和建议
|
||
|
||
当前连接的 MCP 服务器: ${serverName}`
|
||
}
|
||
```
|
||
|
||
### 2. 工具名称转换 (chatService.ts)
|
||
|
||
```typescript
|
||
private convertToolsToOpenAIFormat(mcpTools: any[], serverName: string): any[] {
|
||
return mcpTools.map(tool => ({
|
||
type: 'function',
|
||
function: {
|
||
name: `${serverName}__${tool.name}`, // 添加服务器前缀
|
||
description: tool.description || '',
|
||
parameters: tool.inputSchema || {
|
||
type: 'object',
|
||
properties: {},
|
||
required: []
|
||
}
|
||
}
|
||
}))
|
||
}
|
||
```
|
||
|
||
### 3. 工具名称解析 (chatService.ts)
|
||
|
||
```typescript
|
||
private async executeToolCalls(
|
||
conversation: Conversation,
|
||
toolCalls: any[],
|
||
model: string | undefined,
|
||
onChunk: (chunk: string) => void,
|
||
mcpServerId: string
|
||
): Promise<void> {
|
||
for (const toolCall of toolCalls) {
|
||
const fullFunctionName = toolCall.function.name
|
||
const args = JSON.parse(toolCall.function.arguments)
|
||
|
||
console.log('🔧 执行工具调用:', {
|
||
fullName: fullFunctionName,
|
||
id: toolCall.id,
|
||
arguments: args
|
||
})
|
||
|
||
// 解析 serverName__toolName 格式
|
||
const parts = fullFunctionName.split('__')
|
||
if (parts.length !== 2) {
|
||
console.error('❌ 工具名称格式错误，应为 serverName__toolName:', fullFunctionName)
|
||
continue
|
||
}
|
||
|
||
const toolName = parts[1]
|
||
console.log('🎯 提取工具名称:', toolName)
|
||
|
||
try {
|
||
// 调用 MCP 工具（使用不带前缀的工具名）
|
||
const result = await this.mcpClient.callTool(
|
||
mcpServerId,
|
||
toolName, // 使用原始工具名
|
||
args
|
||
)
|
||
|
||
// 添加工具结果到消息历史（使用完整名称）
|
||
const toolResultMessage: Message = {
|
||
id: Date.now().toString(),
|
||
role: 'tool',
|
||
content: JSON.stringify(result),
|
||
timestamp: new Date(),
|
||
status: 'success',
|
||
toolCallId: toolCall.id,
|
||
toolName: fullFunctionName // 保持完整名称
|
||
}
|
||
|
||
conversation.messages.push(toolResultMessage)
|
||
this.saveConversations()
|
||
|
||
// 继续对话
|
||
await this.callModelStream(conversation, model, onChunk, mcpServerId)
|
||
|
||
} catch (error) {
|
||
console.error('❌ 工具执行失败:', error)
|
||
// 错误处理...
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 测试场景
|
||
|
||
### 场景 1: 发布文章
|
||
|
||
```
|
||
用户: 帮我发布一篇关于"春季穿搭指南"的小红书笔记
|
||
|
||
AI 处理:
|
||
1. 识别需要使用 xiaohongshu__public_content 工具
|
||
2. 创作完整文章（标题、正文、标签、分类）
|
||
3. 调用工具发布
|
||
4. 返回发布结果和链接
|
||
```
|
||
|
||
### 场景 2: 多工具选择
|
||
|
||
假设有多个 MCP 服务器:
|
||
|
||
```
|
||
- xiaohongshu__public_content (发布小红书)
|
||
- weibo__post_status (发布微博)
|
||
- notion__create_page (创建 Notion 页面)
|
||
```
|
||
|
||
```
|
||
用户: 帮我把这篇文章同时发到小红书和微博
|
||
|
||
AI 处理:
|
||
1. 理解需要两个工具
|
||
2. 为小红书创作合适格式的内容
|
||
3. 为微博创作合适格式的内容（字数限制）
|
||
4. 依次调用两个工具
|
||
5. 返回两个平台的发布结果
|
||
```
|
||
|
||
### 场景 3: 错误处理
|
||
|
||
```
|
||
用户: 发布文章到小红书，标题是"测试"
|
||
|
||
AI 处理:
|
||
1. 识别内容不完整
|
||
2. 提示用户补充正文内容
|
||
3. 等待用户补充后再调用工具
|
||
```
|
||
|
||
## 优势总结
|
||
|
||
### 1. **智能参数生成**
|
||
- AI 自动创作内容，无需用户逐一填写参数
|
||
- 符合平台特色（小红书风格 vs 微博风格）
|
||
|
||
### 2. **工具名称隔离**
|
||
- `serverName__toolName` 避免多服务器冲突
|
||
- 清晰的工具来源
|
||
|
||
### 3. **友好的用户体验**
|
||
- 自然语言输入："帮我发布..."
|
||
- 自动处理所有技术细节
|
||
- 结果友好呈现
|
||
|
||
### 4. **可扩展性**
|
||
- 轻松添加新 MCP 服务器
|
||
- 支持任意数量和类型的工具
|
||
- System Prompt 自动生成
|
||
|
||
### 5. **多轮对话支持**
|
||
- 工具结果自动传回 AI
|
||
- 可以追问、修改、重试
|
||
|
||
## 对比 Cherry Studio
|
||
|
||
| 特性 | mcp-client-vue | Cherry Studio |
|
||
|------|---------------|---------------|
|
||
| 工具名称格式 | ✅ `serverName__toolName` | ✅ `serverName__toolName` |
|
||
| System Prompt | ✅ 自动生成 | ✅ 自动生成 |
|
||
| 参数自动注入 | ✅ AI 生成 | ✅ AI 生成 |
|
||
| 多轮对话 | ✅ 完整支持 | ✅ 完整支持 |
|
||
| 流式响应 | ✅ SSE 真流式 | ✅ 真流式 |
|
||
| 错误处理 | ✅ 完善 | ✅ 完善 |
|
||
| UI 界面 | Vue 3 + Naive UI | Electron + React |
|
||
|
||
## 下一步优化
|
||
|
||
1. **批量工具调用**: 同时调用多个工具
|
||
2. **工具调用历史**: 记录和展示工具调用日志
|
||
3. **工具执行超时**: 防止长时间阻塞
|
||
4. **工具权限控制**: 敏感操作需要用户确认
|
||
5. **工具调用缓存**: 避免重复调用
|
||
|
||
## 相关文件
|
||
|
||
- `/web/src/services/chatService.ts` - 核心服务
|
||
- `/web/src/services/modelServiceManager.ts` - 模型管理
|
||
- `/web/src/services/MCPClientService.ts` - MCP 客户端
|
||
- `/web/src/components/Chat/ChatLayout.vue` - UI 组件
|
||
|
||
---
|
||
|
||
**版本**: v1.0.2+
|
||
**更新时间**: 2024-01
|
||
**作者**: MCP Client Vue Team
|