Skill: loonghao/dcc-mcp-creator (version 0.17.47)

--- name: dcc-mcp-creator description: >- Infrastructure skill - guide developers and agents through creating or modernizing a full DCC-MCP adapter for Nuke, Blender, 3ds Max, Unreal, ZBrush, Houdini, Maya, and custom studio tools. Use when building server, dispatcher, gateway, packaging, and runtime integration. Not for authoring individual SKILL.md tool packages - use dcc-mcp-skills-creator. license: MIT-0 compatibility: "dcc-mcp-core 0.17+, Python 3.7+" allowed-tools: Bash Read Write Edit metadata: dcc-mcp: dcc: python layer: infrastructure version: "0.17.47" # x-release-please-version search-hint: >- create DCC MCP adapter, Nuke MCP, DccServerBase, HostExecutionBridge, dispatcher, readiness, resources, gateway, Blender, 3ds Max, Unreal, ZBrush, Houdini, Maya tags: "adapter-development, host-runtime, dispatcher, gateway, nuke, blender, 3dsmax, unreal, zbrush" skill-reference-docs: - "references/*.md" openclaw: homepage: https://github.com/loonghao/dcc-mcp-core/blob/main/skills/dcc-mcp-creator/SKILL.md --- # DCC-MCP Creator Use this skill when you are creating a new DCC-MCP adapter or modernizing an existing adapter repository: server composition, host-thread dispatch, sidecar/gateway wiring, readiness, resources, project state, diagnostics, install lifecycle, or cross-DCC verification. For individual skill packages (`SKILL.md`, `tools.yaml`, scripts, groups, and skill taxonomy), load `dcc-mcp-skills-creator` instead. ## Fast Workflow 1. Classify the host integration: - Embedded Python host: Blender, 3ds Max Python, Houdini, Maya, Nuke. - External bridge host: ZBrush, Photoshop, Unity, custom tools. - Game/editor host with mixed Python or C++ bridge: Unreal, Unity. 2. Read the relevant reference: - [ADAPTER_WORKFLOW.md](references/ADAPTER_WORKFLOW.md) for the build path. - [HOST_PATTERN_MATRIX.md](references/HOST_PATTERN_MATRIX.md) for host-specific wiring. - [CORE_ESCALATION_CHECKLIST.md](references/CORE_ESCALATION_CHECKLIST.md) before adding adapter-local glue. - [TESTING_AND_RELEASE.md](references/TESTING_AND_RELEASE.md) before validating or publishing. 3. Start from `DccServerBase` + `DccServerOptions.from_env(...)`. 4. Route host API calls through `HostExecutionBridge`; do not hand-roll a second script executor. 5. Keep DCC identity data-driven: `dcc_name`, `server_name`, env-var prefix, skill names, and gateway metadata. 6. Use core helpers for skill discovery, `MinimalModeConfig`, project tools, resources, diagnostics, context snapshots, install lifecycle, and gateway failover before writing adapter-local wrappers. 7. Choose the `dcc-mcp-server` run mode deliberately: no subcommand or `auto` for backwards-compatible first-wins auto-gateway, `serve --no-auto-gateway` when a separate daemon owns the gateway port, and `gateway` for a machine-wide daemon with no inline DCC execution. 8. If the adapter cannot share the gateway `FileRegistry`, register remotely through `POST /v1/instances/register`, refresh with `/heartbeat`, and deregister on shutdown; the gateway will expose the row as `source: "http"` in `gateway://instances` / `GET /v1/instances`, preserve `instance_short` and `mcp_url`, and route it through the same `live_instances` contract. 9. For same-LAN convenience discovery, build with `mdns` and pair adapter-side `--advertise-mdns` with gateway-side `--discover-mdns`; treat this as a multicast discovery hint only, keep auth/TLS policy explicit, and prefer HTTP registration or relay for routed/subnet-crossing production deployments. 10. For NAT or routed-subnet deployments, run the tunnel agent with stable `instance_id`, `capabilities_fingerprint`, `adapter_version`, and `scene` metadata, then configure the standalone gateway with `--relay-source ADMIN_URL=PUBLIC_BASE_URL`; the gateway will expose active tunnels as `source: "relay"` rows with relay details in `source_meta` after probing `/v1/healthz` through `<PUBLIC_BASE_URL>/tunnel/<tunnel_id>/mcp`. 11. Preserve gateway caller attribution when adding adapter wrappers or admin/debug routes: let MCP `initialize.params.clientInfo`, MCP `_meta.agent_context`, REST `meta.agent_context`, `x-dcc-mcp-*` headers, and safe `User-Agent` fallbacks flow through core rather than logging raw prompts or local machine data. 12. For lifecycle/memory/telemetry policy, use `register_lifecycle_hooks(...)`, `search_skills(..., session_id=...)`, `dispatch_session_start(...)`, `dispatch_before_tool_call(...)`, `dispatch_after_tool_call(...)`, and `dispatch_session_end(...)`; pair `MemoryRecorder(InMemoryMemoryStore()).install(hooks)` with those hooks when adapters need bounded memory summaries, failed-pattern avoidance, or session compaction, and disable the recorder for privacy-sensitive deployments. Open a focused core issue/RFC only when those public hooks cannot express the adapter boundary. 13. Add one executable smoke path: unit tests for construction plus either headless DCC, mock dispatcher MCP calls, gateway REST replay, mDNS same-LAN discovery smoke, relay-source smoke, or `just idle-memory-smoke` for standalone server idle/regression checks. 14. For gateway/admin observability, surface explicit state instead of silent zeroes: traffic panels should report disabled, unavailable, filtered, or genuine no-traffic states; skill panels should distinguish discovered, loaded, searched, selected, called, failed, and low-adoption skills; and admin-facing frames/paths should stay metadata-only or aliased unless an operator explicitly configures a private raw sink. 15. Preserve workflow observability: adapter calls should carry request, parent, trace, session, DCC, transport, and artifact/validation metadata so the Admin workflow graph can show Intent → Discovery → Skill Load → Tool Calls → Fallbacks → Artifacts → Validation → Report without raw log reading. 16. Preserve bounded `agent_context` task/session/turn metadata and artifact/validation-friendly tool names so Admin task outcomes can group workflows, calls, deliverables, and checks without reading raw payloads or local paths. ## Example: New Nuke Adapter When asked to create a Nuke MCP adapter, start by mapping the host lifecycle: how Python is loaded, how the UI/main thread must be entered, what headless mode is available, how plugins are installed, and which operations should be bundled as default skills. Then scaffold the adapter around core primitives: - `DccServerBase` for MCP/HTTP and skill catalog behavior. - `DccServerOptions.from_env("NUKE")` or an adapter-specific equivalent for env-driven configuration. - `HostExecutionBridge` plus a Nuke dispatcher for all Nuke API calls. - Core project, readiness, resource, diagnostics, and gateway helpers before adapter-local glue. - `dcc-mcp-skills-creator` for the first `nuke-*` skill packages. ## Non-Negotiables - Do not touch a DCC API from a Tokio/HTTP worker thread. - Do not parse or rewrite `SKILL.md`, `tools.yaml`, `groups.yaml`, or prompt/workflow files in adapter runtime code when core exposes a typed object or catalog API. - Do not reach into `server._server` unless no public core API exists; if you must, file a core issue and keep the adapter shim small. - Do not create Maya-only abstractions in shared core or adapter templates. - Do not expose raw script execution as the primary user workflow when a typed skill can cover the task. - Do not publish local paths, private machine names, or source-attribution markers in public issues or PR text.

