@i-scope/mcp-server 0.4.2

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog — @i-scope/mcp-server
+
+All notable changes to this package will be documented here. The format
+is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.4.2] — 2026-05-20
+
+### Added
+
+- **`system_abi_check` MCP tool** — wraps `protocol/version` on
+  `iScopeBridge.exe` (no COM, no Oscilloscope). Returns client vs server
+  wire ABI semver, compatibility kind (`ok` / `warn` / `fatal`), optional
+  `policy` argument (`strict` | `warn` | `ignore`), and user hints when
+  the bundled helper is stale relative to `@i-scope/iscope-bridge-client`.
+
+### Changed
+
+- Root `npm run test:prepublish` gate (headless matrix) runs before
+  `publish-all` in live mode; see `scripts/test-prepublish-matrix.cjs`.
+
+## [0.4.0] — 2026-05-19
+
+### Added — `system_preflight_check` MCP tool
+
+A new MCP tool that surfaces a structured pre-flight diagnostic for
+the iScope debug stack. It wraps the `preflight/check` JSON-RPC
+method of `iScopeBridge.exe` (introduced in
+`@i-scope/iscope-bridge-client` v0.3.0) and probes the local
+registry for the two prerequisites Oscilloscope needs to expose
+JScript debugging:
+
+- The Windows Script Debugger (Machine Debug Manager, `pdm.dll`,
+  CLSID `{0BFCC060-8C1D-11D0-ACCD-00AA0060275C}`). When this CLSID
+  is missing, Oscilloscope shows the "Unable to create debuger
+  object!" dialog at first `ExecuteFile` and silently declines to
+  run scripts in debug mode. The verdict
+  `'script-debugger-not-registered'` carries actionable user hints
+  ("install Build Tools / Remote Tools for Visual Studio") and a
+  download URL for the AI / UI to surface as a clickable link.
+- The Oscilloscope `ScopeAppDbgCtrl` CLSID
+  (`{176ED004-4A4D-439F-BDEC-5A78CC5BFC7B}`) — a side-check that
+  lets an AI agent distinguish "Script Debugger missing" from
+  "Oscilloscope not installed" failure modes.
+
+The tool is read-only, idempotent, and does NOT require
+Oscilloscope to be running. AI agents should call it proactively
+when the user reports "F5 just sits there", "breakpoints are
+ignored", or whenever `debug_launch` fails with a generic
+"engine returned but emitted no sink events" symptom.
+
+### Changed — DAP adapter pre-launch hook
+
+`@i-scope/dap-adapter` now calls `bridge.preflightCheck()` between
+`bridge.start()` and `bridge.initialize()` during `launchRequest`
+processing. The structured pre-flight failure surfaces through the
+existing `showErrorWithDownloadLink` host dependency, replacing the
+ad-hoc registry probe that used to live inside the 4-second
+engine-start watchdog. The old watchdog still calls
+`isScriptDebuggerInstalled()` as a fallback diagnostic for clients
+that bypass the pre-launch hook, but no longer drives the
+download-link modal — the pre-flight already did.
+
+### Bumped dependency
+
+- `@i-scope/iscope-bridge-client` `^0.3.0` (was `^0.2.0`). v0.3.0
+  introduced the typed `preflightCheck()` wrapper that the new
+  tool calls into and the adapter pre-launch hook depends on.
+
+## [0.3.0] — 2026-05-19
+
+### Added — UI modal control tools (interactive AI agent)
+
+Four new MCP tools that surface Oscilloscope's child dialogs as a
+programmatically driveable tree. They unblock AI agents (and CI
+pipelines) when a script is stuck on a `Host.Configure()` form, when
+Oscilloscope itself shows a diagnostic prompt, or whenever a
+`debug_continue` / `debug_step_*` silently times out because of a
+modal in the way.
+
+- `ui_modal_list` — enumerate every visible top-level dialog owned by
+  Oscilloscope, with full child-controls inventory (HWND, controlId,
+  className, text, isVisible / isEnabled, isChecked for checkboxes /
+  radios) and a `signature` classification (`configure` / `diagnostic`
+  / `unknown`) so the AI knows which dialogs are safe to drive
+  automatically. Read-only / idempotent / safe regardless of debug
+  session state.
+- `ui_modal_click` — programmatic button click via
+  `SendMessage(WM_COMMAND, MAKEWPARAM(controlId, BN_CLICKED))`.
+  Standard ids: `1`=IDOK, `2`=IDCANCEL, `6`=IDYES, `7`=IDNO; custom
+  buttons in Configure forms use whatever id `ui_modal_list` reports.
+- `ui_modal_fill` — fill an `Edit` (`WM_SETTEXT`) or `ComboBox`
+  (`CB_FINDSTRINGEXACT` + `CB_SETCURSEL` when the value matches an
+  existing item, `WM_SETTEXT` fallback otherwise). Returns
+  `previousText` for verification / diffing.
+- `ui_modal_dismiss` — explicit modal close. `mode='close'` →
+  `PostMessage(WM_CLOSE)` (= X button); `mode='cancel'` /
+  `mode='ok'` → `SendMessage(WM_COMMAND, IDCANCEL/IDOK)`.
+
+### Safety contract enforced in C++ (`iScopeBridge.exe`)
+
+- `GetWindowThreadProcessId(targetHwnd) == oscPid` — every UI handler
+  refuses to touch a window owned by a different process. Returns
+  JSON-RPC error `-32602` (invalid params) on mismatch.
+- Target HWND must NOT be the Oscilloscope main window — only owned
+  dialogs are mutated.
+- All synchronous `SendMessage`s use `SendMessageTimeout(SMTO_ABORTIFHUNG,
+  500 ms)` — a hung target STA cannot stall the helper thread.
+
+### Bumped dependency
+
+- `@i-scope/iscope-bridge-client` `^0.2.0` (was `^0.1.0`). v0.2.0
+  introduced the typed `uiModal*()` wrappers that the new tools call
+  into.
+
+## [0.2.0] — 2026-05-19
+
+### Changed (breaking by deployment, NOT by tool API)
+
+- DAP server is now spawned through
+  `require.resolve('@i-scope/dap-adapter/dist/src/server.js')` — the
+  adapter lives in its own published package
+  ([`@i-scope/dap-adapter`](https://www.npmjs.com/package/@i-scope/dap-adapter))
+  and is pulled in as a regular `dependencies` entry. `npm install
+  @i-scope/mcp-server` is now sufficient for an end-user install; no
+  monorepo clone, no extension build, no `ISCOPE_EXTENSION_PATH` env.
+- The internal launcher `scripts/iscope-mcp-debug-server.cjs` and the
+  `vscode-stub.cjs` mock are gone. The adapter has no `require('vscode')`
+  in its runtime path anymore, so direct `node server.js` works.
+- `DapDriverOptions.extensionPath` became optional — kept as a
+  `bundledRoot` override for embedded use-cases.
+
+### Tool surface
+
+- No changes to the 16 debug tools. Same input/output schemas, same
+  state machine.
+
+## [0.1.0] — 2026-05-15
+
+### Added
+
+- Initial public release. 16 MCP tools for AI-driven .ajs debugging:
+  `debug_launch` / `debug_disconnect` / `debug_current_state`,
+  `debug_set_breakpoints`, `debug_continue` / `debug_step_*`,
+  `debug_wait_for_paused` / `debug_read_output`,
+  `debug_stack_trace` / `debug_scopes` / `debug_variables` /
+  `debug_evaluate`, `debug_snapshot`, `debug_resolve_source`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iScope
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# @i-scope/mcp-server
+
+[![npm version](https://img.shields.io/npm/v/%40i-scope%2Fmcp-server.svg?label=npm)](https://www.npmjs.com/package/@i-scope/mcp-server)
+[![npm downloads](https://img.shields.io/npm/dm/%40i-scope%2Fmcp-server.svg)](https://www.npmjs.com/package/@i-scope/mcp-server)
+[![License: MIT](https://img.shields.io/npm/l/%40i-scope%2Fmcp-server.svg)](./LICENSE)
+[![Node](https://img.shields.io/node/v/%40i-scope%2Fmcp-server.svg)](#)
+
+> **Part of the [`@i-scope/debugger`](https://www.npmjs.com/package/@i-scope/debugger) SDK** — one of seven leaf packages aggregated by the `@i-scope/debugger` meta-umbrella.
+> Most users should install the meta (`npm install @i-scope/debugger`),
+> which transitively pulls this package in together with the rest of the
+> Debugger SDK (DAP adapter, native helper, source-map / VLST / COM
+> leaves). Install `@i-scope/mcp-server` **directly** only when you want
+> the MCP server surface without the rest of the SDK on your top-level
+> `package.json` (e.g. an MCP-only Cursor / Claude Code config via
+> `npx -y @i-scope/mcp-server`).
+
+Model Context Protocol (MCP) server that lets AI agents drive a
+`Oscilloscope.exe` debug session for `.ajs` scripts — set breakpoints,
+step, read variables and call stack, evaluate watch expressions — all
+through standard MCP tools layered on top of the iScope DAP adapter.
+
+> **Status:** v0.4.0 — **21 MCP tools** shipped across three phases:
+> Phase 1 (16 debug tools), Phase 2 (4 UI modal control tools —
+> `ui_modal_list / _click / _fill / _dismiss`), Phase 3 (1 system
+> diagnostics tool — `system_preflight_check`). Phase 4+ planned:
+> `control_*` (open file, run script, …) and `data_*` (read channels,
+> measure signals). See [`info/Plan.md`](../../info/Plan.md) in the
+> parent repo.
+
+## Quick start
+
+1. **Prerequisites** (Windows):
+
+   - `Oscilloscope.exe` v5 installed (default install path is supported
+     out-of-the-box; for portable installs see the
+     `oscilloscopePath` launch argument).
+
+2. **Install** the MCP server. Two flavours:
+
+   **End-user (npm-only)** — no repo clone, no local build:
+
+   ```pwsh
+   npm install -g @i-scope/mcp-server
+   # ...or use npx in mcp.json (see step 3).
+   ```
+
+   This pulls in `@i-scope/dap-adapter`, `@i-scope/iscope-bridge-client`,
+   and the native helper `@i-scope/iscope-bridge` (which bundles
+   `iScopeBridge.exe`) as transitive dependencies. No `ISCOPE_*`
+   environment variable required.
+
+   **Monorepo developer** — full local build:
+
+   ```pwsh
+   npm install
+   npm run build:packages
+   npm --workspace=@i-scope/iscope-bridge run build:msbuild
+   ```
+
+3. **Configure your MCP client** (Cursor example, `.cursor/mcp.json`):
+
+   ```json
+   {
+     "mcpServers": {
+       "iscope-debug": {
+         "command": "npx",
+         "args": ["-y", "@i-scope/mcp-server"]
+       }
+     }
+   }
+   ```
+
+   For local development from the monorepo:
+
+   ```json
+   {
+     "mcpServers": {
+       "iscope-debug": {
+         "command": "node",
+         "args": ["${workspaceFolder}/packages/mcp-server/dist/src/index.js"]
+       }
+     }
+   }
+   ```
+
+   `ISCOPE_EXTENSION_PATH` is optional now — set it only when you want
+   to override the helper-binary lookup with a custom bundled root.
+
+3. **Reload Cursor** and ask your AI agent:
+
+   > "Run `dist/Analyzer.ajs` and pause on `src/index.ts:42`, show me
+   > the value of `signal` at that point."
+
+   The agent will use `debug_launch` + `debug_set_breakpoints` +
+   `debug_continue` + `debug_variables` to inspect your script.
+
+## Architecture
+
+```
+AI Agent (Cursor / Claude Code)
+  ↕ MCP JSON-RPC over stdio
+@i-scope/mcp-server  (this package)
+  ↕ DAP over stdio (custom DapClient → spawned server.js)
+@i-scope/dap-adapter (AjsDebugSession + stdio server entry)
+  ↕ JSON-RPC over stdio
+@i-scope/iscope-bridge-client → @i-scope/iscope-bridge (iScopeBridge.exe)
+  ↕ COM (DISPID Invoke)
+Oscilloscope.exe     (JScript engine + ScopeAppDbgCtrl)
+```
+
+Each MCP tool delegates to the existing DAP adapter — no debug logic is
+duplicated. The session state machine
+(`idle → launching → running ⇄ paused → terminated`) lives in
+[`src/dap-driver.ts`](src/dap-driver.ts). Tool groups live under
+[`src/tools/`](src/tools).
+
+## Tool reference
+
+v0.4.2 ships **22 tools** (16 debug + 4 UI modal + 2 system diagnostics).
+Every tool is invokable via the standard MCP `tools/call` request;
+consult the tool descriptions inside the running server (`tools/list`)
+for the canonical schemas.
+
+### Lifecycle
+
+| Tool                  | Purpose                                                                 |
+|-----------------------|-------------------------------------------------------------------------|
+| `debug_launch`        | Spawn the DAP adapter, start `program` under Oscilloscope.              |
+| `debug_disconnect`    | Tear down the session; close Oscilloscope (if we launched it).          |
+| `debug_current_state` | Lock-free snapshot of session state + last-known stop info.             |
+
+### Breakpoints
+
+| Tool                    | Purpose                                                  |
+|-------------------------|----------------------------------------------------------|
+| `debug_set_breakpoints` | Replace the breakpoint set for one source file. Pass `lines:[]` to clear. |
+
+### Execution control
+
+| Tool                | Purpose                                                                 |
+|---------------------|-------------------------------------------------------------------------|
+| `debug_continue`    | Resume; returns the next paused/terminated transition.                  |
+| `debug_step_over`   | Step over (same frame).                                                 |
+| `debug_step_into`   | Step into the called function.                                          |
+| `debug_step_out`    | Step out of the current frame.                                          |
+
+### Sync
+
+| Tool                    | Purpose                                                              |
+|-------------------------|----------------------------------------------------------------------|
+| `debug_wait_for_paused` | Block until the next pause / termination (or timeout).              |
+| `debug_read_output`     | Cursor-paginated read of buffered `Host.ReportOut` + adapter logs.   |
+
+### Inspection
+
+| Tool                | Purpose                                                                 |
+|---------------------|-------------------------------------------------------------------------|
+| `debug_stack_trace` | Get the current call stack with source-map provenance per frame.        |
+| `debug_scopes`      | List scopes (Locals, …) for a given frame.                              |
+| `debug_variables`   | Enumerate variables under a scope or compound `variablesReference`.     |
+| `debug_evaluate`    | Evaluate a JScript expression (watch / hover / repl).                   |
+
+### Composite
+
+| Tool             | Purpose                                                                  |
+|------------------|--------------------------------------------------------------------------|
+| `debug_snapshot` | Stack + scopes + locals in one round-trip, atomically under one mutex.   |
+
+### Source maps (no debug session required)
+
+| Tool                   | Purpose                                                            |
+|------------------------|--------------------------------------------------------------------|
+| `debug_resolve_source` | Translate `.ts ↔ .ajs` positions for any on-disk pair.            |
+
+### UI modal control (interactive AI agent)
+
+Surface Oscilloscope's child dialogs as a programmatically driveable
+tree. Use these tools when a `debug_continue` / `debug_step_*`
+unexpectedly times out — the script is most likely blocked on a
+`Host.Configure()` form, or Oscilloscope itself is reporting a
+diagnostic prompt that needs dismissal.
+
+| Tool               | Purpose                                                                                                  |
+|--------------------|----------------------------------------------------------------------------------------------------------|
+| `ui_modal_list`    | Enumerate every visible top-level dialog owned by Oscilloscope, with child controls and a `signature` classification (`configure` / `diagnostic` / `unknown`). |
+| `ui_modal_click`   | Programmatic button click (`WM_COMMAND` + `BN_CLICKED`). Standard ids: `1`=IDOK, `2`=IDCANCEL, `6`=IDYES, `7`=IDNO. |
+| `ui_modal_fill`    | Set the text of a child `Edit` (`WM_SETTEXT`) or `ComboBox` (`CB_FINDSTRINGEXACT` + `CB_SETCURSEL`, `WM_SETTEXT` fallback). Returns `previousText` for diffing. |
+| `ui_modal_dismiss` | Explicit close — `mode='close'` → `PostMessage(WM_CLOSE)` (the X button); `mode='cancel'` / `'ok'` → `SendMessage(WM_COMMAND, IDCANCEL/IDOK)`. |
+
+Safety contract enforced in C++ for every UI tool:
+
+- `GetWindowThreadProcessId(hwnd) == oscPid` — we never touch a window
+  owned by a different process.
+- Target HWND must not be the Oscilloscope main window — we only act
+  on its owned dialogs.
+- All synchronous calls use `SendMessageTimeout(SMTO_ABORTIFHUNG,
+  500 ms)` — a hung target STA cannot stall the helper.
+
+#### AI usage pattern — Configure() form
+
+```ts
+// 1. debug_continue times out — script is likely blocked on a modal.
+const list = await callTool('ui_modal_list', {});
+const m = list.modals.find(m => m.signature === 'configure');
+if (m) {
+    // 2. Find the input + the OK button.
+    const edit = m.controls.find(c => c.className === 'Edit');
+    const ok   = m.controls.find(c => c.controlId === 1 /* IDOK */);
+    // 3. Fill and submit.
+    await callTool('ui_modal_fill',  { hwnd: m.hwnd, controlId: edit.controlId, text: '42' });
+    await callTool('ui_modal_click', { hwnd: m.hwnd, controlId: ok.controlId });
+    // 4. Resume — engine should now proceed past the blocked Configure() call.
+}
+```
+
+#### AI usage pattern — diagnostic dismissal
+
+```ts
+const list = await callTool('ui_modal_list', {});
+const diag = list.modals.find(m => m.signature === 'diagnostic');
+if (diag) {
+    // Read diag.title, take action, then dismiss with Enter/Esc.
+    await callTool('ui_modal_dismiss', { hwnd: diag.hwnd, mode: 'ok' });
+}
+```
+
+These tools work **without an active debug session** (Oscilloscope only
+needs to be running) and are SAFE to mix with an active DAP session —
+COM lets multiple clients attach to Oscilloscope. The complementary
+Q4b auto-rescue mechanism (`packages/iscope-bridge/src/Q4bProbe.cpp`)
+remains as a safety net during `disconnect`, but `ui_modal_*` is the
+preferred primary path for interactive control.
+
+### System diagnostics
+
+Verify host machine prerequisites before (or after a failure during)
+any debug session. Read-only / idempotent — safe to call without
+Oscilloscope running.
+
+| Tool                     | Purpose                                                                                                 |
+|--------------------------|---------------------------------------------------------------------------------------------------------|
+| `system_preflight_check` | Verify that Windows Script Debugger (Machine Debug Manager, `pdm.dll`) is installed and that Oscilloscope's COM classes are registered. Returns a structured verdict (`ok` / `script-debugger-not-registered` / `script-debugger-file-missing`), per-check details, and human-readable hints + a download URL. Read-only / idempotent; safe to call before any debug session and without Oscilloscope running. AI agents should call this proactively when a launch fails or a user reports "BP ignored". |
+| `system_abi_check` | Probe `iScopeBridge.exe` wire ABI via `protocol/version` (no COM). Compares helper `abi` semver to `@i-scope/iscope-bridge-client`. Optional `policy` (`strict` default). Call when mixing npm versions or after swapping a custom helper binary — before `debug_launch` if you see `ProtocolVersionMismatchError`. |
+
+Wire contract: preflight response shape is exported from
+`@i-scope/com-protocol-types` as `PreflightCheckResponse`.
+
+#### AI usage pattern — preflight before launch
+
+```ts
+const r = await callTool('system_preflight_check', {});
+if (!r.ok) {
+    // Surface r.userHints + r.downloadUrl to the user.
+    // Distinguish: r.verdict === 'script-debugger-not-registered' → install MDM
+    //              r.verdict === 'script-debugger-file-missing'   → repair install
+    //              r.oscilloscope.comRegistered === false         → Oscilloscope itself is not installed
+}
+```
+
+### Frame source-map provenance
+
+Every frame in `debug_stack_trace` / `debug_snapshot` carries a
+`sourceOrigin` field:
+
+- `mapped` — `source` is `.ts` because the adapter resolved the
+  bundler's source map.
+- `unmapped-fallback` — launch was `.ts` but the `.ajs.map` had a gap
+  for this line; `source` is the raw `.ajs` so you don't act on stale
+  TS coordinates.
+- `generated` — launch was directly against `.ajs` / `.apn` / `.aps`.
+
+## Tool-namespace reservation (Phase 4+)
+
+Each MCP tool name is prefixed by a short namespace identifying which
+Oscilloscope **COM-domain** it targets. The table below reserves the
+allocation **ahead of time** so future expansion of Oscilloscope's COM
+surface (a third remote-control object, additional file/app operations
+on `ScopeAppControl`, signal-data access on the existing debug object)
+does not collide with the `debug_*` / `ui_modal_*` / `system_*` tools
+already shipped.
+
+| Prefix          | COM-domain in Oscilloscope.exe                 | Status              | Purpose                                                                                       |
+|-----------------|------------------------------------------------|---------------------|-----------------------------------------------------------------------------------------------|
+| `debug_*`       | `ScopeAppDbgCtrl` (debug COM object)           | **shipped** (16)    | Launch, breakpoints, step, stack, variables, evaluate, snapshot. Phase 1.                     |
+| `ui_modal_*`    | Win32 GUI (modal-dialog rescue, not COM)       | **shipped** (4)     | List / click / fill / dismiss native modal dialogs blocking the engine. Phase 2.              |
+| `system_*`      | host machine (registry / file-system probe)    | **shipped** (1)     | Preflight diagnostics — MDM / `pdm.dll` / Oscilloscope COM registration. Phase 3.             |
+| `system_abi_check` | `iScopeBridge.exe` JSON-RPC (`protocol/version`) | **shipped** v0.4.2 | Wire ABI semver probe before `initialize` (no Oscilloscope required). See `info/Naming-Taxonomy.md` §11. |
+| `app_*`         | `ScopeAppControl` (existing file/app COM)      | **reserved** (none) | `OpenFile`, future `SaveAs`, file-tab manipulation, app-level UI control. Phase 4a.           |
+| `device_*`      | `ScopeAppRemoteControl` (planned 3rd COM)      | **reserved** (none) | Remote control of the oscilloscope **instrument** (channel config, triggers, capture, …).    |
+| `remote_*`      | `ScopeAppRemoteControl` (planned 3rd COM)      | **reserved** (none) | Remote control of the **application** itself (start/stop measurement, switch mode, …).        |
+| `data_*`        | signal-data access (multi-COM, read-only)      | **reserved** (none) | Read channel samples, measure (peak / RMS / FFT), edge detection on a loaded `.mwf`.          |
+| `analyzer_*`    | `.aps` analyzer-panel runtime                  | **reserved** (none) | Drive analyzer-panel state from MCP (load `.aps`, list panels, dump results). Q8 follow-on.   |
+
+### Why this matters
+
+Without the reservation, a Phase 4 implementer who sees Oscilloscope
+gain a third COM object called "Remote Control" would naturally pick
+`control_*` as the prefix — colliding with `ScopeAppControl` (the
+existing file-operations COM). The split `app_*` vs `device_*` vs
+`remote_*` keeps the COM-domain → prefix mapping injective: an AI
+agent can always tell from the tool name which Oscilloscope subsystem
+will be touched.
+
+### Cross-reference
+
+The npm-package side of this question (why Phase 4+ does **not**
+require new `@i-scope/*` packages, only minor/major version bumps of
+the existing seven leaves) is covered in
+[`info/Naming-Taxonomy.md`](https://gitlab.com/i-scope/Debugger/-/blob/main/info/Naming-Taxonomy.md)
+§9 "MCP tool-namespace allocation" and §6.7 "ABI extension ≠ new npm
+package".
+
+## Integration with @i-scope SDK
+
+If you use `@i-scope/cli-tools` (`iscope create-analyzer`) to scaffold
+analyzers, this MCP server transparently understands the resulting
+TypeScript → `.ajs` source maps. Pass `.ts` paths to `program` and
+`source` — frames and breakpoints come back in `.ts` space
+automatically. The same source maps the platform's
+`@i-scope/webpack-config` produces are consumed unchanged here; see
+the platform's `docs/guides/debugging.md` for the producer side.
+
+## Testing
+
+Three integration tests (drive the server through the official
+`@modelcontextprotocol/sdk` client over stdio) plus one unit-test
+suite for the pure driver internals:
+
+```pwsh
+# Unit tests — no Oscilloscope, no DAP child. Covers Mutex, output-
+# buffer pagination, classifyFrame with reverse source-map lookup.
+npm --workspace=@i-scope/mcp-server run test:unit
+
+# Integration: pure source-map translation. No Oscilloscope.
+npm --workspace=iscope-debugger run test:mcp-sourcemaps
+
+# Integration: full launch → read output → disconnect cycle.
+# Requires Oscilloscope.exe + a .mwf.
+npm --workspace=iscope-debugger run test:mcp
+
+# Integration: snapshot equivalence — asserts debug_snapshot returns
+# the same payload as the headless inspect.cjs harness on the VLST
+# fixture. Requires Oscilloscope + .mwf.
+npm --workspace=iscope-debugger run test:mcp-snapshot
+```
+
+Integration test scripts live in
+`extension/cursor-vscode/src/tests/{18,19,20}-mcp-*.ts`; unit tests in
+`packages/mcp-server/src/__tests__/dap-driver.test.ts`.
+
+## Related packages
+
+This package is one of seven leaves of the
+[`@i-scope/debugger`](https://www.npmjs.com/package/@i-scope/debugger) SDK
+meta-umbrella. The full family:
+
+| Package | Role |
+|---------|------|
+| [`@i-scope/debugger`](https://www.npmjs.com/package/@i-scope/debugger) | **meta** — one-install entry point for the whole SDK |
+| **`@i-scope/mcp-server`** *(you are here)* | MCP server for AI agents (21 tools: 16 debug + 4 UI modal + 1 system) |
+| [`@i-scope/dap-adapter`](https://www.npmjs.com/package/@i-scope/dap-adapter) | DAP server (`AjsDebugSession`) — embeddable + stdio |
+| [`@i-scope/iscope-bridge-client`](https://www.npmjs.com/package/@i-scope/iscope-bridge-client) | Node JSON-RPC client to the native helper |
+| [`@i-scope/iscope-bridge`](https://www.npmjs.com/package/@i-scope/iscope-bridge) | Win32 native helper binary (`iScopeBridge.exe`) |
+| [`@i-scope/source-map-bridge`](https://www.npmjs.com/package/@i-scope/source-map-bridge) | TS ↔ AJS source-map manager |
+| [`@i-scope/vlst-parser`](https://www.npmjs.com/package/@i-scope/vlst-parser) | Parser for VLST locals/Watch blobs |
+| [`@i-scope/com-protocol-types`](https://www.npmjs.com/package/@i-scope/com-protocol-types) | TS-mirror of COM DISPID / event constants |
+
+See [`info/Naming-Taxonomy.md`](https://gitlab.com/i-scope/Debugger/-/blob/main/info/Naming-Taxonomy.md)
+for the rationale behind the package allocation.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/src/abi-check.d.ts

@@ -0,0 +1,19 @@
+import { type ProtocolVersionResponse, type AbiPolicy, type AbiCompatKind, type AbiWarningPayload } from '@i-scope/iscope-bridge-client';
+export interface AbiCheckResult {
+    ok: boolean;
+    clientAbi: string;
+    serverAbi: string;
+    server: string;
+    buildTime?: string;
+    compatKind: AbiCompatKind;
+    compatReason: string;
+    policy: AbiPolicy;
+    warnings: AbiWarningPayload[];
+    userHints: string[];
+}
+/**
+ * Evaluate wire ABI compatibility from a `protocol/version` response.
+ * Does not spawn the helper — callers supply the RPC result.
+ */
+export declare function evaluateAbiCheck(version: ProtocolVersionResponse, policy?: AbiPolicy, clientAbi?: string): AbiCheckResult;
+//# sourceMappingURL=abi-check.d.ts.map

package/dist/src/abi-check.js

@@ -0,0 +1,66 @@
+"use strict";
+// ABI probe logic shared by BridgeDriver and unit tests.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateAbiCheck = evaluateAbiCheck;
+const iscope_bridge_client_1 = require("@i-scope/iscope-bridge-client");
+/**
+ * Evaluate wire ABI compatibility from a `protocol/version` response.
+ * Does not spawn the helper — callers supply the RPC result.
+ */
+function evaluateAbiCheck(version, policy = 'strict', clientAbi = iscope_bridge_client_1.ISCOPE_BRIDGE_ABI_VERSION) {
+    const serverAbi = version.abi;
+    const compat = (0, iscope_bridge_client_1.checkAbiCompat)(clientAbi, serverAbi);
+    const warnings = [];
+    try {
+        (0, iscope_bridge_client_1.applyAbiPolicy)(serverAbi, policy, (w) => warnings.push(w), clientAbi);
+    }
+    catch (e) {
+        if (e instanceof iscope_bridge_client_1.ProtocolVersionMismatchError) {
+            return {
+                ok: false,
+                clientAbi,
+                serverAbi,
+                server: version.server,
+                buildTime: version.buildTime,
+                compatKind: 'fatal',
+                compatReason: e.message,
+                policy,
+                warnings,
+                userHints: buildUserHints(clientAbi, serverAbi, 'fatal', e.message),
+            };
+        }
+        throw e;
+    }
+    const ok = policy === 'ignore'
+        || policy === 'warn'
+        || compat.kind !== 'fatal';
+    return {
+        ok,
+        clientAbi,
+        serverAbi,
+        server: version.server,
+        buildTime: version.buildTime,
+        compatKind: compat.kind,
+        compatReason: compat.reason,
+        policy,
+        warnings,
+        userHints: buildUserHints(clientAbi, serverAbi, compat.kind, compat.reason),
+    };
+}
+function buildUserHints(clientAbi, serverAbi, kind, reason) {
+    if (kind === 'ok') {
+        return [`Wire ABI ${serverAbi} matches client expectation ${clientAbi}.`];
+    }
+    if (kind === 'warn') {
+        return [
+            reason || `Server ABI ${serverAbi} is older than client ${clientAbi}.`,
+            'Session may still work; upgrade iScopeBridge.exe when convenient.',
+        ];
+    }
+    return [
+        reason || `ABI incompatible: client expects ${clientAbi}, helper reports ${serverAbi}.`,
+        'Rebuild and redeploy iScopeBridge.exe from the same monorepo tag as @i-scope/iscope-bridge-client.',
+        'If you mix npm packages, pin matching versions from the same release.',
+    ];
+}
+//# sourceMappingURL=abi-check.js.map