youfool-devops-gd-jdk21/MCP_IMPLEMENTATION.md

# 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配置：

```yaml
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. 获取可用工具
```bash
GET /api/ai/mcp/tools
```

### 2. 生成MCP版本AI回答
```bash
POST /api/ai/mcp/answer
Content-Type: application/json

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

### 3. 测试特定工具
```bash
GET /api/ai/mcp/test/repair_query?repairId=R12345
GET /api/ai/mcp/test/similarity_search?queryText=数据库连接失败
```

## 工作流程

### MCP工具调用流程

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

### 处理优先级

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

## 优势对比

### MCP版本优势

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

### 原版本问题

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

## 一致性保证

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

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

## 监控和调试

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

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

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

## 部署说明

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

## 注意事项

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

## 未来扩展

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

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