path: references/ADAPTER_WORKFLOW.md
content: # Adapter Workflow

Use this reference to build a new adapter or simplify an existing one.

## 1. Choose the Runtime Shape

Use the smallest shape that can honestly run the host API:

| Host shape | Typical DCCs | Recommended path |
|---|---|---|
| Embedded Python, GUI | Blender, Houdini, Maya, 3ds Max Python | `DccServerBase` with `HostExecutionBridge` and a host dispatcher |
| Embedded Python, headless | mayapy, Blender background, Houdini hython | `DccServerBase` with inline or blocking dispatcher |
| External bridge | ZBrush, Photoshop, Unity, proprietary tools | `DccServerBase` plus IPC/WebSocket/HTTP bridge helpers |
| Editor/game engine | Unreal, Unity | Adapter-owned plugin bridge plus typed skill tools; keep Python optional |

## 2. Build the Composition Root

Adapter server modules should be composition roots, not utility bins. Keep them
responsible for wiring only:

- Resolve options with `DccServerOptions.from_env(...)`.
- Pass the adapter's bundled `skills/` directory.
- Attach `HostExecutionBridge` before skill discovery.
- Register resources, project tools, diagnostics, prompts, and adapter
  instruction resources before `start()`.
- Keep `start_server()` and `stop_server()` thin wrappers.

Minimal skeleton:

```python
from pathlib import Path

from dcc_mcp_core import DccServerBase, DccServerOptions, HostExecutionBridge


class MyDccServer(DccServerBase):
    def __init__(self, port: int = 8765, dispatcher=None, **kwargs):
        bridge = HostExecutionBridge(dispatcher=dispatcher) if dispatcher else None
        options = DccServerOptions.from_env(
            "mydcc",
            Path(__file__).parent / "skills",
            port=port,
            execution_bridge=bridge,
            **kwargs,
        )
        super().__init__(options=options)

    def _version_string(self) -> str:
        return "unknown"
```

