8.0 KiB

Raw Blame History

MCP (Model Context Protocol) 实现文档

概述

本文档介绍了在youfool-devops-gd系统中实现的真正的MCP (Model Context Protocol) 版本。与原有的硬编码数据库查询不同，MCP版本允许LLM动态调用工具来获取数据，提供更灵活和可扩展的AI回答服务。

架构对比

原有流程（硬编码版本）

用户请求 → AIAnswerController → AIAnswerService.generateAnswer() → 
直接数据库查询 (repair表、repair_handle表、ai_knowledge_base表) → 
构建预处理的prompt → qwenChatService.chatCompletion() → 返回AI回答

MCP流程（动态工具调用版本）

用户请求 → AIAnswerMCPController → AIAnswerServiceMCP.generateAnswerWithMCP() → 
QwenChatService.chatCompletionWithMCP() → 
LLM动态调用MCP工具 (repair_query, repair_feedback_query, similarity_search) → 
MCPServer.executeTool() → 返回AI回答 + 工具使用记录

核心组件

1. MCPServer

位置: com.chinaweal.youfool.devops.ai.mcp.MCPServer
功能: 提供MCP工具的注册、管理和执行
支持的工具:
- repair_query: 根据工单ID查询工单详细信息
- repair_feedback_query: 查询工单的feedback步骤处理结果
- similarity_search: 基于文本内容进行向量相似度检索
- knowledge_query: 在知识库中精确匹配记录

2. AIAnswerServiceMCP

位置: com.chinaweal.youfool.devops.ai.service.AIAnswerServiceMCP
功能: 提供基于MCP的AI回答生成服务
特点:
- 支持动态工具调用
- 包含完整的错误处理和降级机制
- 提供流式和非流式两种模式

3. QwenChatService（扩展）

功能扩展: 增加了MCP工具调用支持
新方法:
- chatCompletionWithMCP(): 支持MCP的聊天完成
- streamChatCompletionWithMCP(): 支持MCP的流式聊天完成
- processMCPToolCalls(): 处理MCP工具调用逻辑

4. AIAnswerMCPController

位置: com.chinaweal.youfool.devops.ai.controller.AIAnswerMCPController
功能: 提供MCP版本的REST API接口
端点:
- GET /api/ai/mcp/tools: 获取可用的MCP工具列表
- POST /api/ai/mcp/answer: 生成AI回答(MCP版本)
- POST /api/ai/mcp/answer/stream: 生成AI回答流式输出(MCP版本)
- POST /api/ai/mcp/compare: 比较MCP版本与原版本结果
- GET /api/ai/mcp/test/{toolName}: 测试MCP工具调用

配置说明

在 application.yml 中添加了以下MCP配置：

ai:
  mcp:
    enabled: true                      # 是否启用MCP服务
    server-name: youfool-devops-mcp    # MCP服务器名称
    version: 1.0.0                     # MCP版本
    tool-timeout: 30000                # 工具执行超时时间（毫秒）
    log-tool-calls: true               # 是否记录工具调用日志
    cache:
      enabled: true                    # 工具调用结果缓存
      ttl: 300000                      # 5分钟缓存
    tools:
      repair-query:
        enabled: true
        description: "查询工单详细信息"
      repair-feedback-query:
        enabled: true
        description: "查询工单feedback处理结果"
      similarity-search:
        enabled: true
        description: "基于文本相似度搜索"
        default-top-k: 5
        default-threshold: 0.7
      knowledge-query:
        enabled: true
        description: "知识库精确查询"

工具详细说明

1. repair_query

功能: 根据工单ID查询工单详细信息
输入参数:
- repairId (string): 工单ID
返回数据: 工单基本信息（ID、标题、业务模块、问题类型、优先级、故障描述等）

2. repair_feedback_query

功能: 查询工单的feedback步骤处理结果
输入参数:
- repairId (string): 工单ID
返回数据: feedback记录列表，包括处理结果、处理人、处理时间等

