cbm-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Manfred Hantschel
+
+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

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# CBM MCP: VICE Monitor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Build](https://github.com/thred/cbm-mcp/actions/workflows/build.yml/badge.svg)](https://github.com/thred/cbm-mcp/actions/workflows/build.yml)
+[![License: MIT](https://img.shields.io/github/license/thred/cbm-mcp)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](package.json)
+
+An MCP server that lets AI agents debug Commodore software in a locally running
+[VICE](https://vice-emu.sourceforge.io/) emulator, through VICE's text remote
+monitor.
+
+It runs **locally over stdio**, next to VICE. Nothing is hosted, and the
+unauthenticated VICE monitor should never be exposed beyond loopback.
+
+## What You Can Do
+
+The server covers the command families of the
+[VICE monitor](https://vice-emu.sourceforge.io/vice_12.html), so an agent can:
+
+- **Inspect** CPU registers, memory (as hex, PETSCII or screen codes), the text
+  screen, call stacks, memory banks and I/O state.
+- **Disassemble and assemble** code, and annotate it with labels and comments.
+- **Control execution** by stepping, running until a condition, setting
+  breakpoints, watchpoints and tracepoints, and resuming or resetting the machine.
+- **Modify state** by writing registers and memory, filling, moving, comparing
+  and searching memory, and typing on the emulated keyboard.
+- **Work with media and files** such as disk images, programs, snapshots and
+  binary data, as well as VICE settings and resources.
+- **Profile and trace** with CPU history and profiling data, where the VICE
+  build supports it.
+- **Export graphics** such as sprites and character sets as images, and capture
+  screenshots.
+
+The available commands depend on the VICE version, the emulated machine, and
+build options. The server also sends debugging guidance to the agent, covering
+safe inspection, memory banking, side effects and cleanup. A
+[command catalog](docs/commands.md) documents the details.
+
+## Quick Start
+
+You need Node.js 24+ and a VICE emulator with its text remote monitor enabled.
+
+1. Start VICE with the text monitor (the executable name depends on your
+   installation and machine; do not use the binary monitor):
+
+    ```sh
+    x64sc -remotemonitor -remotemonitoraddress ip4://127.0.0.1:6510
+    ```
+
+2. Add the server to your MCP client's configuration:
+
+    ```json
+    {
+        "servers": {
+            "cbm-mcp": {
+                "type": "stdio",
+                "command": "npx",
+                "args": ["--yes", "cbm-mcp@latest"]
+            }
+        }
+    }
+    ```
+
+3. Ask your agent, for example: "Connect to VICE and show the CPU registers."
+
+Harnesses differ in where they keep this configuration, and some use
+`mcpServers` instead of `servers`. Pin a version instead of `latest` for
+repeatable setups.
+
+### Configuration
+
+Optional environment variables, set in the client's `env` object:
+
+| Variable          | Default     | Meaning                                           |
+| ----------------- | ----------- | ------------------------------------------------- |
+| `VICE_HOST`       | `127.0.0.1` | Monitor hostname or IP address, without `ip4://`  |
+| `VICE_PORT`       | `6510`      | Text monitor TCP port                             |
+| `VICE_TIMEOUT_MS` | `5000`      | Timeout per handshake or command, in milliseconds |
+
+Invalid settings fail startup with a diagnostic on stderr. Starting the MCP does
+not connect to or pause VICE.
+
+## Agent Skill via APM
+
+This repository is also an [APM](https://github.com/microsoft/apm) package. It
+ships the `cbm-mcp` agent skill with C64, VIC-II and 6510 reference material,
+which complements the general guidance the server already provides. Install it
+into a project with:
+
+```sh
+apm install thred/cbm-mcp
+```
+
+APM deploys the skill for your configured agent targets. The MCP server entry in
+[apm.yml](apm.yml) launches a local build (`dist/stdio.js`), so it only works
+inside a source checkout; configure the server for other projects as described
+in Quick Start.
+
+## Safety
+
+- Connecting to the monitor **pauses emulation**, and it stays paused until the
+  agent resumes it deliberately.
+- Disconnecting never quits VICE. Only one monitor client can be attached at a
+  time, so use one controller at a time.
+- Reading I/O can have side effects, which VICE's monitor can be told to
+  suppress. Stepping and writes change machine state and are not undone
+  automatically. A timeout cannot guarantee that a command did not execute, so
+  state-changing operations should not be retried blindly.
+- Some capabilities reset or quit the emulator, write to disks, access host files
+  or run monitor scripts. Host paths are interpreted by VICE without a sandbox.
+  Use your MCP client's approval controls; tool annotations and confirmation
+  fields are not a security boundary, and only trusted clients and files should be
+  used.
+
+## Development
+
+Install from source and run the checks:
+
+```sh
+npm install
+npm run build
+npm test
+npm run test:typecheck
+```
+
+To use a checkout instead of the npm package, configure the client with
+`"command": "node"` and `"args": ["/absolute/path/to/cbm-mcp/dist/cli.js"]`.
+Launch the executable directly rather than through `npm start`, whose banners
+would corrupt the MCP stream on stdout. `npm run dev` starts the TypeScript
+sources for manual runs. Restart the server in the client after rebuilding.
+
+The default tests use an in-process fixture instead of VICE. With VICE's text
+monitor running, `npm run test:live` additionally runs read-only checks against
+the real emulator. **It pauses the emulator and leaves it paused.** The live test
+is skipped by default.
+
+If a new connection times out even though the port is listening, disconnect other
+monitor clients. VICE can also retain a stale session while paused: leave the
+monitor or resume once in VICE's UI, then reconnect.
+
+The source layout is small: the monitor connection (`src/vice/monitor-client.ts`)
+is independent of MCP, the tools live in `src/vice/monitor-tools.ts`, the server
+factory is in `src/server.ts`, and `src/cli.ts` and `src/stdio.ts` provide the
+stdio executable. Other MCP transports can reuse the server factory; a
+network-facing transport needs proper authentication.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./stdio.js";
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,YAAY,CAAC"}

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./stdio.js";
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,YAAY,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { McpUtils, type McpTool, type ToolArguments } from "./mcp-utils.js";
+export { createViceMonitorServer, createViceServer } from "./server.js";
+export { MonitorClient, type MonitorOptions } from "./vice/monitor-client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { McpUtils } from "./mcp-utils.js";
+export { createViceMonitorServer, createViceServer } from "./server.js";
+export { MonitorClient } from "./vice/monitor-client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAoC,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,aAAa,EAAuB,MAAM,0BAA0B,CAAC"}

package/dist/mcp-utils.d.ts

@@ -0,0 +1,59 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+export type ToolArguments = Record<string, unknown>;
+export interface McpTool extends Tool {
+    run: (args: ToolArguments) => Promise<string>;
+}
+export type McpToolMetadata = Pick<Tool, "name" | "description" | "inputSchema" | "annotations">;
+export type FormattedArguments = Record<string, string>;
+export interface ToolField {
+    schema: Record<string, unknown>;
+    optional?: boolean;
+    format: (value: unknown) => string;
+}
+/** Shared MCP server and argument helpers for the project's separate servers. */
+export declare class McpUtils {
+    /** Mark a behavior method as an MCP tool using explicit runtime metadata. */
+    static tool(metadata: McpToolMetadata): MethodDecorator;
+    /** Validate an integer argument against an inclusive range. */
+    static integer(args: ToolArguments, name: string, min: number, max: number, fallback?: number): number;
+    /** Format a number as a VICE-style hexadecimal value. */
+    static hex(value: number, width?: number): string;
+    /** Validate a string argument against a fixed set of choices. */
+    static choice(args: ToolArguments, name: string, values: readonly string[], fallback?: string): string;
+    /** Build MCP tool metadata and an input schema from reusable field definitions. */
+    static toolMetadata(name: string, description: string, fields: Record<string, ToolField>, annotations?: Tool["annotations"]): McpToolMetadata;
+    /** Define an inclusive integer field and format its values for commands. */
+    static numberField(min?: number, max?: number, decimal?: boolean): ToolField;
+    /** Define a fixed-choice field, optionally formatting numeric choices as hexadecimal. */
+    static enumerationField(values: readonly (string | number | boolean)[], hexadecimal?: boolean): ToolField;
+    /** Define a bounded string field constrained by a regular expression. */
+    static textField(pattern: RegExp, description: string, maxLength?: number): ToolField;
+    /** Define a command-safe quoted string field. */
+    static quotedField(description: string, allowEmpty?: boolean): ToolField;
+    /** Define a string field for literal text that cannot contain control characters or backslashes. */
+    static keyboardTextField(description: string, maxLength?: number): ToolField;
+    /** Make a field optional and supply its command-token fallback when omitted. */
+    static optionalField(field: ToolField, fallback?: string): ToolField;
+    /** Define a bounded array field and format its entries as space-separated tokens. */
+    static arrayField(field: ToolField, maxItems?: number, unique?: boolean): ToolField;
+    /** Validate and format all provided values, rejecting unknown or null fields. */
+    static formatArguments(args: ToolArguments, fields: Record<string, ToolField>): FormattedArguments;
+    /** Join nonempty formatted arguments into a command token string. */
+    static joinArguments(...values: string[]): string;
+    private static containsLineBreakOrNull;
+    private static containsControlCharacter;
+    /** Create a protocol server from either a decorated catalog or an existing tool array. */
+    static createToolServer(name: string, catalog: object, options?: {
+        version?: string;
+        instructions?: string;
+        isError?: (text: string) => boolean;
+    }): Server;
+    static createToolServer(name: string, tools: McpTool[], options?: {
+        version?: string;
+        instructions?: string;
+        isError?: (text: string) => boolean;
+    }): Server;
+    private static decoratedTools;
+}
+//# sourceMappingURL=mcp-utils.d.ts.map

package/dist/mcp-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.d.ts","sourceRoot":"","sources":["../src/mcp-utils.ts"],"names":[],"mappings":"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"}

package/dist/mcp-utils.js

@@ -0,0 +1,259 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+const decoratedMethods = new WeakMap();
+/** Shared MCP server and argument helpers for the project's separate servers. */
+export class McpUtils {
+    /** Mark a behavior method as an MCP tool using explicit runtime metadata. */
+    static tool(metadata) {
+        return (target, propertyKey) => {
+            let methods = decoratedMethods.get(target);
+            if (!methods) {
+                methods = new Map();
+                decoratedMethods.set(target, methods);
+            }
+            methods.set(propertyKey, metadata);
+        };
+    }
+    /** Validate an integer argument against an inclusive range. */
+    static integer(args, name, min, max, fallback) {
+        const value = args[name] ?? fallback;
+        if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+            throw new Error(`${name} must be an integer from ${min} to ${max}.`);
+        }
+        return value;
+    }
+    /** Format a number as a VICE-style hexadecimal value. */
+    static hex(value, width = 4) {
+        return `$${value.toString(16).padStart(width, "0")}`;
+    }
+    /** Validate a string argument against a fixed set of choices. */
+    static choice(args, name, values, fallback) {
+        const value = args[name] ?? fallback;
+        if (typeof value !== "string" || !values.includes(value)) {
+            throw new Error(`${name} must be one of: ${values.join(", ")}.`);
+        }
+        return value;
+    }
+    /** Build MCP tool metadata and an input schema from reusable field definitions. */
+    static toolMetadata(name, description, fields, annotations) {
+        return {
+            name,
+            description,
+            inputSchema: {
+                type: "object",
+                properties: Object.fromEntries(Object.entries(fields).map(([key, field]) => [key, field.schema])),
+                required: Object.entries(fields)
+                    .filter(([, field]) => !field.optional)
+                    .map(([key]) => key),
+                additionalProperties: false,
+            },
+            ...(annotations === undefined ? {} : { annotations }),
+        };
+    }
+    /** Define an inclusive integer field and format its values for commands. */
+    static numberField(min = 0, max = 65535, decimal = false) {
+        return {
+            schema: { type: "integer", minimum: min, maximum: max },
+            format: (value) => {
+                if (typeof value !== "number" || !Number.isInteger(value) || value < min || value > max) {
+                    throw new Error(`Expected an integer from ${min} to ${max}.`);
+                }
+                return decimal ? String(value) : `$${value.toString(16)}`;
+            },
+        };
+    }
+    /** Define a fixed-choice field, optionally formatting numeric choices as hexadecimal. */
+    static enumerationField(values, hexadecimal = false) {
+        return {
+            schema: { type: typeof values[0] === "number" ? "integer" : typeof values[0], enum: values },
+            format: (value) => {
+                if (!values.includes(value)) {
+                    throw new Error(`Expected one of: ${values.join(", ")}.`);
+                }
+                return hexadecimal && typeof value === "number" ? `$${value.toString(16)}` : String(value);
+            },
+        };
+    }
+    /** Define a bounded string field constrained by a regular expression. */
+    static textField(pattern, description, maxLength = 4096) {
+        return {
+            schema: { type: "string", minLength: 1, maxLength, pattern: pattern.source, description },
+            format: (value) => {
+                if (typeof value !== "string" ||
+                    !value.trim() ||
+                    value.length > maxLength ||
+                    McpUtils.containsLineBreakOrNull(value) ||
+                    !pattern.test(value)) {
+                    throw new Error(`Expected ${description} (maximum ${maxLength} characters).`);
+                }
+                return value;
+            },
+        };
+    }
+    /** Define a command-safe quoted string field. */
+    static quotedField(description, allowEmpty = false) {
+        return {
+            schema: { type: "string", minLength: allowEmpty ? 0 : 1, maxLength: 4096, description },
+            format: (value) => {
+                if (typeof value !== "string" ||
+                    (!allowEmpty && !value.trim()) ||
+                    value.length > 4096 ||
+                    value.includes('"') ||
+                    value.includes("\\") ||
+                    McpUtils.containsControlCharacter(value)) {
+                    throw new Error(`Expected ${description}, without double quotes, backslashes, or control characters.`);
+                }
+                return `"${value}"`;
+            },
+        };
+    }
+    /** Define a string field for literal text that cannot contain control characters or backslashes. */
+    static keyboardTextField(description, maxLength = 4096) {
+        return {
+            schema: { type: "string", minLength: 1, maxLength, description },
+            format: (value) => {
+                if (typeof value !== "string" ||
+                    !value.trim() ||
+                    value.length > maxLength ||
+                    value.includes("\\") ||
+                    McpUtils.containsControlCharacter(value)) {
+                    throw new Error(`Expected ${description}, without backslashes or control characters.`);
+                }
+                return value;
+            },
+        };
+    }
+    /** Make a field optional and supply its command-token fallback when omitted. */
+    static optionalField(field, fallback = "") {
+        return { ...field, optional: true, format: (value) => (value === undefined ? fallback : field.format(value)) };
+    }
+    /** Define a bounded array field and format its entries as space-separated tokens. */
+    static arrayField(field, maxItems = 256, unique = false) {
+        return {
+            schema: { type: "array", items: field.schema, minItems: 1, maxItems, uniqueItems: unique },
+            format: (value) => {
+                if (!Array.isArray(value) ||
+                    value.length < 1 ||
+                    value.length > maxItems ||
+                    (unique && new Set(value).size !== value.length)) {
+                    throw new Error(`Expected 1-${maxItems} ${unique ? "unique " : ""}items.`);
+                }
+                return value.map((entry) => field.format(entry)).join(" ");
+            },
+        };
+    }
+    /** Validate and format all provided values, rejecting unknown or null fields. */
+    static formatArguments(args, fields) {
+        for (const key of Object.keys(args)) {
+            if (!Object.hasOwn(fields, key)) {
+                throw new Error(`Unknown argument: ${key}`);
+            }
+        }
+        return Object.fromEntries(Object.entries(fields).map(([key, field]) => {
+            if (args[key] === null) {
+                throw new Error(`${key} must not be null.`);
+            }
+            try {
+                return [key, field.format(args[key])];
+            }
+            catch (error) {
+                throw new Error(`${key}: ${error instanceof Error ? error.message : String(error)}`, {
+                    cause: error,
+                });
+            }
+        }));
+    }
+    /** Join nonempty formatted arguments into a command token string. */
+    static joinArguments(...values) {
+        return values.filter(Boolean).join(" ");
+    }
+    static containsLineBreakOrNull(value) {
+        for (const character of value) {
+            const code = character.charCodeAt(0);
+            if (code === 0x0a || code === 0x0d || code === 0x00) {
+                return true;
+            }
+        }
+        return false;
+    }
+    static containsControlCharacter(value) {
+        for (const character of value) {
+            const code = character.charCodeAt(0);
+            if (code < 0x20 || code === 0x7f) {
+                return true;
+            }
+        }
+        return false;
+    }
+    static createToolServer(name, catalogOrTools, options = {}) {
+        const tools = Array.isArray(catalogOrTools) ? catalogOrTools : this.decoratedTools(catalogOrTools);
+        const names = new Set();
+        for (const tool of tools) {
+            if (names.has(tool.name)) {
+                throw new Error(`Duplicate MCP tool name: ${tool.name}`);
+            }
+            names.add(tool.name);
+        }
+        const server = new Server({ name, version: options.version ?? "1.0.0" }, { capabilities: { tools: {} }, instructions: options.instructions });
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: tools.map((tool) => {
+                const { run: unused, ...toolWithoutRun } = tool;
+                void unused;
+                return toolWithoutRun;
+            }),
+        }));
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            try {
+                const tool = tools.find((entry) => entry.name === request.params.name);
+                if (!tool) {
+                    throw new Error(`Unknown tool: ${request.params.name}`);
+                }
+                const args = request.params.arguments ?? {};
+                for (const argumentName of Object.keys(args)) {
+                    if (!Object.hasOwn(tool.inputSchema.properties ?? {}, argumentName)) {
+                        throw new Error(`Unknown argument: ${argumentName}`);
+                    }
+                    if (args[argumentName] === null) {
+                        throw new Error(`${argumentName} must not be null.`);
+                    }
+                }
+                const text = await tool.run(args);
+                if (options.isError?.(text)) {
+                    throw new Error(text);
+                }
+                return { content: [{ type: "text", text: text || "Command completed." }] };
+            }
+            catch (error) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+                };
+            }
+        });
+        return server;
+    }
+    static decoratedTools(catalog) {
+        const tools = [];
+        for (let prototype = Object.getPrototypeOf(catalog); prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)) {
+            for (const methodName of Object.getOwnPropertyNames(prototype)) {
+                const metadata = decoratedMethods.get(prototype)?.get(methodName);
+                const method = Object.getOwnPropertyDescriptor(prototype, methodName)?.value;
+                if (!metadata || typeof method !== "function") {
+                    continue;
+                }
+                tools.push({
+                    ...metadata,
+                    run: async (args) => {
+                        const result = await Reflect.apply(method, catalog, [args]);
+                        if (typeof result !== "string") {
+                            throw new Error(`Tool ${metadata.name} must return text.`);
+                        }
+                        return result;
+                    },
+                });
+            }
+        }
+        return tools;
+    }
+}
+//# sourceMappingURL=mcp-utils.js.map