## 3. Add Progressive Skills

Use `MinimalModeConfig` for startup policy:

```python
from dcc_mcp_core import MinimalModeConfig

minimal = MinimalModeConfig(
    skills=("mydcc-scripting", "mydcc-scene"),
    deactivate_groups={"mydcc-scene": ("heavy",)},
    env_var_minimal="DCC_MCP_MYDCC_MINIMAL",
    env_var_default_tools="DCC_MCP_MYDCC_DEFAULT_TOOLS",
)
server.register_builtin_actions(minimal_mode=minimal)
```

Only eager-load the skills needed for discovery, diagnostics, and a first useful
scene query. Leave authoring, render, export, and pipeline skills loadable on
demand.

## 4. Publish Adapter Context

Prefer core-owned surfaces:

- `set_context_snapshot_provider(...)` for post-tool scene/document context.
- `register_adapter_instructions(...)` for adapter instruction resources.
- `register_project_tools(...)` for resumable project state.
- `server.resources()` or a public resource binder when available.
- `plugin_manifest(...)` for machine-readable install metadata.

If a needed adapter context requires private inner-server access, keep the shim
in one adapter-local module and open a core issue.

## 5. Decide What Belongs in Core

Escalate to core when more than one adapter would need the same helper:

- skill metadata lifecycle hooks;
- host-thread readiness bits;
- resource registration patterns;
- sidecar/install lifecycle;
- gateway search/describe/call response shape;
- app UI automation contracts;
- file/artifact handoff;
- diagnostics, agent trace packets, compact debug negotiation, and issue-report exports.

Adapter repositories should contain host facts and host API calls. Core should
own reusable MCP, gateway, catalog, lifecycle, and wire contracts.

Admin issue reports are public-safe by default. They should expose request
status, DCC type, tool family, timing, sanitized error kind, token accounting,
redaction status, and relative debug links without raw payload previews or local
machine details. Full debug bundles remain a core-owned explicit raw export
(`?mode=raw`) for reviewed local evidence only.

Gateway/admin token accounting has two distinct concepts. Payload token fields
(`payload_token_usage`, `payload_token_accounting`, trace input/output tokens)
estimate captured request/response previews and must report missing coverage
explicitly. Response token accounting (`token_usage`, `response_token_accounting`,
original/returned/saved tokens) describes JSON/TOON compaction savings and must
not be used as a substitute for missing payload estimates.


path: references/CORE_ESCALATION_CHECKLIST.md
content: # Core Escalation Checklist

Use this before adding adapter-local framework code. If the answer is "yes" for
two or more adapters, prefer a core issue/RFC.

## Escalate to Core

Open a core issue when the adapter needs:

- a lifecycle hook around skill discovery, skill load, unload, group activation,
  resource subscription, client initialize, or tool dispatch;
- a typed skill object transform that must apply to programmatic, MCP, REST, and
  gateway load paths;
- a public `DccServerBase` wrapper over a private inner server API;
- a reusable resource/prompt/project registration pattern;
- a readiness bit or health check shared by host dispatchers;
- a gateway search/describe/call response field;
- install, uninstall, or sidecar lifecycle behavior;
- cross-DCC app UI automation contracts;
- common artefact/file handoff and retention behavior;
- policy, audit, telemetry, or debug bundle fields.

## Keep Local to the Adapter

Keep code adapter-local when it is only:

- the host's import path, version query, or startup hook;
- the exact host API call, such as `bpy.ops`, `pymxs.runtime`, or Unreal editor APIs;
- a DCC-specific menu, shelf, plugin, or bootstrap script;
- domain tool behavior that belongs to one DCC skill package;
- a studio-specific deployment policy.

## Current Core Requests From Adapter Review

