dcc-mcp-core 0.14.2

Foundational library for the DCC Model Context Protocol (MCP) ecosystem

dcc-mcp-core

中文 | English

Production-grade foundation for AI-assisted DCC workflows combining the Model Context Protocol (MCP) and a zero-code Skills system. Provides a Rust-powered core with Python bindings (PyO3) delivering enterprise-grade performance, security, and scalability — all with zero runtime Python dependencies. Supports Python 3.7–3.13.

Note: This project is in active development (v0.14+). APIs may evolve; see CHANGELOG.md for version history.

---

The Problem & Our Solution

Why Not Just Use CLI?

CLI tools are blind to DCC state. They can't see the active scene, selected objects, or viewport context. They execute in isolation, forcing the AI to:

• Make multiple roundtrips to gather context
• Rebuild state from CLI outputs (fragile, slow)
• Lack visual feedback from the viewport
• Scale poorly with context explosion as requests grow

Why MCP (Model Context Protocol)?

MCP is AI-native, but stock MCP lacks two critical capabilities for DCC automation:

1. Context Explosion — MCP has no mechanism to scope tools to specific sessions or instances, causing request bloat with multi-DCC setups
2. No Lifecycle Control — Can't discover instance state (active scene, documents, process health) or control startup/shutdown

Our Approach: MCP + Skills System

We reuse and extend the existing MCP ecosystem, adding:

Capability	Benefit
Gateway Election & Version Awareness	Multi-instance load balancing; automatic handoff when newer DCC launches
Session Isolation	Each AI session talks to its own DCC instance; prevents context bleeding
Skills System (Zero-Code)	Define tools as SKILL.md + scripts/; no Python glue code needed
Progressive Discovery	Scope tools by DCC type, instance, scene, product; prevents context explosion
Instance Tracking	Know active documents, PIDs, display names; enable smart routing
Structured Results	Every tool returns (success, message, context, prompt) for AI reasoning

This isn't reinventing MCP — it's solving MCP's blind spots for desktop automation.

---

Why dcc-mcp-core Over Alternatives?

Aspect	dcc-mcp-core	Generic MCP	CLI Tools	Browser Extensions
DCC State Awareness	Scenes, docs, instance IDs	No	No	Partial
Multi-Instance Support	Gateway election + session isolation	Single endpoint	No	No
Context Scoping	By DCC/scene/product	Global tools	No	Limited
Zero-Code Tools	SKILL.md + scripts	Full Python required	Scripts only	No
Performance	Rust + zero-copy + IPC	Python overhead	Process overhead	Network overhead
Security	Sandbox + audit log	Manual	Manual	None
Cross-Platform	Windows/macOS/Linux	Yes	Limited	Browser only

AI-friendly docs: AGENTS.md | CLAUDE.md | GEMINI.md | CODEBUDDY.md | .agents/skills/dcc-mcp-core/SKILL.md

Architecture: The Three-Layer Stack

+-----------------------------------------------------------------+
|  AI Agent (Claude, GPT, etc.)                                    |
|  Calls tools via MCP protocol (tools/list, tools/call)           |
+-------------------------------+---------------------------------+
                                |
                        MCP Streamable HTTP
                                |
+-------------------------------v---------------------------------+
|  Gateway Server (Rust/HTTP)                                      |
|  +-- Version-Aware Instance Election                             |
|  +-- Session Isolation & Routing                                 |
|  +-- Tool Discovery (skills-derived)                             |
|  +-- Cancellation & Notifications (SSE)                          |
+-------------------------------+---------------------------------+
                                |
                 IPC (Named Pipe / Unix Socket / TCP)
                                |
          +---------------------+---------------------+
          |                     |                     |
  +-------v-------+   +-------v-------+   +-------v-------+
  |  Maya Bridge   |   | Blender Bridge |   | Houdini Bridge|
  |  Plugin (Rust) |   | Plugin (Rust)  |   | Plugin (Rust)|
  +-------+--------+   +-------+--------+   +-------+-------+
          |                     |                     |
    Python 3.7+           Python 3.7+           Python 3.7+
    (zero deps)           (zero deps)           (zero deps)

Layer 1: AI Agent — Calls tools via standard MCP protocol (tools/list, tools/call, notifications).

Layer 2: Gateway — Orchestrates discovery, session isolation, and request routing. Maintains __gateway__ sentinel for version-aware election.

Layer 3: DCC Adapters — Python bridge plugins (Maya, Blender, Photoshop) with embedded Skills system. Each registers documents, scene state, and active process info. WebView-host adapters (AuroraView, browser panels) use a narrower capability surface.