package/dist/mcp-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-utils.js","sourceRoot":"","sources":["../src/mcp-utils.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,39 @@
+import { MonitorClient } from "./vice/monitor-client.js";
+/** Creates the text-monitor MCP server without choosing a transport. */
+export declare function createViceMonitorServer(monitor?: MonitorClient): import("@modelcontextprotocol/sdk/server").Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+/** @deprecated Use createViceMonitorServer for the text-monitor MCP. */
+export declare const createViceServer: typeof createViceMonitorServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAazD,wEAAwE;AACxE,wBAAgB,uBAAuB,CAAC,OAAO,gBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAKpE;AAED,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,gCAA0B,CAAC"}

package/dist/server.js

@@ -0,0 +1,22 @@
+import { McpUtils } from "./mcp-utils.js";
+import { MonitorClient } from "./vice/monitor-client.js";
+import { ViceMonitorTools } from "./vice/monitor-tools.js";
+const DEBUGGER_INSTRUCTIONS = `Debug VICE through its text monitor. Start with vice_status (socket state only), vice_registers, and small reads. Use the current PC for disassembly. Inspection pauses emulation; reuse connections. Confirm machine, device/CPU, bank, and video model before hardware assumptions; use vice_help for command details.
+
+JSON integers are decimal (53280 = $d020); prefix numbers in expressions. Length counts bytes; range ends are inclusive. vice_memory/disassemble target C:, while registers/stepping use the current device. Distinguish CPU-visible memory, RAM, and video memory; query vice_bank before choosing a view. Query vice_sidefx before I/O reads; preserve and restore its setting.
+
+Prefer testable hypotheses, bounded reads/steps, and temporary checkpoints over patches. Stepping changes state; step-over/run-until can stall. No asynchronous breakpoint notifications: inspection itself can stop execution. Remove only your own checkpoints/labels.
+
+Establish user intent before mutations, execution control, or file operations; preserve affected state. Never blindly retry a timed-out mutation. Command delivery is not success acknowledgment. An expected read returning only 'Command completed.' has no usable data; try one read-only reconnect, then ask about VICE's UI if unresponsive.
+
+vice_resume sends exit and disconnects; another inspection pauses again. Disconnect does not resume or quit. Keep emulation running when no active debugging need requires a pause; resume after inspection unless the user asked to leave it paused. Longer pauses are fine when justified. Report facts versus hypotheses, changes/cleanup, and final execution state.`;
+/** Creates the text-monitor MCP server without choosing a transport. */
+export function createViceMonitorServer(monitor = new MonitorClient()) {
+    return McpUtils.createToolServer("cbm-vice-text-monitor", new ViceMonitorTools(monitor), {
+        instructions: DEBUGGER_INSTRUCTIONS,
+        isError: (text) => /(?:^|\n)\s*(?:ERROR\b|Unknown command\b)/i.test(text),
+    });
+}
+/** @deprecated Use createViceMonitorServer for the text-monitor MCP. */
+export const createViceServer = createViceMonitorServer;
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,qBAAqB,GAAG;;;;;;;;yWAQ2U,CAAC;AAE1W,wEAAwE;AACxE,MAAM,UAAU,uBAAuB,CAAC,OAAO,GAAG,IAAI,aAAa,EAAE;IACjE,OAAO,QAAQ,CAAC,gBAAgB,CAAC,uBAAuB,EAAE,IAAI,gBAAgB,CAAC,OAAO,CAAC,EAAE;QACrF,YAAY,EAAE,qBAAqB;QACnC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,2CAA2C,CAAC,IAAI,CAAC,IAAI,CAAC;KAC5E,CAAC,CAAC;AACP,CAAC;AAED,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAG,uBAAuB,CAAC"}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stdio.d.ts.map

package/dist/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../src/stdio.ts"],"names":[],"mappings":""}