ec-sim-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) EC-Sim (https://ec-sim.com). All rights reserved.
+
+This package (the Ec-Sim MCP server) is proprietary software.
+
+You may install and run unmodified copies of this package, free of charge, for the sole purpose
+of connecting an MCP client to the Ec-Sim editor at https://ec-sim.com.
+
+No other licence is granted. In particular you may not modify, redistribute, sublicense or
+embed this software in another product or service without prior written permission from the
+copyright holder.
+
+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 COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE.

package/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# Ec-Sim MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets an AI agent (Claude Code, Claude Desktop, any MCP client) design and simulate circuits in
+Ec-Sim **while the editor is open in your browser**. The agent's changes appear on the schematic
+as it makes them, simulations run in the tab, and the waveforms it measures are the ones you see.
+
+```
+agent  ⇄  stdio  ⇄  this server  ⇄  WebSocket on 127.0.0.1  ⇄  editor tab
+```
+
+The server is a relay. The circuit, the engine and the results stay in the tab, so the engine's
+origin lock and the web app's own code paths apply unchanged. Nothing is uploaded.
+
+## Use
+
+Needs Node.js 20 or newer. Register the server with your MCP client. In Claude Code:
+
+```bash
+claude mcp add ec-sim -- npx -y ec-sim-mcp
+```
+
+In Claude Desktop and other clients that use a JSON configuration:
+
+```json
+{ "mcpServers": { "ec-sim": { "command": "npx", "args": ["-y", "ec-sim-mcp"] } } }
+```
+
+From a checkout of the repository (development):
+
+```bash
+cd mcp && npm ci
+claude mcp add ec-sim -- node /path/to/Ec-Sim/mcp/src/server.mjs
+# against a local dev server (cd web && npm run dev):
+claude mcp add ec-sim -e ECSIM_EDITOR_URL=http://localhost:5173/editor -- node /path/to/Ec-Sim/mcp/src/server.mjs
+```
+
+Then ask the agent for something ("build an RC low-pass with a 1 kHz corner and show me the step
+response"). Its first call, `open_editor`, opens a pairing link in your browser. Press **Connect**
+in the dialog. A badge in the menu bar shows the link and has a Disconnect button.
+
+| Variable | Meaning |
+|---|---|
+| `ECSIM_EDITOR_URL` | Editor to pair with. Default `https://ec-sim.com/editor`. Only this origin may link. |
+| `ECSIM_MCP_PORT` | Loopback port for the tab link. Default: any free port. |
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `open_editor` | Link to a tab (opens the pairing link, waits for Connect) |
+| `list_component_types` | Part types, pins, parameters with SI units and defaults |
+| `list_parts` | The editor's parts library (diodes, BJTs, MOSFETs, JFETs, op-amps): categories, or one category's table in SI, with limits on any column (`where`), sorting, word search and paging |
+| `list_examples`, `load_example` | Built-in circuits |
+| `get_circuit` | The circuit as a netlist (works for hand-drawn circuits), ERC result, revision |
+| `place_part` | Place one part without wires, at a cell, rotated or mirrored; the reply gives its pin positions |
+| `draw_wire`, `remove_wire` | Draw one wire along a stated path (pins, points, corners); remove a wire or one of its segments |
+| `place_symbol`, `remove_symbol` | Ground symbols and net labels at a stated point |
+| `move_label` | Move a part's designator and value text, a probe's badge, or a net label / ground symbol |
+| `get_drawing` | The drawing with positions: parts, pin coordinates and nets, symbols, wires with ids |
+| `set_circuit` | Replace the circuit from a structured netlist or a SPICE deck; drawn and wired automatically |
+| `edit_circuit` | Change values and parameters, swap in a library part, add and remove parts, move, turn or mirror a part, move a pin to another net (all or nothing) |
+| `set_probes` | Choose the signals in the waveform viewer |
+| `set_design_notes` | Write the project's design notes (Edit > Design Notes in the editor); `get_circuit` returns them |
+| `set_math_waveforms` | Named expressions drawn as traces in the viewer (`avg`, `rms`, `d/dt`, `integ`, arithmetic); the tool description carries the syntax |
+| `run_simulation` | Transient, AC, DC operating point, DC sweep; time accuracy normal/high/very high; returns a summary, not waveforms |
+| `measure` | Scalars from the last result: levels, timing, settling, −3 dB points, math expressions |
+| `get_waveform` | The plotted data: resampled points, capped at 2000 per signal; `from`/`to` return one part of the run |
+| `export_waveforms` | Write the full-resolution data of the last run to a CSV file on this computer and return its path |
+| `screenshot` | PNG of the schematic (the whole drawing, or a close-up around named parts) or of the waveform viewer as shown, returned as an image |
+| `export` | SPICE netlist, BOM, share link |
+
+Definitions are in `src/tools.mjs`; the handlers are in the web app
+(`web/src/agent/agentHandlers.ts` in the repository). A web test fails if the two lists differ.
+
+## How it stays safe and honest
+
+- **Loopback only.** The server listens on 127.0.0.1. The tab connects to the literal address.
+- **Three checks before a tab links:** the page's `Origin` must be the editor, the `Host` header
+  must be a loopback name, and the first message must carry the random token from the pairing link.
+  The token is removed from the address bar as soon as the page has read it.
+- **You confirm in the tab.** Nothing links until you press Connect, and the dialog warns about
+  unsaved changes.
+- **Every agent change is one undo step**, applied through the editor's normal state and validated
+  like an opened file.
+- **Revisions.** Every change to the document, yours or the agent's, increments a revision.
+  `edit_circuit` must name the revision it is based on and fails if you edited in between.
+  An agent change waits while you are dragging something.
+- **Netlist = drawing.** The agent states parts and net names; the tab draws real parts, wires,
+  net labels and ground symbols, then reads the drawing back through the editor's connectivity
+  and refuses the change if any pin is not on the net that was asked for.
+- **Library parts take the editor's path.** A part's `model` applies the same catalog entry, the
+  same way, as picking it in the Property Inspector. `list_parts` shows that catalog converted to
+  SI with `deviceDefaults.ts`.
+- **SI at the boundary.** Conversion to the datasheet units the Property Inspector shows uses the
+  same table (`deviceDefaults.ts`) as the path to the engine. Defaults reported to the agent are
+  computed from that table, not copied.
+- **One file, where you say.** `export_waveforms` is the only tool that writes to disk: a `.csv`
+  at an absolute path (or a new file in the system temp folder), never over an existing file
+  unless asked, and complete or absent.
+- **Bounded output.** No tool returns a raw waveform; lists and text are capped, and a screenshot
+  is at most 2400 px wide.
+
+## How the agent draws
+
+**First everything at once, then tidying by hand.** The agent is told to plan the placement, draw
+the whole circuit with one `set_circuit` call (the editor places and wires it, as described in the
+next section), look at a screenshot, and then fix what does not read cleanly one change at a
+time: `move_part` for a part in the wrong place or out of line, `remove_wire` and `draw_wire` for
+a wire with a detour or a needless crossing, `move_label` for text in the way. You see the
+circuit appear and then being cleaned up.
+
+The hand tools work like this:
+
+- Positions are in grid steps of 20 px. A layout cell is 16 steps wide and 12 high; the part in
+  cell (col, row) is centred at (10 + 16 col, 10 + 12 row).
+- A wire goes exactly where the agent says. Nothing is snapped: an off-grid point or a wire
+  through a part is refused. Two points that are not in line get one corner between them.
+- Nothing is assumed about what a wire connects. The reply to `draw_wire` reports what the
+  editor's connectivity finds on it: the pins it joined and their net, and warnings when it
+  bridged a part, joined two named nets, crossed other wires or left an end open. After hand
+  changes the agent compares `get_circuit` with the circuit it meant.
+- Each step is one undo step. `revision` is optional on these tools.
+
+A circuit can also be built entirely by hand (`place_part`, then `draw_wire`), which the agent is
+told is fine for a handful of parts or for adding to an existing circuit.
+
+The wording that steers the agent (workflow, layout and wire style) is `INSTRUCTIONS` in
+`src/tools.mjs`.
+
+## How the automatic drawing works
+
+Parts go on a layout grid (320 × 240 px cells): where the agent says with `at: {col, row}` and
+`rotation`, otherwise row by row in the order listed. Every connected pin is led out of its part
+on a short stub. Then, per net (`web/src/agent/wireRouter.ts`):
+
+- Pins are joined by orthogonal wires on the 20 px grid, nearest first, as short as the placement
+  allows. A pin is led two grid steps out of its part before a wire turns or joins, and a wire
+  keeps two straight grid steps on each side of a crossing where there is room (a preference: it
+  gives way when other connections need the space).
+- A wire may cross another
+  net's wire but never ends on it, runs along it or passes over one of its corners, so a crossing
+  is never a connection.
+- A pin gets a **net label instead of a wire** only when no clear path exists within about
+  1800 px of wire (bends and crossings count extra). The reply to `set_circuit` / `edit_circuit`
+  then carries a `drawing` note naming those nets, so the agent can move parts closer.
+- Each net gets one label that carries its name (what `V(name)` refers to). Ground pins get a
+  ground symbol each.
+- `add_part` puts the new part in the free cell nearest to the pins it connects to and wires it to
+  the existing net, including nets of a hand-drawn circuit that have no label.
+- `remove_part` also removes the wires that were left leading nowhere.
+- `move_part` and `connect` take the part out with the wires drawn for it and draw it again at its
+  (new) place on its (new) nets. Every other connection must come out exactly as it was, or the
+  change is refused. Probes follow their parts and nets.
+
+A circuit given as a SPICE deck goes through the editor's SPICE import instead, which puts a net
+label on every pin.
+
+After the agent draws or extends a circuit, the editor zooms your view to the whole drawing, and
+the server's instructions tell the agent to look at a screenshot of the layout before going on.
+
+If the wired drawing ever fails the read-back, the circuit is drawn with a label on every pin
+instead and the reply says so.
+
+## Limits
+
+- Placement is the agent's job: there is no automatic placement. The server's instructions
+  (`LAYOUT` in `src/tools.mjs`) tell it how to choose cells: signal flow left to right, series
+  parts in one row, shunt parts upright in the row below their node, tidy rows and columns, then
+  check the screenshot and fix with `move_part`.
+- Parts sit in the middle of a cell unless the agent says otherwise. Pins of three-pin parts are
+  not on the centre line, so `list_component_types` gives every pin's offset from the centre for
+  each rotation, and `line_up` (in `place_part`, `add_part` and `move_part`) shifts a part so one
+  of its pins is exactly in line with a pin of another part.
+- `move_part` on a hand-wired part redraws that part's wires automatically.
+- `list_parts` covers the built-in library only. Passives have no library entries.
+- Design notes are not part of undo, and writing them does not change the circuit revision.
+- No parameter sweeps, Monte Carlo or thermal tools yet.
+- One tab at a time; a second tab that links takes over.
+- A page on `https://ec-sim.com` connecting to `ws://127.0.0.1` has only been tested from a local
+  dev server (`http://localhost`). Browsers treat loopback as trustworthy, but Chrome may show a
+  local-network permission prompt and Safari may refuse; this needs checking on the live site.
+
+## Tests
+
+```bash
+cd mcp && npm test                      # server: MCP over stdio, origin/host/token checks, relay
+cd web && npx vitest run src/test/agent_bridge.test.ts src/test/agent_bridge_editor.test.tsx
+# Real browser, real engine (needs chromium and a running dev server on port 5199):
+cd web && npx vite --port 5199 --strictPort &
+node mcp/scripts/e2e-browser.mjs /tmp/ecsim-e2e.png
+```

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "ec-sim-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server that lets an AI agent drive the Ec-Sim circuit simulator in an open browser tab",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "circuit-simulator",
+    "spice",
+    "electronics",
+    "ec-sim"
+  ],
+  "homepage": "https://ec-sim.com/docs/files-and-reference#ai-agents",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "bin": {
+    "ec-sim-mcp": "src/server.mjs"
+  },
+  "scripts": {
+    "start": "node src/server.mjs",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "ws": "^8.23.0"
+  }
+}

