@i-scope/mcp-server 0.4.2

package/src/index.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// @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.
+
+import * as os from 'node:os';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { BridgeDriver } from './bridge-driver.js';
+import { DapDriver } from './dap-driver.js';
+import { registerBreakpointTools } from './tools/breakpoints.js';
+import { registerExecutionTools } from './tools/execution.js';
+import { SERVER_INFO, SERVER_INSTRUCTIONS } from './tools/helpers.js';
+import { registerInspectionTools } from './tools/inspection.js';
+import { registerLifecycleTools } from './tools/lifecycle.js';
+import { registerAbiCheckTools } from './tools/abi-check.js';
+import { registerPreflightTools } from './tools/preflight.js';
+import type { ToolDrivers } from './tools/registry.js';
+import { registerSnapshotTools } from './tools/snapshot.js';
+import { registerSourceMapTools } from './tools/source-maps.js';
+import { registerSyncTools } from './tools/sync.js';
+import { registerUIModalTools } from './tools/ui-modal.js';
+
+function silenceStdout(): void {
+    // 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: unknown[]) => console.error('[stdout-redirect]', ...args)) as typeof console.log;
+    console.info  = ((...args: unknown[]) => console.error('[stdout-redirect]', ...args)) as typeof console.info;
+    /* eslint-enable no-console */
+}
+
+async function main(): Promise<void> {
+    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${SERVER_INFO.version}] starting on ${os.platform()} ${os.arch()}` +
+        (extensionPath ? `; ISCOPE_EXTENSION_PATH=${extensionPath}` : '') +
+        `\n`,
+    );
+
+    const dap = new DapDriver({
+        extensionPath,
+        log: (line) => process.stderr.write(line + '\n'),
+    });
+    const bridge = new BridgeDriver({
+        bundledRoot: extensionPath,
+        log: (line) => process.stderr.write(line + '\n'),
+    });
+    const drivers: ToolDrivers = { dap, bridge };
+
+    const server = new McpServer(SERVER_INFO, {
+        instructions: SERVER_INSTRUCTIONS,
+        capabilities: {
+            tools: { listChanged: false },
+            logging: {},
+        },
+    });
+
+    registerLifecycleTools(server, drivers);
+    registerBreakpointTools(server, drivers);
+    registerExecutionTools(server, drivers);
+    registerSyncTools(server, drivers);
+    registerInspectionTools(server, drivers);
+    registerSnapshotTools(server, drivers);
+    registerSourceMapTools(server, drivers);
+    registerUIModalTools(server, drivers);
+    registerPreflightTools(server, drivers);
+    registerAbiCheckTools(server, drivers);
+
+    const transport = new 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: string): void => {
+        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 = (): void => {
+        // 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);
+});

package/src/state.ts

@@ -0,0 +1,115 @@
+// 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.
+
+/** High-level lifecycle of a single MCP debug session. */
+export type SessionState =
+    | 'idle'        // No DAP child spawned. Initial / post-disconnect.
+    | 'launching'   // DAP child spawned, launchRequest in flight.
+    | 'running'     // Script is running, no break / pause.
+    | 'paused'      // Engine stopped on a breakpoint / step / error.
+    | 'terminated'; // Script finished or crashed; child still around
+                    // until disconnect tool cleans up.
+
+/** 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;       // forwards-compat catch-all
+
+/** 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'              // .ts surfaced through source map
+    | 'generated'           // raw .ajs (user launched against .ajs)
+    | 'unmapped-fallback';  // .ts launch but no mapping for this line
+
+/** 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;
+}

package/src/tools/abi-check.ts

@@ -0,0 +1,66 @@
+// system_abi_check — wire ABI probe via `protocol/version` (no COM).
+
+import { z } from 'zod';
+
+import { fail, ok } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const policySchema = z.enum(['strict', 'warn', 'ignore']).optional();
+
+const warningShape = z.object({
+    clientAbi: z.string(),
+    serverAbi: z.string(),
+    reason:    z.string(),
+});
+
+export const registerAbiCheckTools: ToolGroupRegistrar = (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:           z.boolean(),
+                clientAbi:    z.string(),
+                serverAbi:    z.string(),
+                server:       z.string(),
+                buildTime:    z.string().optional(),
+                compatKind:   z.enum(['ok', 'warn', 'fatal']),
+                compatReason: z.string(),
+                policy:       policySchema,
+                warnings:     z.array(warningShape),
+                userHints:    z.array(z.string()),
+            },
+            annotations: {
+                title:          'Check iScopeBridge wire ABI',
+                readOnlyHint:   true,
+                idempotentHint: true,
+            },
+        },
+        async (args) => {
+            try {
+                const result = await bridge.abiCheck(args.policy);
+                return ok(result as unknown as Record<string, unknown>);
+            } catch (e) {
+                return fail(`system_abi_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/breakpoints.ts

