Maya MCP Plan

Goal: create a local Maya bridge that lets Codex/ChatGPT inspect, analyze, and assist with SystemLink weapon meshes through safe, whitelisted Maya commands.

This is not meant to replace Maya as the art tool. It is meant to make Maya scriptable from the AI workflow so mesh analysis, socket placement, blockout generation, and export checks become faster and more repeatable.

---

#V1 Deliverable

Build a small local toolchain:

• Tools/MayaMCP/maya_listener.py - loaded inside Maya

• Tools/MayaMCP/server.py - MCP server run from the project workspace

• Tools/MayaMCP/README.md - install, run, and usage notes

V1 should support:

• Import FBX

• Analyze current Maya scene

• Analyze selected objects

• Report mesh stats and hierarchy

• Report joints/skeletons

• Create SystemLink weapon socket locators

• Export FBX to an explicit workspace path

V2 can add:

• Parametric weapon blockout generation

• Existing FBX proportion learning

• Cleanup/validation helpers

• Shelf-button UI inside Maya

• More advanced material and UV reporting

---

#Architecture

Use a two-part local bridge.

#Maya Side

maya_listener.py runs inside Maya and listens on localhost only. It receives JSON requests and executes whitelisted commands through maya.cmds.

The listener should avoid generic eval or arbitrary Python execution in V1.

Example request:

{

  "command": "analyze_scene",

  "args": {}

}

Example response:

{

  "ok": true,

  "result": {

    "meshes": [],

    "joints": [],

    "materials": [],

    "warnings": []

  }

}

#MCP Side

server.py exposes clean tools to AI clients:

• maya_import_fbx

• maya_export_fbx

• maya_analyze_scene

• maya_analyze_selected

• maya_add_systemlink_sockets

• maya_measure_selected

• maya_create_weapon_blockout (V2)

The MCP server translates tool calls into JSON requests for the Maya listener.

---

#Safety Rules

• Bind listener to 127.0.0.1 only.

• Whitelist commands.

• Restrict file paths to the SystemLink workspace.

• Require explicit output paths for export.

• Do not expose arbitrary Python execution in V1.

• Return structured errors instead of executing fallback behavior.

• Log command name, arguments, timestamp, and result status.

This is important because MCP tools can become powerful quickly. The bridge should feel useful, not spooky.

---

#V1 Commands

#import_fbx

Imports an FBX into the current Maya scene.

Inputs:

• path

• namespace optional

• clear_scene optional, default false

Checks:

• Path is inside the workspace or an approved import folder.

• File extension is .fbx.

#analyze_scene

Returns a structured report for the current scene.

Report:

• Scene units

• Mesh transforms

• Mesh shapes

• Vertex count

• Face count

• Estimated triangle count

• Bounding boxes

• Pivots

• Materials

• Joints

• Locators

• Existing socket-like objects

• Warnings

#analyze_selected

Same as analyze_scene, but limited to selected transforms.

#add_systemlink_sockets

Creates or updates standard weapon socket locators:

• MuzzleFlash

• LeftHandGrip

• LeftHandElbow

• ShellEjectSocket

Inputs:

• weapon_type

• length_cm

• Optional locator positions

Default placement can be based on bounding box proportions when explicit positions are not provided.

#export_fbx

Exports selected objects or the whole scene to FBX.

Inputs:

• path

• selection_only

• bake_animation optional, default false

Checks:

• Output path is inside the workspace.

• Extension is .fbx.

---

#SystemLink Weapon Analysis

The analyzer should flag likely issues against SystemLink weapon conventions:

• Missing MuzzleFlash

• Missing left-hand IK locator/socket

• Mesh appears much larger or smaller than expected

• Pivot is far from right-hand grip area

• No joints found for a skeletal weapon

• Very high triangle count for FP or TP target

• No material assignments

• Unexpected negative scale

• Object names are generic, such as pCube1

Reference targets from Docs/ShotgunModelingGuide.md:

• FP weapon: roughly 8,000 to 14,000 triangles

• TP weapon: roughly 2,000 to 4,000 triangles

• Pivot should be at right-hand grip

• +X should point down the barrel

• Required sockets include MuzzleFlash, LeftHandGrip, and LeftHandElbow

---

#V2 Blockout Generator

Once V1 is working, add a parametric weapon blockout generator.

Inputs:

• weapon_name

• weapon_type

• overall_length_cm

• receiver_length_cm

• barrel_length_cm

• barrel_radius_cm

• grip_angle_degrees

• pump_position_cm

• stock_style

• rail_style

• material_style

Generated Maya objects:

• receiver

• barrel

• magazine_tube

• pump

• grip

• trigger_guard

• stock

• rail

• muzzle

• Standard socket locators

The output should be a clean starting point, not final art. The win is speed, consistency, and iteration.

---

#Implementation Steps

1. Create Tools/MayaMCP/.

1. Implement the Maya listener with a minimal command whitelist.

1. Implement analyze_scene.

1. Implement analyze_selected.

1. Implement socket locator creation.

1. Implement FBX import/export wrappers.

1. Implement the MCP server tool definitions.

1. Write setup and run instructions.

1. Test with one known weapon FBX.

1. Iterate on report fields and warnings.

---

#Test Plan

Use one existing weapon FBX as a reference asset.

Test flow:

1. Start Maya.

1. Load maya_listener.py.

1. Start the MCP server.

1. Import the reference FBX.

1. Run scene analysis.

1. Create SystemLink socket locators.

1. Export FBX to a test path.

1. Verify report output is readable and useful.

1. Verify exported FBX can be imported into Unreal.

Expected result:

• AI can see mesh stats and scene structure through MCP.

• AI can point out missing SystemLink requirements.

• AI can create/update standard locators in Maya.

• Artist stays in control of modeling decisions.

---

#Recommended First Milestone

Build the analyzer and socket helper first.

That gives immediate practical value: take any FBX, inspect it, understand scale/proportions/hierarchy, and prepare it for SystemLink import. After that foundation works, the blockout generator becomes much easier to design intelligently.