package/src/bridge.mjs

@@ -0,0 +1,190 @@
+/**
+ * Link between the MCP server and one Ec-Sim editor tab.
+ *
+ * A WebSocket server on the loopback interface. A tab may link only if all of these hold:
+ *   - the connection comes to 127.0.0.1 (the server does not listen anywhere else),
+ *   - the page's Origin is the Ec-Sim editor (any other website is refused),
+ *   - the Host header is a loopback name (defeats DNS rebinding),
+ *   - its first message carries the pairing token from the link the user opened.
+ * The user must also press Connect in the tab before it links (that part lives in the web app).
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { WebSocketServer } from 'ws';
+
+export const BRIDGE_PROTOCOL = 1;
+const HELLO_TIMEOUT_MS = 5000;
+const MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
+
+export class NoEditorError extends Error {}
+
+export class EditorBridge {
+  /**
+   * @param {{ editorUrl: string, port?: number, log?: (msg: string) => void }} opts
+   */
+  constructor(opts) {
+    this.editorUrl = new URL(opts.editorUrl);
+    this.allowedOrigin = this.editorUrl.origin;
+    this.requestedPort = opts.port ?? 0;
+    this.log = opts.log ?? (() => {});
+    this.token = randomBytes(24).toString('hex');
+    this.tab = null;
+    this.nextId = 1;
+    /** @type {Map<number, { resolve: Function, reject: Function, timer: NodeJS.Timeout, socket: object }>} */
+    this.pending = new Map();
+    this.tabWaiters = [];
+    this.wss = null;
+    this.port = 0;
+  }
+
+  start() {
+    return new Promise((resolve, reject) => {
+      const wss = new WebSocketServer({
+        host: '127.0.0.1',
+        port: this.requestedPort,
+        path: '/bridge',
+        maxPayload: MAX_MESSAGE_BYTES,
+        verifyClient: (info, done) => {
+          const origin = info.origin || '';
+          const host = String(info.req.headers.host || '').replace(/:\d+$/, '');
+          if (origin !== this.allowedOrigin) {
+            this.log(`Refused a connection from origin "${origin}" (only ${this.allowedOrigin} may link).`);
+            done(false, 403, 'Origin not allowed');
+          } else if (host !== '127.0.0.1' && host !== 'localhost') {
+            done(false, 403, 'Host not allowed');
+          } else {
+            done(true);
+          }
+        },
+      });
+      wss.once('error', reject);
+      wss.once('listening', () => {
+        this.port = wss.address().port;
+        this.wss = wss;
+        wss.on('error', (err) => this.log(`Bridge error: ${err.message}`));
+        resolve();
+      });
+      wss.on('connection', (socket) => this.onConnection(socket));
+    });
+  }
+
+  /** The link the user opens to pair a tab with this server. */
+  get pairingUrl() {
+    const url = new URL(this.editorUrl);
+    url.hash = `agent=${this.port}.${this.token}`;
+    return url.toString();
+  }
+
+  get connected() {
+    return this.tab !== null;
+  }
+
+  onConnection(socket) {
+    let authed = false;
+    const helloTimer = setTimeout(() => {
+      if (!authed) socket.close(4401, 'no pairing token received');
+    }, HELLO_TIMEOUT_MS);
+
+    socket.on('message', (data) => {
+      let msg;
+      try {
+        msg = JSON.parse(data.toString());
+      } catch {
+        return;
+      }
+      if (!authed) {
+        if (msg?.type !== 'hello' || !this.tokenMatches(msg.token)) {
+          socket.close(4401, 'wrong pairing token');
+          return;
+        }
+        if (msg.protocol !== BRIDGE_PROTOCOL) {
+          socket.close(4426, 'the editor and the MCP server versions do not match');
+          return;
+        }
+        authed = true;
+        clearTimeout(helloTimer);
+        if (this.tab && this.tab !== socket) {
+          const old = this.tab;
+          this.dropTab(old, 'another tab took over the link');
+          old.close(4000, 'another tab took over the link');
+        }
+        this.tab = socket;
+        socket.send(JSON.stringify({ type: 'welcome', protocol: BRIDGE_PROTOCOL }));
+        this.log('Editor tab linked.');
+        for (const w of this.tabWaiters.splice(0)) w(true);
+        return;
+      }
+      if (msg?.type === 'response' && this.pending.has(msg.id)) {
+        const p = this.pending.get(msg.id);
+        this.pending.delete(msg.id);
+        clearTimeout(p.timer);
+        if (msg.ok) p.resolve(msg.result);
+        else p.reject(new Error(String(msg.error?.message || 'The editor reported an error.')));
+      }
+    });
+    socket.on('close', () => {
+      clearTimeout(helloTimer);
+      if (this.tab === socket) {
+        this.log('Editor tab unlinked.');
+        this.dropTab(socket, 'the editor tab was closed or unlinked');
+      }
+    });
+    socket.on('error', () => {});
+  }
+
+  tokenMatches(candidate) {
+    if (typeof candidate !== 'string') return false;
+    const a = Buffer.from(candidate);
+    const b = Buffer.from(this.token);
+    return a.length === b.length && timingSafeEqual(a, b);
+  }
+
+  dropTab(socket, why) {
+    if (this.tab === socket) this.tab = null;
+    for (const [id, p] of this.pending) {
+      if (p.socket !== socket) continue;
+      this.pending.delete(id);
+      clearTimeout(p.timer);
+      p.reject(new NoEditorError(`The request was not completed: ${why}.`));
+    }
+  }
+
+  /** Resolves true when a tab is linked, false after `timeoutMs`. */
+  waitForTab(timeoutMs) {
+    if (this.tab) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const done = (ok) => {
+        clearTimeout(timer);
+        const i = this.tabWaiters.indexOf(done);
+        if (i >= 0) this.tabWaiters.splice(i, 1);
+        resolve(ok);
+      };
+      const timer = setTimeout(() => done(false), timeoutMs);
+      this.tabWaiters.push(done);
+    });
+  }
+
+  /** Sends one request to the linked tab and resolves with its result. */
+  request(method, params, timeoutMs) {
+    const socket = this.tab;
+    if (!socket) return Promise.reject(new NoEditorError('No editor tab is linked.'));
+    return new Promise((resolve, reject) => {
+      const id = this.nextId++;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`The editor did not answer ${method} within ${Math.round(timeoutMs / 1000)} s.`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer, socket });
+      socket.send(JSON.stringify({ type: 'request', id, method, params: params ?? {} }));
+    });
+  }
+
+  close() {
+    for (const w of this.tabWaiters.splice(0)) w(false);
+    if (this.tab) this.dropTab(this.tab, 'the MCP server is shutting down');
+    return new Promise((resolve) => {
+      if (!this.wss) return resolve();
+      for (const client of this.wss.clients) client.terminate();
+      this.wss.close(() => resolve());
+    });
+  }
+}

