Isaac MCP docs revamp verified against the running Isaac Sim code

What they did

The author revamped the documentation for an Isaac Sim MCP server and, crucially, verified every claim against the running code rather than trusting the existing docs. They rewrote the home README with a live CI badge, architecture diagram, tool table and a shorter Quick Start that begins from an existing Isaac Sim install. They added a docs index separating current references from design and history, an environment variable reference, and a generated tool-arguments page. They extended check_docs.py so it fails on stale generated arguments or README totals and also scans the mcp, npm and extension READMEs. Corrections included wrong tool counts (39, 89, and a stale 100), a client invocation that fails on stock python3, installer behavior, workspace folder names, missing architecture layers, private-repo claims, an obsolete README and a stale roadmap, and a hero link to a draft release public readers could not open. Live workflow facts surfaced: Quick Start leaves the timeline playing, joint tools need the articulation root, a new stage has no /World, and helper scripts need the MCP SDK. They ran local checks (check_docs, check_assets, check_portable_paths, gen_host_catalog --check, wheel and sdist build, npm pack dry-run, host suite 2127 passed / 7 skipped), confirmed generated arguments match the live server schemas for all 111 tools, and ran live sessions on Isaac Sim 6.2.0.0 headless PhysX from a fresh clone with a throwaway HOME: smoke_tools 20/20, verify.sh all passed, validate_scene_tools 32 calls passed, plus a walk over real MCP. They fixed six setup-script bugs, each with a test, and a Lab 3 run 8 root cause where a flattening save wrote a session-only viewportHandle into the file, breaking /scan on reopen. A separate agent on OpenCode Go DeepSeek V4.1 Flash tested commit 0c109d0 in a clean worktree as a skeptical new user and found one CI-blocking private-path literal plus smaller issues, all fixed.

How it went

Documentation now matches the running code, with drift checks that fail CI on stale generated arguments or README totals. All local checks passed, generated arguments matched live schemas for all 111 tools, and live verification on Isaac Sim 6.2.0.0 passed smoke_tools 20/20, verify.sh, and 32 validate_scene_tools calls. Six setup bugs were fixed with tests, and the /scan-on-reopen root cause was proven and fixed. An independent agent test on a clean worktree found one CI-blocking issue and smaller problems, all fixed in the final commit.

Worth knowing

Several areas were not exercised: windowed sessions, desktop input and screen recording, sim__lidar__read, sim__physics__configure, sim__stage__clear_owned, sim__controller__update, assets__prepare_workstation, Isaac Lab jobs, external ROS 2 clients and RViz, Newton, and other Sim builds. The --download-sim path was read, not run. Stale camera handles still have no open-time repair, 6.0 and 6.1 were untested, sim-tools hot reload fails with 'owner already registered', and a saved copy can list a removed capture product in RenderSettings.products. Several behavior changes require flags: --force to replace a changed asset file, --config when several Kit configs exist, and reset_camera_render_handles=true to retry a lidar save. The independent agent test is not the human review.

Wiring

The work centers on the repo's own scripts and CI rather than external services. check_docs.py is the drift gate: it regenerates the tool-arguments page from the live server schemas and compares against the committed file, checks README tool totals, and scans mcp/README.md, npm/README.md and the extension docs. gen_host_catalog.py --check validates the host catalog. check_assets.py and check_portable_paths.py guard asset references and path portability. The verification chain runs install.sh (or scripts/install.py with --config when several Kit configs exist) against an existing Isaac Sim, then smoke_tools.py, verify.sh, validate_scene_tools.py and smoke_mcp_surface.py offline, which pins a closed port and avoids stage-clearing calls. scripts/check_checkpoint_refs.py runs up front in verify.sh to fail fast on stale checkpoints. Packaging is validated with a wheel and sdist build plus npm pack --dry-run, and the host suite runs under pytest. The CI minimum-SDK step pins mcp[cli]==1.22.0. Live sessions used Isaac Sim 6.2.0.0 headless PhysX on source d721f91 with disposable sessions and a throwaway HOME. An independent agent ran on OpenCode Go DeepSeek V4.1 Flash in a clean worktree against commit 0c109d0.

Try it yourself

Revamp the documentation in this repo and verify every claim against the running code, not against the existing docs. Steps: (1) Read the source, entry points, install scripts and tool schemas to establish ground truth. (2) Rewrite the home README with a CI badge, architecture diagram, tool table and a short Quick Start that starts from an existing install. (3) Add a docs index separating current references from design and history, an environment variable reference, and a generated tool-arguments page. (4) Extend the docs drift checker so it fails on stale generated arguments or README totals, and make it scan every README including subpackages and extensions. (5) Fix every factual error you find: wrong tool counts, commands that fail on a stock interpreter, installer behavior, folder names, missing architecture layers, private-repo claims, obsolete pages, stale roadmaps, and links public readers cannot open. (6) Run the local checks, build the wheel and sdist, and confirm generated arguments match the live server schemas for every tool. (7) Run live smoke and verification scripts from a fresh clone with a throwaway HOME, and record what you did not exercise. (8) Fix any setup-script bugs you find during the check, each with a test, and call out behavior changes explicitly. Report results with pass counts and a list of untested paths.