dcc-mcp-shogun 0.2.0__tar.gz

dcc_mcp_shogun-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+/.pytest_cache/
+/.ruff_cache/
+/.venv/
+/dist/
+/dist-*/
+/build/
+/artifacts/
+*.egg-info/
+__pycache__/
+*.py[cod]

dcc_mcp_shogun-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

dcc_mcp_shogun-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 loonghao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dcc_mcp_shogun-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: dcc-mcp-shogun
+Version: 0.2.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 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 `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](https://vicon-help.atlassian.net/wiki/spaces/Shogun111/pages/13208701/Use%2BVicon%2BShogunPost%2BSDK%2Binterfaces)
+and [HSL command reference](https://help.vicon.com/download/attachments/196380086/HSL%20scripting%20with%20Vicon%20Shogun.pdf).
+
+## 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.
+- 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

dcc_mcp_shogun-0.2.0/README.md

@@ -0,0 +1,117 @@
+# 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 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 `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](https://vicon-help.atlassian.net/wiki/spaces/Shogun111/pages/13208701/Use%2BVicon%2BShogunPost%2BSDK%2Binterfaces)
+and [HSL command reference](https://help.vicon.com/download/attachments/196380086/HSL%20scripting%20with%20Vicon%20Shogun.pdf).
+
+## 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.
+- 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

dcc_mcp_shogun-0.2.0/docs/showcase.md

@@ -0,0 +1,59 @@
+# Shogun MCP showcase
+
+This showcase demonstrates a bounded motion-capture workflow without publishing
+studio capture data, installation paths, machine names, or credentials.
+
+## What it proves
+
+1. Generate an original 240-frame, 30 FPS BVH motion source.
+2. Launch Shogun Post through the operator's normal package environment.
+3. Bind the adapter to one explicit Shogun Post PID and its owned control port.
+4. Discover the instance and its typed tools through `dcc-mcp-cli`.
+5. Inspect the active scene through Vicon's official external Python SDK.
+6. Probe the host's file-operation capability with the anonymous BVH through
+   the typed `shogun-files` Skill.
+7. Probe the official `Timeline` and `Offline` interfaces through their typed
+   Skills without running UI fallback.
+8. Continue to save/export only when the selected host build accepts the import;
+   otherwise retain the fail-closed result as compatibility evidence.
+
+## Reproduce
+
+```powershell
+python examples/showcase/generate_showcase_bvh.py
+dcc-mcp-shogun --host-pid <SHOGUN_POST_PID>
+dcc-mcp-cli list
+dcc-mcp-cli search scene --dcc-type shogun
+dcc-mcp-cli call <instance>.shogun_scene__inspect_scene --json '{}' --wait
+dcc-mcp-cli load-skill shogun-timeline --dcc-type shogun --instance-id <instance>
+dcc-mcp-cli call <instance>.shogun_timeline__inspect_timeline --json '{}' --wait
+dcc-mcp-cli load-skill shogun-processing --dcc-type shogun --instance-id <instance>
+dcc-mcp-cli call <instance>.shogun_processing__inspect_processing_settings --json '{"section":"reconstruct"}' --wait
+dcc-mcp-cli load-skill shogun-files --dcc-type shogun --instance-id <instance>
+dcc-mcp-cli call <instance>.shogun_files__import_motion --json-file import.json --wait
+```
+
+The generated asset is deterministic and safe to commit. It contains no actor,
+production, or filesystem metadata. A real production scene is intentionally
+not included.
+
+## Acceptance evidence
+
+- the selected Shogun PID owns the resolved local control-stream listener;
+- the adapter registers as `shogun` and reports Shogun Post 1.19;
+- `inspect_scene` completes against the live application;
+- Shogun Post 1.19 rejects the official SDK `ImportFile` call with
+  `ControlError`, and a follow-up typed inspection confirms no partial scene
+  mutation;
+- import, save, and export implementations use only the official SDK and return
+  path-redacted result metadata, but are not presented as live-supported on
+  that host build;
+- Shogun Post 1.19 rejects the official `Timeline` and `Offline` interface
+  commands as invalid for that host application; typed calls return bounded
+  errors, so support is not overclaimed and no processing mutation is attempted;
+- returned scene paths are reduced to file names;
+- vendor exceptions are reduced to exception class names without tracebacks;
+- unit tests, skill validation, package build, metadata check, and CI all pass.
+
+The illustration is an explanatory workflow graphic, not a Shogun screenshot.
+Real-host acceptance retains separate CLI results and host-visible evidence.