{
  "markdown": "# qsys-tools\n\n> Open-source tooling for **QSC Q-SYS** audio/video systems — control a Core from\n> your shell, your code, or an AI agent, and run Q-SYS Designer natively on your Mac.\n\n[![npm qsys-cli](https://img.shields.io/npm/v/qsys-cli.svg?label=qsys-cli)](https://www.npmjs.com/package/qsys-cli)\n[![npm qsys-qrc](https://img.shields.io/npm/v/qsys-qrc.svg?label=qsys-qrc)](https://www.npmjs.com/package/qsys-qrc)\n[![npm qsys-mcp](https://img.shields.io/npm/v/qsys-mcp.svg?label=qsys-mcp)](https://www.npmjs.com/package/qsys-mcp)\n[![npm qsys-mac](https://img.shields.io/npm/v/qsys-mac.svg?label=qsys-mac)](https://www.npmjs.com/package/qsys-mac)\n[![node ≥18](https://img.shields.io/badge/node-%E2%89%A518-brightgreen.svg)](https://nodejs.org)\n[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#licensing)\n\nEvery Q-SYS Core — and Q-SYS Designer in **Emulate mode** — serves QSC's published\n**QRC** protocol (JSON-RPC 2.0 over TCP, port 1710). It's the same external-control\ninterface Crestron/AMX integrations use. These tools speak it natively: **zero QSC\ncode, no SDK, no hardware required for development.**\n\n| Package | What it is |\n|---|---|\n| [`qsys-cli`](packages/qsys) | CLI (command: `qsys`) — status, component inventory, get/set controls with ramps, live watch, snapshots |\n| [`qsys-qrc`](packages/qsys-qrc) | TypeScript QRC client — wire framing, change groups, keepalive, transparent auto-reconnect, typed protocol surface |\n| [`qsys-mcp`](packages/qsys-mcp) | [MCP](https://modelcontextprotocol.io) server (`io.github.reowens/qsys-mcp` in the MCP Registry) — 18 tools that let an AI agent inspect and drive a live Q-SYS system |\n| [`qsys-mac`](packages/qsys-mac) | npm bootstrapper (command: `qsys-mac`) — downloads/verifies the signed Q-SYS Mac Installer DMG and delegates to its helper |\n| [`qsys-mac-installer`](packages/qsys-mac-installer) | **Q-SYS Designer for macOS** — signed/notarized BYO-installer wrapper app + DMG source |\n\n## Quick start — shell\n\n```sh\nexport QSYS_HOST=192.168.1.10     # your Core, or 127.0.0.1 for Designer Emulate\n\nnpx qsys-cli status               # engine/design status\nnpx qsys-cli ls                   # list components\nnpx qsys-cli get MainGain         # read a named control\nnpx qsys-cli set MainGain -6 --ramp 2\nnpx qsys-cli watch MainGain       # stream changes until Ctrl-C\nnpx qsys-cli snapshot load Bank 1 --ramp 1\n```\n\n```\n$ qsys status\nDesign     RobertOwens-L1 (code Hd4b6C9TXKzL)\nPlatform   Emulator (emulator)\nState      Active\n\n$ qsys set-component Main_Mixer input.1.gain -6 --ramp 2\nNAME          VALUE  STRING   POSITION\ninput.1.gain  -6     -6.00dB  0.585\n```\n\nInstall the command globally with `npm i -g qsys-cli` (the binary is plain `qsys`).\nEvery command takes `--json` for scripting; `watch` emits JSON lines.\n\n## Quick start — AI agent (MCP)\n\n```sh\nclaude mcp add qsys -- npx -y qsys-mcp\n```\n\nor in any MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"qsys\": { \"command\": \"npx\", \"args\": [\"-y\", \"qsys-mcp\"] }\n  }\n}\n```\n\nThen ask the agent to connect to your Core (or the Designer emulator) and it can read\nmeters, flip mutes, ramp gains, watch controls for changes, and recall snapshots —\nwith auto-reconnect across Core restarts. Details in\n[`packages/qsys-mcp`](packages/qsys-mcp).\n\nRegistry-aware MCP clients can discover it as `io.github.reowens/qsys-mcp`.\n\n## Quick start — your own code\n\n```sh\nnpm install qsys-qrc\n```\n\n```ts\nimport { QrcClient } from 'qsys-qrc';\n\nconst qrc = new QrcClient({ host: '192.168.1.10' });\nawait qrc.connect();\n\nconst status = await qrc.statusGet();          // typed helpers…\nawait qrc.setControl('MainGain', -6, 2);       // value -6, 2 s ramp\nconst [gain] = await qrc.getControl(['MainGain']);\n\nawait qrc.send('Component.GetComponents');     // …or raw QRC methods\n\nqrc.close();\n```\n\nChange groups (poll-based watch), component access, snapshots, and logon are all\ncovered by typed helpers — see [`packages/qsys-qrc`](packages/qsys-qrc).\n\n## Q-SYS Designer on your Mac\n\nFor most users, use the signed DMG installer app. Run it once to create `Q-SYS Designer.app`, then\neither trash the installer app or keep it around as a small manager for Launch, Reinstall, and Remove.\nThe installed Designer app and its Application Support data remain independent of the installer app.\n\nDirect DMG path:\n\n```sh\nopen https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4\n```\n\nOr use the npm bootstrapper:\n\n```sh\nnpx qsys-mac install \"/path/to/Q-SYS Designer Installer 10.4.0.exe\"\n```\n\nIt downloads and verifies the signed Q-SYS Mac Installer DMG, mounts it, and runs\nthe bundled helper. The npm package does not contain Q-SYS Designer or the app\npayload. You provide **your own** free Designer installer download (BYO — nothing\nof QSC's is redistributed).\n\nFor read-only support diagnostics, run:\n\n```sh\nnpx qsys-mac doctor\n```\n\nCurrent macOS prerequisite: Rosetta 2. The signed DMG bundles Wine, .NET, `7z`,\nicon tooling, `msiinfo`, and native helper binaries; normal setup does not need\nHomebrew or host Python.\n\nPrefer a GUI installer app? Homebrew can install it:\n\n```sh\nbrew tap reowens/qsys\nbrew trust reowens/qsys\nbrew install --cask qsys-mac-installer\nopen -a \"Q-SYS Mac Installer\"\n```\n\n`brew trust` is required by current Homebrew for third-party cask taps.\n\nThe signed installer source lives in\n[`packages/qsys-mac-installer`](packages/qsys-mac-installer). It provisions Wine +\n.NET into Application Support and gives you a real Dock/Finder/menu-bar citizen.\nThe current signed DMG is\n[`qsys-mac-installer 0.1.4`](https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4).\n\nBonus: Designer's **Emulate mode** serves QRC on `127.0.0.1:1710`, so all of the\ntools above work hardware-free against it — that's how this repo's tooling is\nvalidated.\n\n## No hardware?\n\nPoint any of the tools at Q-SYS Designer running in Emulate mode (`--host\n127.0.0.1`). Two protocol facts worth knowing: QRC has no method to *enumerate*\nnamed controls or snapshot banks (you need their names from the design), and\n`Component.GetComponents` returns only components with script access enabled.\n\n## Development\n\nThis is a [pnpm](https://pnpm.io) workspace (Node 22.13+; pnpm comes from the\n`packageManager` field via [corepack](https://nodejs.org/api/corepack.html)).\n\n```sh\ngit clone https://github.com/reowens/qsys-tools.git\ncd qsys-tools\ncorepack enable        # provisions the pinned pnpm\npnpm install\npnpm -r build          # builds packages in dependency order (qsys-qrc first)\npnpm run typecheck\npnpm test\n```\n\nThe e2e suites (QRC integration, the MCP-over-mock end-to-end, and the\ntransparent-reconnect/AutoPoll-replay regression) run against\n[`qsys-mock-core`](packages/qsys-mock-core) — an in-repo, design-driven Q-SYS Core\nmock — so `pnpm test` exercises the full protocol with no hardware. Deeper\nconformance testing (validated-against-Designer rendering, ramps/meters, and a\nlibrary of real Q-SYS designs) uses a separate, fuller emulator.\n\n`qsys-mac-installer` builds separately with Xcode — see\n[`packages/qsys-mac-installer`](packages/qsys-mac-installer) (`scripts/package.sh` for the\nsign/notarize pipeline).\n\nMaintainer release steps are documented in [`RELEASE.md`](RELEASE.md).\n\nWhen working from this source checkout, use the workspace script instead of\n`npx qsys-mac` so the local workspace package isn't confused with the published\none:\n\n```sh\npnpm run qsys-mac -- status\npnpm run qsys-mac -- install \"/path/to/Q-SYS Designer Installer 10.4.0.exe\"\n```\n\n## Licensing\n\nThe original `qsys-tools` source code is **MIT** licensed, including the QRC packages, the\n`qsys-mac` npm bootstrapper, and the `qsys-mac-installer` wrapper app.\n\nThe signed macOS installer DMG is a multi-license binary distribution because it bundles\nredistributable third-party components such as Wine, .NET, p7zip, icoutils, `msiinfo`, and their\nruntime libraries. Those components remain under their own licenses and notices; see\n[`packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md`](packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md).\n\nEach package carries its own LICENSE file.\n\n## Disclaimer\n\nThis is an independent open-source project, **not affiliated with, endorsed by, or\nsponsored by QSC, LLC**. \"Q-SYS\" and \"Q-SYS Designer\" are trademarks of QSC, LLC,\nused nominatively. These tools speak the publicly documented QRC protocol and\ncontain no QSC code.\n",
  "bytes": 8404,
  "sha": "905fd4b2b3df409a81202c1efea3376036411a73d0d553bc864a255c67f92d28",
  "repo_slug": "reowens/qsys-tools",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_reowens_qsys_mcp_0bd3632d/readme"
}