@i-scope/mcp-server 0.4.2

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+"use strict";
+// @i-scope/mcp-server entry point.
+//
+// Wires:
+//   StdioServerTransport (stdin/stdout pipes to the MCP client, e.g.
+//   Cursor / Claude Desktop) → McpServer → tool registry → DapDriver
+//   (spawns the `server.js` shipped inside `@i-scope/dap-adapter` as
+//   the DAP child process; no path arithmetic required).
+//
+// Tool groups (each in its own file under ./tools):
+//   - lifecycle:    debug_launch / debug_disconnect / debug_current_state
+//   - breakpoints:  debug_set_breakpoints
+//   - execution:    debug_continue / debug_step_over|into|out
+//   - sync:         debug_wait_for_paused / debug_read_output
+//   - inspection:   debug_stack_trace / debug_scopes / debug_variables / debug_evaluate
+//   - snapshot:     debug_snapshot (composite — equivalent to inspect.cjs)
+//   - source-maps:  debug_resolve_source (no debug session needed)
+//
+// Cursor wiring (`.cursor/mcp.json`):
+//   {
+//     "mcpServers": {
+//       "iscope-debugger": {
+//         "command": "npx",
+//         "args": ["-y", "@i-scope/mcp-server"]
+//       }
+//     }
+//   }
+//   No ENV variables required — everything is resolved through the
+//   installed npm packages (`@i-scope/dap-adapter` →
+//   `@i-scope/iscope-bridge-client` → `@i-scope/iscope-bridge`).
+//   For monorepo development use the dist path directly:
+//   `command: "node", args: ["E:/.../packages/mcp-server/dist/src/index.js"]`.
+//
+// Stdout discipline:
+//   StdioServerTransport reads the JSON-RPC wire from stdin and
+//   writes it to stdout. ANY accidental console.log poisons the
+//   stream. We force all of our diagnostics through stderr and we
+//   monkey-patch console.log → console.error in this file so even a
+//   stray dependency log lands on the safe channel.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const os = __importStar(require("node:os"));
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const bridge_driver_js_1 = require("./bridge-driver.js");
+const dap_driver_js_1 = require("./dap-driver.js");
+const breakpoints_js_1 = require("./tools/breakpoints.js");
+const execution_js_1 = require("./tools/execution.js");
+const helpers_js_1 = require("./tools/helpers.js");
+const inspection_js_1 = require("./tools/inspection.js");
+const lifecycle_js_1 = require("./tools/lifecycle.js");
+const abi_check_js_1 = require("./tools/abi-check.js");
+const preflight_js_1 = require("./tools/preflight.js");
+const snapshot_js_1 = require("./tools/snapshot.js");
+const source_maps_js_1 = require("./tools/source-maps.js");
+const sync_js_1 = require("./tools/sync.js");
+const ui_modal_js_1 = require("./tools/ui-modal.js");
+function silenceStdout() {
+    // Reroute anything that wants to write to stdout (rogue
+    // dependency console.log, etc.) onto stderr. The MCP transport
+    // owns stdout.
+    /* eslint-disable no-console */
+    const origLog = console.log.bind(console);
+    void origLog;
+    console.log = ((...args) => console.error('[stdout-redirect]', ...args));
+    console.info = ((...args) => console.error('[stdout-redirect]', ...args));
+    /* eslint-enable no-console */
+}
+async function main() {
+    silenceStdout();
+    // `ISCOPE_EXTENSION_PATH` is optional now — it only acts as a
+    // `bundledRoot` override forwarded to the spawned DAP server.
+    // The default deployment installs `@i-scope/dap-adapter` and
+    // `@i-scope/iscope-bridge` from npm and needs no env at all.
+    const extensionPath = process.env['ISCOPE_EXTENSION_PATH'] || undefined;
+    process.stderr.write(`[@i-scope/mcp-server v${helpers_js_1.SERVER_INFO.version}] starting on ${os.platform()} ${os.arch()}` +
+        (extensionPath ? `; ISCOPE_EXTENSION_PATH=${extensionPath}` : '') +
+        `\n`);
+    const dap = new dap_driver_js_1.DapDriver({
+        extensionPath,
+        log: (line) => process.stderr.write(line + '\n'),
+    });
+    const bridge = new bridge_driver_js_1.BridgeDriver({
+        bundledRoot: extensionPath,
+        log: (line) => process.stderr.write(line + '\n'),
+    });
+    const drivers = { dap, bridge };
+    const server = new mcp_js_1.McpServer(helpers_js_1.SERVER_INFO, {
+        instructions: helpers_js_1.SERVER_INSTRUCTIONS,
+        capabilities: {
+            tools: { listChanged: false },
+            logging: {},
+        },
+    });
+    (0, lifecycle_js_1.registerLifecycleTools)(server, drivers);
+    (0, breakpoints_js_1.registerBreakpointTools)(server, drivers);
+    (0, execution_js_1.registerExecutionTools)(server, drivers);
+    (0, sync_js_1.registerSyncTools)(server, drivers);
+    (0, inspection_js_1.registerInspectionTools)(server, drivers);
+    (0, snapshot_js_1.registerSnapshotTools)(server, drivers);
+    (0, source_maps_js_1.registerSourceMapTools)(server, drivers);
+    (0, ui_modal_js_1.registerUIModalTools)(server, drivers);
+    (0, preflight_js_1.registerPreflightTools)(server, drivers);
+    (0, abi_check_js_1.registerAbiCheckTools)(server, drivers);
+    const transport = new stdio_js_1.StdioServerTransport();
+    // Graceful cleanup so we don't orphan Oscilloscope on ^C / IDE
+    // restart. The MCP transport closes naturally when stdin EOFs,
+    // but we still need to tear down the DAP child explicitly.
+    let shuttingDown = false;
+    const shutdown = (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        process.stderr.write(`[@i-scope/mcp-server] ${signal} received, shutting down\n`);
+        // Fire-and-forget: best-effort disconnect, then exit. Don't
+        // await — node's signal handler should be quick.
+        Promise.allSettled([
+            dap.disconnect(),
+            bridge.disconnect(),
+        ]).then((results) => {
+            for (const r of results) {
+                if (r.status === 'rejected')
+                    process.stderr.write(`[@i-scope/mcp-server] disconnect error: ${r.reason}\n`);
+            }
+            process.exit(0);
+        });
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    transport.onclose = () => {
+        // Client disconnected (Cursor restarted, user removed the
+        // server from .cursor/mcp.json, ...). Same cleanup path.
+        shutdown('transport-close');
+    };
+    await server.connect(transport);
+    process.stderr.write('[@i-scope/mcp-server] ready; awaiting MCP requests on stdio\n');
+}
+main().catch((err) => {
+    process.stderr.write(`[@i-scope/mcp-server] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/src/state.d.ts

@@ -0,0 +1,86 @@
+/** High-level lifecycle of a single MCP debug session. */
+export type SessionState = 'idle' | 'launching' | 'running' | 'paused' | 'terminated';
+/** DAP `StoppedEvent.reason` values we care about — narrowed to the
+ *  subset the iScope adapter actually emits. The MCP layer keeps the
+ *  raw DAP string verbatim so AI doesn't lose nuance. */
+export type StoppedReason = 'breakpoint' | 'step' | 'exception' | 'entry' | 'pause' | 'goto' | string;
+/** Origin of the `source` path returned in a frame.
+ *
+ *  AI uses this to detect "source map gap" without parsing
+ *  configuration. `unmapped-fallback` is the loudest signal — it means
+ *  the user launched against `.ts` but for THIS specific line the
+ *  bundler did not emit a mapping, so we surface the generated `.ajs`
+ *  position instead of pretending we know the original. */
+export type SourceOrigin = 'mapped' | 'generated' | 'unmapped-fallback';
+/** One stack frame, post-translation. Mirrors DAP `StackFrame` plus
+ *  the source-map provenance fields. */
+export interface FrameInfo {
+    /** DAP frame id. Stable across `stack_trace` calls within ONE
+     *  paused state; invalidated on resume/step/terminate. */
+    id: number;
+    /** Frame name from the engine (`probe`, `Host script block`, ...). */
+    name: string;
+    /** Source path the user would recognise — `.ts` if we mapped,
+     *  `.ajs` otherwise. */
+    source: string;
+    /** Provenance of `source` (see {@link SourceOrigin}). */
+    sourceOrigin: SourceOrigin;
+    /** 1-based start line of the active statement in `source`. */
+    line: number;
+    /** 1-based start column in `source`. */
+    column: number;
+    /** 1-based end line for statement highlight; may equal `line`. */
+    endLine?: number;
+    /** 1-based end column (exclusive of trailing `;`). */
+    endColumn?: number;
+    /** Always populated when an `.ajs` exists, even for mapped
+     *  frames — useful when the AI wants to cross-reference with raw
+     *  engine offsets / engine logs. */
+    generatedSource?: string;
+    /** 1-based line in the generated `.ajs` regardless of mapping. */
+    generatedLine?: number;
+    /** 1-based column in the generated `.ajs`. */
+    generatedColumn?: number;
+}
+/** Snapshot of "where execution is right now" produced after every
+ *  state transition into `paused`. */
+export interface StoppedInfo {
+    reason: StoppedReason;
+    /** Innermost-frame error description when reason==='exception'. */
+    description?: string;
+    /** Full call stack, innermost first. */
+    frames: FrameInfo[];
+}
+/** One buffered `OutputEvent`. Cursor pagination uses `id` (monotonic
+ *  insertion order). */
+export interface OutputEntry {
+    /** Monotonic, gapless integer. Starts at 1. AI passes the highest
+     *  seen `id` back as `cursor` to read the tail. */
+    id: number;
+    /** DAP category: `stdout` / `stderr` / `console` / `important` ... */
+    category: string;
+    /** Raw text from the engine / adapter. May or may not end in `\n`
+     *  — we do not normalise. */
+    text: string;
+    /** Unix epoch ms when this MCP server received the event. */
+    timestamp: number;
+}
+/** Result returned by execution-control / sync tools after waiting on
+ *  the next state transition. Either "we paused" (with details) or
+ *  "the script ended" (`terminated: true`) — never both. */
+export type ExecutionTransition = {
+    state: 'paused';
+    stopped: StoppedInfo;
+} | {
+    state: 'terminated';
+    exitInfo?: TerminationInfo;
+} | {
+    state: 'timeout';
+    waitedMs: number;
+};
+export interface TerminationInfo {
+    /** Best-effort reason from the adapter / helper. Empty when the
+     *  script ended cleanly via `DBGEID_STOP`. */
+    reason?: string;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/src/state.js

@@ -0,0 +1,15 @@
+"use strict";
+// Shared types for the MCP server.
+//
+// Why these live in a dedicated module:
+//   - DapDriver, every tool group, and (Phase 2/3) BridgeDriver all
+//     need to talk about the same notions: "paused state", "frame",
+//     "output entry". Without a single source of truth the field names
+//     drift between tools and the AI gets a confusing tool-result
+//     surface.
+//   - Tool input/output Zod schemas live next to each tool's
+//     registration; THESE types are the runtime data exchanged between
+//     the driver layer and the tool layer (post-validation). The Zod
+//     side is presentation; this side is implementation.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1,3 @@
+import type { ToolGroupRegistrar } from './registry.js';
+export declare const registerAbiCheckTools: ToolGroupRegistrar;
+//# sourceMappingURL=abi-check.d.ts.map

package/dist/src/tools/abi-check.js

@@ -0,0 +1,64 @@
+"use strict";
+// system_abi_check — wire ABI probe via `protocol/version` (no COM).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAbiCheckTools = void 0;
+const zod_1 = require("zod");
+const helpers_js_1 = require("./helpers.js");
+const policySchema = zod_1.z.enum(['strict', 'warn', 'ignore']).optional();
+const warningShape = zod_1.z.object({
+    clientAbi: zod_1.z.string(),
+    serverAbi: zod_1.z.string(),
+    reason: zod_1.z.string(),
+});
+const registerAbiCheckTools = (server, { bridge }) => {
+    server.registerTool('system_abi_check', {
+        title: 'Check iScopeBridge wire ABI',
+        description: 'Probe the bundled iScopeBridge.exe JSON-RPC wire ABI via `protocol/version` ' +
+            '(no Oscilloscope, no COM, no debug session). Returns client vs server semver, ' +
+            'compatibility kind (ok / warn / fatal), and actionable hints when the helper ' +
+            'binary is older or newer than @i-scope/iscope-bridge-client expects. Call before ' +
+            'debug_launch when upgrading packages or after copying a custom helper binary.',
+        inputSchema: {
+            policy: policySchema.describe('Semver policy: strict (default) — fatal on MAJOR mismatch; warn — emit warnings only; ignore — skip checks.'),
+        },
+        outputSchema: {
+            ok: zod_1.z.boolean(),
+            clientAbi: zod_1.z.string(),
+            serverAbi: zod_1.z.string(),
+            server: zod_1.z.string(),
+            buildTime: zod_1.z.string().optional(),
+            compatKind: zod_1.z.enum(['ok', 'warn', 'fatal']),
+            compatReason: zod_1.z.string(),
+            policy: policySchema,
+            warnings: zod_1.z.array(warningShape),
+            userHints: zod_1.z.array(zod_1.z.string()),
+        },
+        annotations: {
+            title: 'Check iScopeBridge wire ABI',
+            readOnlyHint: true,
+            idempotentHint: true,
+        },
+    }, async (args) => {
+        try {
+            const result = await bridge.abiCheck(args.policy);
+            return (0, helpers_js_1.ok)(result);
+        }
+        catch (e) {
+            return (0, helpers_js_1.fail)(`system_abi_check failed: ${errMsg(e)}`);
+        }
+    });
+};
+exports.registerAbiCheckTools = registerAbiCheckTools;
+function errMsg(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    try {
+        return JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+//# sourceMappingURL=abi-check.js.map

package/dist/src/tools/breakpoints.d.ts

@@ -0,0 +1,3 @@
+import type { ToolGroupRegistrar } from './registry.js';
+export declare const registerBreakpointTools: ToolGroupRegistrar;
+//# sourceMappingURL=breakpoints.d.ts.map

package/dist/src/tools/breakpoints.js

@@ -0,0 +1,56 @@
+"use strict";
+// debug_set_breakpoints.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBreakpointTools = void 0;
+const zod_1 = require("zod");
+const helpers_js_1 = require("./helpers.js");
+const setBreakpointsInput = {
+    source: zod_1.z.string().describe('Absolute or workspace-relative source path. `.ts` is fine — the adapter will map lines to the generated `.ajs` automatically. ⚠ REPLACE semantics: the list of lines you pass becomes THE complete breakpoint set for THIS source file. To clear all breakpoints in this file pass lines: []. Existing breakpoints in OTHER source files are NOT touched.'),
+    lines: zod_1.z.array(zod_1.z.number().int().positive()).describe('1-based line numbers in `source`. Empty array clears all breakpoints in `source`. Lines outside executable code (comments, blank lines) are silently dropped by the engine — they will come back `verified: false`.'),
+};
+const registerBreakpointTools = (server, { dap }) => {
+    server.registerTool('debug_set_breakpoints', {
+        title: 'Set breakpoints',
+        description: 'Replace breakpoints for ONE source file. Returns one `{line, verified}` per requested line in the same order. May be called before debug_launch (the adapter buffers them until configurationDone) or while paused (mid-run set is forwarded as individual SetResetBrkPnt RPCs). Calling while the script is running is fine but the engine cannot install BPs until the next pause — verified flags reflect best effort.',
+        inputSchema: setBreakpointsInput,
+        outputSchema: {
+            breakpoints: zod_1.z.array(zod_1.z.object({
+                line: zod_1.z.number().optional(),
+                verified: zod_1.z.boolean(),
+                message: zod_1.z.string().optional(),
+            })),
+        },
+        annotations: {
+            title: 'Set breakpoints',
+            idempotentHint: true,
+            destructiveHint: false,
+        },
+    }, async (args) => {
+        try {
+            const body = await dap.setBreakpoints(args.source, args.lines);
+            const bps = (body?.breakpoints ?? []).map((bp) => ({
+                line: bp.line,
+                verified: bp.verified === true,
+                message: bp.message,
+            }));
+            return (0, helpers_js_1.ok)({ breakpoints: bps });
+        }
+        catch (e) {
+            return (0, helpers_js_1.fail)(`debug_set_breakpoints failed: ${errMsg(e)}`);
+        }
+    });
+};
+exports.registerBreakpointTools = registerBreakpointTools;
+function errMsg(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    try {
+        return JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+//# sourceMappingURL=breakpoints.js.map

package/dist/src/tools/execution.d.ts

@@ -0,0 +1,3 @@
+import type { ToolGroupRegistrar } from './registry.js';
+export declare const registerExecutionTools: ToolGroupRegistrar;
+//# sourceMappingURL=execution.d.ts.map

package/dist/src/tools/execution.js

@@ -0,0 +1,75 @@
+"use strict";
+// debug_continue / debug_step_over / debug_step_into / debug_step_out.
+//
+// All four tools share the same shape: send a DAP request, wait for
+// the next state transition (stopped / terminated / timeout), return
+// it as the response. The AI doesn't need to call a separate
+// `debug_wait_for_paused` afterwards.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerExecutionTools = void 0;
+const zod_1 = require("zod");
+const helpers_js_1 = require("./helpers.js");
+const stepInput = {
+    timeoutMs: zod_1.z.number().int().positive().optional().describe('Max ms to wait for the resulting paused/terminated event. Defaults to 30 000. If the script keeps running past this timeout, returns {state:"timeout"}; you can then call debug_wait_for_paused to keep waiting.'),
+};
+const transitionShape = zod_1.z.object({
+    state: zod_1.z.enum(['paused', 'terminated', 'timeout']),
+    stopped: zod_1.z.unknown().optional(),
+    exitInfo: zod_1.z.unknown().optional(),
+    waitedMs: zod_1.z.number().optional(),
+});
+function makeResume(dap, label, dapCall) {
+    return async (args) => {
+        try {
+            const t = await dap.resumeAndWait(dapCall, args.timeoutMs);
+            return (0, helpers_js_1.ok)({ transition: (0, helpers_js_1.shapeTransition)(t) });
+        }
+        catch (e) {
+            return (0, helpers_js_1.fail)(`${label} failed: ${errMsg(e)}`);
+        }
+    };
+}
+const registerExecutionTools = (server, { dap }) => {
+    server.registerTool('debug_continue', {
+        title: 'Continue',
+        description: 'Resume the script. Returns the next paused state (breakpoint / step done / exception) or `terminated` if the script finishes. The response contains the new stack — no need to call debug_stack_trace separately when stopped on a breakpoint.',
+        inputSchema: stepInput,
+        outputSchema: { transition: transitionShape },
+        annotations: { title: 'Continue', idempotentHint: false },
+    }, makeResume(dap, 'debug_continue', (dc) => dc.request('continue', { threadId: 1 })));
+    server.registerTool('debug_step_over', {
+        title: 'Step over',
+        description: 'Step over: execute the current statement and pause on the next one in the SAME frame (do not descend into function calls).',
+        inputSchema: stepInput,
+        outputSchema: { transition: transitionShape },
+        annotations: { title: 'Step over', idempotentHint: false },
+    }, makeResume(dap, 'debug_step_over', (dc) => dc.request('next', { threadId: 1 })));
+    server.registerTool('debug_step_into', {
+        title: 'Step into',
+        description: 'Step into: execute the current statement and, if it calls a function, pause on the first statement of that function.',
+        inputSchema: stepInput,
+        outputSchema: { transition: transitionShape },
+        annotations: { title: 'Step into', idempotentHint: false },
+    }, makeResume(dap, 'debug_step_into', (dc) => dc.request('stepIn', { threadId: 1 })));
+    server.registerTool('debug_step_out', {
+        title: 'Step out',
+        description: 'Step out: resume until the current frame returns, then pause in the caller.',
+        inputSchema: stepInput,
+        outputSchema: { transition: transitionShape },
+        annotations: { title: 'Step out', idempotentHint: false },
+    }, makeResume(dap, 'debug_step_out', (dc) => dc.request('stepOut', { threadId: 1 })));
+};
+exports.registerExecutionTools = registerExecutionTools;
+function errMsg(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    try {
+        return JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+//# sourceMappingURL=execution.js.map

package/dist/src/tools/helpers.d.ts

@@ -0,0 +1,27 @@
+import type { CallToolResult, Implementation } from '@modelcontextprotocol/sdk/types.js';
+import type { ExecutionTransition, FrameInfo, OutputEntry, StoppedInfo } from '../state.js';
+/** Wrap a structured payload as a CallToolResult with a JSON-text
+ *  mirror. `structuredContent` is validated by the SDK against the
+ *  tool's `outputSchema` (when one is declared). */
+export declare function ok<T extends Record<string, unknown>>(payload: T): CallToolResult;
+/** Build the standard error result. We deliberately use the SDK's
+ *  `isError` flag rather than throwing, so the AI gets a clear tool-
+ *  level error response instead of a transport failure. */
+export declare function fail(message: string, details?: Record<string, unknown>): CallToolResult;
+/** Drop `undefined` values so JSON.stringify produces a clean
+ *  output. The MCP SDK's strict JSON-Schema validator may reject
+ *  payloads where an optional field is explicitly `undefined`
+ *  (becomes `null` after JSON.parse). */
+export declare function pruneUndefined<T extends Record<string, unknown>>(o: T): T;
+export declare function shapeFrame(f: FrameInfo): Record<string, unknown>;
+export declare function shapeStopped(s: StoppedInfo): Record<string, unknown>;
+export declare function shapeTransition(t: ExecutionTransition): Record<string, unknown>;
+export declare function shapeOutputEntry(e: OutputEntry): Record<string, unknown>;
+/** Centralised server identity. Bumped together with package.json. */
+export declare const SERVER_INFO: Implementation;
+/** Server instructions surfaced to the LLM by clients that respect
+ *  the MCP spec (Claude Desktop / Cursor do). Keep concise — the AI
+ *  reads tool descriptions on each call already; this is for cross-
+ *  tool workflow rules that don't fit any single tool's description. */
+export declare const SERVER_INSTRUCTIONS: string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/src/tools/helpers.js

@@ -0,0 +1,134 @@
+"use strict";
+// Helpers shared across tool groups.
+//
+// Two concerns live here:
+//   1. Pack a CallToolResult that has BOTH structuredContent (the
+//      JSON the AI cares about) AND a `content` text mirror (so MCP
+//      clients that ignore structuredContent still get something
+//      readable). The MCP SDK validates structuredContent against
+//      `outputSchema` when one is declared.
+//   2. Translate driver-level types (ExecutionTransition, FrameInfo,
+//      ...) into AI-friendly objects. The driver types are wire-
+//      level; we expose only the fields the AI needs.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS = exports.SERVER_INFO = void 0;
+exports.ok = ok;
+exports.fail = fail;
+exports.pruneUndefined = pruneUndefined;
+exports.shapeFrame = shapeFrame;
+exports.shapeStopped = shapeStopped;
+exports.shapeTransition = shapeTransition;
+exports.shapeOutputEntry = shapeOutputEntry;
+/** Wrap a structured payload as a CallToolResult with a JSON-text
+ *  mirror. `structuredContent` is validated by the SDK against the
+ *  tool's `outputSchema` (when one is declared). */
+function ok(payload) {
+    const text = {
+        type: 'text',
+        text: JSON.stringify(payload),
+    };
+    return {
+        content: [text],
+        structuredContent: payload,
+    };
+}
+/** Build the standard error result. We deliberately use the SDK's
+ *  `isError` flag rather than throwing, so the AI gets a clear tool-
+ *  level error response instead of a transport failure. */
+function fail(message, details) {
+    const text = {
+        type: 'text',
+        text: details
+            ? `${message}\n${JSON.stringify(details, null, 2)}`
+            : message,
+    };
+    return {
+        content: [text],
+        isError: true,
+        structuredContent: { error: message, ...(details ?? {}) },
+    };
+}
+/** Drop `undefined` values so JSON.stringify produces a clean
+ *  output. The MCP SDK's strict JSON-Schema validator may reject
+ *  payloads where an optional field is explicitly `undefined`
+ *  (becomes `null` after JSON.parse). */
+function pruneUndefined(o) {
+    for (const k of Object.keys(o)) {
+        if (o[k] === undefined)
+            delete o[k];
+    }
+    return o;
+}
+function shapeFrame(f) {
+    return pruneUndefined({
+        id: f.id,
+        name: f.name,
+        source: f.source,
+        sourceOrigin: f.sourceOrigin,
+        line: f.line,
+        column: f.column,
+        endLine: f.endLine,
+        endColumn: f.endColumn,
+        generatedSource: f.generatedSource,
+        generatedLine: f.generatedLine,
+        generatedColumn: f.generatedColumn,
+    });
+}
+function shapeStopped(s) {
+    return pruneUndefined({
+        reason: s.reason,
+        description: s.description,
+        frames: s.frames.map(shapeFrame),
+    });
+}
+function shapeTransition(t) {
+    if (t.state === 'paused')
+        return { state: 'paused', stopped: shapeStopped(t.stopped) };
+    if (t.state === 'terminated')
+        return pruneUndefined({
+            state: 'terminated',
+            exitInfo: t.exitInfo ? pruneUndefined({ reason: t.exitInfo.reason }) : undefined,
+        });
+    return { state: 'timeout', waitedMs: t.waitedMs };
+}
+function shapeOutputEntry(e) {
+    return {
+        id: e.id,
+        category: e.category,
+        text: e.text,
+        timestamp: e.timestamp,
+    };
+}
+/** Centralised server identity. Bumped together with package.json. */
+exports.SERVER_INFO = {
+    name: '@i-scope/mcp-server',
+    version: '0.4.2',
+    title: 'iScope Debugger',
+};
+/** Server instructions surfaced to the LLM by clients that respect
+ *  the MCP spec (Claude Desktop / Cursor do). Keep concise — the AI
+ *  reads tool descriptions on each call already; this is for cross-
+ *  tool workflow rules that don't fit any single tool's description. */
+exports.SERVER_INSTRUCTIONS = [
+    'iScope MCP server: drives a `.ajs` (or transpiled-from-`.ts`) debug session in Oscilloscope.exe via the iScope DAP adapter.',
+    '',
+    'Workflow rules:',
+    '- Call `debug_launch` before any other debug_* tool. State must be "paused" before stack_trace / scopes / variables / evaluate.',
+    '- Execution tools (`debug_continue`, `debug_step_*`) return the NEXT paused state (or terminated/timeout) — no separate `debug_wait_for_paused` call needed in the common case.',
+    '- `debug_set_breakpoints` REPLACES the breakpoint set for the given source. Passing `lines: []` clears them. Pass the COMPLETE list each time.',
+    '- Always finish with `debug_disconnect`. Leaking a session orphans Oscilloscope when this server exits.',
+    '- Source maps: pass `.ts` paths to `program` and `source` whenever a TS sibling exists — frames come back in `.ts` with `sourceOrigin: "mapped"`. `sourceOrigin: "unmapped-fallback"` signals that the .ajs.map has a gap; treat returned positions as raw `.ajs` coordinates.',
+    '- Use `debug_resolve_source` to translate `.ts ↔ .ajs` positions without launching a session (e.g. when inspecting engine error logs).',
+    '',
+    'UI modal control (`ui_modal_*`):',
+    '- Use `ui_modal_list` to see if Oscilloscope is currently showing any child dialog (Configure() input form, "Save changes?" prompt, "Unable to..." error).',
+    '- A `debug_continue`/`debug_step_*` that silently times out is often the AI signal that a script-level Configure() modal is blocking the engine — list, fill, click OK, and execution will resume.',
+    '- These tools work WITHOUT an active debug session (Oscilloscope only needs to be running) and are SAFE to mix with an active DAP session.',
+    '',
+    'System diagnostics:',
+    '- Use `system_preflight_check` proactively when a launch silently fails / breakpoints are ignored / Oscilloscope reports "Unable to create debuger object!". It probes the registry for the Windows Script Debugger (Machine Debug Manager) and the Oscilloscope COM CLSID — the two prerequisites of the iScope debug stack — and returns a structured verdict with user-actionable hints + download URL when something is missing. Read-only / idempotent / does not require Oscilloscope to be running.',
+    '- Use `system_abi_check` when mixing npm package versions or after swapping iScopeBridge.exe — it calls `protocol/version` (no COM) and compares wire ABI semver to @i-scope/iscope-bridge-client. Run before debug_launch if you see ProtocolVersionMismatchError or suspect a stale helper binary.',
+    '',
+    'Pause is NOT supported (Oscilloscope COM API has no Pause()). Use breakpoints + step instead.',
+].join('\n');
+//# sourceMappingURL=helpers.js.map

package/dist/src/tools/inspection.d.ts

@@ -0,0 +1,3 @@
+import type { ToolGroupRegistrar } from './registry.js';
+export declare const registerInspectionTools: ToolGroupRegistrar;
+//# sourceMappingURL=inspection.d.ts.map