siglent-sdg-mcp 1.0.0 → 2.0.3

package/README.md

@@ -1,20 +1,29 @@
 # siglent-sdg-mcp
 
+[![CI](https://github.com/MagnusJohansson/siglent-sdg-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MagnusJohansson/siglent-sdg-mcp/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/MagnusJohansson/siglent-sdg-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/MagnusJohansson/siglent-sdg-mcp/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/MagnusJohansson/siglent-sdg-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/MagnusJohansson/siglent-sdg-mcp)
+[![npm](https://img.shields.io/npm/v/siglent-sdg-mcp)](https://www.npmjs.com/package/siglent-sdg-mcp)
+[![License: MIT](https://img.shields.io/github/license/MagnusJohansson/siglent-sdg-mcp)](LICENSE)
+
 A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that lets AI assistants control Siglent SDG waveform generators over your local network. Connect Claude to your bench and generate, modulate, and configure signals through natural language.
 
 ## Overview
 
 This MCP server communicates with Siglent SDG waveform generators via SCPI commands over TCP sockets (port 5025). No VISA drivers or NI-MAX installation required — just a network connection to your generator.
 
+![Oscilloscope screenshot captured via MCP](docs/Siglent-SDG-1032X.jpeg)
+
 **Key features:**
 
-- 21 tools covering output control, waveform generation, modulation, sweep, burst, arbitrary waveforms, and more
+- 20 tools covering output control, waveform generation, modulation, sweep, burst, arbitrary waveforms, and more (21 with the opt-in raw SCPI tool)
 - Dual-channel support (C1 and C2)
 - 8 waveform types: sine, square, ramp, pulse, noise, arbitrary, DC, PRBS
 - 8 modulation types: AM, DSB-AM, FM, PM, PWM, ASK, FSK, PSK
 - Auto-connect on startup via environment variable
 - Query queue serializes commands automatically — tools can safely run in parallel
-- Raw SCPI escape hatch for any command not covered by the built-in tools
+- Read-only SCPI query escape hatch; raw SCPI commands are opt-in
+- Security guardrails: command-injection protection, query-only `scpi_query`, connect-target allowlist (see [Security](#security))
 
 ## Compatibility
 
@@ -105,12 +114,14 @@ Replace `/path/to/siglent-sdg-mcp` with the actual path to your clone.
 | `SIGLENT_IP` | No | — | Fallback if `SIGLENT_SDG_IP` is not set |
 | `SIGLENT_SDG_PORT` | No | `5025` | TCP port (only change if your setup differs) |
 | `SIGLENT_PORT` | No | `5025` | Fallback if `SIGLENT_SDG_PORT` is not set |
+| `SIGLENT_ALLOWED_HOSTS` | No | — | Comma-separated hosts the `connect` tool may use, in addition to `SIGLENT_SDG_IP`. `*` allows any host (not recommended). See [Security](#security) |
+| `SIGLENT_ALLOW_RAW_SCPI` | No | `false` | Register the raw `scpi_command` tool. Requires `SIGLENT_SDG_IP` or `SIGLENT_ALLOWED_HOSTS` naming specific hosts (`*` is not accepted) |
 
 ### Auto-Connect Behavior
 
 If `SIGLENT_SDG_IP` (or `SIGLENT_IP`) is set, the server attempts to connect to the generator immediately after starting. This runs in the background and does **not** block the MCP server — Claude can start using other tools right away. If the generator is offline or unreachable, the server logs a warning and you can connect manually later using the `connect` tool.
 
-If neither variable is set, the server starts without a connection. Use the `connect` tool to connect when ready.
+If neither variable is set, the server starts without a connection. Use the `connect` tool to connect when ready. In that case `connect` only accepts private-LAN IP addresses; see [Security](#security).
 
 ## Using with Other AI Clients
 
@@ -294,7 +305,7 @@ ChatGPT Desktop only supports remote HTTPS MCP servers (called "connectors"), no
 
 ## Tools
 
-21 tools across 9 categories.
+20 tools across 9 categories by default; `scpi_command` is only registered when `SIGLENT_ALLOW_RAW_SCPI=true`.
 
 | Category | Tool | Description |
 |----------|------|-------------|
@@ -317,8 +328,8 @@ ChatGPT Desktop only supports remote HTTPS MCP servers (called "connectors"), no
 | | `copy_channel` | Copy all parameters from one channel to another |
 | | `configure_sync` | Configure sync output signal |
 | | `equal_phase` | Synchronize phase of both channels |
-| SCPI | `scpi_query` | Send arbitrary SCPI query and return the response |
-| | `scpi_command` | Send arbitrary SCPI command (no response expected) |
+| SCPI | `scpi_query` | Send a read-only SCPI query (single header ending in `?`) and return the response |
+| | `scpi_command` | *Opt-in.* Send a single raw SCPI command (no response expected) |
 
 ## Example Conversations
 
@@ -358,6 +369,26 @@ ChatGPT Desktop only supports remote HTTPS MCP servers (called "connectors"), no
 >
 > Claude calls `configure_burst` with `channel: "C1"`, `state: "ON"`, `burst_mode: "NCYC"`, `cycles: "5"`, `trigger_source: "EXT"`.
 
+## Security
+
+An MCP server turns a language model's output into actions. For this server those actions are physical: a wrong command can put 20 Vpp into a 3.3 V circuit. Tool arguments are therefore treated as **untrusted input**, whether they came from your request, from a document the model read, or from a prompt injection.
+
+What the server enforces, regardless of what the model was told:
+
+| Guardrail | What it prevents |
+|-----------|------------------|
+| **Command-boundary check** on every string written to the socket: no control characters (incl. newlines), no `;`, ASCII only, max 512 chars | Smuggling extra SCPI commands through any parameter (`load: "50\nC1:OUTP ON"`) |
+| **Strict parameter formats** for the free-text parameters (`load`, `cycles`, arbitrary waveform `name`) | Breaking out of a parameter or a quoted string |
+| **`scpi_query` is query-only**: a single header ending in `?`; parameters after `?` only for queries documented to take them (`STL?`, `MMEMory:CATalog?`), and only in their documented forms; common commands only as pure queries (`*IDN?`, `*OPC?`, ...) | Using the "read-only" tool to change state (`scpi_query("C1:OUTP ON")`, `"C1:BSWV? AMP,10"`, `"*RST?"`) |
+| **Raw `scpi_command` is off by default**, and can only be enabled together with named instrument hosts (`*` is not accepted) | An unrestricted command channel to the instrument, or to other SCPI devices on the LAN (power supplies often use port 5025 too) |
+| **Connect allowlist**: `connect` only reaches `SIGLENT_SDG_IP`, `SIGLENT_ALLOWED_HOSTS`, or (if neither is set) private-LAN IP addresses, and only the instrument port | Using the server as a TCP client to reach other services, e.g. `169.254.169.254` |
+**What it does not protect against:**
+
+- **Output voltage.** This server does **not** limit amplitude or offset. The model can set anything the generator allows, up to 20 Vpp. To protect a circuit, set the generator's own limit on the front panel or with `C1:BSWV MAX_OUTPUT_AMP,<Vpp>` (on models that support it). **This backstop only holds while raw SCPI is off**: with `SIGLENT_ALLOW_RAW_SCPI=true`, the model can send `MAX_OUTPUT_AMP` itself and raise the limit. Whether `reset` (`*RST`) restores the generator's default limit isn't documented; check it on your model before relying on the backstop. Server-side limits are being designed separately: a first version was reviewed and found to be bypassable, so it isn't shipped (see the threat model).
+- **Other clients on port 5025.** Anyone with network access to the instrument can control it directly, without going through this server. The instrument has no authentication. Network segmentation is the control for that.
+
+The full threat model, including residual risks, is in [docs/threat-model.md](docs/threat-model.md).
+
 ## Architecture
 
 ```
@@ -368,6 +399,7 @@ Claude Code <-- stdio/JSON-RPC --> siglent-sdg-mcp <-- TCP/SCPI --> Generator:50
 - **Protocol:** SCPI commands over raw TCP sockets, newline-terminated
 - **Query Queue:** All SCPI queries are serialized through an internal queue. The generator processes one command at a time, so even when tools issue parallel requests, the queue ensures they're sent sequentially.
 - **Auto-Connect:** If `SIGLENT_SDG_IP` is set, connects in the background on startup without blocking the MCP server.
+- **Security choke point:** every command and query passes through `connection.ts`, which applies the checks in `src/security/` before anything is written to the socket.
 
 ## Development
 
@@ -376,8 +408,27 @@ npm run build       # Compile TypeScript
 npm run watch       # Watch mode — recompile on changes
 npm run dev         # Build and run
 npm run inspector   # Launch with MCP Inspector for debugging
+npm test            # Unit tests + end-to-end tests against the SCPI simulator
+```
+
+The end-to-end tests run the real server and connection code over a real TCP socket against a small SCPI simulator (`tests/simulator/`), so no hardware is needed. Security tests assert on what actually reached the simulator, not only on the error returned.
+
+To check against real hardware (never turns an output on, aborts unless both outputs are off, because channel coupling can carry C1 changes to C2, uses 1 Vpp on C1, and changes C1's waveform settings):
+
+```bash
+npm run hardware-check -- 192.168.1.126
 ```
 
+### Releasing
+
+Publishing is triggered by **publishing a GitHub Release**, not by pushing a tag:
+
+1. Bump `version` in `package.json` and add a section to `CHANGELOG.md`, then merge to `main`.
+2. Create a release (draft first) with tag `vX.Y.Z` on `main`, using the changelog section as the release notes.
+3. Publish the release. This runs the npm publish (tests first, with provenance) and the GHCR image build.
+
+The npm workflow fails if the tag doesn't match the `package.json` version. A pre-release publishes to the npm `next` dist-tag, and doesn't move the Docker `latest` tag. A draft release publishes nothing.
+
 ### Docker (local build)
 
 Build the image locally:
@@ -408,8 +459,13 @@ Then use the local image in your `.mcp.json`:
 
 ```
 src/
-  index.ts              # Entry point, MCP server setup
-  connection.ts         # TCP socket manager with query queue
+  index.ts              # Entry point: stdio transport, auto-connect
+  server.ts             # MCP server factory, tool registration
+  config.ts             # Environment parsing, effective security settings
+  connection.ts         # TCP socket manager with query queue (security choke point)
+  security/
+    scpi-guard.ts       # Command-boundary and query-only checks
+    host-policy.ts      # Connect-target allowlist
   tools/
     connection.ts       # connect, disconnect, identify
     output.ts           # get_output, configure_output
@@ -419,7 +475,11 @@ src/
     burst.ts            # get_burst, configure_burst
     arbitrary.ts        # get_arbitrary_wave, set_arbitrary_wave
     utility.ts          # reset, copy_channel, configure_sync, equal_phase
-    scpi.ts             # scpi_query, scpi_command
+    scpi.ts             # scpi_query, scpi_command (opt-in)
+tests/
+  unit/                 # Guard, host policy and config tests
+  integration/          # End-to-end security tests via MCP client
+  simulator/            # SCPI simulator (TCP)
 ```
 
 ## Troubleshooting
@@ -433,12 +493,14 @@ The generator isn't connected yet. Either set `SIGLENT_SDG_IP` in your `.mcp.jso
 - Verify the generator's IP address (check the generator's Utility > Interface menu)
 - Ensure port 5025 is accessible (try `telnet <generator-ip> 5025` from your machine)
 - Check that no firewall is blocking the connection
-- The generator only accepts one TCP connection at a time — close any other SCPI clients
+- Close other SCPI clients (another MCP server instance, a second Claude session, NI-MAX, scripts). The SDG1032X accepts more than one TCP connection, so a second client does not fail to connect. It interferes instead (see below)
 
 ### Query timeout
 
 Some SCPI queries can take a few seconds. The default timeout is 5 seconds. For `scpi_query`, you can increase the timeout with the `timeout_ms` parameter.
 
+Timeouts on queries that normally answer instantly (`identify`, `get_output`) usually mean **another client is talking to the generator at the same time**. A common cause is a second Claude Code session whose MCP config also starts this server with `SIGLENT_SDG_IP` set, so both auto-connect. The server serializes its own queries, but it can't coordinate with other processes, and their commands and replies interleave on the instrument. Close the other client and reconnect.
+
 ### Docker: can't reach the waveform generator
 
 By default, Docker containers can reach LAN devices via the bridge network (NAT). If the container can't connect to your generator:

package/build/config.d.ts

@@ -0,0 +1,12 @@
+import type { HostPolicy } from "./security/host-policy.js";
+export interface ServerConfig {
+    /** Instrument address used for auto-connect and as the default for `connect`. */
+    defaultHost?: string;
+    defaultPort: number;
+    hostPolicy: HostPolicy;
+    /** Whether the raw `scpi_command` tool is registered. */
+    rawScpiEnabled: boolean;
+    /** Human-readable notes about the effective configuration, logged at startup. */
+    notes: string[];
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): ServerConfig;

package/build/config.js

@@ -0,0 +1,56 @@
+const DEFAULT_PORT = 5025;
+function parsePort(name, value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new Error(`${name} must be a TCP port (1-65535), got "${value}".`);
+    }
+    return n;
+}
+function isTrue(value) {
+    return value !== undefined && ["1", "true", "yes", "on"].includes(value.trim().toLowerCase());
+}
+export function loadConfig(env = process.env) {
+    const notes = [];
+    const defaultHost = (env.SIGLENT_SDG_IP || env.SIGLENT_IP || "").trim() || undefined;
+    const defaultPort = parsePort("SIGLENT_SDG_PORT", env.SIGLENT_SDG_PORT) ??
+        parsePort("SIGLENT_PORT", env.SIGLENT_PORT) ??
+        DEFAULT_PORT;
+    // Connect-target policy: the configured instrument plus any explicitly
+    // allowed hosts. If neither is set, only private-LAN IP literals are accepted.
+    const allowedHosts = (env.SIGLENT_ALLOWED_HOSTS ?? "")
+        .split(",")
+        .map((h) => h.trim())
+        .filter((h) => h.length > 0);
+    if (defaultHost && !allowedHosts.includes(defaultHost)) {
+        allowedHosts.push(defaultHost);
+    }
+    if (allowedHosts.includes("*")) {
+        notes.push("WARNING: SIGLENT_ALLOWED_HOSTS=* allows connecting to any host.");
+    }
+    // Raw SCPI turns `connect` into a general command channel. Without an
+    // explicit host list, `connect` falls back to "any private-LAN IP on the
+    // instrument port", which also matches bench power supplies and electronic
+    // loads (they commonly use 5025 too). So raw SCPI requires named hosts,
+    // and "*" doesn't name one.
+    const rawScpiEnabled = isTrue(env.SIGLENT_ALLOW_RAW_SCPI);
+    if (rawScpiEnabled && (allowedHosts.length === 0 || allowedHosts.includes("*"))) {
+        throw new Error("SIGLENT_ALLOW_RAW_SCPI requires SIGLENT_SDG_IP or SIGLENT_ALLOWED_HOSTS naming specific " +
+            "hosts ('*' is not accepted), so raw commands can only reach instruments you have named.");
+    }
+    if (rawScpiEnabled) {
+        notes.push("WARNING: raw scpi_command tool enabled; the model can send any SCPI command.");
+    }
+    return {
+        defaultHost,
+        defaultPort,
+        hostPolicy: {
+            allowedHosts,
+            allowedPorts: [...new Set([DEFAULT_PORT, defaultPort])],
+        },
+        rawScpiEnabled,
+        notes,
+    };
+}
+//# sourceMappingURL=config.js.map

package/build/connection.d.ts

@@ -11,13 +11,18 @@ export declare class SiglentConnection {
     private headerParsed;
     private queryQueue;
     private queryRunning;
+    /**
+     * Incremented on every connect(). An attempt that has been superseded by a
+     * newer one (e.g. auto-connect still initializing when the `connect` tool is
+     * called) must not touch the shared socket, and must not disconnect it.
+     */
+    private connectGeneration;
     connect(host: string, port?: number): Promise<string>;
     disconnect(): void;
     isConnected(): boolean;
     getConnectionInfo(): string;
     sendCommand(cmd: string): Promise<void>;
     query(cmd: string, timeout?: number): Promise<string>;
-    queryBinary(cmd: string, timeout?: number): Promise<Buffer>;
     private enqueueQuery;
     private drainQueue;
     private setupSocketListeners;

package/build/connection.js

@@ -1,7 +1,7 @@
 import * as net from "node:net";
+import { assertIsQuery, assertWireSafe } from "./security/scpi-guard.js";
 const DEFAULT_PORT = 5025;
 const DEFAULT_TIMEOUT = 5000;
-const BINARY_TIMEOUT = 30000;
 export class SiglentConnection {
     socket = null;
     host = "";
@@ -15,7 +15,15 @@ export class SiglentConnection {
     headerParsed = false;
     queryQueue = [];
     queryRunning = false;
+    /**
+     * Incremented on every connect(). An attempt that has been superseded by a
+     * newer one (e.g. auto-connect still initializing when the `connect` tool is
+     * called) must not touch the shared socket, and must not disconnect it.
+     */
+    connectGeneration = 0;
     async connect(host, port = DEFAULT_PORT) {
+        const generation = ++this.connectGeneration;
+        const superseded = () => generation !== this.connectGeneration;
         if (this.socket) {
             this.disconnect();
         }
@@ -29,12 +37,19 @@ export class SiglentConnection {
             }, 5000);
             socket.on("connect", async () => {
                 clearTimeout(connectTimeout);
+                if (superseded()) {
+                    socket.destroy();
+                    reject(new Error("Connection attempt superseded by a newer connect."));
+                    return;
+                }
                 socket.removeAllListeners("error");
                 this.socket = socket;
                 this.setupSocketListeners();
                 try {
                     // Drain any welcome banner
                     await this.delay(200);
+                    if (superseded())
+                        throw new Error("superseded by a newer connect");
                     this.dataBuffer = Buffer.alloc(0);
                     // Try to set CHDR OFF for clean responses (not all SDG models support it)
                     try {
@@ -44,12 +59,19 @@ export class SiglentConnection {
                     catch {
                         // Some models don't support CHDR — that's OK
                     }
+                    if (superseded())
+                        throw new Error("superseded by a newer connect");
                     // Query identification
                     const idn = await this.query("*IDN?");
+                    if (superseded())
+                        throw new Error("superseded by a newer connect");
                     resolve(idn);
                 }
                 catch (err) {
-                    this.disconnect();
+                    // Only the current attempt may tear down the shared connection;
+                    // a superseded one would otherwise kill the newer socket.
+                    if (!superseded())
+                        this.disconnect();
                     reject(new Error(`Connected but failed to initialize: ${err instanceof Error ? err.message : String(err)}`));
                 }
             });
@@ -86,6 +108,9 @@ export class SiglentConnection {
         return `${this.host}:${this.port}`;
     }
     async sendCommand(cmd) {
+        // The connection is the single choke point to the instrument, so this
+        // check applies regardless of which tool built the command.
+        assertWireSafe(cmd);
         this.ensureConnected();
         return new Promise((resolve, reject) => {
             this.socket.write(cmd + "\n", (err) => {
@@ -97,14 +122,13 @@ export class SiglentConnection {
         });
     }
     async query(cmd, timeout = DEFAULT_TIMEOUT) {
+        // A query must be structurally a query; otherwise "C1:OUTP ON" sent via a
+        // read-only tool would change state and simply time out waiting for a reply.
+        assertIsQuery(cmd);
         this.ensureConnected();
         const buf = await this.enqueueQuery(cmd, false, timeout);
         return buf.toString("utf-8").trim();
     }
-    async queryBinary(cmd, timeout = BINARY_TIMEOUT) {
-        this.ensureConnected();
-        return this.enqueueQuery(cmd, true, timeout);
-    }
     enqueueQuery(cmd, binary, timeout) {
         return new Promise((resolve, reject) => {
             this.queryQueue.push({ cmd, binary, timeout, resolve, reject });

package/build/index.js

@@ -1,16 +1,9 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { registerConnectionTools } from "./tools/connection.js";
-import { registerOutputTools } from "./tools/output.js";
-import { registerBasicWaveTools } from "./tools/basic-wave.js";
-import { registerModulationTools } from "./tools/modulation.js";
-import { registerSweepTools } from "./tools/sweep.js";
-import { registerBurstTools } from "./tools/burst.js";
-import { registerArbitraryTools } from "./tools/arbitrary.js";
-import { registerUtilityTools } from "./tools/utility.js";
-import { registerScpiTools } from "./tools/scpi.js";
+import { loadConfig } from "./config.js";
 import { connection } from "./connection.js";
+import { assertConnectAllowed } from "./security/host-policy.js";
+import { createServer } from "./server.js";
 // Prevent uncaught errors from killing the MCP server process
 process.on("uncaughtException", (err) => {
     console.error("Uncaught exception:", err);
@@ -18,29 +11,34 @@ process.on("uncaughtException", (err) => {
 process.on("unhandledRejection", (reason) => {
     console.error("Unhandled rejection:", reason);
 });
-const server = new McpServer({
-    name: "siglent-sdg-mcp",
-    version: "1.0.0",
-});
-// Register all tool groups
-registerConnectionTools(server);
-registerOutputTools(server);
-registerBasicWaveTools(server);
-registerModulationTools(server);
-registerSweepTools(server);
-registerBurstTools(server);
-registerArbitraryTools(server);
-registerUtilityTools(server);
-registerScpiTools(server);
+// Fail closed on invalid configuration: exit non-zero instead of starting
+// with a security setting silently ignored.
+let config;
+try {
+    config = loadConfig();
+}
+catch (err) {
+    console.error(`Configuration error: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}
+for (const note of config.notes) {
+    console.error(note);
+}
+const server = createServer(config);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("siglent-sdg-mcp server running on stdio");
     // Auto-connect if env var is set (fire-and-forget, don't block MCP startup)
-    const autoIp = process.env.SIGLENT_SDG_IP || process.env.SIGLENT_IP;
+    const autoIp = config.defaultHost;
     if (autoIp) {
-        const port = parseInt(process.env.SIGLENT_SDG_PORT || process.env.SIGLENT_PORT || "5025", 10);
-        connection.connect(autoIp, port).then((idn) => console.error(`Auto-connected to ${autoIp}: ${idn}`), (err) => {
+        const port = config.defaultPort;
+        Promise.resolve()
+            .then(() => {
+            assertConnectAllowed(autoIp, port, config.hostPolicy);
+            return connection.connect(autoIp, port);
+        })
+            .then((idn) => console.error(`Auto-connected to ${autoIp}: ${idn}`), (err) => {
             console.error(`Auto-connect to ${autoIp} failed: ${err instanceof Error ? err.message : String(err)}`);
             console.error("Use the 'connect' tool to connect manually.");
         });

package/build/security/host-policy.d.ts

@@ -0,0 +1,16 @@
+export interface HostPolicy {
+    /**
+     * Exact host names / IPs that may be connected to. "*" allows any host.
+     * When empty, only private-LAN IP literals are allowed.
+     */
+    allowedHosts: string[];
+    /** Ports that may be connected to. */
+    allowedPorts: number[];
+}
+/**
+ * Private-LAN ranges where bench instruments live (RFC 1918 and IPv6 ULA).
+ * Deliberately excluded: loopback (local services) and link-local
+ * 169.254.0.0/16 (includes cloud metadata endpoints such as 169.254.169.254).
+ */
+export declare function isPrivateLanAddress(host: string): boolean;
+export declare function assertConnectAllowed(host: string, port: number, policy: HostPolicy): void;

package/build/security/host-policy.js

@@ -0,0 +1,57 @@
+/**
+ * Connect-target policy.
+ *
+ * The `connect` tool lets the model choose a host and port. Without host and
+ * port restrictions, that plus a raw-command tool is a general-purpose TCP client: the model
+ * (or anyone who can steer it via prompt injection) could reach any service
+ * the server can reach and write arbitrary lines to it.
+ */
+import * as net from "node:net";
+import { ScpiPolicyError } from "./scpi-guard.js";
+function ipv4ToInt(ip) {
+    return ip.split(".").reduce((acc, octet) => (acc << 8) + Number(octet), 0) >>> 0;
+}
+function inCidr(ip, base, bits) {
+    const mask = bits === 0 ? 0 : (~0 << (32 - bits)) >>> 0;
+    return (ipv4ToInt(ip) & mask) === (ipv4ToInt(base) & mask);
+}
+/**
+ * Private-LAN ranges where bench instruments live (RFC 1918 and IPv6 ULA).
+ * Deliberately excluded: loopback (local services) and link-local
+ * 169.254.0.0/16 (includes cloud metadata endpoints such as 169.254.169.254).
+ */
+export function isPrivateLanAddress(host) {
+    if (net.isIPv4(host)) {
+        return (inCidr(host, "10.0.0.0", 8) ||
+            inCidr(host, "172.16.0.0", 12) ||
+            inCidr(host, "192.168.0.0", 16));
+    }
+    if (net.isIPv6(host)) {
+        const first = host.toLowerCase().split(":")[0];
+        // fc00::/7 (unique local addresses)
+        return /^f[cd][0-9a-f]{2}$/.test(first);
+    }
+    return false;
+}
+export function assertConnectAllowed(host, port, policy) {
+    if (!Number.isInteger(port) || !policy.allowedPorts.includes(port)) {
+        throw new ScpiPolicyError(`Port ${port} is not allowed. Allowed ports: ${policy.allowedPorts.join(", ")}. ` +
+            "Configure SIGLENT_SDG_PORT to use a different instrument port.");
+    }
+    if (policy.allowedHosts.includes("*"))
+        return;
+    if (policy.allowedHosts.length > 0) {
+        const normalized = host.trim().toLowerCase();
+        if (!policy.allowedHosts.some((h) => h.toLowerCase() === normalized)) {
+            throw new ScpiPolicyError(`Host "${host}" is not in the allowed list. ` +
+                "Set SIGLENT_ALLOWED_HOSTS (comma-separated) to allow additional instruments.");
+        }
+        return;
+    }
+    if (!isPrivateLanAddress(host)) {
+        throw new ScpiPolicyError(`Host "${host}" is not allowed. Without SIGLENT_ALLOWED_HOSTS, only private-LAN IP ` +
+            "addresses (10/8, 172.16/12, 192.168/16, fc00::/7) are accepted; host names, loopback " +
+            "and link-local addresses are rejected.");
+    }
+}
+//# sourceMappingURL=host-policy.js.map

package/build/security/scpi-guard.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SCPI guard: checks applied to every string before it is written to the
+ * instrument socket.
+ *
+ * Tool arguments come from a language model and must be treated as untrusted
+ * input. The connection layer is the single choke point every command and
+ * query passes through, so these checks live there rather than in each tool.
+ */
+/** Raised when a command or argument violates the security policy. */
+export declare class ScpiPolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject anything that could smuggle a second command onto the wire.
+ *
+ * - Control characters (incl. \n and \r): the connection terminates every
+ *   command with "\n", so an embedded newline would start a new command.
+ * - ';': the SCPI compound-command separator ("C1:OUTP?;C1:OUTP ON").
+ * - Non-printable or non-ASCII bytes: SCPI is ASCII; nothing legitimate needs them.
+ */
+export declare function assertWireSafe(cmd: string): void;
+export declare function assertIsQuery(cmd: string): void;

package/build/security/scpi-guard.js

@@ -0,0 +1,105 @@
+/**
+ * SCPI guard: checks applied to every string before it is written to the
+ * instrument socket.
+ *
+ * Tool arguments come from a language model and must be treated as untrusted
+ * input. The connection layer is the single choke point every command and
+ * query passes through, so these checks live there rather than in each tool.
+ */
+/** Raised when a command or argument violates the security policy. */
+export class ScpiPolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScpiPolicyError";
+    }
+}
+/**
+ * Reject anything that could smuggle a second command onto the wire.
+ *
+ * - Control characters (incl. \n and \r): the connection terminates every
+ *   command with "\n", so an embedded newline would start a new command.
+ * - ';': the SCPI compound-command separator ("C1:OUTP?;C1:OUTP ON").
+ * - Non-printable or non-ASCII bytes: SCPI is ASCII; nothing legitimate needs them.
+ */
+export function assertWireSafe(cmd) {
+    if (cmd.length === 0) {
+        throw new ScpiPolicyError("Empty SCPI command.");
+    }
+    if (cmd.length > 512) {
+        throw new ScpiPolicyError("SCPI command too long (max 512 characters).");
+    }
+    for (let i = 0; i < cmd.length; i++) {
+        const code = cmd.charCodeAt(i);
+        if (code < 0x20 || code > 0x7e) {
+            throw new ScpiPolicyError(`SCPI command contains a control or non-ASCII character at position ${i} (code ${code}). ` +
+                "Embedded newlines would inject additional commands.");
+        }
+    }
+    if (cmd.includes(";")) {
+        throw new ScpiPolicyError("SCPI compound commands (';') are not allowed. Send one command per call.");
+    }
+}
+/**
+ * Query shape: an optional root colon or '*', a header, then '?' immediately
+ * after it, optionally followed by parameters.
+ *
+ * This is a structural check (allowlist of shape), not a denylist of setter
+ * keywords, so long-form headers or unusual setters cannot slip through:
+ * anything without '?' directly after the header is not a query.
+ */
+const QUERY_PATTERN = /^(\*|:)?([A-Za-z][A-Za-z0-9_:]*)\?(?: ([A-Za-z0-9_,.+\-"/ ]*))?$/;
+/**
+ * Queries that legitimately take parameters after the '?', each with the
+ * exact parameter shapes the SDG programming guide documents. For any other
+ * query, trailing parameters are rejected: whether the instrument ignores
+ * them or acts on them ("C1:BSWV? FRQ,1234") is firmware-dependent, so they
+ * are not allowed through a tool that promises to be read-only.
+ *
+ * WVDT? is deliberately absent: its reply is binary waveform data, which the
+ * text query path can't frame, and its parameters overlap the WVDT setter.
+ */
+const QUOTED_PATH = '"[A-Za-z0-9_\\-./ ]{1,64}"';
+const QUERY_PARAMETER_RULES = [
+    {
+        // STL?, STL? BUILDIN, STL? USER, STL? USER,"net_storage/wave"
+        name: "STL?",
+        header: /^(STL|STORELIST)$/i,
+        params: new RegExp(`^(BUILDIN|USER(,${QUOTED_PATH})?)$`, "i"),
+    },
+    {
+        // MMEMory:CATalog? "Local" (and the :DATA:ARBitrary / :STATe:XMLanguage variants)
+        name: "MMEMory:CATalog?",
+        header: /^MMEM(ORY)?:CAT(ALOG)?(:DATA:ARB(ITRARY)?|:STAT(E)?:XML(ANGUAGE)?)?$/i,
+        params: new RegExp(`^${QUOTED_PATH}$`),
+    },
+];
+/**
+ * IEEE 488.2 common commands that are pure queries. Others that accept a '?'
+ * form (*RST?, *TST?, *CLS?) are actions, or would run a self-test.
+ */
+const COMMON_QUERIES = new Set(["IDN", "OPC", "ESR", "STB", "ESE", "SRE", "OPT"]);
+export function assertIsQuery(cmd) {
+    assertWireSafe(cmd);
+    const m = QUERY_PATTERN.exec(cmd.trim());
+    if (!m) {
+        throw new ScpiPolicyError(`Not a SCPI query: "${cmd}". A query must be a single header ending in '?' ` +
+            "(e.g. 'C1:BSWV?'). Commands that change instrument state are not allowed here.");
+    }
+    const [, prefix, header, params] = m;
+    const name = header.toUpperCase();
+    if (prefix === "*" && !COMMON_QUERIES.has(name)) {
+        throw new ScpiPolicyError(`"*${name}?" is not allowed: only the common queries ` +
+            `${[...COMMON_QUERIES].map((q) => `*${q}?`).join(", ")} are permitted.`);
+    }
+    if (params !== undefined && params.trim() !== "") {
+        const rule = QUERY_PARAMETER_RULES.find((r) => r.header.test(header));
+        if (!rule) {
+            throw new ScpiPolicyError(`Parameters after '?' are only allowed for ${QUERY_PARAMETER_RULES.map((r) => r.name).join(", ")}. ` +
+                `"${cmd}" could be interpreted as a command by the instrument.`);
+        }
+        if (!rule.params.test(params.trim())) {
+            throw new ScpiPolicyError(`Parameters "${params.trim()}" are not a documented form for ${rule.name}.`);
+        }
+    }
+}
+//# sourceMappingURL=scpi-guard.js.map

package/build/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServerConfig } from "./config.js";
+export declare const SERVER_VERSION = "2.0.3";
+/** Build the MCP server with all tools registered under the given configuration. */
+export declare function createServer(config: ServerConfig): McpServer;

package/build/server.js

@@ -0,0 +1,29 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerConnectionTools } from "./tools/connection.js";
+import { registerOutputTools } from "./tools/output.js";
+import { registerBasicWaveTools } from "./tools/basic-wave.js";
+import { registerModulationTools } from "./tools/modulation.js";
+import { registerSweepTools } from "./tools/sweep.js";
+import { registerBurstTools } from "./tools/burst.js";
+import { registerArbitraryTools } from "./tools/arbitrary.js";
+import { registerUtilityTools } from "./tools/utility.js";
+import { registerScpiTools } from "./tools/scpi.js";
+export const SERVER_VERSION = "2.0.3";
+/** Build the MCP server with all tools registered under the given configuration. */
+export function createServer(config) {
+    const server = new McpServer({
+        name: "siglent-sdg-mcp",
+        version: SERVER_VERSION,
+    });
+    registerConnectionTools(server, config);
+    registerOutputTools(server);
+    registerBasicWaveTools(server);
+    registerModulationTools(server);
+    registerSweepTools(server);
+    registerBurstTools(server);
+    registerArbitraryTools(server);
+    registerUtilityTools(server);
+    registerScpiTools(server, config);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/build/tools/arbitrary.js

@@ -35,8 +35,9 @@ export function registerArbitraryTools(server) {
             .describe("Index of the built-in arbitrary waveform (0-198). Examples: 0=Sine, 2=StairUp, 10=ExpFal, 18=Sinc, 19=Gaussian, 26=Cardiac"),
         name: z
             .string()
+            .regex(/^[A-Za-z0-9_\-./ ]{1,64}$/, "Name may contain letters, digits, space, '_', '-', '.', '/' (max 64)")
             .optional()
-            .describe('Name of the waveform (for user-defined waves, use quotes). Can also be a path like "Local/wave1.bin"'),
+            .describe('Name of the waveform for user-defined waves (without quotes). Can also be a path like "Local/wave1.bin"'),
     }, { readOnlyHint: false }, async ({ channel, index, name }) => {
         try {
             if (index === undefined && !name) {

package/build/tools/burst.js

@@ -59,6 +59,7 @@ export function registerBurstTools(server) {
             .describe("Trigger edge (when EXT or MAN)"),
         cycles: z
             .string()
+            .regex(/^(INF|\d{1,7})$/i, "Cycles must be an integer or 'INF'")
             .optional()
             .describe("Number of burst cycles (integer, or 'INF' for infinite)"),
         delay: z

package/build/tools/connection.d.ts

@@ -1,2 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerConnectionTools(server: McpServer): void;
+import type { ServerConfig } from "../config.js";
+export declare function registerConnectionTools(server: McpServer, config: ServerConfig): void;

package/build/tools/connection.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
 import { connection } from "../connection.js";
-export function registerConnectionTools(server) {
-    server.tool("connect", "Connect to a Siglent SDG waveform generator over TCP. Returns device identification on success.", {
+import { assertConnectAllowed } from "../security/host-policy.js";
+export function registerConnectionTools(server, config) {
+    server.tool("connect", "Connect to a Siglent SDG waveform generator over TCP. Returns device identification on success. Only hosts and ports allowed by the server configuration can be used.", {
         host: z
             .string()
             .optional()
@@ -11,7 +12,8 @@ export function registerConnectionTools(server) {
             .optional()
             .describe("TCP port (defaults to 5025)"),
     }, { readOnlyHint: false, openWorldHint: true }, async ({ host, port }) => {
-        const targetHost = host || process.env.SIGLENT_SDG_IP || process.env.SIGLENT_IP;
+        const targetHost = host || config.defaultHost;
+        const targetPort = port ?? config.defaultPort;
         if (!targetHost) {
             return {
                 content: [
@@ -24,12 +26,13 @@ export function registerConnectionTools(server) {
             };
         }
         try {
-            const idn = await connection.connect(targetHost, port);
+            assertConnectAllowed(targetHost, targetPort, config.hostPolicy);
+            const idn = await connection.connect(targetHost, targetPort);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Connected to ${targetHost}:${port || 5025}\nDevice: ${idn}`,
+                        text: `Connected to ${targetHost}:${targetPort}\nDevice: ${idn}`,
                     },
                 ],
             };

package/build/tools/output.js

@@ -35,6 +35,7 @@ export function registerOutputTools(server) {
             .describe("Output state: ON or OFF"),
         load: z
             .string()
+            .regex(/^(HZ|\d+(\.\d+)?)$/i, "Load must be 'HZ' or a number of ohms")
             .optional()
             .describe("Load impedance in ohms (50-100000) or 'HZ' for high impedance"),
         polarity: z

package/build/tools/scpi.d.ts

@@ -1,2 +1,3 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerScpiTools(server: McpServer): void;
+import type { ServerConfig } from "../config.js";
+export declare function registerScpiTools(server: McpServer, config: ServerConfig): void;

package/build/tools/scpi.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { connection } from "../connection.js";
-export function registerScpiTools(server) {
-    server.tool("scpi_query", "Send an arbitrary SCPI query to the waveform generator and return the response. Use this as an escape hatch for commands not covered by other tools. Note: CHDR is set to OFF, so responses contain only values (no headers).", {
+export function registerScpiTools(server, config) {
+    server.tool("scpi_query", "Send a read-only SCPI query to the waveform generator and return the response. Use this as an escape hatch for queries not covered by other tools. The command must be a single SCPI header ending in '?' (e.g. 'C1:BSWV?'); anything that could change instrument state is rejected. Note: CHDR is set to OFF, so responses contain only values (no headers).", {
         command: z
             .string()
             .describe("SCPI query command to send (e.g. '*IDN?', 'C1:BSWV?', 'C1:OUTP?')"),
@@ -33,11 +33,14 @@ export function registerScpiTools(server) {
             };
         }
     });
-    server.tool("scpi_command", "Send an arbitrary SCPI command to the waveform generator (no response expected). Use this as an escape hatch for commands not covered by other tools.", {
+    // Raw commands are off by default: they bypass every per-tool constraint.
+    if (!config.rawScpiEnabled)
+        return;
+    server.tool("scpi_command", "Send an arbitrary SCPI command to the waveform generator (no response expected). Use this as an escape hatch for commands not covered by other tools. Only one command per call; newlines and ';' are rejected.", {
         command: z
             .string()
             .describe("SCPI command to send (e.g. '*RST', 'C1:OUTP ON', 'C1:BSWV WVTP,SINE')"),
-    }, { readOnlyHint: false }, async ({ command }) => {
+    }, { readOnlyHint: false, destructiveHint: true }, async ({ command }) => {
         try {
             await connection.sendCommand(command);
             return {

package/build/tools/utility.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { connection } from "../connection.js";
 export function registerUtilityTools(server) {
-    server.tool("reset", "Reset the waveform generator to factory default settings (*RST).", {}, { readOnlyHint: false }, async () => {
+    server.tool("reset", "Reset the waveform generator to factory default settings (*RST).", {}, { readOnlyHint: false, destructiveHint: true }, async () => {
         try {
             await connection.sendCommand("*RST");
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siglent-sdg-mcp",
-  "version": "1.0.0",
+  "version": "2.0.3",
   "description": "MCP server for Siglent SDG waveform generator control via SCPI over TCP sockets",
   "type": "module",
   "main": "build/index.js",
@@ -19,7 +19,8 @@
     "inspector": "npx @modelcontextprotocol/inspector node build/index.js",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "hardware-check": "npm run build && node scripts/hardware-check.mjs"
   },
   "keywords": [
     "mcp",
@@ -32,16 +33,16 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/magnusjohansson/siglent-sdg-mcp.git"
+    "url": "git+https://github.com/MagnusJohansson/siglent-sdg-mcp.git"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "zod": "^3.25.0"
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.12"
   },
   "engines": {
     "node": ">=20"