dcc-diagnostics git:20260422.2082784A

Immutable. This exact content is served forever at /api/v1/blob/c2e9bae124642401.

---
name: dcc-diagnostics
description: >-
  Infrastructure skill — DCC-agnostic observability primitives: capture
  screenshots, query audit logs, inspect tool performance metrics, and monitor
  process health. Works in any DCC environment (Maya, Blender, Houdini, Unreal,
  etc.) or standalone Python. Use for debugging any skill failure or verifying
  DCC state. Not for primary task execution — use a domain skill for actual DCC
  operations.
license: MIT
metadata:
  dcc-mcp.dcc: python
  dcc-mcp.version: "1.0.0"
  dcc-mcp.layer: infrastructure
  dcc-mcp.search-hint: "screenshot, capture, audit log, metrics, performance, process monitor, diagnostics, debug, health check, observability"
  dcc-mcp.tags: "diagnostics, observability, screenshot, audit, metrics, debug, infrastructure"
tools:
  - name: screenshot
    description: "Capture a screenshot of the current display or a specific window. Returns the image as a base64-encoded PNG. Useful for visual debugging — capture what's visible on screen when an error occurs."
    input_schema:
      type: object
      properties:
        format:
          type: string
          description: "Image format: 'png' (default), 'jpeg', or 'raw_bgra'"
          default: png
        scale:
          type: number
          description: "Scale factor 0.0-1.0 (default 1.0 = native resolution). Use 0.5 to halve the size."
          default: 1.0
        jpeg_quality:
          type: integer
          description: "JPEG quality 0-100 (default 85). Only used when format is 'jpeg'."
          default: 85
        window_title:
          type: string
          description: "Capture only the window whose title contains this substring. If omitted, captures the full screen."
        save_path:
          type: string
          description: "If provided, save the image to this file path in addition to returning base64."
        timeout_ms:
          type: integer
          description: "Maximum milliseconds to wait for a frame (default 5000)."
          default: 5000
    read_only: true
    idempotent: false
    source_file: scripts/screenshot.py
    next-tools:
      on-success: []
      on-failure: [dcc_diagnostics__audit_log, dcc_diagnostics__process_status]

  - name: audit_log
    description: "Query the dcc-mcp-core sandbox audit log — list recent action invocations, filter by outcome (success/denied), or search by action name. Helps diagnose why an action was blocked or what the agent did recently."
    input_schema:
      type: object
      properties:
        filter:
          type: string
          description: "Filter entries: 'all' (default), 'success', 'denied', or 'error'"
          default: all
        action_name:
          type: string
          description: "Only return entries for this specific action name."
        limit:
          type: integer
          description: "Maximum number of entries to return (default 50)."
          default: 50
    read_only: true
    idempotent: true
    source_file: scripts/audit_log.py
    next-tools:
      on-success: [dcc_diagnostics__tool_metrics]
      on-failure: []

  - name: tool_metrics
    description: "Show performance metrics for registered tools — invocation counts, success rates, average and P95/P99 latencies. Use to identify slow or failing tools."
    input_schema:
      type: object
      properties:
        action_name:
          type: string
          description: "If provided, return metrics only for this tool. Otherwise return all."
        sort_by:
          type: string
          description: "Sort results by: 'name', 'invocations' (default), 'avg_ms', 'p95_ms', or 'failure_rate'"
          default: invocations
        limit:
          type: integer
          description: "Maximum number of tools to return (default 20)."
          default: 20
    read_only: true
    idempotent: true
    source_file: scripts/tool_metrics.py
    next-tools:
      on-success: [dcc_diagnostics__process_status]
      on-failure: []

  - name: process_status
    description: "Check the health of tracked DCC processes — list running PIDs, check if a specific process is alive, and inspect crash recovery policy. Use when a DCC tool stops responding."
    input_schema:
      type: object
      properties:
        pid:
          type: integer
          description: "Check status of a specific process ID. If omitted, returns summary of all tracked processes."
    read_only: true
    idempotent: true
    source_file: scripts/process_status.py
    next-tools:
      on-success: []
      on-failure: [dcc_diagnostics__audit_log]
---

# DCC Diagnostics

Cross-DCC observability and debugging tools powered by `dcc-mcp-core`.

All tools work in any DCC environment (Maya, Blender, Houdini, Unreal, 3ds Max)
or standalone Python — no DCC-specific APIs required.

## Tools

### `dcc_diagnostics__screenshot`

Capture the current screen or a specific window as a PNG/JPEG image.
Backed by the `dcc_mcp_core.Capturer` class which uses:

- **Windows**: DXGI Desktop Duplication API (<16ms per frame)
- **Linux**: X11 XShmGetImage
- **Fallback**: Mock synthetic backend (headless/CI)

### `dcc_diagnostics__audit_log`

Query the sandbox audit log from `dcc_mcp_core.SandboxContext`.
Returns recent tool invocations with outcome (success/denied) and timestamps.

### `dcc_diagnostics__tool_metrics`

Inspect per-tool performance counters from `dcc_mcp_core.ToolRecorder`:
invocation count, success rate, average latency, P95/P99 percentiles.

### `dcc_diagnostics__process_status`

Check process health via `dcc_mcp_core.PyProcessMonitor`.
Lists tracked PIDs and their liveness status.

## Usage with any DCC MCP server

```python
import os
os.environ["DCC_MCP_SKILL_PATHS"] = "/path/to/dcc-diagnostics"

from dcc_mcp_maya import start_server  # or dcc_mcp_blender, etc.
handle = start_server(port=8765)
# dcc_diagnostics__screenshot is now available as an MCP tool
```