Repository navigation
Architecture
TypeScript, stdio MCP server, built on the MCP TypeScript SDK. The layout follows siglent-sds-mcp; the implementation is original.
MCP client (Claude, Inspector, ...)
| stdio
v
src/index.ts ── createServer() in src/server.ts ── registers the tool groups
|
v
src/tools/*.ts one file per tool group; every tool is registered through defineTool
| (src/tools/util.ts), which runs it as one exclusive session
v
src/sessionLock.ts FIFO exclusive-session lock behind connection.runExclusive
|
v
src/instrument.ts applyCommands (*CLS, send, check error queue), strict reply parsing, warnings helpers
src/acquisition.ts sweep start/complete synchronization
src/errors.ts error-queue drain
src/scpi.ts number/bool formatting and parsing, the safety denylist
|
v
src/connection.ts serialized queue, *OPC? sync, timeouts, hold-off, on top of a transport
src/blocks.ts IEEE 488.2 "#" block parser (handles LF and CRLF trailers)
|
v
src/transports/ raw SCPI over TCP (raw.ts) or VXI-11 (vxi11.ts, on src/vxi11/)
|
v
TCP port 5025 (raw), or port 111 and the core-channel port (VXI-11), on the analyzer
Other files: src/discovery.ts (portmapper UDP broadcast per local subnet, reply trust rules, *IDN? identification) and src/autoHost.ts (host=auto), src/autoconnect.ts (connect from UTS_IP, UTS_PORT, UTS_TRANSPORT at startup, never throws) and src/target.ts (host and port validation).
UtsConnection (src/connection.ts) is a singleton, on top of a pluggable transport, that turns the analyzer's quirks (see Instrument Behavior) into predictable behavior:
- One serialized queue for commands and queries. A command is never written in the middle of a pending query.
-
Commands are synced with
*OPC?. After each command it waits for the*OPC?reply before anything else is written (default timeout 3 s). A command can opt out (sync: false), which the sweep helper does. - Every query has a timeout (default 5 s text, 30 s binary) that names the command.
- Hold-off after a timeout: the next job waits until 2.5 s after the failed query was sent, because the instrument stalls after an unsupported query.
-
msSinceQueryTimeout()lets callers recognize stale-113errors posted after an unsupported query. -
Binary replies (
queryBinary) use the block parser and swallow a late CR/LF trailer so it can never be read as the next reply. - Input hygiene: a command containing CR/LF, control characters or non-ASCII is refused before sending, so one call can never smuggle a second command.
- Pending and queued jobs are rejected cleanly when the connection is closed or lost; "not connected" tells the user to call
connect.
The wire under the connection is a Transport (src/transports/transport.ts). Two exist:
-
Raw SCPI over TCP (port 5025): LF-terminated lines, CRLF replies,
#binary blocks assembled inraw.ts. While a single sweep runs the analyzer ignores every line it receives, so the sweep helper stays silent and polls*OPC?. -
VXI-11 (the default through
UTS_TRANSPORT=auto, orvxi11): ONC RPC over TCP through the portmapper on port 111, implemented without dependencies insrc/vxi11/. The analyzer queues commands sent during a sweep instead of dropping them, so the sweep helper writes:INITiate:IMMediateand does one blocking*OPC?read. It never answers a read that has nothing to deliver, so a timeout is the client's own deadline (see the verified-hardware notes).
Wire differences are expressed as capability flags (syncsCommands, dropsInputDuringSweep, holdOffAfterTimeout, completeLargeBlocks), never as transport-name checks in tools, so a tool behaves the same on both. UTS_TRANSPORT is auto (default: VXI-11 when the analyzer registers it with the portmapper, else raw), raw or vxi11; UTS_VXI11_DEVICE names the device (default inst0). New transports must pass the shared contract suite tests/transportContract.ts.
An MCP client may send several tool calls at once, but the analyzer has one command stream, one global error queue and ignores commands during a single sweep. So each tool's whole operation is one exclusive session: defineTool runs the handler inside connection.runExclusive, a first-in first-out lock (src/sessionLock.ts) that nested helper calls join, so applyCommands never deadlocks. Results and errors of parallel calls are never mixed up.
- The lock is per instrument. With several instruments (
UTS_INSTRUMENTS,connectwith aname) each has its own connection, queue and lock, and the optionalinstrumentargument picks one, so calls to different instruments run in parallel. - A long operation such as
single_sweepmakes the other calls to the same instrument wait their turn. - A call that waits longer than
UTS_BUSY_TIMEOUT_Sseconds (default 120) fails withInstrument busyand nothing was sent. - The session is released on every path: when the tool returns, fails or times out, or when the connection is closed or lost (which also fails every waiting call).
- Invalid input is refused before waiting for the lock.
- A sweep started with
start_sweepandwait=falsereleases the lock when that call returns, so usesingle_sweeporstart_sweepwithwait=trueunlesswait_for_sweep_completefollows.
The tool contract test runs every tool in parallel as well, and fails if a tool bypasses defineTool.
Taking set_frequency as the example:
- Validate the arguments (nothing is sent if they are invalid; coupled parameter groups cannot be mixed).
-
applyCommandssends*CLS, then each command (each synced with*OPC?), then reads:SYSTem:ERRor?until it reports no error. Errors from the instrument become an error result with their code and text; a failure part-way lists the commands already sent. -
Read the state back with strict parsers (
queryNumber,queryBool,queryParsed). -
Compare requested and actual values and return the state plus
warningsfor anything the instrument changed or clamped.
Getters are the same idea without steps 1 to 2: strict parsing, a malformed or empty reply is an error that names the command and quotes the reply, and a getter that fails part-way never returns partial data.
src/acquisition.ts picks the wait by the transport's capabilities. On the raw socket the only completion signal that works is: start the sweep without the usual *OPC? sync, stay silent for the sweep time read from :SENSe:SWEep:TIME?, then poll *OPC? with a short timeout until the first reply. Over VXI-11 it writes :INITiate:IMMediate and does one blocking *OPC? read. The timeout defaults to the sweep time plus 10 s, which also covers a sweep waiting for a video trigger.
Required of every tool and enforced by a contract test:
- Tools never throw; failures are error results with actionable messages.
- Setters validate, apply with
applyCommands, read back, and report adjusted values as warnings. - Getters parse strictly and fail whole rather than return partial data.
- Multi-step operations that change temporary state restore it (try/finally), and say so if restoring fails.
- Connection problems (not connected, closed, timeout, write failure) each have a distinct message.
- Hardware behavior (clamp vs error vs ignored) is documented per tool.
- Every tool has failure-mode tests.
tests/integration/tool-contract.test.ts runs every registered tool against a fake connection under not-connected, timeout, write-failure, garbage-reply, empty-reply, instrument-error and part-way-failure modes, and fails if a tool is missing from its table. A second test fails if a registered tool has no section in docs/tools-reference.md.
- One instrument at a time (a single connection). Multiple instruments are a proposal: issue #67.
- VXI-11 has been verified on one analyzer only (UTS3036B, firmware V1.04.0040); other models fall back to raw SCPI when they do not offer it.
-
A long sweep blocks other tool calls, by design, up to
UTS_BUSY_TIMEOUT_S. -
Release status: the limit line and tracking generator tools are available since v0.4.0. The
screenshottool needs VXI-11 because the analyzer stops a large reply after 144,800 bytes over raw TCP (issue #42); it refuses with instructions over raw. See the Roadmap.
MIT licensed. Verified on a UNI-T UTS3036B (firmware V1.04.0040); other models are untested. This wiki is generated from the repository's docs/ folder, which is authoritative: change it there, not here.