# dcc-mcp-3dsmax - AI reference

## Start server (inside 3ds Max MAXScript Listener)

```python
import dcc_mcp_3dsmax
server = dcc_mcp_3dsmax.start_server()
# MCP URL: http://127.0.0.1:9765/mcp
dcc_mcp_3dsmax.stop_server()
```

## MCP host config

```json
{"mcpServers": {"3dsmax": {"url": "http://127.0.0.1:9765/mcp"}}}
```

## Public exports (lazy-loaded)

- `MaxMcpServer`, `MaxServerOptions`, `start_server`, `stop_server`, `get_server`, `prepare_server`
- `max_success`, `max_error`, `max_warning`, `max_from_exception`, `with_max`, `get_runtime`
- `require_param`, `require_any_param`, `get_param`, `missing_param_error`, `MissingParamError`
- `is_max_available`, `get_selection`, `clear_selection`, `select_nodes`
- `get_3dsmax_version_string`, `get_3dsmax_version_number`, `is_3dsmax_available`
- `get_3dsmax_capabilities`, `get_3dsmax_capabilities_dict`
- `DEFAULT_GATEWAY_PORT`, `DEFAULT_PORT`, `SERVER_NAME`
- `ReadinessBinder`, `MaxCapabilityManifestBuilder`, `MaxContextSnapshotProvider`
- `MaxResourceBinder`, `ProjectToolsIntegration`, `MaxSceneResolver`

## Progressive loading

```python
server.discover_skills()         # scan all paths
server.load_skill("3dsmax-scene")
server.loaded_skill_count()
```

### Stage: scene (default loaded)
- `3dsmax_scene__get_scene_info`, `list_scene_nodes`, `list_cameras`, `get_selection`, `get_bounding_box`, `get_node_visibility`, `get_scene_metadata`, `set_selection`, `duplicate_nodes`, `delete_nodes`, `group_nodes`, `parent_node`, `unparent_node`, `set_visibility`, `center_pivots`, `freeze_transforms`

### Stage: authoring (load on demand)
- `3dsmax_modeling__create_box`, `create_sphere`, `create_cylinder`, `create_plane`
- `3dsmax_geometry_io__validate_geometry_file`, `import_fbx`, `import_geometry`, `export_fbx`, `export_obj`
- `3dsmax_import_to_scene__import_to_scene`
- `3dsmax_mesh_ops__get_mesh_topology`, `get_selected_mesh_topology`, `get_smoothing_groups`, `get_modifier_stack`, `triangulate_meshes`, `cleanup_meshes`, `attach_meshes`, `detach_selected_faces`, `apply_subdivision`, `create_proxy_meshes`, `set_explicit_normals`, `clear_explicit_normals`, `assign_smoothing_group`
- `3dsmax_uv_atlas__list_uv_channels`, `create_uv_channel`, `delete_uv_channel`, `copy_uv_channel`, `get_uv_shell_summary`, `apply_uv_projection`, `unwrap_uvs`, `pack_uvs`, `detect_uv_overlaps`, `normalize_uvs`, `prepare_texture_atlas`
- `3dsmax_materials__create_standard_material`, `apply_material`, `list_scene_materials`, `list_node_material_assignments`, `inspect_material`, `list_bitmap_connections`, `create_physical_material`, `create_pbr_material`, `reset_material`, `set_material_attributes`, `assign_bitmap_texture`, `report_missing_textures`
- `3dsmax_animation__set_keyframe`, `play_animation`, `get_time_settings`, `get_animation_controllers`, `list_keyframes`, `set_current_time`, `set_timeline_settings`, `set_transform_keyframe`, `delete_keyframes`, `set_key_interpolation`, `bake_transform_animation`, `export_animation_curves`, `import_animation_curves`
- `3dsmax_rigging__create_helper_node`, `create_bone_node`, `create_joint_chain`, `create_path_helper`, `list_rig_state`, `apply_deformer_modifier`, `remove_deformer_modifier`, `set_constraint_target`, `get_character_system_availability`
- `3dsmax_render__capture_viewport`, `create_preview`, `get_render_settings`, `get_scene_render_statistics`, `set_render_output_options`, `set_frame_range`, `set_render_resolution`, `set_render_camera`, `set_render_quality_preset`
- `3dsmax_transform__set_node_position`, `move_nodes`
- `3dsmax_viewport__capture_viewport`
- `3dsmax_validation__validate_naming`, `validate_transforms`, `validate_pivots`, `validate_mesh_topology`, `validate_smoothing_groups`, `validate_material_assignments`, `validate_texture_paths`, `validate_uv_channels`, `validate_uv_overlaps`, `run_asset_readiness_checks`
- `3dsmax_display__list_layers`, `create_layer`, `delete_layer`, `assign_nodes_to_layer`, `list_node_display_state`, `set_node_display_state`, `list_custom_properties`, `get_custom_property`, `set_custom_property`, `delete_custom_property`
- `3dsmax_camera_lighting__list_cameras`, `list_lights`, `create_camera`, `set_active_camera`, `create_light`, `set_light_properties`, `create_three_point_light_rig`
- `3dsmax_scripting__execute_python`, `execute_maxscript`, `run_python_check`, `list_runtime_symbols`, `inspect_runtime_symbol`, `list_macros`, `resolve_node_reference`, `reload_adapter_module`

## Env vars (key)

| Variable | Default | Purpose |
|----------|---------|---------|
| `DCC_MCP_3DSMAX_METRICS` | `0` | Enable `/metrics` Prometheus endpoint |
| `DCC_MCP_3DSMAX_JOB_STORAGE` | platform default | SQLite job DB path |
| `DCC_MCP_3DSMAX_DISABLE_EXECUTE_PYTHON` | `0` | Disable `execute_python` |
| `DCC_MCP_3DSMAX_DISABLE_ARBITRARY_SCRIPT` | `0` | Disable all arbitrary script execution |
| `DCC_MCP_3DSMAX_ENABLE_GATEWAY_FAILOVER` | `1` | Gateway failover |
| `DCC_MCP_3DSMAX_QT_UI_INSPECTOR` | `0` | Enable Qt UI inspector tools |
| `DCC_MCP_3DSMAX_SEMANTIC_INDEX` | `0` | Enable semantic recall |
| `DCC_MCP_3DSMAX_PROJECT_TOOLS` | `1` | Enable project state tools |
| `DCC_MCP_3DSMAX_SKILL_PATHS` | None | Extra skill paths |
| `DCC_MCP_3DSMAX_READINESS_TIMEOUT_SECS` | None | Readiness probe timeout |
| `DCC_MCP_3DSMAX_RESOURCES` | `1` | Enable `scene://current` |
| `DCC_MCP_3DSMAX_BRIDGE_PORT` | random | Runtime bridge port |
| `DCC_MCP_GATEWAY_PORT` | `9765` | Gateway election port |

## Dev (Windows)

```bash
just setup                    # dev environment setup
just lint                     # ruff lint
just test-quick               # quick tests (no 3ds Max needed)
just test                     # full test suite
```

## Architecture notes

- Gateway URL: `http://127.0.0.1:9765/mcp` (stable, shared across instances)
- Main thread pump via `dcc-mcp-core` HostUiDispatcherBase + .NET timer adapter
- MZP installer creates isolated version dirs under `<user scripts>/dcc_mcp_3dsmax/versions/`
- Entry point registered: `dcc_mcp.adapters: 3dsmax = "dcc_mcp_3dsmax:MaxMcpServer"`

See `AGENTS.md`, `docs/API.md`, `docs/BUNDLED_SKILLS.md`, `docs/SIDECAR.md`.