@@ -0,0 +1,59 @@
+// debug_set_breakpoints.
+
+import { z } from 'zod';
+import type { DebugProtocol } from '@vscode/debugprotocol';
+
+import { fail, ok } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+
+const setBreakpointsInput = {
+    source: 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: z.array(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`.',
+    ),
+};
+
+export const registerBreakpointTools: ToolGroupRegistrar = (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: z.array(z.object({
+                    line:     z.number().optional(),
+                    verified: z.boolean(),
+                    message:  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: DebugProtocol.Breakpoint) => ({
+                    line:     bp.line,
+                    verified: bp.verified === true,
+                    message:  bp.message,
+                }));
+                return ok({ breakpoints: bps });
+            } catch (e) {
+                return fail(`debug_set_breakpoints 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/execution.ts

@@ -0,0 +1,105 @@
+// 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.
+
+import { z } from 'zod';
+
+import { fail, ok, shapeTransition } from './helpers.js';
+import type { ToolGroupRegistrar } from './registry.js';
+import type { DapDriver } from '../dap-driver.js';
+import type { DapClient } from '../dap-client.js';
+
+const stepInput = {
+    timeoutMs: 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 = z.object({
+    state: z.enum(['paused', 'terminated', 'timeout']),
+    stopped:  z.unknown().optional(),
+    exitInfo: z.unknown().optional(),
+    waitedMs: z.number().optional(),
+});
+
+function makeResume(
+    dap: DapDriver,
+    label: string,
+    dapCall: (dc: DapClient) => Promise<unknown>,
+) {
+    return async (args: { timeoutMs?: number }) => {
+        try {
+            const t = await dap.resumeAndWait(dapCall, args.timeoutMs);
+            return ok({ transition: shapeTransition(t) });
+        } catch (e) {
+            return fail(`${label} failed: ${errMsg(e)}`);
+        }
+    };
+}
+
+export const registerExecutionTools: ToolGroupRegistrar = (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 })),
+    );
+};
+
+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/helpers.ts

@@ -0,0 +1,142 @@
+// 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.
+
+import type {
+    CallToolResult,
+    Implementation,
+    TextContent,
+} 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 function ok<T extends Record<string, unknown>>(payload: T): CallToolResult {
+    const text: TextContent = {
+        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. */
+export function fail(message: string, details?: Record<string, unknown>): CallToolResult {
+    const text: TextContent = {
+        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). */
+export function pruneUndefined<T extends Record<string, unknown>>(o: T): T {
+    for (const k of Object.keys(o)) {
+        if (o[k] === undefined) delete o[k];
+    }
+    return o;
+}
+
+export function shapeFrame(f: FrameInfo): Record<string, unknown> {
+    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,
+    });
+}
+
+export function shapeStopped(s: StoppedInfo): Record<string, unknown> {
+    return pruneUndefined({
+        reason:      s.reason,
+        description: s.description,
+        frames:      s.frames.map(shapeFrame),
+    });
+}
+
+export function shapeTransition(t: ExecutionTransition): Record<string, unknown> {
+    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 };
+}
+
+export function shapeOutputEntry(e: OutputEntry): Record<string, unknown> {
+    return {
+        id:        e.id,
+        category:  e.category,
+        text:      e.text,
+        timestamp: e.timestamp,
+    };
+}
+
+/** Centralised server identity. Bumped together with package.json. */
+export const SERVER_INFO: Implementation = {
+    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. */
+export const 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');