Resources reference

The MCP server exposes five resources under the hypercolor:// URI scheme. Resources are read-only context an agent can pull at any time without spending a tool call. Where a tool like get_status is an explicit action, a resource is ambient knowledge the client subscribes to and re-reads when it needs the current picture. Point an assistant at hypercolor://state before it acts and it already knows the daemon is running, which effect is live, and how many devices are lit.

🔗The five resources

Every resource returns application/json. Each carries a priority hint between 0.0 and 1.0 that tells the client how valuable the context is relative to its budget. The set is fixed at five: there is no layout or sensor resource. Those live data points are reachable through the get_layout and get_sensor_data tools instead.

🔗hypercolor://state

The single most useful resource. A compact snapshot of the daemon: whether it is running or paused, global brightness, the live FPS pair, the active effect, device counts, and which input sources are enabled.

{
  "running": true,
  "paused": false,
  "brightness": 100,
  "fps": {
    "target": 60,
    "actual": 59.8
  },
  "effect": {
    "id": "aurora",
    "name": "Aurora"
  },
  "devices": {
    "connected": 3,
    "total": 4,
    "total_leds": 212
  },
  "inputs": {
    "audio": "enabled",
    "screen": "disabled"
  },
  "uptime_seconds": 4127,
  "version": "0.1.0"
}

Field notes worth pinning:

• brightness is an integer percentage from 0 to 100, matching the set_brightness tool’s scale, not a 0.0–1.0 float.
• fps.target is the current adaptive tier (one of 10, 20, 30, 45, 60); fps.actual is the measured rate. A gap between them is the first signal of render pressure. See the render pipeline for how the controller shifts tiers.
• effect is null when nothing is applied, otherwise an object with id and name.
• inputs.audio and inputs.screen are each "enabled", "disabled", or "unknown" (the last only when config is unavailable).
• version is the daemon’s package version, baked in at build time.

🔗hypercolor://effects

The complete effect catalog: every effect the registry knows about, native and HTML alike, with the metadata an agent needs to choose one.

{
  "effects": [
    {
      "id": "aurora",
      "name": "Aurora",
      "description": "Slow-drifting northern-lights ribbons",
      "category": "ambient",
      "tags": ["calm", "blue", "green", "slow"]
    }
  ],
  "total": 47
}

The catalog blends roughly a dozen native Rust built-ins with the SDK’s HTML effects, so the total is the source of truth for how many are installed on this daemon. Do not hardcode a count in agent logic; read it from the resource. The same data drives the list_effects tool, which adds fuzzy search on top. For building new entries, see native Rust effects and the effects overview.

🔗hypercolor://devices

The full hardware inventory: every known device with its connection status, driver origin, output backend, LED count, and zone configuration. The shape mirrors the REST device inventory exactly, so the same payload an agent reads here is what the REST API returns.

{
  "devices": [
    {
      "id": "razer-huntsman-elite",
      "name": "Razer Huntsman Elite"
    }
  ],
  "summary": {
    "total": 4,
    "connected": 3,
    "total_leds": 212
  }
}

The summary block is the quick read: total is everything ever discovered, connected counts only devices currently renderable, and total_leds sums LED counts across the whole rig. Each entry in devices carries the full inventory payload (driver, backend, topology, zone assignment); read individual fields from the live resource rather than assuming a fixed schema, since device detail varies by driver family. For connection troubleshooting, see devices not found.

🔗hypercolor://profiles

Every saved profile. A profile is a named, persisted lighting setup an agent can restore wholesale through the set_profile tool.

{
  "profiles": [
    {
      "id": "evening-calm",
      "name": "Evening calm",
      "description": "Dim blue ambient for the desk",
      "brightness": 35,
      "primary": "aurora",
      "displays": [],
      "layout_id": "desk-main"
    }
  ],
  "total": 1
}

Each profile reports its id, name, description, saved brightness, the primary effect, any displays (HTML faces bound to LCDs), and the associated layout_id. To activate one, call the set_profile tool with the profile id.

🔗hypercolor://audio

Real-time audio analysis straight off the spectrum channel: overall level, the bass/mid/treble split, beat detection, and a compact spectrum summary. This is the resource for building audio-reactive behavior.

{
  "enabled": true,
  "source": "alsa_output.pci-0000_00_1f.3.analog-stereo.monitor",
  "sample_rate": 2048,
  "levels": {
    "overall": 0.61,
    "bass": 0.78,
    "mid": 0.42,
    "treble": 0.19
  },
  "beat": {
    "detected": true,
    "confidence": 0.83,
    "bpm_estimate": 128.0
  },
  "spectrum_summary": {
    "bins": 64
  }
}

Field notes:

• enabled reflects the daemon’s audio config. When audio is off, source and sample_rate are null and the levels read zero.
• source is the configured capture device. For reactivity to work this must be a monitor source (what the speakers are playing), not a microphone. See audio setup for choosing the right PipeWire or PulseAudio device.
• sample_rate is the configured FFT size, not a hardware Hz value.
• levels are normalized energies in [0.0, 1.0] per band.
• beat.bpm_estimate is null until the detector locks a tempo.
• spectrum_summary.bins reports how many spectrum bins are available; the full per-bin data streams over the WebSocket spectrum channel rather than this resource.

🔗How resources relate to tools

Resources and tools cover overlapping ground on purpose. The split is action versus context.

graph LR
  A[Agent] -->|reads ambient| R[hypercolor:// resources]
  A -->|takes action| T[MCP tools]
  R --> S[state]
  R --> E[effects]
  R --> D[devices]
  T -->|mutates| ENG[Engine]
  R -.snapshot of.-> ENG

Read hypercolor://state to orient, browse hypercolor://effects to choose, then call a tool such as set_effect to act. The state resource will reflect the change on its next read, since every surface operates on the same engine through the event bus. For the action side of the contract, see the tools reference; for guided multi-step playbooks, see agent workflows.