qsys-mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Owens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# qsys-mcp
+
+> Let an AI agent inspect and control a **Q-SYS** audio/video system over QSC's published **QRC** protocol — against a real Core or Q-SYS Designer's built-in emulator.
+
+[![npm](https://img.shields.io/npm/v/qsys-mcp.svg)](https://www.npmjs.com/package/qsys-mcp)
+[![node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](https://nodejs.org)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`qsys-mcp` is an [MCP](https://modelcontextprotocol.io) server. It speaks QSC's **QRC** external-control protocol (JSON-RPC 2.0 over TCP) — the same interface third-party control systems like Crestron and AMX use — and exposes it to an LLM agent as a set of tools. Point it at a physical Q-SYS Core *or* at Q-SYS Designer running in **Emulate mode** and the agent can read meters, flip mutes, ramp gains, and watch controls for changes.
+
+It's a pure wire-protocol client: **zero QSC code**, no SDK, no hardware required for development. That makes it a clean, sanctioned layer QSC ships on no platform — AI-native control — and it runs anywhere Node does.
+
+## Highlights
+
+- **18 tools** covering connect, status, discovery, read, write (with ramps), snapshots, the full change-group lifecycle (add/poll/remove/clear/invalidate/destroy), and disconnect.
+- **No hardware needed** — develop entirely against Designer's Emulate-mode soft-core on `localhost`.
+- **Cross-platform** — `node:net` only; CI proves it on Linux, macOS, and Windows × Node 18 & 20.
+- **Context-friendly** — list/get tools take `filter` / `names_only` / `type` so large designs don't flood the agent's context.
+- **Safe by default** — write tools warn when they're hitting a live Core (not an emulator); a 30 s `NoOp` keepalive holds the socket open through QRC's 60 s idle close.
+- **Self-healing** — on a dropped socket (Core restart, leaving Emulate, a network blip) the client auto-reconnects and replays your change-group registrations, so polling resumes without re-calling `qsys_connect`. Opt out with `reconnect: false`.
+
+## Quick start
+
+Run it straight from npm (no install):
+
+```bash
+npx -y qsys-mcp       # MCP server on stdio
+```
+
+> Formerly published as `q-sys-mcp` (now unpublished) — as of 0.3.0 the package
+> name matches the command: **`qsys-mcp`**. Update any existing MCP configs.
+
+Or from source:
+
+```bash
+git clone https://github.com/reowens/qsys-mcp.git
+cd qsys-mcp
+npm install             # builds dist/ via the prepare hook
+node dist/index.js
+```
+
+### Connect it to your agent
+
+Add it to your MCP client config (Claude Desktop, etc.):
+
+```json
+{
+  "mcpServers": {
+    "q-sys": {
+      "command": "npx",
+      "args": ["-y", "qsys-mcp"]
+    }
+  }
+}
+```
+
+From a local checkout instead, use `"command": "node"` with `"args": ["/absolute/path/to/qsys-mcp/dist/index.js"]`.
+
+Always call `qsys_connect` first (host `127.0.0.1`, port `1710` for a local emulator) before any other tool.
+
+## What it can do
+
+Once connected, just ask in natural language — the agent picks the tools.
+
+> **You:** *"Connect to my Q-SYS emulator and bring the main gain down to −20 dB over 2 seconds."*
+
+The agent runs:
+
+1. `qsys_connect` → `{ host: "127.0.0.1", port: 1710 }`
+2. `qsys_list_components` → `{ type: "gain" }` — finds the `Levels` gain block
+3. `qsys_set_component` → `{ name: "Levels", controls: [{ name: "gain", value: -20, ramp: 2 }] }`
+
+Or, if you've exposed that fader as a **Named Control** in Designer:
+
+```
+qsys_set_control → { name: "MainGain", value: -20, ramp: 2 }
+```
+
+To watch a control live (meters, button states), create a change group and poll it:
+
+```
+qsys_create_change_group → { id: "meters", controls: ["MainGain"] }
+qsys_poll_change_group    → { id: "meters" }   // returns only what changed since the last poll
+```
+
+## Tools
+
+| Tool | QRC method | Purpose |
+|------|------------|---------|
+| `qsys_connect` | (socket) + `Logon`/`StatusGet` | Connect to a Core/emulator |
+| `qsys_status` | `StatusGet` | Engine status (platform, design, run state) |
+| `qsys_list_components` | `Component.GetComponents` | List named components |
+| `qsys_get_component_controls` | `Component.GetControls` | A component's controls + values |
+| `qsys_get_control` | `Control.Get` | Get Named Control values |
+| `qsys_get_component` | `Component.Get` | Get specific component control values |
+| `qsys_set_control` | `Control.Set` | Set a Named Control (with optional ramp) |
+| `qsys_set_component` | `Component.Set` | Set component controls (with optional ramps) |
+| `qsys_load_snapshot` | `Snapshot.Load` | Recall a saved snapshot (with optional ramp) |
+| `qsys_save_snapshot` | `Snapshot.Save` | Capture current settings into a snapshot |
+| `qsys_create_change_group` | `ChangeGroup.AddControl` | Watch Named Controls for changes |
+| `qsys_change_group_add_component` | `ChangeGroup.AddComponentControl` | Watch a component's controls |
+| `qsys_poll_change_group` | `ChangeGroup.Poll` | Get changes since last poll |
+| `qsys_change_group_remove` | `ChangeGroup.Remove` | Stop watching specific Named Controls |
+| `qsys_change_group_clear` | `ChangeGroup.Clear` | Remove all controls, keep the group |
+| `qsys_change_group_invalidate` | `ChangeGroup.Invalidate` | Force the next poll to resend everything |
+| `qsys_destroy_change_group` | `ChangeGroup.Destroy` | Free a change group's server-side state |
+| `qsys_disconnect` | (socket) | Close the connection |
+
+`qsys_list_components` and `qsys_get_component_controls` accept optional `filter` (case-insensitive name substring), `names_only`, and — for components — `type`, to trim large designs before they reach the agent's context.
+
+### Named Controls vs. components
+
+Q-SYS exposes controls two ways, and the tools mirror that split:
+
+- **Named Controls** (`qsys_get_control` / `qsys_set_control`) reach a control only if it's been *explicitly exposed* — dragged into the **Named Controls** pane in Designer with a unique name. Flat namespace, addressed by that one name.
+- **Component controls** (`qsys_get_component_controls` / `qsys_get_component` / `qsys_set_component`) reach any control on a component whose parent has a **Code Name** with **Script Access** enabled — no per-control naming needed.
+
+If `qsys_get_control` can't find a name, it almost always means the control hasn't been added to the Named Controls pane.
+
+## Requirements
+
+- **Node.js ≥ 18.**
+- **A control target on port 1710:**
+  - a real **Q-SYS Core** with a design loaded and in **Run** mode, or
+  - **Q-SYS Designer in Emulate mode** — open a design and press **F6** (*Save to Design & Run*; **not** F5, which deploys to a physical Core). Connect to `127.0.0.1:1710`.
+
+QRC is fully functional in Emulate mode, so you can build and test without any hardware.
+
+> Writes mutate the running/emulated system. On an emulator, nothing persists unless you save the design in Designer.
+
+## Develop & verify
+
+```bash
+npm test                               # offline: QRC integration + MCP-over-mock (no hardware)
+npm run smoke -- 127.0.0.1 1710        # read-only smoke against a live emulator/Core
+npm run smoke:mcp -- 127.0.0.1 1710    # full MCP-over-stdio smoke against a live target
+npm run smoke:write -- 127.0.0.1 1710  # live WRITE round-trip: set a gain, verify, restore
+npm run smoke:named -- MainGain        # live Named-Control read/set + change-group poll
+npm run smoke:keepalive                # idle >60s, prove the socket survives QRC's idle close
+```
+
+`npm test` needs no hardware; every `smoke:*` script needs a live target (a real Core, or Designer in Emulate mode, on port 1710).
+
+**CI** runs `npm ci && npm run build && npm run typecheck && npm test` on Linux, macOS, and Windows × Node 18 & 20 ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)). The whole suite is hardware-free — a mock QRC server plus an in-memory MCP transport — so the full matrix runs without a Core.
+
+## Roadmap / out of scope
+
+- **WebSocket transport** via `@q-sys/qrwc` — a convenience adapter for real Cores. Raw QRC is the primary transport today; the lib is still beta.
+- **Real-Core validation** — every test so far runs against Designer's emulator; a physical Core run is the honest trigger to graduate to `1.0.0`.
+- **Design authoring** (reading/writing `.qsys` files) — out of scope: `.qsys` is a compressed .NET `BinaryFormatter` graph type-coupled to QSC's assemblies.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes, or the [GitHub releases](https://github.com/reowens/qsys-mcp/releases) page.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Q-SYS and QRC are trademarks/protocols of QSC, LLC; this project is an independent client and is not affiliated with or endorsed by QSC.

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { buildServer } from './server.js';
+async function main() {
+    const server = buildServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the MCP channel; logs go to stderr.
+    console.error('qsys-mcp running on stdio');
+}
+main().catch((err) => {
+    console.error('fatal error:', err);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,354 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { QrcClient } from 'qsys-qrc';
+let client = null;
+let lastEngineStatus = null;
+function ok(data) {
+    const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+    return { content: [{ type: 'text', text }] };
+}
+function fail(message) {
+    return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+}
+function requireClient() {
+    // Don't gate on isConnected(): a reconnect-enabled client may be mid-drop, and
+    // its send() transparently waits for the socket to come back. Only a missing
+    // client (never connected, or explicitly disconnected) is a hard error.
+    if (!client) {
+        throw new Error('Not connected to Q-SYS. Call qsys_connect first.');
+    }
+    return client;
+}
+/** Warn when a write targets a live Core rather than an emulator. */
+function liveCoreWarning() {
+    if (lastEngineStatus && lastEngineStatus.IsEmulator === false) {
+        return `⚠ Writing to a LIVE Q-SYS Core (design "${lastEngineStatus.DesignName}"), not an emulator — this changes real audio.`;
+    }
+    return null;
+}
+const controlValue = z.union([z.number(), z.string(), z.boolean()]);
+/** Client-side trim — QRC has no server-side filter/pagination, so we shape the full response. */
+function shapeComponents(comps, opts) {
+    let out = comps;
+    if (opts.filter) {
+        const f = opts.filter.toLowerCase();
+        out = out.filter((c) => c.Name.toLowerCase().includes(f));
+    }
+    if (opts.type) {
+        const t = opts.type.toLowerCase();
+        out = out.filter((c) => (c.Type ?? '').toLowerCase().includes(t));
+    }
+    return opts.names_only ? out.map((c) => ({ Name: c.Name, Type: c.Type })) : out;
+}
+function shapeControls(res, opts) {
+    let ctrls = res.Controls;
+    if (opts.filter) {
+        const f = opts.filter.toLowerCase();
+        ctrls = ctrls.filter((c) => c.Name.toLowerCase().includes(f));
+    }
+    if (opts.names_only)
+        return { Name: res.Name, Controls: ctrls.map((c) => c.Name) };
+    return { ...res, Controls: ctrls };
+}
+export function buildServer() {
+    const server = new McpServer({ name: 'qsys-mcp', version: '0.1.0' });
+    server.registerTool('qsys_connect', {
+        title: 'Connect to Q-SYS',
+        description: 'Connect to a Q-SYS Core or to Q-SYS Designer running in Emulate mode (press F6 in Designer), over the QRC protocol (TCP). For a local emulator use host "127.0.0.1" and port 1710. Must be called before any other tool.',
+        inputSchema: {
+            host: z.string().default('127.0.0.1').describe('Core IP/hostname, or 127.0.0.1 for a local Designer emulator'),
+            port: z.number().int().default(1710).describe('QRC port (default 1710)'),
+            user: z.string().optional().describe('Username, if the design requires authentication'),
+            password: z.string().optional().describe('Password, if the design requires authentication'),
+            reconnect: z
+                .boolean()
+                .default(true)
+                .describe('Auto-reconnect on a dropped socket (Core restart, network blip), replaying change-group registrations so polling resumes. Default true.'),
+        },
+    }, async ({ host, port, user, password, reconnect }) => {
+        try {
+            if (client)
+                client.close();
+            const c = new QrcClient({ host, port, reconnect });
+            c.on('engineStatus', (s) => {
+                lastEngineStatus = s;
+            });
+            c.on('error', () => {
+                /* surfaced per-request; avoid crashing the server on transient socket errors */
+            });
+            c.on('reconnecting', (attempt) => console.error(`[qrc] connection dropped — reconnecting (attempt ${attempt})…`));
+            c.on('reconnected', () => console.error('[qrc] reconnected; change-group registrations replayed'));
+            c.on('reconnectFailed', () => console.error('[qrc] reconnect gave up; will retry on the next request'));
+            await c.connect();
+            if (user && password)
+                await c.logon(user, password);
+            client = c;
+            const status = await c.statusGet();
+            lastEngineStatus = status;
+            return ok({ connected: true, host, port, status });
+        }
+        catch (e) {
+            client = null;
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_status', {
+        title: 'Q-SYS engine status',
+        description: 'Get the Q-SYS engine status: platform, design name, run state, emulator flag.',
+        inputSchema: {},
+    }, async () => {
+        try {
+            return ok(await requireClient().statusGet());
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_list_components', {
+        title: 'List components',
+        description: 'List named components in the running/emulated design, with type and properties (Component.GetComponents). On large designs use filter/type/names_only to trim the response.',
+        inputSchema: {
+            filter: z.string().optional().describe('Case-insensitive substring; only components whose name contains it are returned'),
+            type: z.string().optional().describe('Case-insensitive substring on component type (e.g. "gain", "mixer")'),
+            names_only: z.boolean().optional().describe('Return only name + type per component (drop properties) to save context'),
+        },
+    }, async ({ filter, type, names_only }) => {
+        try {
+            return ok(shapeComponents(await requireClient().getComponents(), { filter, type, names_only }));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_get_component_controls', {
+        title: 'Get component controls',
+        description: "List a named component's controls and current values (Component.GetControls). Use filter/names_only to trim large components.",
+        inputSchema: {
+            name: z.string().describe('Component name (as returned by qsys_list_components)'),
+            filter: z.string().optional().describe('Case-insensitive substring; only controls whose name contains it are returned'),
+            names_only: z.boolean().optional().describe('Return only control names (drop values/positions) to save context'),
+        },
+    }, async ({ name, filter, names_only }) => {
+        try {
+            return ok(shapeControls(await requireClient().getComponentControls(name), { filter, names_only }));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_get_control', {
+        title: 'Get control values',
+        description: 'Get the current values of one or more Named Controls (Control.Get).',
+        inputSchema: { names: z.array(z.string()).min(1).describe('Named Control names') },
+    }, async ({ names }) => {
+        try {
+            return ok(await requireClient().getControl(names));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_get_component', {
+        title: 'Get specific component control values',
+        description: 'Get specific control values within a named component (Component.Get).',
+        inputSchema: {
+            name: z.string().describe('Component name'),
+            controls: z.array(z.string()).min(1).describe('Control names within the component'),
+        },
+    }, async ({ name, controls }) => {
+        try {
+            return ok(await requireClient().getComponent(name, controls));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_set_control', {
+        title: 'Set a control value',
+        description: 'Set a Named Control value, optionally ramped over a number of seconds (Control.Set). This MUTATES the running/emulated system.',
+        inputSchema: {
+            name: z.string().describe('Named Control name'),
+            value: controlValue.describe('New value (number, string, or boolean)'),
+            ramp: z.number().optional().describe('Ramp time in seconds (optional)'),
+        },
+    }, async ({ name, value, ramp }) => {
+        try {
+            const result = await requireClient().setControl(name, value, ramp);
+            const warning = liveCoreWarning();
+            return ok(warning ? { warning, result } : result);
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_set_component', {
+        title: 'Set component control values',
+        description: 'Set one or more control values within a named component, each optionally ramped (Component.Set). This MUTATES the running/emulated system.',
+        inputSchema: {
+            name: z.string().describe('Component name'),
+            controls: z
+                .array(z.object({
+                name: z.string(),
+                value: controlValue,
+                ramp: z.number().optional(),
+            }))
+                .min(1),
+        },
+    }, async ({ name, controls }) => {
+        try {
+            const mapped = controls.map((c) => ({
+                Name: c.name,
+                Value: c.value,
+                ...(c.ramp != null ? { Ramp: c.ramp } : {}),
+            }));
+            const result = await requireClient().setComponent(name, mapped);
+            const warning = liveCoreWarning();
+            return ok(warning ? { warning, result } : result);
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_load_snapshot', {
+        title: 'Recall a snapshot',
+        description: 'Recall control settings from a saved snapshot bank/number, optionally ramped over seconds (Snapshot.Load). This MUTATES the running/emulated system.',
+        inputSchema: {
+            bank: z.string().describe('Snapshot bank name, as named in Q-SYS Designer'),
+            number: z.number().int().min(1).describe('Snapshot number within the bank (1-based)'),
+            ramp: z.number().optional().describe('Ramp time in seconds (optional)'),
+        },
+    }, async ({ bank, number, ramp }) => {
+        try {
+            const result = await requireClient().snapshotLoad(bank, number, ramp);
+            const warning = liveCoreWarning();
+            return ok(warning ? { warning, result } : result);
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_save_snapshot', {
+        title: 'Save a snapshot',
+        description: 'Capture the current control settings into a snapshot bank/number (Snapshot.Save). This OVERWRITES the stored snapshot.',
+        inputSchema: {
+            bank: z.string().describe('Snapshot bank name, as named in Q-SYS Designer'),
+            number: z.number().int().min(1).describe('Snapshot number within the bank (1-based)'),
+        },
+    }, async ({ bank, number }) => {
+        try {
+            return ok(await requireClient().snapshotSave(bank, number));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_create_change_group', {
+        title: 'Create or extend a change group',
+        description: 'Create a change group (or add Named Controls to an existing one) so you can poll for changes (ChangeGroup.AddControl).',
+        inputSchema: {
+            id: z.string().describe('Change group id (any string; reused on poll)'),
+            controls: z.array(z.string()).min(1).describe('Named Control names to watch'),
+        },
+    }, async ({ id, controls }) => {
+        try {
+            return ok(await requireClient().changeGroupAddControl(id, controls));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_poll_change_group', {
+        title: 'Poll a change group',
+        description: 'Poll a change group; returns the controls that changed since the last poll (ChangeGroup.Poll).',
+        inputSchema: { id: z.string().describe('Change group id') },
+    }, async ({ id }) => {
+        try {
+            return ok(await requireClient().changeGroupPoll(id));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_change_group_add_component', {
+        title: 'Add component controls to a change group',
+        description: "Add a named component's controls to a change group so you can poll them for changes (ChangeGroup.AddComponentControl).",
+        inputSchema: {
+            id: z.string().describe('Change group id (any string; reused on poll)'),
+            component: z.string().describe('Component name'),
+            controls: z.array(z.string()).min(1).describe('Control names within the component to watch'),
+        },
+    }, async ({ id, component, controls }) => {
+        try {
+            return ok(await requireClient().changeGroupAddComponentControl(id, component, controls));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_destroy_change_group', {
+        title: 'Destroy a change group',
+        description: 'Destroy a change group, freeing its server-side state (ChangeGroup.Destroy).',
+        inputSchema: { id: z.string().describe('Change group id') },
+    }, async ({ id }) => {
+        try {
+            return ok(await requireClient().changeGroupDestroy(id));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_change_group_remove', {
+        title: 'Remove controls from a change group',
+        description: 'Remove Named Controls from a change group, leaving the group in place (ChangeGroup.Remove). Returns any unknown control names.',
+        inputSchema: {
+            id: z.string().describe('Change group id'),
+            controls: z.array(z.string()).min(1).describe('Named Control names to stop watching'),
+        },
+    }, async ({ id, controls }) => {
+        try {
+            return ok(await requireClient().changeGroupRemove(id, controls));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_change_group_clear', {
+        title: 'Clear a change group',
+        description: 'Remove all controls from a change group without destroying it (ChangeGroup.Clear).',
+        inputSchema: { id: z.string().describe('Change group id') },
+    }, async ({ id }) => {
+        try {
+            return ok(await requireClient().changeGroupClear(id));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    server.registerTool('qsys_change_group_invalidate', {
+        title: 'Invalidate a change group',
+        description: 'Invalidate a change group so the next poll resends every watched control, not just the changes (ChangeGroup.Invalidate). Handy after a reconnect to force a full snapshot.',
+        inputSchema: { id: z.string().describe('Change group id') },
+    }, async ({ id }) => {
+        try {
+            return ok(await requireClient().changeGroupInvalidate(id));
+        }
+        catch (e) {
+            return fail(e.message);
+        }
+    });
+    // ChangeGroup.AutoPoll is intentionally omitted: MCP stdio is request/response,
+    // so a Core-pushed poll has nowhere to land; manual qsys_poll_change_group covers it.
+    server.registerTool('qsys_disconnect', {
+        title: 'Disconnect from Q-SYS',
+        description: 'Close the QRC connection to the Core/emulator. A later qsys_connect is required before other tools.',
+        inputSchema: {},
+    }, async () => {
+        if (client) {
+            client.close();
+            client = null;
+            lastEngineStatus = null;
+        }
+        return ok({ disconnected: true });
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "qsys-mcp",
+  "version": "0.3.0",
+  "description": "Control a Q-SYS audio/video system from an AI agent over QSC's QRC protocol — against a real Core or Q-SYS Designer in Emulate mode. Open-source, cross-platform, zero QSC code.",
+  "type": "module",
+  "bin": {
+    "qsys-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "postbuild": "node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node ../../scripts/run-if-emulator.mjs \"tsx test/integration.ts && tsx test/mcp-mock.ts && tsx test/reconnect.ts\"",
+    "test:mcp": "tsx test/mcp-mock.ts",
+    "test:reconnect": "tsx test/reconnect.ts",
+    "smoke": "tsx test/live-smoke.ts",
+    "smoke:write": "tsx test/live-write.ts",
+    "smoke:mcp": "tsx test/mcp-smoke.ts",
+    "smoke:named": "tsx test/live-named.ts",
+    "smoke:keepalive": "tsx test/keepalive.ts"
+  },
+  "keywords": [
+    "q-sys",
+    "qsys",
+    "qsc",
+    "mcp",
+    "model-context-protocol",
+    "qrc",
+    "av",
+    "audiovisual",
+    "audio",
+    "dsp",
+    "ai-agent",
+    "claude-code",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reowens/qsys-tools.git",
+    "directory": "packages/qsys-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/reowens/qsys-tools/issues"
+  },
+  "homepage": "https://github.com/reowens/qsys-tools/tree/main/packages/qsys-mcp#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "qsys-qrc": "^0.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}