Metadata-Version: 2.5
Name: dcc-mcp-shogun
Version: 0.7.0
Summary: Typed DCC-MCP adapter for Vicon Shogun Post motion-capture workflows
Author-email: loonghao <hal.long@outlook.com>
License: MIT
License-File: LICENSE
Keywords: animation,dcc,mcp,motion-capture,shogun,vicon
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.9
Requires-Dist: dcc-mcp-core<1.0.0,>=0.19.86
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# dcc-mcp-shogun

![dcc-mcp-shogun brand lockup](docs/assets/dcc-mcp-shogun.svg)

[![CI](https://github.com/dcc-mcp/dcc-mcp-shogun/actions/workflows/ci.yml/badge.svg)](https://github.com/dcc-mcp/dcc-mcp-shogun/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/dcc-mcp-shogun.svg)](https://pypi.org/project/dcc-mcp-shogun/)
[![Python](https://img.shields.io/pypi/pyversions/dcc-mcp-shogun.svg)](https://pypi.org/project/dcc-mcp-shogun/)

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

![Motion data to typed tools to verified scene](docs/images/shogun-scene-showcase.webp)

The adapter uses Vicon's official local `ViconShogunPost` control-stream SDK and
its `Scene`, `Timeline`, `Offline`, `Channel`, `FIRFilter`, and
`WeightedAverageFilter` contracts. 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 the capability-gated Scene object graph, hierarchy, transforms,
  attribute/channel names, bounded channel samples and gaps, optical-camera
  calibration summaries, selection, visibility, selectability, and opacity;
- inspect and explicitly change current frame, selected time ranges,
  range selection derived from keys, play/animation ranges, and playback through
  the capability-gated `Timeline` interface;
- inspect bounded Clip timing, offsets, time scale, lock and SMPTE alignment;
  read or explicitly change the active Clip; and update an allowlisted Clip
  timing subset with vendor read-back verification and rollback;
- inspect Character frame bounds and shot-QA flags, and update only six
  allowlisted Boolean workflow fields with vendor read-back verification and
  rollback, while excluding artist identities and free-form notes;
- repair one explicit marker sample with read-back verification; select channel
  keys from the current ranges, delete one explicit key or selected keys, and
  apply bounded FIR or weighted-average filtering that defaults to selected keys;
- inspect a stable allowlist of processing settings and invoke reconstruct,
  ROM labeling, subject calibration, auto-label, occlusion fixing, solve,
  QuickPost, or retarget through the official `Offline` interface; reconstruction,
  occlusion, and solving setting updates are allowlisted and rollback-aware;
- 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. Clip mutation cannot create,
remove, rename, or reparent NLE objects, and Character mutation cannot read or
write artist identities or free-form notes. Both mutation paths validate every
field before connecting, verify the vendor read-back, and attempt rollback on
partial failure. Cleanup never exposes the SDK's
unbounded `DeleteAllKeys` operation. Single-sample writes are finite and bounded,
return the previous value, and fail if Shogun does not return the requested
sample. 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 bulk raw trajectory writes. Existing outputs
fail closed unless `overwrite=true`, and public results omit full file-system
paths. The Scene surface does not expose object creation, removal, reparenting,
or raw attribute writes. Attribute values and camera device identifiers are
intentionally omitted from inspection results.

The subject, marker, skeleton, constraint, parameter, and trajectory queries in
`shogun-scene` are live-validated against Shogun Post 1.19. The newer official
`Scene` object model remains capability-gated because that host can ship the SDK
surface while rejecting its commands. The same host 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.

`shogun-editing` is separately capability-gated. Its schemas and SDK mappings
are tested against the 1.19 SDK contract. All five tools were also loaded and
dispatched through a live 1.19 host: against an empty scene, each mutation was
safely rejected as a bounded `ControlError`, with the scene remaining empty.
Trajectory write and filter effects on a non-empty disposable take are not yet
claimed as live-validated. A host-build or scene-state rejection never falls
back to arbitrary script execution.

`shogun-production-context` exposes eight Clip and Character tools. Its four
read-only tools were loaded and dispatched through a live 1.19 host; the blank
scene returned bounded `ControlError` responses and the host remained
available. All eight current tools were then loaded from the packaged Skill in
a live 1.19 adapter; `get_active_clip` reached the official Scene interface and
returned the same bounded `ControlError` on the blank scene without affecting
host availability. The active-Clip, Clip-timing, and Character-QA mutation
contracts are SDK-mapped, schema-tested, read-back verified, rollback-aware,
and remain capability-gated until a disposable non-empty scene is available
for live mutation evidence. The official Database interface is intentionally
not public: an isolated read probe coincided with host termination, so it
remains deferred until that stability signal can be reproduced and resolved.

The implemented contracts follow Vicon's official
[Shogun Post documentation](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost118/overview),
[Python scripting guide](https://vicon-help.atlassian.net/wiki/spaces/ShogunPost118/pages/544283341/Python%2Bscripting%2Bwith%2BVicon%2BShogun%2BPost),
and [HSL command reference](https://help.vicon.com/download/attachments/196380086/HSL%20scripting%20with%20Vicon%20Shogun.pdf).
See the maintained [official SDK coverage matrix](docs/official-sdk-coverage.md)
for implemented and intentionally deferred interface families.

## Showcase

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

See [`docs/showcase.md`](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`:

```powershell
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

```powershell
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.
- Attribute inspection returns names only, and camera summaries omit device IDs.
- The scene Skill limits mutation to selection and display state; the file Skill
  exposes only bounded import/save/export operations; editing requires an
  explicit object/channel or subject/marker/frame; 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
