dcc-mcp-shogun

A typed, local-first DCC-MCP adapter for Vicon Shogun Post motion-capture inspection, timeline control, bounded processing, and file workflows.

The adapter uses Vicon's official local ViconShogunPost control-stream SDK and its Timeline and Offline interfaces. It does not expose arbitrary Python or HSL execution. Application controls not exposed by the SDK remain an explicit, exact-window DCC UI Control fallback.

Shogun Post ships an external Python SDK. The adapter runs in its own Python process and connects to the application's local control stream; it does not rely on a general-purpose Python interpreter embedded in the Shogun Post UI.

Capabilities

• inspect path-redacted scene metadata and bounded subject lists;
• inspect subject markers, skeleton hierarchy, constraints, and static subject parameters;
• query one marker trajectory value or an inclusive window of at most 2,000 frames;
• inspect and explicitly change current frame, selected time ranges, and play range through the capability-gated Timeline interface;
• inspect a stable allowlist of processing settings and invoke reconstruct, auto-label, occlusion fixing, solve, or retarget through the official Offline interface;
• expose capability-gated import, save, and export calls that map directly to the official SDK;
• register one Shogun Post GUI instance with the DCC-MCP local gateway.

The mutating surface is deliberately narrow. Processing requires an explicit current_frame or selected_ranges scope; the complete play range is not an available implicit default. The adapter does not expose scene replacement, arbitrary HSL/Python execution, or raw trajectory writes. Existing outputs fail closed unless overwrite=true, and public results omit full paths.

The read-only shogun-scene Skill is live-validated against Shogun Post 1.19. That host build rejected the SDK's ImportFile call with ControlError, without partially changing the scene. The separate shogun-files Skill therefore remains explicitly host-build and license-capability gated: its tools are typed and fail closed, but import/save/export are not claimed as live-supported on 1.19.

The same 1.19 host exposes the official Timeline and Offline Python classes but rejects their commands as invalid for that host application. The shogun-timeline and shogun-processing Skills therefore remain explicitly capability-gated: their schemas and SDK mappings are tested, while 1.19 support is not claimed. A rejection is returned as a bounded typed error and never triggers UI automation.

The implemented contracts follow Vicon's official Python SDK interface guide and HSL command reference.

Showcase

The repository includes an original, deterministic 240-frame BVH motion source and generator under examples/showcase. It is intended for reproducible import experiments without redistributing production capture data.

See docs/showcase.md for the full launch, discovery, inspection, and evidence workflow.

Local development

Start Vicon Shogun Post with your normal application launcher. Then install this adapter in a Python environment that can import dcc-mcp-core:

python -m pip install -e ".[dev]"
dcc-mcp-shogun --host-pid <SHOGUN_POST_PID>

The adapter discovers the official SDK beside the selected host process. An operator can instead set DCC_MCP_SHOGUN_SDK_PATH to the SDK's Win64 directory. The adapter resolves the selected host process's control-stream listener; DCC_MCP_SHOGUN_CONTROL_PORT may override it only when that port is owned by the same host process.

The DCC-MCP listener uses an OS-assigned loopback port unless --mcp-port or DCC_MCP_SHOGUN_PORT is explicitly set. Use dcc-mcp-cli list, search, describe, and call rather than storing the resolved endpoint.

Validation

python -m ruff check src tests tools
python -m ruff format --check src tests tools
python -m pytest
python tools/lint_skills.py
python -m build

Privacy and safety

• Connections are limited to the local Shogun control stream.
• Tool results reduce file paths to base names.
• Errors report exception classes, not SDK install paths or machine details.
• The scene Skill is read-only; the file Skill exposes only bounded import/save/export operations; processing never defaults to the full play range.
• Authentication, licensing, UAC, and security dialogs are never automated.

Vicon and Shogun are trademarks of Vicon Motion Systems Ltd. This independent adapter is not affiliated with or endorsed by Vicon.

License

MIT