package/src/server.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+/**
+ * Ec-Sim MCP server.
+ *
+ * Speaks MCP over stdio to an AI agent and relays its tool calls to an Ec-Sim editor tab in the
+ * user's browser (see bridge.mjs). The circuit and the simulation stay in the tab, so the user
+ * watches the agent work.
+ *
+ * Environment:
+ *   ECSIM_EDITOR_URL   editor to pair with (default https://ec-sim.com/editor). For development
+ *                      use the Vite server, e.g. http://localhost:5173/editor
+ *   ECSIM_MCP_PORT     loopback port for the tab link (default: any free port)
+ */
+import { spawn } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync } from 'node:fs';
+import { rename, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { once } from 'node:events';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { EditorBridge, NoEditorError } from './bridge.mjs';
+import { EDITOR_TOOLS, INSTRUCTIONS, LOCAL_TOOLS } from './tools.mjs';
+
+const log = (msg) => process.stderr.write(`[ec-sim-mcp] ${msg}\n`);
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_EXPORT_ROWS = 5_000_000;
+const SIM_DEFAULT_S = 120;
+const SIM_MAX_S = 600;
+
+function openInBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', url]] : ['xdg-open', [url]];
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+      child.once('error', () => resolve(false));
+      child.once('spawn', () => {
+        child.unref();
+        resolve(true);
+      });
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value) }] });
+/** A reply that carries a picture (`image: {mimeType, data}`) becomes an image block plus the rest as text. */
+function reply(value) {
+  const image = value && typeof value === 'object' ? value.image : undefined;
+  if (!image || typeof image.data !== 'string' || typeof image.mimeType !== 'string') return text(value);
+  const { image: _picture, ...rest } = value;
+  return { content: [{ type: 'image', data: image.data, mimeType: image.mimeType }, { type: 'text', text: JSON.stringify(rest) }] };
+}
+const failure = (message) => ({ content: [{ type: 'text', text: message }], isError: true });
+
+async function main() {
+  const port = process.env.ECSIM_MCP_PORT ? Number(process.env.ECSIM_MCP_PORT) : 0;
+  if (!Number.isInteger(port) || port < 0 || port > 65535) throw new Error('ECSIM_MCP_PORT must be a port number.');
+  const bridge = new EditorBridge({ editorUrl: process.env.ECSIM_EDITOR_URL || 'https://ec-sim.com/editor', port, log });
+  await bridge.start();
+  log(`Waiting for an editor tab. Pairing link: ${bridge.pairingUrl}`);
+
+  const notLinked = () =>
+    failure(`No Ec-Sim editor tab is linked. Call open_editor, or ask the user to open this link and press Connect: ${bridge.pairingUrl}`);
+
+  async function openEditor(args) {
+    const launch = args.launch !== false;
+    const waitS = Math.max(0, Math.min(300, typeof args.wait_s === 'number' ? args.wait_s : 60));
+    if (bridge.connected) return text({ linked: true });
+    let launched = false;
+    if (launch) launched = await openInBrowser(bridge.pairingUrl);
+    const linked = await bridge.waitForTab(waitS * 1000);
+    if (linked) return text({ linked: true });
+    return text({
+      linked: false,
+      pairing_link: bridge.pairingUrl,
+      next: launched
+        ? 'The link was opened in the browser, but the user has not pressed Connect yet. Ask them to, then call open_editor again.'
+        : 'Ask the user to open the pairing link in their browser and press Connect, then call open_editor again.',
+    });
+  }
+
+  /**
+   * Writes the recorded data to a CSV file. The tab hands over the rows piece by piece (a whole
+   * run does not fit in one message); the file is complete or absent, never half written.
+   */
+  async function exportWaveforms(args) {
+    let target;
+    if (args.path !== undefined) {
+      if (typeof args.path !== 'string' || !isAbsolute(args.path) || !/\.csv$/i.test(args.path)) return failure('path must be an absolute path that ends in .csv.');
+      target = resolve(args.path);
+      if (existsSync(target) && args.overwrite !== true) return failure(`${target} already exists. Give another path, or "overwrite": true.`);
+    } else {
+      const dir = join(tmpdir(), 'ec-sim-mcp');
+      mkdirSync(dir, { recursive: true });
+      target = join(dir, `waveforms-${new Date().toISOString().replace(/[:.]/g, '-')}.csv`);
+    }
+    const partial = `${target}.part`;
+    const out = createWriteStream(partial);
+    let failed = null;
+    out.on('error', (err) => {
+      failed = err;
+    });
+    let info = null;
+    let rows = 0;
+    try {
+      for (let offset = 0; offset !== null; ) {
+        const piece = await bridge.request('waveform_rows', { signals: args.signals, from: args.from, to: args.to, offset }, DEFAULT_TIMEOUT_MS);
+        if (failed) throw failed;
+        if (offset === 0) {
+          if (piece.total > MAX_EXPORT_ROWS) throw new Error(`The result has ${piece.total} rows, more than the ${MAX_EXPORT_ROWS} one file may hold. Limit it with from/to.`);
+          info = piece;
+          out.write(`${piece.header}\n`);
+        }
+        if (piece.rows && !out.write(`${piece.rows}\n`)) await once(out, 'drain');
+        rows = piece.next ?? piece.total;
+        offset = piece.next;
+      }
+      out.end();
+      await once(out, 'finish');
+      if (failed) throw failed;
+      await rename(partial, target);
+    } catch (err) {
+      out.destroy();
+      await rm(partial, { force: true });
+      if (err instanceof NoEditorError && !bridge.connected) return notLinked();
+      return failure(`The file was not written: ${err?.message || String(err)}`);
+    }
+    return text({
+      path: target,
+      rows,
+      columns: info.header.split(',').length,
+      header: info.header,
+      bytes: (await stat(target)).size,
+      range: { axis: info.axis, from: info.from, to: info.to },
+      stale: info.stale,
+    });
+  }
+
+  const server = new Server({ name: 'ec-sim', version: '0.1.0' }, { capabilities: { tools: {} }, instructions: INSTRUCTIONS });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...LOCAL_TOOLS, ...EDITOR_TOOLS] }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = req.params.arguments && typeof req.params.arguments === 'object' ? req.params.arguments : {};
+    if (name === 'open_editor') return openEditor(args);
+    if (name !== 'export_waveforms' && !EDITOR_TOOLS.some((t) => t.name === name)) return failure(`Unknown tool "${name}".`);
+    if (!bridge.connected) return notLinked();
+    if (name === 'export_waveforms') return exportWaveforms(args);
+    let timeoutMs = DEFAULT_TIMEOUT_MS;
+    if (name === 'run_simulation') {
+      const s = typeof args.timeout_s === 'number' && args.timeout_s > 0 ? Math.min(args.timeout_s, SIM_MAX_S) : SIM_DEFAULT_S;
+      // The tab stops the run itself at timeout_s; allow it time to report what it had
+      timeoutMs = (s + 20) * 1000;
+    }
+    // A long list of operations redraws many wires: allow it more time than a single change
+    if (name === 'edit_circuit' && Array.isArray(args.operations)) timeoutMs = Math.min(DEFAULT_TIMEOUT_MS + args.operations.length * 500, 180_000);
+    try {
+      return reply(await bridge.request(name, args, timeoutMs));
+    } catch (err) {
+      if (err instanceof NoEditorError && !bridge.connected) return notLinked();
+      return failure(err?.message || String(err));
+    }
+  });
+
+  const shutdown = async () => {
+    await bridge.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+  process.stdin.on('close', shutdown);
+
+  await server.connect(new StdioServerTransport());
+}
+
+main().catch((err) => {
+  log(`Fatal: ${err?.stack || err}`);
+  process.exit(1);
+});

