# McpAPI到MCP工具转换功能 - 实现任务列表

## 任务概述

本任务列表基于需求文档和设计文档，提供了一系列具体的编码任务来实现McpAPI到MCP工具转换功能。每个任务都是渐进式的，确保功能逐步构建并可以及时验证。

## 实现任务

### 1. 创建McpAPI文件加载器组件

- [x] 1.1 创建`src/mcp_server_tke/mcpapi_loader.py`文件，实现基础的McpAPILoader类
  - 实现`__init__`方法，设置mcpapi目录路径
  - 实现`load_mcpapi_files`方法框架，返回空字典
  - 添加基础的日志记录和错误处理
  - 满足需求1.1：系统在服务启动时自动扫描`./mcpapi/`目录

- [x] 1.2 实现YAML文件解析功能
  - 实现`_parse_yaml_file`方法，支持基本的YAML解析
  - 添加文件读取和基本的字符串处理逻辑
  - 处理文件不存在、权限错误等异常情况
  - 满足需求1.2：解析符合项目自定义格式的McpAPI YAML文件

- [x] 1.3 完善文件扫描和批量加载逻辑
  - 在`load_mcpapi_files`中实现目录扫描，支持.yaml和.yml文件
  - 调用`_parse_yaml_file`处理每个文件
  - 实现错误处理：忽略格式错误文件并记录警告日志
  - 满足需求1.3和1.4：忽略错误文件并提供有意义的错误信息

### 2. 创建动态工具处理器组件

- [x] 2.1 创建`src/mcp_server_tke/dynamic_tool_handler.py`文件，实现DynamicToolHandler类基础结构
  - 实现`__init__`方法，接收和存储mcpapi数据
  - 添加必要的导入语句（mcp.types, typing等）
  - 实现`generate_mcp_tools`方法框架，返回空列表
  - 满足需求2.1：将McpAPI文件中的tools.name转换为MCP工具名称

- [x] 2.2 实现MCP工具转换逻辑
  - 实现`_convert_to_mcp_tool`方法，处理单个工具规范转换
  - 处理工具名称和描述的直接映射
  - 实现基础的inputSchema生成框架
  - 满足需求2.1和2.2：转换工具名称和描述

- [x] 2.3 实现输入Schema生成功能
  - 实现`_build_input_schema`方法，处理参数类型转换
  - 支持string、integer、boolean、object、array类型映射
  - 处理必填参数收集和默认值设置
  - 满足需求2.3：转换args为inputSchema，包括类型映射和必填参数

- [x] 2.4 完善Schema生成，支持嵌套对象
  - 在`_build_input_schema`中添加嵌套object属性处理
  - 实现递归处理properties的逻辑
  - 确保生成符合JSON Schema规范的定义
  - 满足需求2.3和2.4：处理嵌套对象属性和JSON Schema规范

- [x] 2.5 实现动态工具调用处理功能
  - 实现`handle_tool_call`方法，接收工具名称和参数
  - 添加参数验证逻辑，根据工具规范验证输入参数
  - 实现基础的API请求构建和调用框架
  - 满足需求4.2和4.3：调用通用处理函数并返回标准响应格式

### 3. 集成动态工具到服务器

- [x] 3.1 修改`src/mcp_server_tke/server.py`，添加动态工具支持的初始化代码
  - 在模块级别导入McpAPILoader和DynamicToolHandler
  - 添加全局变量存储动态工具处理器实例
  - 在模块初始化时加载McpAPI文件并创建处理器
  - 满足需求3.1：返回现有静态工具加上动态生成工具的完整列表

- [x] 3.2 修改`handle_list_tools`函数以包含动态工具
  - 获取现有的静态工具列表（保持不变）
  - 调用动态工具处理器的`generate_mcp_tools`方法
  - 将静态工具和动态工具合并返回
  - 满足需求3.2和3.3：保持现有工具不变，动态工具追加到后面

- [x] 3.3 修改`handle_call_tool`函数以支持动态工具调用
  - 在现有的静态工具处理逻辑后添加动态工具检查
  - 如果工具名称不是静态工具，调用动态工具处理器的`handle_tool_call`方法
  - 保持现有静态工具的调用逻辑完全不变
  - 满足需求4.1和4.4：识别动态工具调用并保持静态工具逻辑不变

### 4. 添加错误处理和日志记录

- [x] 4.1 完善McpAPILoader的错误处理和日志
  - 在文件加载过程中添加INFO级别日志，记录成功加载的文件
  - 添加WARNING级别日志，记录文件解析失败的情况
  - 处理目录不存在的情况，返回空结果而不抛出异常
  - 满足需求5.1和5.3：记录文件加载过程和解析错误

- [x] 4.2 完善DynamicToolHandler的错误处理和日志
  - 在工具生成过程中添加INFO级别日志，记录生成的工具数量
  - 在工具调用过程中添加详细日志，包括工具名称和参数
  - 添加参数验证失败的友好错误消息
  - 满足需求5.2和5.4：记录工具生成和调用过程

- [x] 4.3 实现统一的错误处理机制
  - 在动态工具调用中复用现有的TKE错误处理机制
  - 确保API调用失败时使用现有的异常处理逻辑
  - 避免在错误消息中暴露内部实现细节
  - 满足需求4.5和5.5：统一错误处理和友好错误消息

### 5. 创建测试用例

- [x] 5.1 创建测试数据文件
  - 在`tests/fixtures/`目录下创建`valid_mcpapi.yaml`测试文件
  - 创建`invalid_format.yaml`用于测试错误处理
  - 创建`complex_mcpapi.yaml`测试复杂参数类型
  - 满足需求6.6：使用模拟数据进行测试

- [x] 5.2 为McpAPILoader编写单元测试
  - 在`tests/test_tool_tke.py`中添加McpAPILoader的测试用例
  - 测试正常文件加载、目录不存在、文件格式错误等场景
  - 使用unittest.mock模拟文件系统操作
  - 满足需求6.1：测试McpAPI文件加载

- [x] 5.3 为DynamicToolHandler编写单元测试  
  - 添加工具生成正确性的测试，验证schema转换
  - 测试参数类型处理、必填参数收集等功能
  - 测试动态工具调用的基本流程
  - 满足需求6.2和6.4：测试工具生成和调用流程

- [x] 5.4 编写集成测试
  - 测试完整的工具列表返回（静态+动态工具）
  - 测试动态工具的端到端调用流程
  - 验证静态工具功能不受影响
  - 满足需求6.3和7.1：测试工具列表完整性和向后兼容性

- [x] 5.5 添加错误场景测试
  - 测试文件不存在、权限错误等异常情况
  - 测试参数验证失败的处理
  - 验证错误日志记录的正确性
  - 满足需求6.5：测试错误场景

### 6. 向后兼容性验证

- [x] 6.1 验证现有静态工具功能完整性
  - 运行现有的CreateCluster、DeleteCluster测试
  - 确保现有工具的API行为和响应格式不变
  - 验证无McpAPI文件时系统正常启动
  - 满足需求7.1、7.2和7.4：现有工具保持不变

- [x] 6.2 测试系统在无McpAPI文件情况下的行为
  - 模拟mcpapi目录不存在的场景
  - 验证系统只返回静态工具列表
  - 确保服务正常启动和运行
  - 满足需求7.3和7.4：无McpAPI文件时正常运行

## 完成标准

- 所有复选框任务都已完成
- 所有测试用例都通过
- 现有功能保持完全不变
- 系统能够成功加载示例McpAPI文件并转换为MCP工具
- 动态工具可以正常调用并返回预期结果
