@i-scope/mcp-server 0.4.2

package/src/tools/inspection.ts

@@ -0,0 +1,173 @@
+// debug_stack_trace / debug_scopes / debug_variables / debug_evaluate.
+
+import { z } from 'zod';
+import type { DebugProtocol } from '@vscode/debugprotocol';
+
+import { fail, ok, shapeFrame } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const variableShape = z.object({
+    name:               z.string(),
+    type:               z.string().optional(),
+    value:              z.string(),
+    variablesReference: z.number(),
+});
+
+export const registerInspectionTools: ToolGroupRegistrar = (server, { dap }) => {
+    server.registerTool(
+        'debug_stack_trace',
+        {
+            title: 'Get call stack',
+            description:
+                'Full JScript call stack at the current pause point. Frames are innermost-first (frames[0] is where execution stopped, frames[last] is the global script body). Each frame.source is `.ts` when source-map mapping succeeded (sourceOrigin: "mapped") or `.ajs` otherwise (sourceOrigin: "generated" or "unmapped-fallback"). State must be "paused".',
+            inputSchema: {},
+            outputSchema: {
+                frames: z.array(z.unknown()),
+            },
+            annotations: {
+                title: 'Get call stack',
+                readOnlyHint: true,
+                idempotentHint: true,
+            },
+        },
+        async () => {
+            try {
+                const body = await dap.stackTrace();
+                const frames = await Promise.all(
+                    (body?.stackFrames ?? []).map(
+                        async (f: DebugProtocol.StackFrame) => shapeFrame(await dap.classifyFrame(f)),
+                    ),
+                );
+                return ok({ frames });
+            } catch (e) {
+                return fail(`debug_stack_trace failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    server.registerTool(
+        'debug_scopes',
+        {
+            title: 'Get scopes for a frame',
+            description:
+                'Return the variable scopes (Locals, Globals, ...) available for the given frame. Each scope has a `variablesReference` you pass to debug_variables to enumerate its contents. The iScope adapter exposes one "Locals" scope per frame; Globals are surfaced as a special `[Globals]` row inside Locals.',
+            inputSchema: {
+                frameId: z.number().int().describe(
+                    'Frame id from debug_stack_trace.frames[].id. Stable only within ONE paused state — invalidated by step / continue / disconnect.',
+                ),
+            },
+            outputSchema: {
+                scopes: z.array(z.object({
+                    name:               z.string(),
+                    variablesReference: z.number(),
+                    expensive:          z.boolean().optional(),
+                })),
+            },
+            annotations: {
+                title: 'Get scopes for a frame',
+                readOnlyHint: true,
+                idempotentHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const body = await dap.scopes(args.frameId);
+                const scopes = (body?.scopes ?? []).map((s: DebugProtocol.Scope) => ({
+                    name:               s.name,
+                    variablesReference: s.variablesReference,
+                    expensive:          s.expensive,
+                }));
+                return ok({ scopes });
+            } catch (e) {
+                return fail(`debug_scopes failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    server.registerTool(
+        'debug_variables',
+        {
+            title: 'Get variables for a scope or compound',
+            description:
+                'Enumerate variables under the given `variablesReference`. Pass the reference returned by debug_scopes (top-level) or by a previous debug_variables call on a compound (drill-down). Each child variable with `variablesReference > 0` is itself expandable. Returns name, type (Num/Str/Obj/Arr/...), value (string render) and the reference for further drill-down.',
+            inputSchema: {
+                variablesReference: z.number().int().positive().describe(
+                    'Handle from debug_scopes.scopes[].variablesReference or a previous debug_variables result. Invalidated on step / continue / disconnect.',
+                ),
+            },
+            outputSchema: {
+                variables: z.array(variableShape),
+            },
+            annotations: {
+                title: 'Get variables',
+                readOnlyHint: true,
+                idempotentHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const body = await dap.variables(args.variablesReference);
+                const variables = (body?.variables ?? []).map((v: DebugProtocol.Variable) => ({
+                    name:               v.name,
+                    type:               v.type,
+                    value:              v.value,
+                    variablesReference: v.variablesReference ?? 0,
+                }));
+                return ok({ variables });
+            } catch (e) {
+                return fail(`debug_variables failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    server.registerTool(
+        'debug_evaluate',
+        {
+            title: 'Evaluate an expression',
+            description:
+                'Evaluate a JScript expression in the context of a paused frame. Context "watch" is for Watch-pane semantics (no side effects); "hover" for tool-tip rendering; "repl" for free-form input. The expression runs through the engine\'s ParceExpressions path — it sees the frame\'s real local scope, so `myVar.field[3]` works as in the editor. Returns the result string and an optional `variablesReference` when the result is compound (drill in via debug_variables).',
+            inputSchema: {
+                expression: z.string().describe(
+                    'JScript expression to evaluate. Engine quirks: ES3 only, no arrow funcs / let / const; `JSON.stringify` is polyfilled by the iScope runtime but only inside user scripts — at watch-time we hit the raw engine, so prefer plain property access.',
+                ),
+                frameId: z.number().int().optional().describe(
+                    'Frame id from debug_stack_trace.frames[].id. Omit to evaluate in the innermost frame (default).',
+                ),
+                context: z.enum(['watch', 'hover', 'repl']).optional().describe(
+                    'Default "watch".',
+                ),
+            },
+            outputSchema: {
+                result:              z.string(),
+                type:                z.string().optional(),
+                variablesReference:  z.number(),
+            },
+            annotations: {
+                title: 'Evaluate expression',
+                readOnlyHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const body = await dap.evaluate(
+                    args.expression,
+                    args.frameId,
+                    args.context ?? 'watch',
+                );
+                return ok({
+                    result:             body?.result ?? '',
+                    type:               body?.type,
+                    variablesReference: body?.variablesReference ?? 0,
+                });
+            } catch (e) {
+                return fail(`debug_evaluate failed: ${errMsg(e)}`);
+            }
+        },
+    );
+};
+
+function errMsg(e: unknown): string {
+    if (e instanceof Error) return e.message;
+    if (typeof e === 'string') return e;
+    try { return JSON.stringify(e); } catch { return String(e); }
+}

package/src/tools/lifecycle.ts

@@ -0,0 +1,129 @@
+// debug_launch / debug_disconnect / debug_current_state.
+
+import { z } from 'zod';
+
+import { fail, ok, pruneUndefined, shapeStopped, shapeTransition } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const launchInput = {
+    program: z.string().describe(
+        'Absolute or workspace-relative path to the script to debug. Accepts .ajs, .apn, .aps (engine-native), OR .ts (auto-resolved to a sibling .ajs). Pass .ts whenever a TS sibling exists — frames will come back in TS with sourceOrigin="mapped". The adapter rejects other extensions before they reach Oscilloscope to avoid a modal "syntax error" wedge.',
+    ),
+    mwfFile: z.string().optional().describe(
+        'Override mwf oscillogram path. If omitted, falls back to the `iScopeAjs.mwfPath` setting or env OSCILLOGRAM_MWF. Must point at a real .mwf, otherwise Oscilloscope shows a modal "Please load oscillogram file…" that wedges the COM thread (the helper validates first, but only when this field is non-empty).',
+    ),
+    autoLaunch: z.boolean().optional().describe(
+        'Default true. When true and Oscilloscope.exe is not running, the helper launches it. When false the helper attaches to an already-running instance — and will FAIL if none is found.',
+    ),
+    openFileBeforeRun: z.boolean().nullable().optional().describe(
+        'Tri-state. true = always OpenFile(mwfFile); false = never OpenFile (use whatever is loaded); null/undefined = smart (OpenFile only if we launched Oscilloscope AND have a path). The `null` default matches the extension behaviour and is usually right.',
+    ),
+    stopOnEntry: z.union([z.boolean(), z.literal('auto')]).optional().describe(
+        'Halt at the first executable line. true=always, false=never (default), "auto"=stop only if no breakpoint is set in `program`. Useful for short scripts that finish before you can react.',
+    ),
+    oscilloscopePath: z.string().optional().describe(
+        'Override Oscilloscope.exe path. Empty/omitted = helper resolves via registry + default install locations.',
+    ),
+    helperPath: z.string().optional().describe(
+        'Override iScopeBridge.exe path. Empty/omitted = bundled helper.',
+    ),
+    outFiles: z.array(z.string()).optional().describe(
+        'Glob array of additional .ajs bundles to preload source maps for. `${workspaceFolder}` is substituted. Needed when breakpoints sit in .ts files whose generated .ajs the adapter hasn\'t opened on its own.',
+    ),
+    timeoutMs: z.number().int().positive().optional().describe(
+        'Override per-DAP-request timeout for the initial spawn + launch round-trip. Defaults to 30 000 ms.',
+    ),
+};
+
+const transitionShape = z.object({
+    state: z.enum(['paused', 'running', 'terminated', 'timeout']),
+    stopped: z.unknown().optional(),
+    exitInfo: z.unknown().optional(),
+    waitedMs: z.number().optional(),
+});
+
+export const registerLifecycleTools: ToolGroupRegistrar = (server, { dap }) => {
+    server.registerTool(
+        'debug_launch',
+        {
+            title: 'Launch debug session',
+            description:
+                'Spawn the iScope DAP adapter and start `program` under Oscilloscope.exe. Returns the immediate state: "paused" (stopOnEntry hit / startup halt), "running" (script is executing), or "timeout" (running but no event in 1.5 s — call debug_wait_for_paused next). State must be "idle" or "terminated"; call debug_disconnect first if a previous session is still active.',
+            inputSchema: launchInput,
+            outputSchema: { transition: transitionShape },
+            annotations: {
+                title: 'Launch debug session',
+                idempotentHint: false,
+                openWorldHint: true,    // spawns processes, touches FS
+                destructiveHint: false,
+            },
+        },
+        async (args) => {
+            try {
+                const t = await dap.launch(args);
+                return ok({ transition: shapeTransition(t) });
+            } catch (e) {
+                return fail(`debug_launch failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    server.registerTool(
+        'debug_disconnect',
+        {
+            title: 'Disconnect debug session',
+            description:
+                'Cleanly tear down the active debug session: DAP disconnectRequest → helper shutdown with closePolicy=ifWeLaunched → Oscilloscope graceful close (only if we launched it). Always call this before exiting your AI workflow — leaking a session orphans Oscilloscope when this server exits.',
+            inputSchema: {},
+            outputSchema: { state: z.string() },
+            annotations: {
+                title: 'Disconnect debug session',
+                idempotentHint: true,
+                destructiveHint: false,
+            },
+        },
+        async () => {
+            try {
+                await dap.disconnect();
+                return ok({ state: dap.getState() });
+            } catch (e) {
+                return fail(`debug_disconnect failed: ${errMsg(e)}`);
+            }
+        },
+    );
+
+    server.registerTool(
+        'debug_current_state',
+        {
+            title: 'Inspect current debug state',
+            description:
+                'Lock-free snapshot of where the session is right now. Returns state (idle/launching/running/paused/terminated). For state="paused" also returns the StoppedInfo (reason, optional exception description, frames[]). Cheap; safe to call any time without waiting on anything.',
+            inputSchema: {},
+            outputSchema: {
+                state: z.enum(['idle', 'launching', 'running', 'paused', 'terminated']),
+                stopped: z.unknown().optional(),
+                terminationInfo: z.unknown().optional(),
+            },
+            annotations: {
+                title: 'Inspect current debug state',
+                readOnlyHint: true,
+                idempotentHint: true,
+            },
+        },
+        async () => {
+            const state = dap.getState();
+            const stopped = dap.getStoppedSnapshot();
+            const term = dap.getTerminationInfo();
+            const payload: Record<string, unknown> = { state };
+            if (stopped) payload['stopped'] = shapeStopped(stopped);
+            if (term)    payload['terminationInfo'] = pruneUndefined({ reason: term.reason });
+            return ok(payload);
+        },
+    );
+};
+
+function errMsg(e: unknown): string {
+    if (e instanceof Error) return e.message;
+    if (typeof e === 'string') return e;
+    try { return JSON.stringify(e); } catch { return String(e); }
+}

package/src/tools/preflight.ts

@@ -0,0 +1,95 @@
+// system_preflight_check — proactive environment diagnostic for the
+// iScope debug stack.
+//
+// The tool wraps the `preflight/check` JSON-RPC method of
+// `iScopeBridge.exe` (helper-cpp). It performs a registry-only probe
+// of:
+//   1. The Windows Script Debugger (Machine Debug Manager, pdm.dll)
+//      that Oscilloscope's JScript debug engine builds upon. 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.
+//   2. The Oscilloscope ScopeAppDbgCtrl CLSID — a side-check that
+//      lets an AI agent distinguish "Script Debugger missing" from
+//      "Oscilloscope not installed" failure modes.
+//
+// When an AI should call this tool:
+//   - Proactively on the first `debug_launch` failure that the user
+//     describes as "BP ignored" / "Oscilloscope says 'Unable to
+//     create debuger object'" / "F5 starts then nothing happens".
+//   - Whenever a launch fails with a generic "engine returned but
+//     emitted no sink events" symptom in the Debug Console.
+//
+// The tool does NOT require an active debug session, does NOT require
+// Oscilloscope to be running, and is idempotent / read-only.
+
+import { z } from 'zod';
+
+import { fail, ok } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const scriptDebuggerShape = z.object({
+    registered:       z.boolean(),
+    registryClsid:    z.string(),
+    registryName:     z.string(),
+    inprocServerPath: z.string(),
+    fileExists:       z.boolean().nullable(),
+});
+
+const oscilloscopeShape = z.object({
+    comRegistered: z.boolean(),
+    registryClsid: z.string(),
+    registryName:  z.string(),
+});
+
+export const registerPreflightTools: ToolGroupRegistrar = (server, { bridge }) => {
+
+    server.registerTool(
+        'system_preflight_check',
+        {
+            title: 'Check iScope debug prerequisites',
+            description:
+                'Probe the local machine for the iScope debug stack prerequisites: the Windows Script ' +
+                'Debugger (Machine Debug Manager, pdm.dll — required by Oscilloscope to expose JScript ' +
+                'debugging) and the Oscilloscope ScopeAppDbgCtrl COM registration. Call this proactively ' +
+                'when the user reports "breakpoints are ignored", "F5 just sits there", or whenever ' +
+                'debug_launch / debug_continue silently fails — the most common root cause is a missing ' +
+                'Machine Debug Manager, which the user can fix by installing Build Tools / Remote Tools ' +
+                'for Visual Studio. Registry-only; safe to call at any time, never auto-launches anything.',
+            inputSchema: {},
+            outputSchema: {
+                ok:               z.boolean(),
+                verdict:          z.enum([
+                    'ok',
+                    'script-debugger-not-registered',
+                    'script-debugger-file-missing',
+                    'unknown',
+                ]),
+                scriptDebugger:   scriptDebuggerShape,
+                oscilloscope:     oscilloscopeShape,
+                userHints:        z.array(z.string()),
+                deprecatedAdvice: z.array(z.string()),
+                downloadUrl:      z.string().optional(),
+            },
+            annotations: {
+                title:          'Check iScope debug prerequisites',
+                readOnlyHint:   true,
+                idempotentHint: true,
+            },
+        },
+        async () => {
+            try {
+                const result = await bridge.preflightCheck();
+                return ok(result as unknown as Record<string, unknown>);
+            } catch (e) {
+                return fail(`system_preflight_check failed: ${errMsg(e)}`);
+            }
+        },
+    );
+};
+
+function errMsg(e: unknown): string {
+    if (e instanceof Error) return e.message;
+    if (typeof e === 'string') return e;
+    try { return JSON.stringify(e); } catch { return String(e); }
+}

package/src/tools/registry.ts

@@ -0,0 +1,34 @@
+// Tool registry pattern.
+//
+// Why this exists:
+//   `index.ts` should be a thin shell — `new McpServer` + transport
+//   + a sequence of `registerXxxTools()` calls. Each tool group
+//   (lifecycle, breakpoints, execution, sync, inspection, snapshot,
+//   source-maps) owns its own file and exports a single `register`
+//   function that registers every tool in the group against the
+//   given server instance.
+//
+//   This pattern serves two future goals:
+//     - Phase 2/3 will add control_* and data_* groups; the
+//       registration code in index.ts grows by one line per group.
+//     - Composing only a subset of groups for tests (e.g. inspection
+//       tools alone) becomes trivial — instantiate the driver and
+//       call only the groups you want.
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import type { BridgeDriver } from '../bridge-driver.js';
+import type { DapDriver } from '../dap-driver.js';
+
+/** Drivers passed to every tool-group registrar. Phase 1 tools touch
+ *  only `dap`; Phase 2/3 tools will use `bridge` as well. */
+export interface ToolDrivers {
+    dap: DapDriver;
+    bridge: BridgeDriver;
+}
+
+/** Uniform shape every tool-group file must export.
+ *
+ *  Registrars MUST NOT call `server.connect()` themselves — that is
+ *  the responsibility of `index.ts` after every group has registered. */
+export type ToolGroupRegistrar = (server: McpServer, drivers: ToolDrivers) => void;

package/src/tools/snapshot.ts

@@ -0,0 +1,132 @@
+// debug_snapshot — composite "give me everything" tool.
+//
+// Why a composite tool when the AI could call stack_trace / scopes /
+// variables individually:
+//   - One round-trip = lower latency on stdio MCP transport.
+//   - Atomic: the whole snapshot is taken under a SINGLE mutex
+//     acquisition, so no risk of step happening between the
+//     stack_trace and the variables fetch and yielding mismatched
+//     frame ids.
+//   - Mirrors the existing `scripts/inspect.cjs` headless tool, just
+//     surfaced over MCP — easy mental model.
+
+import { z } from 'zod';
+
+import { fail, ok, pruneUndefined, shapeFrame } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+import type { DapDriver } from '../dap-driver.js';
+
+const variableShape = z.object({
+    name:               z.string(),
+    type:               z.string().optional(),
+    value:              z.string(),
+    variablesReference: z.number(),
+});
+
+const scopeShape = z.object({
+    name:               z.string(),
+    variablesReference: z.number(),
+    expensive:          z.boolean().optional(),
+    variables:          z.array(variableShape).optional(),
+});
+
+const frameSnapshotShape = z.object({
+    frame:  z.unknown(),
+    scopes: z.array(scopeShape),
+});
+
+export const registerSnapshotTools: ToolGroupRegistrar = (server, { dap }) => {
+    server.registerTool(
+        'debug_snapshot',
+        {
+            title: 'Snapshot full debug state',
+            description:
+                'Collect stack trace + scopes + (optionally) one level of variables for every frame in one call. Equivalent to calling debug_stack_trace, then debug_scopes for every frame, then debug_variables for every scope — but atomically under one mutex acquisition. Use this when you want a "where am I and what do the locals look like?" answer in a single round-trip. State must be "paused".',
+            inputSchema: {
+                expandScopes: z.boolean().optional().describe(
+                    'Default true. When true, expand each scope\'s top-level variables; nested compounds are NOT recursed (you still need debug_variables for drill-down). When false, only scope handles are returned.',
+                ),
+                frameLimit: z.number().int().positive().optional().describe(
+                    'Cap the number of frames returned. Defaults to 20. Innermost frames are kept; outer frames trimmed.',
+                ),
+            },
+            outputSchema: {
+                state:  z.literal('paused'),
+                reason: z.string(),
+                description: z.string().optional(),
+                frames: z.array(frameSnapshotShape),
+            },
+            annotations: {
+                title: 'Snapshot full debug state',
+                readOnlyHint: true,
+                idempotentHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const expand = args.expandScopes !== false;
+                const limit  = args.frameLimit ?? 20;
+                const result = await snapshot(dap, expand, limit);
+                return ok(result);
+            } catch (e) {
+                return fail(`debug_snapshot failed: ${errMsg(e)}`);
+            }
+        },
+    );
+};
+
+async function snapshot(
+    dap: DapDriver,
+    expandScopes: boolean,
+    frameLimit: number,
+): Promise<Record<string, unknown>> {
+    if (dap.getState() !== 'paused') {
+        throw new Error(`debug_snapshot requires 'paused' state, got '${dap.getState()}'`);
+    }
+
+    const stackBody = await dap.stackTrace();
+    const allFrames = stackBody?.stackFrames ?? [];
+    const slice = allFrames.slice(0, frameLimit);
+    const frames: Record<string, unknown>[] = [];
+
+    for (const f of slice) {
+        const classified = await dap.classifyFrame(f);
+        const scopesBody = await dap.scopes(f.id);
+        const scopesRaw  = scopesBody?.scopes ?? [];
+
+        const scopes: Record<string, unknown>[] = [];
+        for (const s of scopesRaw) {
+            const scope: Record<string, unknown> = pruneUndefined({
+                name:               s.name,
+                variablesReference: s.variablesReference,
+                expensive:          s.expensive,
+            });
+            if (expandScopes && s.variablesReference > 0) {
+                const vbody = await dap.variables(s.variablesReference);
+                scope['variables'] = (vbody?.variables ?? []).map((v) => ({
+                    name:               v.name,
+                    type:               v.type,
+                    value:              v.value,
+                    variablesReference: v.variablesReference ?? 0,
+                }));
+            }
+            scopes.push(scope);
+        }
+
+        frames.push({ frame: shapeFrame(classified), scopes });
+    }
+
+    const stopped = dap.getStoppedSnapshot();
+    return pruneUndefined({
+        state:       'paused' as const,
+        reason:      stopped?.reason ?? 'unknown',
+        description: stopped?.description,
+        frames,
+    });
+}
+
+function errMsg(e: unknown): string {
+    if (e instanceof Error) return e.message;
+    if (typeof e === 'string') return e;
+    try { return JSON.stringify(e); } catch { return String(e); }
+}