---

Quick Start

Installation

# From PyPI (pre-built wheels for Python 3.7+)
pip install dcc-mcp-core

# Or from source (requires Rust 1.85+)
git clone https://github.com/loonghao/dcc-mcp-core.git
cd dcc-mcp-core
pip install -e .

Basic Usage — Load & Execute Skills

import json
from dcc_mcp_core import (
    ToolRegistry, ToolDispatcher, SkillCatalog,
    EventBus, success_result, scan_and_load
)

# 1. Discover skills (scans SKILL.md + scripts/)
skills, skipped = scan_and_load(dcc_name="maya")
print(f"Loaded {len(skills)} skills, skipped {len(skipped)}")

# 2. Register all skill tools in registry
registry = ToolRegistry()
for skill in skills:
    for script_path in skill.scripts:
        skill_name = f"{skill.name.replace('-', '_')}__{Path(script_path).stem}"
        registry.register(
            name=skill_name,
            description=skill.description,
            dcc=skill.dcc
        )

# 3. Set up dispatcher with event lifecycle
dispatcher = ToolDispatcher(registry)
bus = EventBus()
bus.subscribe("action.after_execute", lambda **kw: print(f"Done: {kw['action_name']}"))

# 4. Call a skill (returns structured result)
result = dispatcher.dispatch(
    "maya_geometry__create_sphere",
    json.dumps({"radius": 2.0})
)
print(f"Success: {result['output']['success']}")
print(f"Message: {result['output']['message']}")
print(f"Context: {result['output']['context']}")

Core Concepts

ToolResult — Structured Results for AI

All skill execution results use ToolResult, designed to be AI-friendly with structured context and follow-up guidance:

from dcc_mcp_core import ToolResult, success_result, error_result

# Factory functions (recommended)
ok = success_result(
    "Sphere created",
    prompt="Consider adding materials or adjusting UVs",
    object_name="sphere1", position=[0, 1, 0]
)
# ok.context == {"object_name": "sphere1", "position": [0, 1, 0]}

err = error_result(
    "Failed to create sphere",
    "Radius must be positive"
)

# Direct construction
result = ToolResult(
    success=True,
    message="Operation completed",
    context={"key": "value"}
)

# Access fields
result.success      # bool
result.message     # str
result.prompt       # Optional[str] -- AI next-step suggestion
result.error        # Optional[str] -- error details
result.context      # dict -- arbitrary structured data

ToolRegistry & Dispatcher — The Skill Execution System

import json
from dcc_mcp_core import (
    ToolRegistry, ToolDispatcher, ToolValidator,
    EventBus, SemVer, VersionedRegistry
)

# Registry with search support
registry = ToolRegistry()
registry.register("my_skill", description="My skill", category="tools", version="1.0.0")

# Validated dispatcher (takes only registry; validate separately with ToolValidator)
dispatcher = ToolDispatcher(registry)
dispatcher.register_handler("my_skill", lambda params: {"done": True})
result = dispatcher.dispatch("my_skill", json.dumps({}))
# result == {"action": "my_skill", "output": {"done": True}, "validation_skipped": True}

# Event-driven architecture
bus = EventBus()
sub_id = bus.subscribe("action.before_execute", lambda **kw: print(f"before: {kw}"))
bus.publish("action.before_execute", action_name="test")
bus.unsubscribe("action.before_execute", sub_id)

Skills System — Zero-Code MCP Tool Registration

The Skills system is dcc-mcp-core's core innovation: it lets you register any script (Python, MEL, MaxScript, Batch, Shell, JS) as an MCP tool with zero Python code. Reuses the existing OpenClaw Skills format.

How It Works

+-----------------------------------+
|  Directory:  my-automation/       |
|  +-- SKILL.md  (metadata)         |
|  +-- scripts/                     |
|      +-- cleanup.py               |
|      +-- publish.sh               |
|      +-- validate.mel             |
+-----------------------------------+
          |  (discovery)
+-----------------------------------+
|  SkillCatalog (progressive loading)     |
|  +-- Dual-cache: by-paths &       |
|  |   by-config (session-bound)    |
|  +-- Scoped: Repo/User/System     |
|  +-- Policies: implicit invoke,   |
|      product filters, deps        |
+-----------------------------------+
          |  (registration)
+-----------------------------------+
|  ToolRegistry + SkillCatalog    |
|  (callable by AI via MCP tools)   |
+-----------------------------------+

