Maya MCP Server

# Maya MCP Server 设计文档 ## 概述 Maya MCP Server 是一个实现模型上下文协议(MCP)的服务器，允许AI助手通过标准化接口连接到Autodesk Maya并执行各种3D建模、动画和渲染操作。系统采用客户端-服务器架构，包含三个主要组件： 1. **MCP Server** - 实现MCP协议的Python服务器，处理AI客户端请求 2. **Maya Plugin** - 在Maya中运行的Python插件，提供本地API接口 3. **Communication Bridge** - 连接MCP服务器和Maya插件的通信桥梁 ## 架构 ### 系统架构图 ```mermaid graph TB AI[AI Assistant/Client] --> MCP[MCP Server] MCP --> Bridge[Communication Bridge] Bridge --> Plugin[Maya Plugin] Plugin --> Maya[Maya Application] subgraph "MCP Server Process" MCP Bridge end subgraph "Maya Process" Plugin Maya end ``` ### 通信流程 ```mermaid sequenceDiagram participant AI as AI Client participant MCP as MCP Server participant Bridge as Comm Bridge participant Plugin as Maya Plugin participant Maya as Maya App AI->>MCP: MCP Request (create_cube) MCP->>Bridge: Parse & Validate Bridge->>Plugin: HTTP/Socket Request Plugin->>Maya: maya.cmds.polyCube() Maya-->>Plugin: Result Plugin-->>Bridge: Response Bridge-->>MCP: Formatted Response MCP-->>AI: MCP Response ``` ## 组件和接口 ### 1. MCP Server 组件 **职责:** - 实现MCP协议规范 - 处理工具发现和执行请求 - 管理与AI客户端的连接 - 验证和路由命令到Maya **主要接口:** ```python class MayaMCPServer: async def list_tools() -> List[Tool] async def call_tool(name: str, arguments: dict) -> ToolResult async def get_server_info() -> ServerInfo ``` ### 2. Maya Plugin 组件 **职责:** - 在Maya启动时自动加载 - 提供HTTP/Socket服务器接口 - 执行Maya Python API命令 - 管理场景状态和对象操作 **主要接口:** ```python class MayaMCPPlugin: def initialize_server(self, port: int) def execute_command(self, command: str, args: dict) -> dict def get_scene_info() -> dict def handle_shutdown(self) ``` ### 3. Communication Bridge **职责:** - 管理MCP服务器与Maya插件之间的通信 - 处理连接重试和错误恢复 - 序列化/反序列化数据 **通信协议:** - 使用HTTP REST API或WebSocket连接 - JSON格式数据交换 - 支持异步操作和回调 ## 数据模型 ### MCP工具定义 ```python @dataclass class MayaTool: name: str description: str input_schema: dict # 示例工具 MAYA_TOOLS = [ MayaTool( name="maya_create", description="Create Maya objects (cube, sphere, etc.)", input_schema={ "type": "object", "properties": { "object_type": {"type": "string", "enum": ["polyCube", "sphere"]}, "name": {"type": "string"} }, "required": ["object_type"] } ), MayaTool( name="maya_select", description="Select Maya objects by name", input_schema={ "type": "object", "properties": { "objects": {"type": "array", "items": {"type": "string"}} }, "required": ["objects"] } ), MayaTool( name="maya_execute", description="Execute arbitrary Maya Python command", input_schema={ "type": "object", "properties": { "command": {"type": "string"} }, "required": ["command"] } ) ] ``` ### Maya场景数据模型 ```python @dataclass class MayaObject: name: str type: str transform: dict # position, rotation, scale attributes: dict @dataclass class SceneInfo: selected_objects: List[str] all_objects: List[MayaObject] current_time: float scene_name: str ``` ### 通信消息格式 ```python @dataclass class MayaRequest: command: str arguments: dict request_id: str @dataclass class MayaResponse: success: bool result: Any error: Optional[str] request_id: str ``` ## 正确性属性 *属性是一个特征或行为，应该在系统的所有有效执行中保持为真——本质上是关于系统应该做什么的正式声明。属性作为人类可读规范和机器可验证正确性保证之间的桥梁。* **属性 1: 服务器启动后端口监听** *对于任何* 有效的端口号，当MCP服务器或Maya插件启动时，应该在指定端口上成功监听连接 **验证需求: 1.2, 2.2** **属性 2: 配置参数应用** *对于任何* 有效的配置参数集，服务器启动时应该正确读取并应用所有配置设置，包括支持热重载 **验证需求: 1.5, 6.1, 6.2** **属性 3: 资源清理一致性** *对于任何* 运行中的服务器或插件，当关闭时应该正确清理所有资源和连接 **验证需求: 2.4** **属性 4: Maya对象操作一致性** *对于任何* 有效的Maya对象操作（创建、选择、变换、删除），操作应该成功执行并返回正确的结果状态 **验证需求: 3.1, 3.2, 3.3, 3.5** **属性 5: 场景查询完整性** *对于任何* 场景查询请求，返回的信息应该准确反映当前Maya场景的实际状态 **验证需求: 4.1, 4.2, 4.3** **属性 6: 错误信息质量** *对于任何* 失败的操作或无效的命令，系统应该返回详细且有用的错误信息 **验证需求: 5.2, 5.5** **属性 7: 日志记录完整性** *对于任何* 系统操作，应该在日志中记录相应的操作信息和状态变化 **验证需求: 1.4, 6.3** **属性 8: 状态查询准确性** *对于任何* 状态查询请求，返回的服务器健康状态和连接信息应该准确反映实际状态 **验证需求: 6.4** **属性 9: Python代码执行安全性** *对于任何* 有效的Python代码，系统应该在Maya环境中安全执行并返回正确的结果，同时拒绝危险操作 **验证需求: 7.1, 7.2, 7.5** **属性 10: 动态脚本管理** *对于任何* 项目脚本或模块，系统应该支持动态导入、热重载和错误报告 **验证需求: 8.1, 8.2, 8.4** **属性 11: 调试信息详细性** *对于任何* 调试请求，系统应该提供详细的执行信息、变量状态和调试输出 **验证需求: 8.3, 6.5** **属性 12: 测试执行准确性** *对于任何* 模块测试请求，系统应该正确执行测试函数并返回准确的测试结果 **验证需求: 8.5** **属性 13: 安装部署一致性** *对于任何* 标准MCP安装流程，Maya MCP Server应该正确部署并支持版本管理 **验证需求: 9.3, 9.4** ## 错误处理 ### 错误分类和处理策略 **1. 连接错误** - Maya未运行: 返回连接错误，建议启动Maya - 插件未加载: 检测并提示用户加载插件 - 网络中断: 自动重试连接，记录状态 **2. 命令执行错误** - 无效命令: 返回格式错误信息和正确示例 - 语法错误: 返回详细的Python语法错误信息 - 运行时错误: 返回完整的错误堆栈和行号 **3. 资源错误** - 对象不存在: 返回适当的错误信息，不中断流程 - 文件不存在: 提供文件路径建议和创建选项 - 权限错误: 返回权限问题说明和解决方案 **4. 超时和性能错误** - 代码执行超时: 终止执行并返回超时错误 - 内存不足: 提供内存使用建议 - 响应超时: 实现重试机制 ### 错误响应格式 ```python @dataclass class ErrorResponse: error_code: str error_message: str details: dict suggestions: List[str] timestamp: str ``` ## 测试策略 ### 双重测试方法 本项目采用单元测试和基于属性的测试相结合的方法： **单元测试:** - 验证特定示例和边缘情况 - 测试组件间的集成点 - 覆盖错误条件和异常处理 - 验证MCP协议实现的正确性 **基于属性的测试:** - 使用Hypothesis库进行Python属性测试 - 每个属性测试运行最少100次迭代 - 验证跨所有输入的通用属性 - 每个测试都标记对应的设计文档属性 **测试库选择:** - **单元测试**: pytest + pytest-asyncio - **属性测试**: Hypothesis - **Mock测试**: unittest.mock - **集成测试**: pytest-integration **测试标记格式:** 每个基于属性的测试必须使用以下格式标记： ```python # **Feature: maya-mcp-server, Property {number}: {property_text}** ``` ### 测试环境配置 **Maya测试环境:** - 使用Maya的mayapy解释器运行测试 - 模拟Maya场景状态进行测试 - 支持无头模式测试（不需要GUI） **MCP测试环境:** - 模拟MCP客户端连接 - 测试MCP协议消息格式 - 验证工具发现和执行流程 **集成测试:** - 端到端测试完整的AI->MCP->Maya流程 - 测试多客户端并发连接 - 验证长时间运行的稳定性 ### 持续集成 **自动化测试流程:** 1. 代码提交触发测试 2. 运行单元测试和属性测试 3. 执行集成测试 4. 生成测试覆盖率报告 5. 验证MCP协议兼容性 **测试覆盖率目标:** - 单元测试覆盖率: >90% - 属性测试覆盖率: 所有正确性属性 - 集成测试覆盖率: 所有主要用例场景