# QRWC Svelte MCP

A Model Context Protocol (MCP) server for Svelte projects using the [qrwc-svelte](https://www.npmjs.com/package/qrwc-svelte) npm package. This MCP server provides tools, resources, and prompts to help LLMs build UI components that interact with Q-SYS systems.

> **⚠️ Experimental**: This MCP server is currently in the experimental stage. The API and features may change.

> **💡 Recommended**: For the best experience, use this MCP server alongside the [Official Svelte MCP server](https://svelte.dev/docs/mcp/overview) to get comprehensive Svelte documentation and code analysis.

## Overview

The QRWC Svelte MCP server helps LLMs and AI agents write better code for Q-SYS systems by providing:

- Tools to discover components and controls from a Q-SYS Core
- Documentation resources for working with qrwc-svelte
- Example code for common control types
- Prompts optimized for Q-SYS development tasks

## Requirements

- A Q-SYS Core IP address (required as the first argument) - Only hardware and VCore is supported, No Emulation.
- Node.js installed (for running the MCP server)

## Setup

The setup varies based on your chosen MCP client. The core IP address must be provided as the first argument, and you can optionally pass `--no-svelte` to disable Svelte-specific resources and prompts (useful if you're using a different UI framework).

### Command Format

```
npx qrwc-svelte-mcp <core-ip> [--no-svelte]
```

### Claude Code

To include the QRWC Svelte MCP server in Claude Code, run:

```bash
claude mcp add -t stdio -s [scope] qrwc-svelte -- npx qrwc-svelte-mcp <core-ip>
```

Replace `<core-ip>` with your Q-SYS Core IP address. The `[scope]` must be `user`, `project` or `local`.

To disable Svelte-specific resources:

```bash
claude mcp add -t stdio -s [scope] qrwc-svelte -- npx qrwc-svelte-mcp <core-ip> --no-svelte
```

### Claude Desktop

In the Settings > Developer section, click on Edit Config. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration:

```json
{
	"mcpServers": {
		"qrwc-svelte": {
			"command": "npx",
			"args": ["-y","qrwc-svelte-mcp","<core-ip>"]
		}
	}
}
```

Replace `<core-ip>` with your Q-SYS Core IP address.

To disable Svelte-specific resources:

```json
{
	"mcpServers": {
		"qrwc-svelte": {
			"command": "npx",
			"args": ["-y","qrwc-svelte-mcp","<core-ip>", "--no-svelte"]
		}
	}
}
```

### Codex CLI

Add the following to your `config.toml` (which defaults to `~/.codex/config.toml`):

```toml
[mcp_servers.qrwc-svelte]
command = "npx"
args = ["-y", "qrwc-svelte-mcp", "<core-ip>"]
```

Replace `<core-ip>` with your Q-SYS Core IP address.

To disable Svelte-specific resources:

```toml
[mcp_servers.qrwc-svelte]
command = "npx"
args = ["-y", "qrwc-svelte-mcp", "<core-ip>", "--no-svelte"]
```

### Gemini CLI

To include the QRWC Svelte MCP server in Gemini CLI, run:

```bash
gemini mcp add -t stdio -s [scope] qrwc-svelte npx -y qrwc-svelte-mcp <core-ip>
```

Replace `<core-ip>` with your Q-SYS Core IP address. The `[scope]` must be `user`, `project` or `local`.

To disable Svelte-specific resources:

```bash
gemini mcp add -t stdio -s [scope] qrwc-svelte npx -y qrwc-svelte-mcp <core-ip> --no-svelte
```

### OpenCode

Run the command:

```bash
opencode mcp add
```

and follow the instructions, selecting 'Local' under the 'Select MCP server type' prompt:

```
opencode mcp add

┌  Add MCP server
│
◇  Enter MCP server name
│  qrwc-svelte
│
◇  Select MCP server type
│  Local
│
◆  Enter command to run
│  npx -y qrwc-svelte-mcp <core-ip>
```

Replace `<core-ip>` with your Q-SYS Core IP address.

### VS Code

1. Open the command palette
2. Select "MCP: Add Server..."
3. Select "Command (stdio)"
4. Insert `npx -y qrwc-svelte-mcp <core-ip>` in the input and press `Enter` (replace `<core-ip>` with your Q-SYS Core IP address)
5. When prompted for a name, insert `qrwc-svelte`
6. Select if you want to add it as a `Global` or `Workspace` MCP server

To disable Svelte-specific resources, use `npx -y qrwc-svelte-mcp <core-ip> --no-svelte` in step 4.

### Cursor

1. Open the command palette
2. Select "View: Open MCP Settings"
3. Click on "Add custom MCP"

It will open a file with your MCP servers where you can add the following configuration:

```json
{
	"mcpServers": {
		"qrwc-svelte": {
			"command": "npx",
			"args": ["-y", "qrwc-svelte-mcp", "<core-ip>"]
		}
	}
}
```

Replace `<core-ip>` with your Q-SYS Core IP address.

To disable Svelte-specific resources:

```json
{
	"mcpServers": {
		"qrwc-svelte": {
			"command": "npx",
			"args": ["-y", "qrwc-svelte-mcp", "<core-ip>", "--no-svelte"]
		}
	}
}
```

### Zed

1. Open the command palette
2. Search and select "agent:open settings"
3. In settings panel look for `Model Context Protocol (MCP) Servers`
4. Click on "Add Server"
5. Select: "Add Custom Server"

It will open a popup with MCP server config where you can add the following configuration:

```json
{
	"qrwc-svelte": {
		"command": "npx",
		"args": ["-y", "qrwc-svelte-mcp", "<core-ip>"]
	}
}
```

Replace `<core-ip>` with your Q-SYS Core IP address.

To disable Svelte-specific resources:

```json
{
	"qrwc-svelte": {
		"command": "npx",
		"args": ["-y", "qrwc-svelte-mcp", "<core-ip>", "--no-svelte"]
	}
}
```

### Other clients

If we didn't include the MCP client you are using, refer to their documentation for `stdio` servers and use `npx` as the command with `-y qrwc-svelte-mcp <core-ip>` as the arguments. You can optionally add `--no-svelte` as an additional argument to disable Svelte-specific features.

## Available Tools

The MCP server provides the following tools:

### `get_components`

Get a list of components that are currently available on a Q-SYS core.

**Input**: None

**Output**: 
- `success`: Boolean indicating if the request was successful
- `error`: Optional error message
- `data`: Array of component objects with:
  - `name`: Component name
  - `controlCount`: Number of controls in the component

### `get_controls`

Get all controls on a Component, including the type and read/write direction of the control.

**Input**:
- `componentName`: The name of the component to list controls for. Use the `get_components` tool to get a list of component names.

**Output**:
- `success`: Boolean indicating if the request was successful
- `error`: Optional error message
- `data`: Array of control objects with:
  - `name`: Control name
  - `type`: Control type (e.g., "Boolean", "Integer", "Float", "String")
  - `direction`: Control direction ("Read", "Write", or "ReadWrite")

## Available Prompts

### `qrwc-task`

Perform a task that involves the creation or modification of UI elements that are part of a Q-SYS Design. This prompt ensures that common Q-SYS terms and qrwc-svelte knowledge is in the context window.

**Arguments**:
- `task`: Description of the task to perform

**Note**: This prompt is only available when NOT using the `--no-svelte` flag.

## Available Resources

The following resources are available to provide documentation and examples for working with qrwc-svelte:

### `static://qrwc-svelte/setup`

Initial setup and configuration guide for using QRWC with Svelte projects.

### `static://qrwc-svelte/core-concepts`

Core concepts and terminology for working with Q-SYS systems and the QRWC protocol.

### `static://qrwc-svelte/components`

Documentation on working with Q-SYS Components in a Svelte project, including component instantiation and usage.

### `static://qrwc-svelte/controls`

Documentation on working with Q-SYS controls, including how to read and write control values.

### `static://qrwc-svelte/button-examples`

Example code for working with Boolean controls (buttons, toggles, etc.).

### `static://qrwc-svelte/knob-examples`

Example code for working with Integer, Float, and other numeric type controls (knobs, sliders, etc.).

### `static://qrwc-svelte/text-examples`

Example code for working with Text/String based controls.

**Note**: All resources are only available when NOT using the `--no-svelte` flag.

## Usage Examples

### Basic Usage

Connect to a Q-SYS Core at IP address `192.168.1.100`:

```bash
npx -y qrwc-svelte-mcp 192.168.1.100
```

### Disable Svelte-Specific Features

If you're using a different UI framework (not Svelte), you can disable Svelte-specific resources and prompts:

```bash
npx -y qrwc-svelte-mcp 192.168.1.100 --no-svelte
```

When using `--no-svelte`, only the core tools (`get_components` and `get_controls`) are available. All Svelte-specific resources and the `qrwc-task` prompt are disabled.

This is helpful if you are using another framework, and want to create your own prompts that instruct the LLM to fetch controls and components from a Q-SYS Core.

## Related Links

- [qrwc-svelte npm package](https://www.npmjs.com/package/qrwc-svelte)
- [Official Svelte MCP server](https://svelte.dev/docs/mcp/overview)
- [Q-SYS Documentation](https://q-syshelp.qsc.com/)

## License

Apache 2.0