Five Minutes to Your First Skill

1. Create my-tool/SKILL.md:

---
name: maya-cleanup
description: "Scene optimization and cleanup tools"
version: "1.0.0"
dcc: maya
scope: repo  # Trust level: repo < user < system < admin
tags: ["maintenance", "quality"]
policy:
  allow_implicit_invocation: false  # Require explicit load_skill call
  products: ["maya", "houdini"]      # Only show these DCCs
external_deps:
  mcp:
    - name: "usd-tools"
      description: "USD validation"
      transport: "ipc"
---
# Maya Scene Cleanup

Automated tools for optimizing and validating Maya scenes.

2. Create my-tool/scripts/cleanup.py:

#!/usr/bin/env python
"""Clean unused nodes from the scene."""
import sys
result = {"success": True, "message": "Cleaned up 42 unused nodes"}
print(json.dumps(result))
sys.exit(0)

3. Register and call:

import os
os.environ["DCC_MCP_SKILL_PATHS"] = "/path/to/my-tool"

from dcc_mcp_core import scan_and_load, ToolRegistry

skills, skipped = scan_and_load(dcc_name="maya")
registry = ToolRegistry()

# Tools are now: maya_cleanup__cleanup, with structured results
result = dispatcher.dispatch("maya_cleanup__cleanup", json.dumps({}))
print(result["output"])  # {"success": True, "message": "...", "context": {...}}

That's it. No Python glue code. Just metadata + scripts.

Supported Script Types

Extension	Type	Execution
.py	Python	subprocess with system Python
.mel	MEL (Maya)	Via DCC adapter
.ms	MaxScript	Via DCC adapter
.bat, .cmd	Batch	cmd /c
.sh, .bash	Shell	bash
.ps1	PowerShell	powershell -File
.js, .jsx	JavaScript	node
.ts	TypeScript	node (via ts-node or tsx)

See examples/skills/ for 11 complete examples: hello-world, maya-geometry, maya-pipeline, git-automation, ffmpeg-media, imagemagick-tools, usd-tools, clawhub-compat, multi-script, dcc-diagnostics, workflow.

Bundled Skills — Zero Configuration Required

dcc-mcp-core ships two core skills directly inside the wheel. They are available immediately after pip install dcc-mcp-core — no repository clone or DCC_MCP_SKILL_PATHS configuration needed.

Skill	Tools	Purpose
dcc-diagnostics	screenshot, audit_log, tool_metrics, process_status	Observability & debugging for any DCC
workflow	run_chain	Multi-step action chaining with context propagation

from dcc_mcp_core import get_bundled_skills_dir, get_bundled_skill_paths

# Get the bundled skills directory (inside the installed wheel)
print(get_bundled_skills_dir())
# /path/to/site-packages/dcc_mcp_core/skills

# Returns [bundled_dir] or [] -- ready to extend your search path
paths = get_bundled_skill_paths()                    # default ON
paths = get_bundled_skill_paths(include_bundled=False)  # opt-out

DCC adapters (e.g. dcc-mcp-maya) automatically include bundled skills by default. To opt-out: start_server(include_bundled=False).

Solving MCP Context Explosion

The Problem: Stock MCP returns ALL tools in tools/list, even those irrelevant to the user's current task or DCC instance. With 3 DCC instances x 50 skills x 5 scripts = 750 tools, the context window fills instantly.

Our Solution — Progressive Discovery:

1. Instance Awareness — Each DCC registers active documents, PID, display name, scope level
2. Smart Tool Scoping — Tools filtered by:
   • DCC Type — Only Maya tools if working with Maya
   • Scope — Repo skills < User skills < System skills
   • Product — Some tools only for Houdini, not Maya
   • Policy — Implicit-invocation skills grouped separately
3. Session Isolation — AI session pinned to one DCC instance; sees only its tools
4. Gateway Election — If a newer DCC version launches, automatically hand off to it

Example:

Without dcc-mcp-core (stock MCP):

tools/list response includes:
- 100 Maya tools
- 100 Houdini tools
- 100 Blender tools
+ 250 shared tools
= 550 tool definitions in context

With dcc-mcp-core:

tools/list filtered by session instance:
AI talking to Maya instance #1 -> sees 100 Maya tools + 50 shared tools
AI talking to Houdini instance #2 -> sees 100 Houdini tools + 50 shared tools
= 150 tools in context (71% reduction)

This is session-bound tool discovery — not a hack, but a fundamental rethinking of how MCP scales.

---