package/src/tools.mjs

@@ -0,0 +1,446 @@
+/**
+ * Tool definitions of the Ec-Sim MCP server.
+ *
+ * `open_editor` is answered by the server itself. Every other tool is forwarded to the editor
+ * tab, which holds the circuit and runs the simulation (web/src/agent/agentHandlers.ts has one
+ * handler per tool; a web test checks the two lists match).
+ */
+
+const PART = {
+  type: 'object',
+  description: 'One part of the circuit.',
+  properties: {
+    id: { type: 'string', description: 'Designator, unique in the circuit: R1, C2, M1, V1 ...' },
+    type: { type: 'string', description: 'Part type from list_component_types, e.g. resistor, capacitor, nmos, voltage_source.' },
+    value: {
+      type: ['number', 'string'],
+      description: 'Main value in SI (ohm, farad, henry, volt, ampere), as a number or text with a suffix ("4.7k", "100n"). Only for types that list a value.',
+    },
+    nets: {
+      type: 'object',
+      description: 'Pin name -> net name, e.g. {"p1": "in", "p2": "out"}. Use "0" for ground. Pins sharing a net name are connected.',
+      additionalProperties: { type: 'string' },
+    },
+    params: { type: 'object', description: 'Parameters in SI (see list_component_types). Omitted parameters use the simulator defaults.' },
+    model: {
+      type: 'string',
+      description: 'Part number from the library (see list_parts), e.g. "IRF540N" for an nmos. The library entry sets the parameters; "params" override single values.',
+    },
+    at: {
+      type: 'object',
+      description:
+        'Where to draw the part, in cells of the layout grid: col grows to the right, row downwards. Every part sits in the middle of its cell, so parts in one row or one column line up exactly. Left out: the next free cell, in the order the parts are listed. See LAYOUT in the server instructions for how to choose cells.',
+      properties: { col: { type: 'integer', minimum: 0 }, row: { type: 'integer', minimum: 0 } },
+      required: ['col', 'row'],
+    },
+    rotation: { type: 'number', enum: [0, 90, 180, 270], description: 'Rotation in degrees (default 0). Two-pin passives lie horizontal at 0; sources stand vertical.' },
+    line_up: {
+      type: 'object',
+      description:
+        'Shift the part a few grid steps so that one of its pins is exactly in line with a pin of a part already placed: {"pin": "p1", "with": "M1.drain"}. The shift is along one axis, the one that needs the smaller move: a part beside the other lines up in height, a part above or below lines up sideways (at most 4 steps). Use it whenever two connected pins are not on the same line, e.g. a resistor above a transistor\'s drain, so the wire between them is straight. Not available in set_circuit.',
+      properties: { pin: { type: 'string' }, with: { type: 'string' } },
+      required: ['pin', 'with'],
+    },
+    centre: {
+      type: 'object',
+      description: 'Exact centre of the part in grid steps, instead of a cell ("at"), for the rare case where a cell plus line_up does not fit.',
+      properties: { x: { type: 'integer' }, y: { type: 'integer' } },
+      required: ['x', 'y'],
+    },
+    mirrorX: { type: 'boolean', description: 'Flip the part horizontally (left and right swap), applied before the rotation. Use it to turn a transistor so its gate or base faces the other way without swapping drain and source in height.' },
+    mirrorY: { type: 'boolean', description: 'Flip the part vertically (top and bottom swap), applied before the rotation, e.g. to put a transistor\'s source or emitter at the top.' },
+  },
+  required: ['id', 'type', 'nets'],
+};
+
+/** A part for place_part: as PART, placed without wires */
+const PART_BARE = {
+  type: 'object',
+  description: 'The part to place: id, type, value or model, params, and where ("at", "rotation"). No "nets".',
+  properties: Object.fromEntries(Object.entries(PART.properties).filter(([key]) => key !== 'nets')),
+  required: ['id', 'type'],
+};
+
+const REVISION_OPTIONAL = {
+  type: 'number',
+  description: 'Optional: the revision this call is based on; the call then fails if the user changed the circuit since.',
+};
+
+const SIMULATION = {
+  type: 'object',
+  description:
+    'Simulation settings in SI. transient: tStop, tStepMax (default tStop/500), outputStart, zeroStart, accuracy. ac: fStart, fStop, pointsPerDecade (a source needs acMag). dc_op: none. dc_sweep: sweepSource, sweepStart, sweepStop, sweepPoints.',
+  properties: {
+    analysis: { type: 'string', enum: ['transient', 'ac', 'dc_op', 'dc_sweep'] },
+    tStop: { type: 'number' },
+    tStepMax: { type: 'number' },
+    outputStart: { type: 'number' },
+    zeroStart: { type: 'boolean', description: 'Start a transient from zero state instead of the DC operating point.' },
+    fStart: { type: 'number' },
+    fStop: { type: 'number' },
+    pointsPerDecade: { type: 'number' },
+    sweepSource: { type: 'string' },
+    sweepStart: { type: 'number' },
+    sweepStop: { type: 'number' },
+    sweepPoints: { type: 'number' },
+    accuracy: {
+      type: 'string',
+      enum: ['normal', 'high', 'very_high'],
+      description: 'Time accuracy of a transient run (truncation-error tolerance per step: 1e-3, 1e-4, 1e-5). Run again at a higher setting to confirm that a result does not depend on the step size; higher is slower.',
+    },
+  },
+};
+
+const PROBES = {
+  type: 'array',
+  items: { type: 'string' },
+  description: 'Signals to show in the waveform viewer: V(net), I(part), P(part), Ploss(part).',
+};
+
+const REVISION = {
+  type: 'number',
+  description: 'Revision of the circuit this call is based on (from get_circuit or the previous reply). The call fails if the circuit changed since.',
+};
+
+export const LOCAL_TOOLS = [
+  {
+    name: 'open_editor',
+    description:
+      'Connect to the Ec-Sim editor in the user\'s browser. Call this first. Returns whether a tab is linked and, if not, the pairing link; by default it also opens the link in the default browser and waits for the user to press Connect. The user watches every change you make in that tab.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        launch: { type: 'boolean', description: 'Open the pairing link in the default browser when no tab is linked (default true).' },
+        wait_s: { type: 'number', description: 'Seconds to wait for the tab to link (default 60, max 300).' },
+      },
+    },
+  },
+  {
+    name: 'export_waveforms',
+    description:
+      'Write the data of the last simulation to a CSV file on this computer and return its path: one row per solver time point (no resampling), first column time in seconds (or frequency in Hz), one column per signal. Use it when you need the full data, for a script or a spreadsheet; read the file with your own tools. signals may be recorded signals or math expressions; left out, every recorded V, I, P and Ploss signal is written (at most 64). from/to limit the rows to a part of the run. Without "path" the file goes to a new file in the system temp folder.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        signals: { type: 'array', items: { type: 'string' } },
+        from: { type: 'number' },
+        to: { type: 'number' },
+        path: { type: 'string', description: 'Absolute path of the file to write; must end in .csv.' },
+        overwrite: { type: 'boolean', description: 'Replace the file at "path" if it exists (default false).' },
+      },
+    },
+  },
+];
+
+/** Calls the server makes to the tab on its own behalf; they are not offered as tools. */
+export const INTERNAL_METHODS = ['waveform_rows'];
+
+export const EDITOR_TOOLS = [
+  {
+    name: 'list_component_types',
+    description: 'Part types the simulator has, with their pin names, where each pin is relative to the part\'s centre for every rotation (pin_offsets, in grid steps), the unit of their main value, and their parameters (SI units and defaults).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'list_parts',
+    description:
+      'The parts library of the editor (real diodes, zeners, LEDs, BJTs, MOSFETs, JFETs, op-amps) as a table in SI units. Without "type": the categories and how many parts each has. With "type": the table of that category. Narrow it with "where" (limits on any column, in SI: {"bv": {"min": 60}, "rdsOn": {"max": 0.02}}), order it with "sort" (a column name; "-rdsOn" for high to low), and filter by words with "search" (must appear in the part number, description or technology, e.g. "schottky" or "logic-level"). Example: the lowest-resistance N-channel MOSFETs for at least 60 V and 20 A: {"type": "nmos", "where": {"bv": {"min": 60}, "idMax": {"min": 20}}, "sort": "rdsOn", "limit": 10}. Place a part from the table with "model" in a part.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'string', description: 'Part type, e.g. nmos, diode, opamp.' },
+        search: { type: 'string' },
+        where: {
+          type: 'object',
+          description: 'Column name -> {"min": number, "max": number} (either or both), in the SI unit of the column. A part without a value for a limited column is left out.',
+          additionalProperties: { type: 'object', properties: { min: { type: 'number' }, max: { type: 'number' } } },
+        },
+        sort: { type: 'string', description: 'Column to sort by, low to high; put "-" in front for high to low.' },
+        limit: { type: 'integer', description: 'Rows to return (default 50, max 200).' },
+        offset: { type: 'integer', description: 'Rows to skip (for the next page).' },
+      },
+    },
+  },
+  {
+    name: 'list_examples',
+    description: 'Built-in example circuits (keys for load_example).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'load_example',
+    description: 'Replace the circuit in the editor with a built-in example and return it.',
+    inputSchema: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] },
+  },
+  {
+    name: 'get_circuit',
+    description:
+      'The circuit currently in the editor as a netlist: parts with values, parameters and the net on each pin, the simulation settings, the probes, the math waveforms, the design notes, the result of the electrical rule check, and the revision. Works for circuits the user drew by hand too.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'set_circuit',
+    description:
+      'Replace the circuit in the editor. Give either "parts" (structured netlist) or "spice" (a SPICE deck). The editor draws it as a schematic: you choose where each part goes ("at", "rotation") and the editor draws the wires, falling back to a net label only where parts are far apart or the way is blocked. Plan the placement before you call this (LAYOUT in the server instructions): a good placement gives short straight wires, a careless one gives detours and crossings. This is the first step of every new circuit; afterwards look at a screenshot and tidy single parts and wires by hand (move_part, remove_wire, draw_wire, move_label). Returns the electrical rule check, the new revision, and "drawing" notes naming any nets that needed labels. The user can undo it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        parts: { type: 'array', items: PART },
+        spice: { type: 'string', description: 'SPICE deck text (R, C, L, V, I, D, Q, M, J, E, G, F, H, K, .model, .subckt, .tran/.ac/.op).' },
+        simulation: SIMULATION,
+        probes: PROBES,
+      },
+    },
+  },
+  {
+    name: 'edit_circuit',
+    description:
+      'Change the circuit in place; all operations succeed or none is applied. Operations: {"op":"set_value","part":"R1","value":"2.2k"}, {"op":"set_params","part":"M1","params":{"rdsOn":0.02}} (null removes a parameter), {"op":"set_model","part":"M1","model":"IRLZ44N"} (a library part from list_parts), {"op":"add_part","part":{...}} (wired to its nets where a clear path exists), {"op":"remove_part","part":"C3"}, {"op":"move_part","part":"R2","at":{"col":3,"row":1},"rotation":90} (any of at, centre, line_up, rotation, mirrorX, mirrorY; its wires are drawn again. move_part and connect operations that follow each other are made together: places are checked as they end up, so parts can swap places or take a cell another part of the same call leaves, with no need to park anything first), {"op":"connect","part":"R2","nets":{"p2":"out"}} (moves the listed pins to other nets; null disconnects a pin; other pins keep their nets). Use move_part to tidy a layout after looking at the screenshot.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        revision: REVISION,
+        operations: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              op: { type: 'string', enum: ['set_value', 'set_params', 'set_model', 'add_part', 'remove_part', 'move_part', 'connect'] },
+              part: { description: 'Part id (set_value, set_params, remove_part) or a part object (add_part).' },
+              value: { type: ['number', 'string'] },
+              params: { type: 'object' },
+              model: { type: 'string' },
+              at: { type: 'object', properties: { col: { type: 'integer' }, row: { type: 'integer' } } },
+              rotation: { type: 'number', enum: [0, 90, 180, 270] },
+              mirrorX: { type: 'boolean' },
+              mirrorY: { type: 'boolean' },
+              line_up: { type: 'object', properties: { pin: { type: 'string' }, with: { type: 'string' } } },
+              centre: { type: 'object', properties: { x: { type: 'integer' }, y: { type: 'integer' } } },
+              nets: { type: 'object', description: 'connect: pin name -> net name, or null to disconnect the pin.' },
+            },
+            required: ['op', 'part'],
+          },
+        },
+      },
+      required: ['revision', 'operations'],
+    },
+  },
+  {
+    name: 'set_probes',
+    description: 'Choose the signals shown in the editor\'s waveform viewer (replaces the current probes). run_simulation reports numbers for these.',
+    inputSchema: { type: 'object', properties: { signals: PROBES }, required: ['signals'] },
+  },
+  {
+    name: 'get_drawing',
+    description:
+      'The drawing with positions, for wiring by hand: every part with its cell, rotation, and each pin\'s position and net (null = nothing drawn on the pin yet); every ground symbol and net label; every probe; every wire with its id, its corner points and its net. Positions are in grid steps of 20 px: a cell is 16 steps wide and 12 high, and the part in cell (col, row) is centred at (10 + 16 col, 10 + 12 row); x grows to the right, y downwards. Use get_circuit for the netlist itself.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'place_part',
+    description:
+      'Place one part on the schematic without wires, to wire it yourself with draw_wire (for adding to a circuit; a new circuit starts with set_circuit). Give "at" (cell) and, where needed, "rotation", "mirrorX" or "mirrorY"; the reply lists where its pins are, in grid steps, ready for draw_wire. "part" is as in set_circuit but without "nets". Left-out "at": the next free cell.',
+    inputSchema: { type: 'object', properties: { part: PART_BARE, revision: REVISION_OPTIONAL }, required: ['part'] },
+  },
+  {
+    name: 'draw_wire',
+    description:
+      'Draw one wire, exactly where you say: to replace an automatic wire you removed, or to connect a part you placed. "from" and "to" are pins ("R1.p2") or points in grid steps; "via" adds corner points in between. Two consecutive points that are not in line get one corner between them: the horizontal part first, or the vertical part with "first": "vertical". A wire connects at its two ends (to a pin, to another wire\'s end, or to the middle of another wire, which makes a junction dot) and where a pin lies on it; wires that only cross are not connected. Nothing is snapped: a wire through a part is refused. The reply says which pins the wire now connects and the net they are on, and warns if it bridged a part, joined two named nets, crossed other wires or left an end open. Read it: it is your check that the wire did what you meant.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from: { description: 'A pin, written "R1.p2", or a point {"x": ..., "y": ...} in grid steps.' },
+        to: { description: 'A pin, written "R1.p2", or a point {"x": ..., "y": ...} in grid steps.' },
+        via: { type: 'array', items: { description: 'A pin, written "R1.p2", or a point {"x": ..., "y": ...} in grid steps.' }, description: 'Corner points between from and to, in order.' },
+        first: { type: 'string', enum: ['horizontal', 'vertical'], description: 'Which way to leave a point when the next one is not in line (default horizontal).' },
+        revision: REVISION_OPTIONAL,
+      },
+      required: ['from', 'to'],
+    },
+  },
+  {
+    name: 'remove_wire',
+    description:
+      'Remove a wire by its id (from draw_wire or get_drawing), or only one of its segments: "segment" 0 is the one that starts at its first point. Removing a middle segment leaves two shorter wires. The reply lists what is left and says if a net fell apart.',
+    inputSchema: {
+      type: 'object',
+      properties: { wire: { type: 'string' }, segment: { type: 'integer', minimum: 0 }, revision: REVISION_OPTIONAL },
+      required: ['wire'],
+    },
+  },
+  {
+    name: 'place_symbol',
+    description:
+      'Place a ground symbol or a net label with its connection point exactly at "at" (a pin, or a point in grid steps; usually the end of a wire). A ground symbol hangs down from the point and makes the net ground ("0"). A net label names the net ("name"); labels with the same name are one net without a wire between them, and V(name) refers to it. "side" puts a label\'s text left or right of the point.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        type: { type: 'string', enum: ['ground', 'net_label'] },
+        name: { type: 'string', description: 'Net name (net_label only).' },
+        at: { description: 'A pin, written "R1.p2", or a point {"x": ..., "y": ...} in grid steps.' },
+        side: { type: 'string', enum: ['left', 'right'] },
+        revision: REVISION_OPTIONAL,
+      },
+      required: ['type', 'at'],
+    },
+  },
+  {
+    name: 'move_label',
+    description:
+      'Move a piece of text so the drawing reads cleanly. Name exactly one of: "part" (the designator and value text of a part: give "offset" in grid steps from where the editor puts it, x to the right and y downwards, fractions allowed; {"x": 0, "y": 0} puts it back), "probe" (the badge of a probe such as "V(out)": give "offset" the same way), or "symbol" (a net label or ground symbol, by its id: give "at", the pin or point its connection point moves to, and for a label optionally "side" to put the text left or right). Moving text never changes the circuit. Moving a net label or ground symbol can, because it names the net it touches: the reply says if any net changed. Use it after a screenshot shows text over a wire, a part or other text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        part: { type: 'string' },
+        probe: { type: 'string' },
+        symbol: { type: 'string' },
+        offset: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, required: ['x', 'y'] },
+        at: { description: 'A pin, written "R1.p2", or a point {"x": ..., "y": ...} in grid steps.' },
+        side: { type: 'string', enum: ['left', 'right'] },
+        revision: REVISION_OPTIONAL,
+      },
+    },
+  },
+  {
+    name: 'remove_symbol',
+    description: 'Remove a ground symbol or net label by its id (from place_symbol or get_drawing).',
+    inputSchema: { type: 'object', properties: { symbol: { type: 'string' }, revision: REVISION_OPTIONAL }, required: ['symbol'] },
+  },
+  {
+    name: 'set_design_notes',
+    description:
+      'Write the design notes of the project: free text the user reads under Edit > Design Notes and that is saved with the project (get_circuit returns it as "notes"). Use it to record the requirements, the decisions you took and why, and the measured results, so the reasoning stays with the design. "append": true adds a paragraph to what is there, which keeps what the user wrote; without it the text is replaced. At most 20000 characters.',
+    inputSchema: {
+      type: 'object',
+      properties: { text: { type: 'string' }, append: { type: 'boolean' } },
+      required: ['text'],
+    },
+  },
+  {
+    name: 'set_math_waveforms',
+    description: [
+      'Choose the math waveforms shown in the editor\'s waveform viewer (replaces the current ones; an empty list removes them). Each is a named expression over the signals of a transient result, drawn as its own trace. Returns min/max/average/rms/final of each when a result exists. The same expressions work as "signal" in measure and get_waveform.',
+      'Syntax: signals V(net), I(part), P(part), Ploss(part), used with or without a probe; t is time in seconds.',
+      'Operators: + - * / ^ %, comparisons < > == !=, logic && || !, and cond ? a : b.',
+      'Over time: avg(x) and rms(x) are running values from the start, avg(x, T) and rms(x, T) a sliding window of T seconds (one switching period), d/dt(x) the derivative, integ(x) the integral, smooth(x, N) a moving average over N samples.',
+      'Functions: abs sqrt cbrt pow hypot exp ln log10 log2 min max clamp sign floor ceil round trunc sin cos tan asin acos atan atan2 sinh cosh tanh. Constants: pi, e. Numbers take SI suffixes p n u m k M meg (e.g. 1.25u).',
+      'A later waveform may use an earlier one by its name. Examples: "V(in) - V(out)"; "integ(Ploss(M1))" (energy in J); "avg(P(R1), 10u) / avg(-P(V1), 10u) * 100" (efficiency in %).',
+    ].join(' '),
+    inputSchema: {
+      type: 'object',
+      properties: {
+        waveforms: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Trace name: a letter, then letters, digits or _ (e.g. "eff", "v_drop").' },
+              expression: { type: 'string' },
+              unit: { type: 'string', description: 'Unit shown on the axis; inferred from the expression when left out.' },
+            },
+            required: ['name', 'expression'],
+          },
+        },
+      },
+      required: ['waveforms'],
+    },
+  },
+  {
+    name: 'run_simulation',
+    description:
+      'Run the simulation in the editor (the user sees the waveforms) and return its status, warnings, errors with the node or device at fault, the list of recorded signals, and min/max/average/rms/final for each probed signal. Optionally change the simulation settings first. Waveforms are not returned; use measure or get_waveform.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        simulation: SIMULATION,
+        timeout_s: { type: 'number', description: 'Stop the run after this many seconds (default 120, max 600).' },
+      },
+    },
+  },
+  {
+    name: 'measure',
+    description:
+      'Numbers from the last simulation result. signal is a recorded signal such as V(out) or I(L1), or (transient) a math expression such as "V(out)*I(R1)". Measurements: min, max, peak_to_peak, average, rms, initial, final, value_at (needs at), rise_time, fall_time (10-90%), frequency, period, duty_cycle, overshoot, settling_time (band, default 0.02), and for AC results cutoff_3db and phase_at (needs at, in Hz). AC magnitudes are in dB. from/to limit the window (seconds, or Hz for AC).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        signal: { type: 'string' },
+        measurements: { type: 'array', items: { type: 'string' } },
+        from: { type: 'number' },
+        to: { type: 'number' },
+        at: { type: 'number' },
+        band: { type: 'number' },
+      },
+      required: ['signal'],
+    },
+  },
+  {
+    name: 'get_waveform',
+    description: 'The plotted data: points of up to 8 signals from the last result, resampled to at most max_points (default 200, max 2000). from/to return only that part of the run (seconds, or Hz for AC), at full detail within the window. Prefer measure when a number answers the question.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        signals: { type: 'array', items: { type: 'string' } },
+        max_points: { type: 'number' },
+        from: { type: 'number' },
+        to: { type: 'number' },
+      },
+      required: ['signals'],
+    },
+  },
+  {
+    name: 'screenshot',
+    description:
+      'A PNG picture of what the user sees. view "schematic" (default): the whole drawing with its probes, always fitted to the picture whatever the user\'s zoom; give "parts" to get a close-up of the area around those parts instead (useful when a large circuit is too small to read). view "waveforms": the plot panes of the waveform viewer as shown now, with their zoom and cursors (needs a simulation result). Look at the schematic after every set_circuit and after adding parts: check that parts and labels do not overlap, that wires are short and readable, and that the signal flows left to right; if not, place the parts again with "at" and "rotation". For numbers use measure or get_waveform.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        view: { type: 'string', enum: ['schematic', 'waveforms'] },
+        parts: { type: 'array', items: { type: 'string' }, description: 'Schematic only: part ids to zoom in on, e.g. ["M1", "D1"].' },
+        max_width: { type: 'integer', description: 'Largest width of the picture in pixels (default 1400, max 2400).' },
+      },
+    },
+  },
+  {
+    name: 'export',
+    description: 'Export the circuit: "spice" (netlist text), "bom" (CSV), or "share_link" (a URL that opens a copy of the circuit in the editor).',
+    inputSchema: { type: 'object', properties: { format: { type: 'string', enum: ['spice', 'bom', 'share_link'] } }, required: ['format'] },
+  },
+];
+
+export const INSTRUCTIONS = [
+  'Ec-Sim is a circuit simulator that runs in the user\'s browser. This server links you to an open editor tab: the circuit lives there, the simulation runs there, and the user watches every part and wire appear as you work.',
+  'Start with open_editor, then list_component_types (once). All numbers are SI. Ground is net "0". The user can edit the circuit too: if a call reports that the revision changed, call get_circuit and continue from what is there.',
+  '',
+  'HOW TO BUILD A CIRCUIT. Draw the whole circuit in one go, then tidy it by hand like an engineer cleaning up a sketch:',
+  '1. Plan the placement first (LAYOUT below): decide the cell and rotation of every part.',
+  '2. Draw it with one set_circuit call: every part with its "at", "rotation" and nets. The editor places the parts and wires them. Check "check" for errors.',
+  '3. Call screenshot and look at the result critically, as the user will.',
+  '4. Fix what does not read cleanly, one change at a time, so the user can follow: move_part for a part in the wrong place or out of line ("line_up" puts a pin exactly in line with the pin it connects to); remove_wire and draw_wire for a wire with a detour, a jog or a needless crossing; move_label for text or a net label that sits on something. After a few fixes take another screenshot. Stop when the drawing reads cleanly from left to right; do not redraw what is already good. To rearrange a whole block, put all its move_part operations in one edit_circuit call: they are applied together and the wires are drawn once.',
+  '5. After changing wires by hand, call get_circuit and compare the net on every pin with the circuit you intended: read every draw_wire reply too, it lists the pins the wire connected.',
+  '6. Then set_probes -> run_simulation -> measure. Change values with edit_circuit and run again.',
+  'To extend a circuit later, add parts one at a time: edit_circuit add_part wires the part for you, place_part places it bare for wiring with draw_wire. Building a whole circuit with place_part and draw_wire is possible and fine for a handful of parts, but slower; a SPICE deck or a large circuit always starts with set_circuit.',
+  '',
+  'LAYOUT. You place the parts, in cells: col grows to the right, row downwards, and a part sits in the middle of its cell, so a row or a column lines up exactly.',
+  '- Signal flow runs left to right: sources and inputs in column 0, each following stage one column to the right, the load or output last.',
+  '- One main row carries the signal path. Parts in series with the signal (series resistor, inductor, switch, coupling capacitor) lie in that row at rotation 0, one per column, in the order the signal meets them.',
+  '- Parts from a node to ground or to a rail (shunt capacitor, load resistor, divider leg, freewheel diode) stand upright (rotation 90 or 270) in the row directly below the node they hang from, in the same column or the next, so the wire to them is one short line. Parts up to a supply rail go in the row directly above.',
+  '- Feedback parts go in the row above the stage they bridge, in the column of that stage.',
+  '- Keep rows and columns tidy: use consecutive cells, do not leave gaps or stagger parts. Two parts that share a net belong in neighbouring cells; if a net joins many parts, line them up along one row or column.',
+  '- Rotate or mirror a part so its pins face what they connect to ("rotation"; "mirrorX" swaps left and right, "mirrorY" top and bottom). list_component_types gives the pins; place_part and get_drawing give their positions.',
+  '- A source stands in column 0 with its negative pin to ground; a second supply gets its own cell in column 0, above or below.',
+  '- Pins are not all on the centre line of a part: a resistor\'s pins are, a transistor\'s drain and source are one grid step to the side (list_component_types gives pin_offsets for every rotation). Two parts in the same row or column can therefore have connected pins one or two steps out of line, which forces an ugly jog in the wire. Prevent it when placing: give "line_up": {"pin": "p2", "with": "M1.drain"} and the part is shifted so those two pins are exactly in line. Place the part with the most pins first (the transistor, the op-amp), then line the two-pin parts up with it.',
+  '',
+  'WIRES. Positions are in grid steps of 20 px; a cell is 16 steps wide and 12 high, and the part in cell (col, row) is centred at (10 + 16 col, 10 + 12 row).',
+  '- Wires are horizontal and vertical only, as short as the placement allows, with as few corners as possible. Two pins on one line are joined by one straight wire. If a wire between neighbouring parts needs a jog of one or two steps, the parts are out of line: fix the part with move_part and "line_up" instead of drawing the jog.',
+  '- Lead a wire two grid steps straight out of a pin before it turns or meets another wire. Extend that only when other connections need the room.',
+  '- Avoid crossings. Where one cannot be avoided, both wires run straight for at least two grid steps on each side of it.',
+  '- Join a third pin to a net by ending its wire on the existing wire (a junction), two grid steps or more from the nearest pin or corner, not by a second wire into the same pin.',
+  '- Never run a wire over a part or along another wire. Go around, with "via" points.',
+  '- A ground symbol goes two grid steps below a pin that points down (draw the short wire, then place the symbol at its end). Prefer one ground symbol per ground pin over long ground wires.',
+  '- Name the nets you will measure (in, out, sw ...) with one net label each, at a wire end or on a short stub, where its text is clear of parts.',
+  'These are the rules to judge the automatic wiring by and to follow when you redraw a wire. In a screenshot: parts and text must not overlap, wires must be short and straight, rows and columns must line up, and the drawing must read from left to right. Tidy what does not (remove_wire and redraw; move_part for a part; move_label for text or a net label that sits on a wire, a part or other text).',
+  '',
+  'For a real semiconductor or op-amp, select it with list_parts ("where" and "sort" pick by voltage, current, resistance and so on) and name it with "model" instead of typing datasheet values.',
+  'Keep the design notes current with set_design_notes (requirements, decisions, measured results). For data too large to read, export_waveforms writes a CSV file.',
+].join('\n');