@i-scope/debugger

Official single-install entry point for the iScope Debugger SDK — the open-source toolkit for debugging Oscilloscope.exe .ajs (JScript ES3) scripts. This is a pure meta-package: it ships no runtime code, just a curated set of dependencies that transitively pull in every piece of the SDK (DAP adapter, MCP server, Win32 native helper, source-map / VLST / COM-protocol leaves).

Quick install

npm install @i-scope/debugger

That's it. After install you can import from any of the underlying packages — @i-scope/mcp-server, @i-scope/dap-adapter, @i-scope/iscope-bridge-client, etc. — without listing them individually in your own package.json.

Who should install this

| Persona | Recommended install | Entry point | |---------|---------------------|-------------| | AI agent through MCP (Cursor / VS Code) | Marketplace extension i-scope.iscope-debugger | Command Palette → iScope: Enable MCP | | AI agent through MCP (Claude Code / other) | @i-scope/mcp-server (npx -y) | client's mcp.json — see @i-scope/mcp-server README | | DAP host integration (WebStorm, Neovim DAP, custom IDE) | @i-scope/debugger (full set) | import { AjsDebugSession } from '@i-scope/dap-adapter' | | CLI / custom Node tooling | @i-scope/debugger (full set) OR point-pick @i-scope/iscope-bridge-client standalone | import { IScopeBridge } from '@i-scope/iscope-bridge-client' | | VS Code / Cursor F5 debug | Do NOT install this npm meta. Install the Marketplace extension — it bundles the DAP stack. | F5 in .ajs / .ts files; MCP via iScope: Enable MCP |

Note that @i-scope/debugger (this package, published on npmjs.com) and the unscoped iscope-debugger (the VS Code / Cursor extension published on the Visual Studio Marketplace and OpenVSX) are two different artefacts living on two different registries with two different audiences — there is no name collision. End-users install the extension; SDK consumers install this meta-package.

What's inside

Installing @i-scope/debugger transitively brings in the full SDK (2 direct deps + 5 transitive):

• @i-scope/mcp-server (direct dep) — MCP server exposing 22 debugger tools to AI agents (16 debug + 4 UI modal + 2 system).
• @i-scope/dap-adapter (direct dep) — DAP server (AjsDebugSession) for IDE integrations; ships both a stand-alone stdio server (npx iscope-debug-server) and an embeddable class.
• @i-scope/iscope-bridge-client (transitive) — Node JSON-RPC client to the native helper; exports IScopeBridge, resolveHelperPath, OSC_NOT_FOUND detector, VLST helpers.
• @i-scope/iscope-bridge (transitive) — Win32 native helper iScopeBridge.exe (JSON-RPC stdio → COM bridge to Oscilloscope.exe). Binary-only tarball.
• @i-scope/source-map-bridge (transitive) — bidirectional TS ↔ AJS source-map manager (inline / sidecar / implicit, webpack:// URLs).
• @i-scope/vlst-parser (transitive) — pure-TypeScript parser for Oscilloscope VLST blobs (the wire format for locals / Watch).
• @i-scope/com-protocol-types (transitive) — COM constants mirror (DISPID, GSTID, RTID, STEPACT, BRKREASON) — TS dzeркало of Constants.h.

@i-scope/dap-adapter is listed as a direct dep (in addition to being transitive through @i-scope/mcp-server) so the DAP-only persona gets a clean top-level npm update @i-scope/dap-adapter.

Prerequisites

This SDK targets Windows only (the iScopeBridge.exe helper is Win32 native, and Oscilloscope.exe is a Windows COM server). Before the debugger can attach to a running Oscilloscope you need:

• Windows 10 / 11.
• Oscilloscope.exe installed and running with a .mwf waveform loaded.
• Machine Debug Manager (MDM) registered — i.e. pdm.dll present under HKCR\CLSID\{0BB89CE8-...}. Install via "Windows Script Debugger" or via the legacy script56.exe package.
• Node.js ≥ 20 in your host process.

Quick start — MCP integration (most common path)

Cursor / VS Code: install iScope .ajs Debugger and run iScope: Enable MCP. That writes the npx -y @i-scope/mcp-server entry into workspace .cursor/mcp.json or .vscode/mcp.json. Then Developer: Reload Window in this editor (not Oscilloscope).

Other MCP clients (Claude Code, …), after npm install @i-scope/debugger or with npx only — example Cursor-style file if the client uses mcpServers (server id iscope-debug):

{
  "mcpServers": {
    "iscope-debug": {
      "command": "npx",
      "args": ["-y", "@i-scope/mcp-server"]
    }
  }
}

The AI agent now has access to all 22 MCP tools — debug_launch, debug_set_breakpoints, debug_step_into, debug_variables, debug_snapshot, debug_resolve_source, ui_modal_list, system_preflight_check, … See @i-scope/mcp-server README for the full tool reference.

Documentation

• Monorepo: https://gitlab.com/i-scope/Debugger

License

MIT — see LICENSE.