- [RFC: add adapter skill-load transform hooks](https://github.com/loonghao/dcc-mcp-core/issues/1204): adapters need a core-owned hook so metadata transforms apply consistently to programmatic `load_skill`, MCP `load_skill`, REST `/v1/load_skill`, and gateway-mediated loads.
- [RFC: expose public DccServerBase resource registration surface](https://github.com/loonghao/dcc-mcp-core/issues/1205): adapters need a public resource handle/helper instead of private inner-server access.
- [RFC: add reusable adapter readiness binder](https://github.com/loonghao/dcc-mcp-core/issues/1206): embedded adapters need a shared readiness binder for process, dispatcher, host-execution, main-thread, and DCC-ready state.

## Issue Template

```markdown
## Problem

Describe the adapter-local code that should not be repeated in every DCC repo.

## Requested Core Surface

- API name or shape.
- Which load/call/resource/readiness paths it must cover.
- Expected error and observability behavior.

## Acceptance Criteria

- At least one Python adapter test.
- At least one MCP or REST path test when the behavior crosses HTTP.
- Backward compatibility notes for existing adapters.
```

Public issue text must be portable. Do not include local paths, private
hostnames, machine-specific logs, or source-attribution markers.


path: references/HOST_PATTERN_MATRIX.md
content: # Host Pattern Matrix

Use this table when choosing adapter runtime wiring for a new DCC.

| DCC family | Host API | Dispatcher approach | Notes |
|---|---|---|---|
| Blender | `bpy` | GUI timers or background blocking dispatcher | Keep `bpy` imports lazy so discovery works outside Blender. |
| 3ds Max | `pymxs` / MaxPlus | Main-thread dispatcher; Python entry from startup scripts or plugin bootstrap | Treat scene mutations as main-thread-only unless proven safe. |
| Unreal | Python, C++ plugin, or remote control | Prefer an editor plugin bridge; use Python only where deployed | Long operations should become async jobs with progress/cancellation. |
| ZBrush | ZScript, GoZ, HTTP/IPC helper | External bridge; no embedded Python assumption | Keep bridge commands typed and bounded; avoid generic remote execution. |
| Houdini | `hou` | Event-loop callback or headless hython dispatcher | Node graph writes are main-thread-sensitive. |
| Maya | `maya.cmds` / OpenMaya | UI dispatcher in GUI; standalone serialized dispatcher in mayapy | Do not special-case Maya patterns into core without parameterizing host identity. |
| Photoshop / Adobe | UXP/CEP/ExtendScript | External bridge or app UI contract | Use structured bridge calls; do not depend on a Python-in-host runtime. |
| Custom studio tool | Python, socket, HTTP, or CLI | Start with the least-powerful bridge that can satisfy typed tools | Document auth, scope, and shutdown behavior up front. |

## Host API Rules

- Import host modules inside callables or skill script entry points, never at
  package import time.
- Mark scene-touching tools `affinity: main`.
- Use `affinity: any` only for pure file, validation, serialization, or metadata
  operations.
- If a tool can exceed two seconds, declare `execution: async` and a realistic
  `timeout_hint_secs`.
- Long host loops must check core cancellation where available.
- Every bridge path must normalize arguments and return structured envelopes.

## Dispatcher Smoke Tests

Each adapter should have at least one smoke that proves:

- the server starts without a GUI import at discovery time;
- a main-affinity tool runs through the host dispatcher, not the HTTP worker;
- a pure `any` tool can run without blocking the host UI;
- cancellation or timeout produces a structured error;
- gateway REST or direct MCP can search, load, describe, and call one typed tool.


path: references/TESTING_AND_RELEASE.md
content: # Testing And Release

Use the smallest test that proves the adapter contract, then add one live or
HTTP-level smoke when behavior crosses process boundaries.

## Test Layers

| Layer | What to prove |
|---|---|
| Unit | option resolution, server construction, env vars, skill path collection |
| Dispatcher | main-affinity calls run on the host dispatcher and return envelopes |
| Skill lifecycle | `search_skills` -> `load_skill` -> typed tool -> `unload_skill` |
| REST/MCP | direct `/mcp` or `/v1/*` search, describe, load, and call |
| Gateway | multi-instance routing, policy, compact responses, debug traces |
| Live DCC | one host smoke that creates/queries/cleans up real scene state |
| Packaging | wheel or plugin archive installs into the target host runtime |

## Validation Commands

Prefer repository-native commands. For Python projects, prefer `vx uv` when it
is available in the environment, then fall back to direct Python only when the
wrapper is unavailable or hides behavior you need to inspect.

Typical gates:

```bash
python -m ruff check src tests
python -m ruff format --check src tests
python -m pytest
```

For Rust/PyO3 core changes, run the workspace's `just` or `cargo` gates that
match the touched crates.

For `dcc-mcp-core` toolchain or dependency refreshes, prefer vx-managed Cargo so
local runs match CI:

```bash
vx cargo update
vx cargo tree -d
vx cargo build --workspace --all-targets --timings
```

## Live-DCC Smoke Shape

Every adapter should eventually provide one documented smoke:

1. Start the DCC host in the supported mode.
2. Start or load the adapter.
3. Discover one skill.
4. Load it.
5. Call one safe typed tool.
6. Verify host-visible state.
7. Stop the adapter and ensure registry rows are gone.

If CI cannot run the real DCC, keep the mock HTTP test in CI and document the
manual live smoke command in the adapter repository.

## PR Notes

PR descriptions should include:

- short summary of runtime or skill behavior changed;
- validation commands, without machine-specific paths;
- any live-DCC gap that remains;
- linked core issues for deferred shared APIs.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)