Architecture Overview — 15 Rust Crates

dcc-mcp-core is organized as a Rust workspace of 15 crates, compiled into a single native Python extension (_core) via PyO3/maturin:

| Crate | Responsibility | Key Types | |----------------------|-----------| | dcc-mcp-naming | SEP-986 naming validators | validate_tool_name, validate_action_id, TOOL_NAME_RE | | dcc-mcp-models | Data models | ToolResult, SkillMetadata | | dcc-mcp-actions | Tool execution lifecycle | ToolRegistry, EventBus, ToolDispatcher, ToolValidator, ToolPipeline | | dcc-mcp-skills | Skills discovery & loading | SkillScanner, SkillCatalog, SkillWatcher, dependency resolver | | dcc-mcp-protocols | MCP protocol types | ToolDefinition, ResourceDefinition, PromptDefinition, DccAdapter, BridgeKind | | dcc-mcp-transport | IPC communication | DccLinkFrame, IpcChannelAdapter, GracefulIpcChannelAdapter, SocketServerAdapter, TransportAddress | | dcc-mcp-process | Process management | PyDccLauncher, ProcessMonitor, ProcessWatcher, CrashRecoveryPolicy | | dcc-mcp-sandbox | Security | SandboxPolicy, InputValidator, AuditLog | | dcc-mcp-shm | Shared memory | SharedBuffer, BufferPool, LZ4 compression | | dcc-mcp-capture | Screen capture | Capturer, cross-platform backends | | dcc-mcp-telemetry | Observability | TelemetryConfig, RecordingGuard, tracing | | dcc-mcp-usd | USD integration | UsdStage, UsdPrim, scene info bridge | | dcc-mcp-http | MCP Streamable HTTP server | McpHttpServer, McpHttpConfig, McpServerHandle, Gateway (first-wins competition) | | dcc-mcp-server | Binary entry point | dcc-mcp-server CLI, gateway runner | | dcc-mcp-utils | Infrastructure | Filesystem helpers, type wrappers, constants, JSON |

Key Features

• Rust-powered performance: Zero-copy serialization (rmp-serde), LZ4 shared memory, lock-free data structures
• Zero runtime Python deps: Everything compiled into native extension
• Skills system: Zero-code MCP tool registration via SKILL.md + scripts/
• Validated dispatch: Input validation pipeline before execution
• Resilient IPC: DccLink framing via ipckit (IpcChannelAdapter, SocketServerAdapter)
• Process management: Launch, monitor, auto-recover DCC processes
• Sandbox security: Policy-based access control with audit logging
• Screen capture: Cross-platform DCC viewport capture for AI visual feedback
• USD integration: Universal Scene Description read/write bridge
• Structured telemetry: Tracing & recording for observability
• ~180 public Python symbols with full type stubs (.pyi)
• OpenClaw Skills compatible: Reuse existing ecosystem format

Installation

# From PyPI (pre-built wheels)
pip install dcc-mcp-core

# Or from source (requires Rust 1.85+)
git clone https://github.com/loonghao/dcc-mcp-core.git
cd dcc-mcp-core
pip install -e .

Development Setup

# Clone the repository
git clone https://github.com/loonghao/dcc-mcp-core.git
cd dcc-mcp-core

# Recommended: use vx (universal dev tool manager)
# Install vx: https://github.com/loonghao/vx
vx just install     # Install all project dependencies
vx just dev         # Build + install dev wheel
vx just test       # Run Python tests
vx just lint       # Full lint check (Rust + Python)

Without vx

# Manual setup
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install maturin pytest pytest-cov ruff mypy
maturin develop --features python-bindings,ext-module
pytest tests/ -v
ruff check python/ tests/ examples/
cargo clippy --workspace -- -D warnings

Running Tests

vx just test           # All Python tests
vx just test-rust       # All Rust unit tests
vx just test-cov        # With coverage report
vx just ci              # Full CI pipeline
vx just preflight       # Pre-commit checks only

Transport Layer — Inter-Process Communication

dcc-mcp-core provides IPC via DccLink framing (ipckit-based, v0.14+):

from dcc_mcp_core import DccLinkFrame, IpcChannelAdapter, GracefulIpcChannelAdapter, SocketServerAdapter

# Server side: create channel and wait for client
server = IpcChannelAdapter.create("dcc-mcp-maya")
server.wait_for_client()  # blocks until client connects

# Client side: connect to server
client = IpcChannelAdapter.connect("dcc-mcp-maya")
client.send_frame(DccLinkFrame(msg_type=1, seq=1, body=b'{"method":"ping"}'))
reply = client.recv_frame()  # DccLinkFrame

