crestron-mcp 1.8.1

package/README.md

@@ -0,0 +1,81 @@
+# CrestronMCP client
+
+Control a Crestron 4-Series AV system from Claude, in natural language. This is the
+client half of [CrestronMCP](https://solutionav.com.au/crestron-mcp/): an MCP server
+that connects Claude (Desktop or Code) to a processor running the CrestronMCP modules,
+exposing the system as MCP tools over stdio. It speaks the CrestronMCP text protocol
+(see [`PROTOCOL.md`](PROTOCOL.md)) over TCP, with secure-key + TLS authentication.
+
+The client is **free**. Controlling a processor requires that processor to be licensed
+(or on a free trial). See [Licensing](#licensing). One processor licence is AUD $249
+(inc GST); each processor also gets three free 1-week trials. Get a licence at
+<https://solutionav.com.au/crestron-mcp/>.
+
+## Install
+
+### Claude Desktop (recommended)
+Download `crestron-mcp.mcpb` from <https://solutionav.com.au/crestron-mcp/> and open it
+(or Settings → Extensions → Install). Enter the processor's address and its secure key
+(shown on the MCP Server Config module's `Key` output); the port defaults to `50794`.
+
+### Claude Code / other MCP hosts
+No download needed. Run it straight from npm:
+
+```bash
+claude mcp add crestron \
+  --env CRESTRON_HOST=10.0.1.38 \
+  --env CRESTRON_KEY=<the processor's secure key> \
+  -- npx -y crestron-mcp
+```
+
+## Configuration
+
+Resolved low-to-high: `config.json` next to the entry, environment variables, then CLI
+args (`<host> [port]`).
+
+| Env | Meaning |
+| --- | --- |
+| `CRESTRON_HOST` | processor IP / hostname (required) |
+| `CRESTRON_PORT` | TCP port (default `50794`) |
+| `CRESTRON_KEY`  | secure key (mode 2); enables TLS + authentication |
+| `CRESTRON_AUTH` | password (mode 1 only) |
+| `CRESTRON_TLS`  | force TLS without a key |
+
+## Tools
+
+`discover_crestron_system`, `list_crestron_rooms`, `list_crestron_devices`,
+`query_crestron_device`, `get_crestron_time`, `control_crestron_device`,
+`set_crestron_devices`, `pulse_crestron_device`, `ramp_crestron_device`,
+`cancel_crestron_device`, `get_room_status`, `activate_crestron_license`,
+`get_crestron_license_status`, `start_crestron_trial`.
+
+See [`AGENT_GUIDE.md`](AGENT_GUIDE.md) for how an assistant should use them (timing,
+scenes, ramps, nudge-not-nag licensing etiquette).
+
+## Licensing
+
+The processor must be licensed before it accepts control or query commands. If it isn't,
+every tool returns guidance that includes the processor's **activation code (its MAC)**.
+Two ways forward, both in chat:
+
+- **Free trial**: `start_crestron_trial` (no payment; up to 3 × 1 week per processor).
+- **Buy**: get a key for that MAC at <https://solutionav.com.au/crestron-mcp/>, paste it
+  in chat, and the assistant calls `activate_crestron_license`.
+
+The licence is stored **on the processor** (bound to its MAC), so it persists across
+reboots and covers every client. A purchased key only works on that one processor, so it's
+safe to receive in chat.
+
+## Develop
+
+```bash
+npm install
+npm run build      # tsc -> dist/
+npm start          # node dist/index.js
+npm run mcpb       # build the Claude Desktop .mcpb (needs bun)
+```
+
+## License
+
+MIT. See [`LICENSE`](LICENSE). (The client is open; the product is the per-processor
+licence on the box.)

package/dist/config.js

@@ -0,0 +1,71 @@
+/**
+ * Resolve host/port/auth/key/tls. Precedence (low to high): config.json next to
+ * the binary, then environment variables, then CLI args. Mirrors the Python
+ * client's load_config().
+ *
+ *   CRESTRON_HOST / CRESTRON_PORT
+ *   CRESTRON_AUTH    - mode-1 shared password
+ *   CRESTRON_KEY     - mode-2 HMAC key (implies TLS)
+ *   CRESTRON_TLS     - force TLS even without a key
+ *
+ * Licensing is NOT configured here: it lives on the processor, installed once via the
+ * activate_crestron_license tool (the LLM walks the user through it in chat).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+function truthy(v) {
+    return ["1", "true", "yes", "on"].includes(String(v).trim().toLowerCase());
+}
+export function loadConfig(argv = process.argv.slice(2)) {
+    let host = "192.168.1.100";
+    let port = 50794;
+    let auth = "";
+    let key = "";
+    let tls = false;
+    // config.json next to the build output, or one level up (project root / next
+    // to a packaged binary).
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const path of [join(here, "config.json"), join(here, "..", "config.json")]) {
+        try {
+            const cfg = JSON.parse(readFileSync(path, "utf8"));
+            const c = cfg.crestron ?? {};
+            if (c.host !== undefined)
+                host = String(c.host);
+            if (c.port !== undefined)
+                port = Number(c.port);
+            if (c.auth !== undefined)
+                auth = String(c.auth);
+            if (c.key !== undefined)
+                key = String(c.key);
+            if (c.tls !== undefined)
+                tls = Boolean(c.tls);
+            break;
+        }
+        catch {
+            /* not found / unreadable - fall through to env + args */
+        }
+    }
+    const env = process.env;
+    // Empty strings are ignored for host/port (a packaged .mcpb may inject blank
+    // env vars for unset optional fields; CRESTRON_PORT="" must not become 0).
+    if (env.CRESTRON_HOST)
+        host = env.CRESTRON_HOST;
+    if (env.CRESTRON_PORT) {
+        const n = Number(env.CRESTRON_PORT);
+        if (Number.isFinite(n) && n > 0)
+            port = n;
+    }
+    // Credentials: a defined-but-empty value legitimately means "no credential".
+    if (env.CRESTRON_AUTH !== undefined)
+        auth = env.CRESTRON_AUTH;
+    if (env.CRESTRON_KEY !== undefined)
+        key = env.CRESTRON_KEY;
+    if (env.CRESTRON_TLS !== undefined)
+        tls = truthy(env.CRESTRON_TLS);
+    if (argv[0])
+        host = argv[0];
+    if (argv[1])
+        port = Number(argv[1]);
+    return { host, port, auth, key, tls };
+}