Maya MCP Server

# Project Organization & Architecture ## Code Organization ### Source Code (`src/`) - **`server.py`**: Main entry point with CLI argument parsing, logging setup, and async main loop - **`mcp_server.py`**: Core MCP protocol implementation with message routing and tool execution - **`maya_bridge.py`**: Communication layer handling Maya command port connections and command execution - **`models.py`**: Data models, tool definitions, and validation logic using dataclasses and Pydantic - **`config.py`**: Configuration management with YAML/JSON file loading and environment variable support ### Maya Integration (`plug-ins/`) - **`mayamcp.py`**: Maya plugin that auto-loads and opens command port (port 7022) for external communication ### Testing (`tests/`) - **`test_project_structure.py`**: Validates package imports and basic configuration - **`test_server_properties.py`**: Tests server functionality and properties - **`test_tool_discovery.py`**: Tests MCP tool discovery and validation - **`conftest.py`**: Pytest configuration and shared fixtures ## Architecture Patterns ### Async/Await Pattern - All server operations use asyncio for non-blocking I/O - Maya bridge uses async socket connections - Message processing is fully asynchronous ### Dataclass Models - Use `@dataclass` for all data structures (MayaRequest, MayaResponse, etc.) - Include `__post_init__` methods for validation and default initialization - Type hints are mandatory for all model fields ### Configuration Hierarchy 1. Default values in ServerConfig dataclass 2. YAML/JSON configuration files 3. Environment variables (prefix: `MAYA_MCP_`) 4. Command line arguments (highest priority) ### Tool Definition Pattern ```python MayaTool( name="tool_name", description="Clear description", input_schema={ "type": "object", "properties": {...}, "required": [...] } ) ``` ### Error Handling - Use structured error responses with MayaResponse dataclass - Include request_id for tracing - Log errors with appropriate levels (DEBUG, INFO, WARNING, ERROR) - Graceful degradation when Maya is not available ## Security Conventions ### Command Validation - Maintain `allowed_commands` and `blocked_commands` lists in config - Block dangerous operations: `file`, `system`, `eval`, `exec`, `import` - Validate all tool inputs against JSON schemas ### Safe Execution - Use command port isolation for Maya communication - Implement timeout mechanisms for all Maya operations - Sanitize user input before sending to Maya ## Naming Conventions ### Files & Modules - Snake_case for Python files: `maya_bridge.py`, `mcp_server.py` - Clear, descriptive names indicating purpose ### Classes & Functions - PascalCase for classes: `MayaBridge`, `MayaMCPServer` - Snake_case for functions: `execute_command`, `load_config` - Prefix private methods with underscore: `_handle_create_object` ### Tools & Commands - Prefix Maya tools with `maya_`: `maya_create`, `maya_select` - Use descriptive verbs: `create`, `select`, `execute`, `get_selection` ## Logging Strategy ### Logger Hierarchy - Root logger: `maya-mcp-server` - Component loggers: `maya-mcp-server.mcp`, `maya-mcp-server.bridge` - Plugin logger: `maya-mcp-plugin` ### Log Levels - **DEBUG**: Detailed execution flow, message contents - **INFO**: Server lifecycle, connection status, tool execution - **WARNING**: Recoverable errors, Maya connection issues - **ERROR**: Unrecoverable errors, tool execution failures ## Testing Patterns ### Test Organization - One test file per source module - Use descriptive test function names: `test_maya_tools_definition` - Group related tests in classes when appropriate ### Test Data - Use fixtures for common test data in `conftest.py` - Mock Maya connections for unit tests - Test both success and failure scenarios