# McpAPI到MCP工具转换功能需求文档

## 功能概述

本功能旨在为TKE MCP服务器增加动态McpAPI到MCP工具转换能力。系统将保持现有工具（CreateCluster、DeleteCluster）不变，在`handle_list_tools()`函数中增加从`./mcpapi/`目录动态加载YAML文件生成的工具，并通过专门的处理函数处理McpAPI动态工具调用。

## 详细需求

### 1. McpAPI文件动态加载需求

**用户故事**: 作为TKE MCP服务器的开发者，我希望系统能够自动扫描和加载McpAPI定义文件，以便我可以通过添加YAML文件快速扩展MCP工具功能。

**验收标准**:
1. 系统应该在服务启动时自动扫描`./mcpapi/`目录下的所有`.yaml`和`.yml`文件
2. 系统应该解析符合项目自定义格式的McpAPI YAML文件（如`ModifyClusterAttribute.yaml`格式）
3. 系统应该忽略格式不正确或无法解析的YAML文件，并记录警告日志
4. 系统应该处理文件读取错误（如权限问题、文件损坏等）并提供有意义的错误信息

### 2. MCP工具定义自动生成需求

**用户故事**: 作为MCP客户端的使用者，我希望从McpAPI文件自动生成的MCP工具具有正确的schema定义，以便我能够正确地调用这些工具。

**验收标准**:
1. 系统应该将McpAPI文件中的`tools.name`转换为MCP工具名称
2. 系统应该将McpAPI文件中的`tools.description`转换为MCP工具描述
3. 系统应该将McpAPI文件中的`tools.args`转换为MCP工具的`inputSchema`，包括：
   - 参数类型映射（string、integer、boolean、object、array）
   - 必填参数标识（`required: true`）
   - 参数描述和默认值
   - 嵌套对象属性的正确处理
4. 系统应该生成符合JSON Schema规范的`inputSchema`定义
5. 系统应该为每个生成的工具分配唯一的名称，避免与现有工具冲突

### 3. 工具列表集成需求

**用户故事**: 作为MCP客户端，我希望能够通过标准的MCP协议获取所有可用的工具（包括静态定义的和动态生成的），以便我可以了解所有可用功能。

**验收标准**:
1. `handle_list_tools()`函数应该返回现有静态工具加上动态生成工具的完整列表
2. 工具列表应该保持现有的3个静态工具不变：CreateCluster、DeleteCluster
3. 动态生成的工具应该追加到静态工具列表后面
4. 所有工具应该具有相同的数据结构格式（name、description、inputSchema）
5. 系统应该确保工具名称的唯一性，如果发生冲突应该记录错误并跳过重复的工具

### 4. 统一工具调用处理需求

**用户故事**: 作为TKE MCP服务器的维护者，我希望有一个统一的机制来处理McpAPI动态生成的工具调用，以便简化代码维护和错误处理。

**验收标准**:
1. `handle_call_tool()`函数应该能够识别动态生成的工具调用
2. 对于动态工具，系统应该调用`tool_tke.handle()`或类似的通用处理函数
3. 通用处理函数应该接收工具名称、参数，并返回标准的响应格式
4. 系统应该保持现有静态工具（CreateCluster、DeleteCluster）的调用逻辑完全不变
5. 错误处理应该统一，包括参数验证、API调用失败、网络错误等情况

### 5. 错误处理和日志需求

**用户故事**: 作为系统管理员，我希望系统能够提供清晰的错误信息和日志记录，以便我可以快速诊断和解决问题。

**验收标准**:
1. 系统应该记录McpAPI文件加载过程，包括成功加载的文件数量和文件名
2. 系统应该记录工具生成过程，包括生成的工具数量和名称
3. 系统应该记录文件解析错误，包括具体的错误位置和原因
4. 系统应该为工具调用提供详细的日志，包括调用的工具名称、参数和结果
5. 错误消息应该对用户友好，避免暴露内部实现细节

### 6. 测试增强需求

**用户故事**: 作为开发者，我希望有完善的测试用例来验证McpAPI到MCP工具转换功能的正确性。

**验收标准**:
1. `tests/test_tool_tke.py`应该包含McpAPI文件加载的测试用例
2. 应该测试MCP工具定义生成的正确性，包括schema验证
3. 应该测试工具列表返回的完整性（静态+动态工具）
4. 应该测试动态工具调用的端到端流程
5. 应该包含错误场景的测试，如文件不存在、格式错误等
6. 应该使用模拟数据进行测试，避免依赖真实的McpAPI文件

### 7. 向后兼容性需求

**用户故事**: 作为现有系统的用户，我希望新功能不会破坏现有的工具使用方式。

**验收标准**:
1. 现有的CreateCluster、DeleteCluster工具应该保持完全不变
2. 现有的工具调用API应该保持相同的行为和响应格式
3. 如果`./mcpapi/`目录不存在，系统应该正常运行，只提供静态工具
4. 系统应该能够在没有McpAPI文件的情况下正常启动
5. 现有的配置和环境变量应该继续有效

## 技术约束

1. 必须使用Python 3.12+兼容的语法
2. 必须保持与现有MCP协议的兼容性
3. 必须使用现有的日志系统和错误处理机制
4. McpAPI文件格式必须遵循项目现有的自定义格式（如ModifyClusterAttribute.yaml）
5. 不能引入新的外部依赖库，除非绝对必要

## 成功标准

1. 所有需求的验收标准都得到满足
2. 系统能够成功加载和转换示例McpAPI文件
3. 代码通过现有的质量检查标准
