vf_react/docs/MCP_ARCHITECTURE.md

MCP 架构说明

🎯 MCP 是什么？

MCP (Model Context Protocol) 是一个工具调用协议，它的核心职责是：

1. ✅ 定义工具接口：告诉 LLM 有哪些工具可用，每个工具需要什么参数
2. ✅ 执行工具调用：根据请求调用对应的后端 API
3. ✅ 返回结构化数据：将 API 结果返回给调用方

MCP 不负责：

• ❌ 自然语言理解（NLU）
• ❌ 意图识别
• ❌ 结果总结
• ❌ 对话管理

📊 当前架构

方案 1：简单关键词匹配（已实现）

用户输入："查询贵州茅台的股票信息"
    ↓
前端 ChatInterface (关键词匹配)
    ↓
MCP 工具层 (search_china_news)
    ↓
返回 JSON 数据
    ↓
前端显示原始数据

问题：

• ✗ 只能识别简单关键词
• ✗ 无法理解复杂意图
• ✗ 返回的是原始 JSON，用户体验差

方案 2：集成 LLM（推荐）

用户输入："查询贵州茅台的股票信息"
    ↓
LLM (Claude/GPT-4/通义千问)
    ↓ 理解意图：需要查询股票代码 600519 的基本信息
    ↓ 选择工具：get_stock_basic_info
    ↓ 提取参数：{"seccode": "600519"}
MCP 工具层
    ↓ 调用 API，获取数据
返回结构化数据
    ↓
LLM 总结结果
    ↓ "贵州茅台（600519）是中国知名的白酒生产企业，
       当前股价 1650.00 元，市值 2.07 万亿..."
前端显示自然语言回复

优势：

• ✓ 理解复杂意图
• ✓ 自动选择合适的工具
• ✓ 自然语言总结，用户体验好
• ✓ 支持多轮对话

🔧 实现方案

选项 A：前端集成 LLM（快速实现）

适用场景：快速原型、小规模应用

优点：

• 实现简单
• 无需修改后端

缺点：

• API Key 暴露在前端（安全风险）
• 每个用户都消耗 API 额度
• 无法统一管理和监控

实现步骤：

1. 修改 src/components/ChatBot/ChatInterface.js：

import { llmService } from '../../services/llmService';

const handleSendMessage = async () => {
  // ...

  // 使用 LLM 服务替代简单的 mcpService.chat
  const response = await llmService.chat(inputValue, messages);

  // ...
};

2. 配置 API Key（在 .env.local）：

REACT_APP_OPENAI_API_KEY=sk-xxx...
# 或者使用通义千问（更便宜）
REACT_APP_DASHSCOPE_API_KEY=sk-xxx...

选项 B：后端集成 LLM（生产推荐）⭐

适用场景：生产环境、需要安全和性能

优点：

• ✓ API Key 安全（不暴露给前端）
• ✓ 统一管理和监控
• ✓ 可以做缓存优化
• ✓ 可以做速率限制

缺点：

• 需要修改后端
• 增加服务器成本

实现步骤：

1. 安装依赖

pip install openai

2. 修改 mcp_server.py，添加聊天端点

在文件末尾添加：

from mcp_chat_endpoint import MCPChatAssistant, ChatRequest, ChatResponse

# 创建聊天助手实例
chat_assistant = MCPChatAssistant(provider="qwen")  # 推荐使用通义千问

@app.post("/chat", response_model=ChatResponse)
async def chat_endpoint(request: ChatRequest):
    """智能对话端点 - 使用LLM理解意图并调用工具"""
    logger.info(f"Chat request: {request.message}")

    # 获取可用工具列表
    tools = [tool.dict() for tool in TOOLS]

    # 调用聊天助手
    response = await chat_assistant.chat(
        user_message=request.message,
        conversation_history=request.conversation_history,
        tools=tools,
    )

    return response

3. 配置环境变量

在服务器上设置：

# 方式1：使用通义千问（推荐，价格便宜）
export DASHSCOPE_API_KEY="sk-xxx..."

# 方式2：使用 OpenAI
export OPENAI_API_KEY="sk-xxx..."

# 方式3：使用 DeepSeek（最便宜）
export DEEPSEEK_API_KEY="sk-xxx..."

4. 修改前端 mcpService.js

/**
 * 智能对话 - 使用后端LLM处理
 */
async chat(userMessage, conversationHistory = []) {
  try {
    const response = await this.client.post('/chat', {
      message: userMessage,
      conversation_history: conversationHistory,
    });

    return {
      success: true,
      data: response,
    };
  } catch (error) {
    return {
      success: false,
      error: error.message || '对话处理失败',
    };
  }
}

5. 修改前端 ChatInterface.js

const handleSendMessage = async () => {
  // ...

  try {
    // 调用后端聊天API
    const response = await mcpService.chat(inputValue, messages);

    if (response.success) {
      const botMessage = {
        id: Date.now() + 1,
        content: response.data.message,  // LLM总结的自然语言
        isUser: false,
        type: 'text',
        timestamp: new Date().toISOString(),
        toolUsed: response.data.tool_used,  // 可选：显示使用了哪个工具
        rawData: response.data.raw_data,    // 可选：原始数据（折叠显示）
      };
      setMessages((prev) => [...prev, botMessage]);
    }
  } catch (error) {
    // ...
  }
};

💰 LLM 选择和成本

推荐：通义千问（阿里云）

优点：

• 价格便宜（1000次对话约 ¥1-2）
• 中文理解能力强
• 国内访问稳定

价格：

• qwen-plus: ¥0.004/1000 tokens（约 ¥0.001/次对话）
• qwen-turbo: ¥0.002/1000 tokens（更便宜）

获取 API Key：

1. 访问 https://dashscope.console.aliyun.com/
2. 创建 API Key
3. 设置环境变量 DASHSCOPE_API_KEY

其他选择

提供商	模型	价格	优点	缺点
通义千问	qwen-plus	¥0.001/次	便宜、中文好	-
DeepSeek	deepseek-chat	¥0.0005/次	最便宜	新公司
OpenAI	gpt-4o-mini	$0.15/1M tokens	能力强	贵、需翻墙
Claude	claude-3-haiku	$0.25/1M tokens	理解力强	贵、需翻墙

🚀 部署步骤

1. 后端部署

# 安装依赖
pip install openai

# 设置 API Key
export DASHSCOPE_API_KEY="sk-xxx..."

# 重启服务
sudo systemctl restart mcp-server

# 测试聊天端点
curl -X POST https://valuefrontier.cn/mcp/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "查询贵州茅台的股票信息"}'

2. 前端部署

# 构建
npm run build

# 部署
scp -r build/* user@server:/var/www/valuefrontier.cn/

3. 验证

访问 https://valuefrontier.cn/agent-chat，测试对话：

测试用例：

1. "查询贵州茅台的股票信息" → 应返回自然语言总结
2. "今日涨停的股票有哪些" → 应返回涨停股票列表并总结
3. "新能源概念板块表现如何" → 应搜索概念并分析

📊 对比总结

特性	简单匹配	前端LLM	后端LLM ⭐
实现难度	简单	中等	中等
用户体验	差	好	好
安全性	高	低	高
成本	无	用户承担	服务器承担
可维护性	差	中	好
推荐指数	⭐	⭐⭐	⭐⭐⭐⭐⭐

🎯 最终推荐

生产环境：后端集成 LLM (方案 B)

• 使用通义千问（qwen-plus）
• 成本低（约 ¥50/月，10000次对话）
• 安全可靠

快速原型：前端集成 LLM (方案 A)

• 适合演示
• 快速验证可行性
• 后续再迁移到后端