# Multi-client socket server
sock_server = SocketServerAdapter("/tmp/dcc-mcp.sock", max_connections=10)

Process Management — DCC Lifecycle Control

from dcc_mcp_core import (
    PyDccLauncher, PyProcessMonitor, PyProcessWatcher,
    PyCrashRecoveryPolicy
)

# Launch a DCC application
launcher = PyDccLauncher(dcc_type="maya", version="2025")
process = launcher.launch(
    script_path="/path/to/startup.py",
    working_dir="/project",
    env_vars={"MAYA_RENDER_THREADS": "4"}
)

# Monitor health
monitor = PyProcessMonitor()
monitor.track(process)
stats = monitor.stats(process)  # CPU, memory, uptime

# Auto-restart on crash
watcher = PyProcessWatcher(
    recovery_policy=PyCrashRecoveryPolicy(max_restarts=3, cooldown_sec=10)
)
watcher.watch(process)

Sandbox Security — Policy-Based Access Control

from dcc_mcp_core import SandboxContext, SandboxPolicy, InputValidator, AuditLog

# Define a policy (SandboxPolicy accepts optional config dict)
policy = SandboxPolicy()
ctx = SandboxContext(policy)
validator = InputValidator(ctx)

# Validate before execution
allowed, reason = validator.validate("delete_all_files")
if not allowed:
    print(f"Blocked by policy: {reason}")
else:
    print("Allowed — executing...")

# Review audit trail
audit = ctx.audit_log
for entry in audit.entries():
    print(f"{entry.action} -> {entry.outcome}")

More Examples

See the examples/skills/ directory for 11 complete skill packages, and the VitePress docs site for comprehensive guides per module.

Release Process

This project uses Release Please to automate versioning and releases. The workflow is:

1. Develop: Create a branch from main, make changes using Conventional Commits
2. Merge: Open a PR and merge to main
3. Release PR: Release Please automatically creates/updates a release PR that bumps the version and updates CHANGELOG.md
4. Publish: When the release PR is merged, a GitHub Release is created and the package is published to PyPI

Commit Message Format

This project follows Conventional Commits:

Prefix	Description	Version Bump
feat:	New feature	Minor (0.x.0)
fix:	Bug fix	Patch (0.0.x)
feat!: or BREAKING CHANGE:	Breaking change	Major (x.0.0)
docs:	Documentation only	No release
chore:	Maintenance	No release
ci:	CI/CD changes	No release
refactor:	Code refactoring	No release
test:	Adding tests	No release

Examples

# Feature (bumps minor version)
git commit -m "feat: add batch skill execution support"

# Bug fix (bumps patch version)
git commit -m "fix: resolve middleware chain ordering issue"

# Breaking change (bumps major version)
git commit -m "feat!: redesign skill registry API"

# Scoped commit
git commit -m "feat(skills): add PowerShell script support"

# No release trigger
git commit -m "docs: update API reference"
git commit -m "ci: add Python 3.14 to test matrix"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Workflow

1. Fork the repository and clone your fork
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes following the coding standards below
4. Run tests and linting:

   vx just lint       # Check code style
   vx just test       # Run tests
   vx just preflight  # Run all pre-commit checks
   

5. Commit using Conventional Commits format
6. Push and open a Pull Request against main

Coding Standards

• Style: Code is formatted with ruff and isort (line length: 120)
• Type hints: All public APIs must have type annotations
• Docstrings: Google-style docstrings for all public modules, classes, and functions
• Testing: New features must include tests; maintain or improve coverage
• Imports: Use section headers (Import built-in modules, Import third-party modules, Import local modules)

License

This project is licensed under the MIT License - see the LICENSE file for details.

AI Agent Resources

If you're an AI coding agent, also see:

• AGENTS.md — Comprehensive guide for all AI agents (architecture, commands, API reference, pitfalls)
• CLAUDE.md — Claude-specific instructions and workflows
• GEMINI.md — Gemini-specific instructions and workflows
• CODEBUDDY.md — CodeBuddy Code-specific instructions and workflows
• .agents/skills/dcc-mcp-core/SKILL.md — Complete API skill definition for learning and using this library
• python/dcc_mcp_core/init.py — Full public API surface (~180 symbols)
• llms.txt — Concise API reference optimized for LLMs
• llms-full.txt — Complete API reference optimized for LLMs
• CONTRIBUTING.md — Development workflow and coding standards