Skip to content

CODEX.md

Latest commit

 

History

History
100 lines (71 loc) · 5.9 KB

CODEX.md

File metadata and controls

100 lines (71 loc) · 5.9 KB
Raw

Connect Codex and create your first asset

Facet Forge is a local stdio MCP server backed by a running Godot editor. It has no model backend and needs no OpenAI API key. Codex and the app must run on the same computer with access to the same extracted folder. Remote/cloud tasks cannot automatically reach your local studio.

1. Start the creator

Extract the portable release, then run Launch Facet Forge.bat. Leave that window open. For a source checkout, install Godot 4.7.2 and run godot --path /absolute/path/to/facet-forge.

Install Python 3.10 or newer. Confirm python --version works. This project requires no pip install step.

2. Register the tools

With the Codex CLI installed, replace the example path with your actual folder:

codex mcp add facet-forge -- python "C:/Tools/facet-forge/bridge/studio.py" mcp
codex mcp list

If python is not available to Codex, use its full executable path. An equivalent manually reviewed entry in your Codex configuration is:

[mcp_servers.facet-forge]
command = "C:/Python313/python.exe"
args = ["C:/Tools/facet-forge/bridge/studio.py", "mcp"]
tool_timeout_sec = 60

Use your own paths; these are examples. Reload the client if the newly registered tools do not appear. No OAuth login is needed for this local MCP server. Follow your client's tool-approval prompts; do not globally disable approvals.

This setup follows the official Codex MCP documentation. Registration is not automatic and this repository does not modify your Codex configuration.

3. Give Codex context

Open this repository as a Codex project so it can read AGENTS.md, or explicitly provide the instructions from that file. Ask:

Use Facet Forge to create a cute little vase. Inspect the current document first; preserve any existing work. Build it with structured modeling commands, show me the six-view sheet, then save the editable recipe and export a verified GLB. Read this project's AGENTS.md and tool reference before starting.

The tools are named studio_inspect, studio_capabilities, studio_apply, studio_preview, studio_pose, studio_validate, studio_save, studio_load, studio_export, studio_undo, and studio_redo. Clients may add a server prefix when displaying them.

4. Complete first-asset example

  1. Call studio_capabilities with {}.
  2. Call studio_inspect with {}. Note the returned revision R. If the document contains work, save it first and obtain permission before replacing it.
  3. Call studio_apply with the following JSON, replacing 0 with R. Use a fresh request ID for a new attempt:
{
  "request_id": "vase-first-001",
  "base_revision": 0,
  "ops": [
    {"op":"reset","name":"Seafoam Vase"},
    {"op":"create","id":"vase","spec":{
      "kind":"lathe",
      "params":{"profile":[[0,0],[0.4,0.05],[0.65,0.5],[0.3,1],[0.35,1.2]],"sides":24},
      "material":{"color":"38b9b0","roughness":0.35}
    }}
  ]
}
  1. Read the new revision S from the result. Call studio_preview with {"name":"vase_review","revision":S} (substitute the number). It returns a labeled six-view image directly to Codex, plus camera and bounds data.
  2. Actually inspect the returned image. If a surface needs closer review, request {"name":"vase_detail","revision":S,"views":["front_right_high","bottom"]}. These explicit views return individual images.
  3. Call studio_validate with {}. Warnings are not artistic approval.
  4. Call studio_save with {"name":"seafoam_vase"}.
  5. Call studio_export with {"name":"seafoam_vase","revision":S}. Confirm ok, the reimported mesh count, and any diagnostics.

The editable recipe and GLB are now in output/. To edit the vase later, call studio_load with its name and the current base_revision.

Animation review

Load the bundled robot through the demo button or studio_load with name:"hard_observatory" and the current base revision. Inspect its clip names, then request studio_pose with the current revision, clip:"Stargazing", and time:0, 1, 2, or 3. Capture after each pose. Named cameras keep rest-pose framing stable across timestamps. The sidebar also provides a play/pause button and timeline.

CLI fallback and reproducible examples

From the project folder, with the app running:

python bridge/studio.py capabilities
python bridge/studio.py inspect
python scripts/build_example.py easy_mushroom

The example builder intentionally replaces the active document, then validates, saves, exports and captures it. Save your work first. It supports easy_mushroom, medium_teapot, and hard_observatory and uses exactly the public tools available through MCP.

Troubleshooting

Symptom What to check
Session file missing / connection refused Start the Godot app from this exact folder; do not point the bridge at another copy.
Unknown MCP tools Verify codex mcp list, the full Python/script paths, and reload the client.
STALE_REVISION Inspect again and reconcile the edit. Never blindly reset.
REQUEST_ID_REUSED Same ID with a different payload is rejected. A new logical edit needs a new ID.
Timeout after an apply Retry with exactly the same request ID and payload to recover the receipt.
BUSY A capture is in progress; retry once it finishes.
Black/empty render Use a graphical desktop and supported GPU driver; headless mode is for geometry tests, not preview captures.
Tool can return data but agent cannot see images Use an image-capable MCP client, or inspect returned PNG paths through the client's local image tool.
Model is static Only recipes with clips animate. Mushroom/teapot examples are static.

Never paste .runtime/session.json into a chat or issue. It contains a credential. Rendered images and structured scene data sent through MCP become inputs to your chosen assistant; review that assistant's privacy settings separately.