argb-ai MCP Server

Part of the argb-ai ecosystem. Works alongside argb-core and cli.

argb-ai/mcp-server is the Model Context Protocol boundary for AI-native ARGB control. It translates language-model intent into safe, structured lighting actions and exposes hardware state in forms that an AI agent can understand.

Responsibility Boundary

This repository owns:

• MCP tools, resources, prompts, and server lifecycle.
• AI-facing semantics such as vibes, scenes, moods, constraints, and hardware context.
• Validation and safety limits for AI-triggered lighting changes.
• Translation between high-level lighting intent and lower-level argb-core operations.

This repository does not own:

• Low-level USB, serial, HID, or device protocol implementations.
• Terminal UX or command-line workflows.
• Hardware-specific performance primitives unless they belong in argb-core.

Low-level device access should flow through argb-core. Human terminal workflows should live in cli.

Planned MCP Tools

Initial tool ideas:

• set_vibe: apply a high-level lighting intent such as calm, focus, alert, or celebration.
• set_color: set a static color with optional brightness and duration constraints.
• run_effect: start a bounded animation by name with validated parameters.
• stop_effect: stop the current effect and return hardware to a safe state.
• get_hardware_status: report connected controllers, channel state, LED count, and health signals.
• preview_scene: validate and summarize a requested lighting scene without applying it.

Tool names and schemas should be optimized for LLM comprehension, not for mirroring internal Rust APIs.

Planned MCP Resources

Resources should describe the world the model is allowed to act on:

• Connected controllers and their capabilities.
• Channel and LED topology.
• Current lighting state.
• Supported effects and parameter ranges.
• Safety constraints such as refresh-rate limits and brightness caps.

The server should convert raw argb-core data into structured, stable resources that are easy for an AI agent to reason about.

Safety Model

AI-triggered lighting must be bounded by default:

• Limit refresh frequency to protect hardware and USB/serial stability.
• Validate LED counts, color values, brightness, and animation duration.
• Prefer short-lived operations unless a long-running session is explicitly requested.
• Reject ambiguous commands when multiple controllers are connected.
• Keep a safe fallback state for tool failures, disconnects, or malformed requests.

The server should make unsafe states difficult to express through MCP schemas.

AI Collaboration Contract

When using Cursor, Claude, Gemini, or another AI coding assistant in this repository:

• Treat this as the protocol translation layer between LLMs and ARGB hardware.
• Focus on tool schemas, resource models, safety validation, and intent translation.
• Do not build terminal UX here; use cli for command-line workflows.
• Do not implement low-level hardware transport here; use argb-core.
• Keep AI-visible names and descriptions explicit, stable, and semantically rich.

Current Status

This repository is in early design. MCP schemas and resource names may change until the first tagged release.