3. similarity_search

功能: 基于文本内容进行向量相似度检索
输入参数:
- queryText (string): 查询文本
- topK (integer, 可选): 返回前K个结果，默认5
- threshold (number, 可选): 相似度阈值，默认0.7
返回数据: 相似工单列表，包括相似度分数、解决方案等

4. knowledge_query

功能: 在知识库中精确匹配记录
输入参数:
- kbId (string, 可选): 知识库ID
- sourceRepairId (string, 可选): 源工单ID
返回数据: 匹配的知识库记录

使用示例

1. 获取可用工具

GET /api/ai/mcp/tools

2. 生成MCP版本AI回答

POST /api/ai/mcp/answer
Content-Type: application/json

{
  "repairId": "R12345",
  "sessionId": "session-123",
  "language": "Chinese",
  "answerStyle": "professional",
  "includeSimilarCases": true,
  "includeHistory": true
}

3. 测试特定工具

GET /api/ai/mcp/test/repair_query?repairId=R12345
GET /api/ai/mcp/test/similarity_search?queryText=数据库连接失败

工作流程

MCP工具调用流程

请求分析: 系统分析用户请求，提取工单ID
工单查询: 调用 repair_query 获取工单基本信息
反馈查询: 调用 repair_feedback_query 获取处理反馈
相似度检索: 如果没有meaningful feedback，调用 similarity_search 查找相似案例
结果整合: 将所有工具调用结果整合到LLM prompt中
AI生成: LLM基于整合后的信息生成回答

处理优先级

最高优先级: feedback处理结果（经过验证的解决方案）
中等优先级: 相似案例的解决方案
最低优先级: 通用建议和指导

优势对比

MCP版本优势

动态性: LLM可以根据需要动态调用不同工具
可扩展性: 易于添加新的工具和功能
透明性: 记录了具体使用了哪些工具
一致性: 确保与原版本获得相同的数据源
可维护性: 工具调用逻辑独立，便于测试和维护

原版本问题

硬编码: 数据查询逻辑固化在代码中
不灵活: 无法根据具体需求调整查询策略
难扩展: 添加新数据源需要修改核心代码
不透明: 无法了解具体使用了哪些数据源

一致性保证

MCP版本通过以下措施确保与原版本结果的一致性：

相同数据源: 使用完全相同的数据库表和查询逻辑
相同算法: 向量相似度计算使用相同的算法
相同优先级: 保持feedback > 相似案例 > 通用建议的优先级
质量对比: 提供比较接口可以验证两个版本的结果差异

监控和调试

日志记录

所有MCP工具调用都有详细的日志记录
包括调用参数、返回结果、执行时间等信息

性能监控

记录每个工具的执行时间
统计工具调用成功率
监控整体处理时间

测试接口

提供独立的工具测试接口
支持对比测试原版本和MCP版本的结果

部署说明

配置启用: 在 application.yml 中设置 ai.mcp.enabled: true
依赖检查: 确保所有MCP相关的Bean都能正常注入
功能验证: 使用测试接口验证各个工具的功能
对比测试: 使用对比接口验证结果一致性

注意事项

条件启用: MCP服务需要通过配置启用，默认情况下与原版本共存
API隔离: MCP版本使用独立的API端点，不影响原有功能
降级机制: 如果MCP工具调用失败，会降级到原始请求处理
性能考虑: MCP版本由于增加了工具调用，处理时间可能略长

未来扩展

更多工具: 可以轻松添加新的MCP工具
缓存优化: 可以添加更智能的缓存策略
工具链: 支持工具之间的依赖和链式调用
自适应: 根据历史表现自动选择最佳工具组合

这个MCP实现为youfool-devops-gd系统提供了一个现代化、可扩展的AI回答服务架构，既保证了与原有流程的一致性，又为未来的功能扩展奠定了基础。

8.0 KiB Raw Blame History Unescape Escape