# max2021-mcp

Puente estable **HTTP + TCP + MCP** para ejecutar **Python** y **MaxScript** dentro de **Autodesk 3ds Max 2021**, pensado para agentes de Cursor (u otros clientes MCP).

Basado en [boa-control-max](https://github.com/franciscohermida/boa-control-max) (MIT), con parches y workflow verificados en Max **2021.3.6**.

## Arquitectura

```
Cursor (MCP stdio)
    └─ packages/max-mcp-server   →  HTTP localhost:8123
           └─ packages/max-server (Node)
                  └─ TCP 127.0.0.1:7603
                         └─ bridge Python dentro de 3ds Max (PySide2)
                                └─ ejecuta código y responde por HTTP
```

| Pieza | Puerto | Rol |
|-------|--------|-----|
| `max-server` | `8123` | API HTTP + SSE |
| Bridge en Max | `7603` | TCP (arranca con startup de Max) |
| `max-mcp-server` | stdio | Tools MCP `executePyCode` / `executeMxsCode` |

## Requisitos

- Windows + **3ds Max 2021**
- **Node.js 18+**
- **pnpm** (`npm i -g pnpm`)
- Cursor (u otro cliente MCP)

## Instalación (máquina nueva)

```powershell
git clone https://github.com/patriciojuliant/max2021-mcp.git
cd max2021-mcp
pnpm install

# 1) Registra el startup de Max (bridge TCP :7603 al abrir Max)
.\scripts\Install-MaxStartup.ps1

# 2) Escribe/actualiza ~/.cursor/mcp.json
.\scripts\Install-CursorMcp.ps1

# 3) Arranca HTTP :8123 (+ Max si hace falta)
.\scripts\Start-Max2021Mcp.ps1
```

Reiniciá Cursor después de `Install-CursorMcp.ps1`.

## Uso diario

```powershell
.\scripts\Start-Max2021Mcp.ps1
# o solo el bridge HTTP si Max ya está abierto:
.\scripts\Start-Max2021Mcp.ps1 -NoMax
```

Health check:

```powershell
.\scripts\Test-Health.ps1
```

Fallback manual en el Listener de Max:

```maxscript
fileIn @"<REPO>\packages\max-server\src\max-utils\start_max2021_mcp.ms"
```

## Tools MCP

- **`executePyCode`** — preferido. Dejá el valor en `result` (JSON-serializable).
- **`executeMxsCode`** — solo si Python no alcanza.

Ejemplo Python:

```python
import pymxs
rt = pymxs.runtime
result = {"ok": True, "version": str(rt.maxVersion())}
```

## ¿Por qué este fork?

El upstream asume `qtpy` y paths de Max más nuevos. En Max 2021:

- hay que usar **PySide2** (no `qtpy`)
- hace falta un **startup script** para el TCP `:7603`
- el HTTP `:8123` **no** vive dentro de Max; hay que levantarlo aparte
- si falta `:8123`, Cursor muestra `fetch failed` aunque Max esté abierto

Detalle de incidentes y fixes: [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

## Licencia

MIT — ver [LICENSE](LICENSE) y [NOTICE](NOTICE).