maya-mcp-server: Instructions file for Claude Code

Maya MCP Server - Developer Guide

⚠️ Critical Testing Rules

1. Prefer testing with open Maya session - Use manual test scripts in project root
2. Module updates - Always update maya_mcp module when reconnecting (module may be cached from previous sessions)

🏗️ Architecture Overview

Dedicated CommandPort Design

Two types of ports per Maya session:

1. Configuration Port (e.g., 7001): One per Maya session (PID)

   • Used only for bootstrap and discovery
   • Clients connect temporarily to create dedicated ports
   • Outside communication port range

2. Communication Ports (50000-60000): One per MCP client

   • Created during bootstrap via start_command_port()
   • Dedicated to single client for entire session
   • Automatically filtered during port scanning

Maya Session (PID 8453)
├── Configuration Port: 7001 (Python commandPort)
│   └── Used for bootstrap only - clients disconnect after setup
└── Communication Ports: 50000-60000 range
    ├── Port 50625 → MCP Client 1
    ├── Port 51234 → MCP Client 2
    └── Port 52891 → MCP Client 3

SessionManager Port Tracking

self._sessions: dict[str, MayaClient]          # "host:port" -> client (communication port)
self._config_to_session: dict[str, str]        # "host:port" -> session key (config → comm mapping)

Key insight: Don't need _probed_ports set - use _config_to_session to track which configuration ports we've already used to create sessions.

Port Constants

# src/maya_mcp_server/types.py
COMMUNICATION_PORT_MIN = 50000
COMMUNICATION_PORT_MAX = 60000

Filter these out when scanning for configuration ports in _scan_for_sessions().

🔧 Bootstrap Process

Critical Bootstrap Requirements

1. Function return values: All helper functions in maya_mcp_helper.py MUST return strings (usually JSON)
   • If function returns None, _send_receive() hangs waiting for response
   • Example: start_command_port() returns json.dumps({"success": True, "port": port})