@henols/c64-re-tools 1.0.0 → 2.0.0-rc.10

package/src/mcp/main.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env tsx
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { ViceSessionClient } from "../host-client/vice-session.ts";
+import { elapsedMs, startTrace, trace } from "../trace.ts";
+import { VIDEO_STANDARDS, WireFailure, type VideoStandard } from "../protocol/messages.ts";
+import { createMcpServer, type SessionSource } from "./server.ts";
+import { debugTools } from "./tools/debug.ts";
+import { executionTools } from "./tools/execution.ts";
+import { inputTools } from "./tools/input.ts";
+import { machineTools } from "./tools/machine.ts";
+import { mediaTools } from "./tools/media.ts";
+import { memoryTools } from "./tools/memory.ts";
+import { videoTools } from "./tools/video.ts";
+import { PACKAGE } from "../package.ts";
+
+const HELP = `c64-re-tools-mcp
+
+Usage:
+  npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-mcp
+  c64-re-tools-mcp --help
+
+Runs the stateful C64 MCP server on stdio. Each c64-re-tools-mcp process owns
+one C64 emulator, started by the Host Runtime (c64-re-tools-host) when this
+server starts and stopped when it exits. c64-re-tools install declares it for
+the agent, through npx with the newest version of its channel.
+
+Environment:
+  C64RT_VIDEO  pal (default) or ntsc; fixed for the life of the process.
+  C64RT_HOST   host:port of the Host Runtime when it is not on 127.0.0.1:6464,
+               host.docker.internal:6464 or host.containers.internal:6464.`;
+
+function log(line: string): void {
+  process.stderr.write(`c64-re-tools-mcp: ${line}\n`);
+  trace().log(line);
+}
+
+function videoStandard(env: NodeJS.ProcessEnv): VideoStandard {
+  const value = env.C64RT_VIDEO ?? "pal";
+  if ((VIDEO_STANDARDS as readonly string[]).includes(value)) return value as VideoStandard;
+  throw new WireFailure("installation-incomplete", "C64RT_VIDEO must be pal or ntsc. Fix the MCP server configuration and restart it.");
+}
+
+/**
+ * One session at a time (1 MCP = 1 session = 1 VICE). It opens at start; if
+ * that fails (for example the host was not running yet), the next tool call
+ * tries again. When the host connection is lost, the next call opens a new
+ * session (D57). A lost session that the emulator answered first gives its
+ * machine-state-lost once, unless a pending call got it already. Close stops
+ * an open that is still waiting for the host at once.
+ */
+function sessionSource(): { get: SessionSource; close(): Promise<void> } {
+  let opening: Promise<ViceSessionClient> | undefined;
+  let lostNotice: WireFailure | undefined;
+  let closed = false;
+  const stop = new AbortController();
+  const open = () => {
+    const started = performance.now();
+    const current = (async () => ViceSessionClient.open({ videoStandard: videoStandard(process.env), signal: stop.signal }))();
+    opening = current;
+    void current.then(
+      (client) => {
+        trace().event("session.opened", { ms: elapsedMs(started) });
+        void client.closed.then(() => drop(current, client));
+      },
+      () => {},
+    );
+    current.catch((error: unknown) => {
+      log(`session not opened: ${error instanceof Error ? error.message : String(error)}`);
+      if (opening === current) opening = undefined;
+    });
+    return current;
+  };
+  /** Forgets a lost session, once; the next call opens a new one. */
+  const drop = (current: Promise<ViceSessionClient>, client: ViceSessionClient) => {
+    if (closed || opening !== current) return;
+    log("the connection to the host runtime was lost; the next call opens a new session");
+    opening = undefined;
+    if (client.answered) lostNotice = client.unreportedLoss;
+  };
+  open();
+  const get = async (): Promise<ViceSessionClient> => {
+    if (closed) throw new WireFailure("machine-unavailable", "The C64 session is shutting down.");
+    if (lostNotice !== undefined) {
+      const notice = lostNotice;
+      lostNotice = undefined;
+      throw notice;
+    }
+    const current = opening ?? open();
+    const client = await current;
+    if (!client.lost) return client;
+    // The loss is known here before the close event reaches drop.
+    drop(current, client);
+    return get();
+  };
+  return {
+    get,
+    async close() {
+      closed = true;
+      stop.abort();
+      const session = await opening?.catch(() => undefined);
+      await session?.close();
+    },
+  };
+}
+
+async function main(): Promise<void> {
+  if (process.argv.includes("--help") || process.argv.includes("-h")) {
+    process.stdout.write(`${HELP}\n`);
+    return;
+  }
+  startTrace("mcp", { warn: log });
+  const session = sessionSource();
+  const server = createMcpServer({ tools: [...machineTools, ...executionTools, ...debugTools, ...memoryTools, ...videoTools, ...inputTools, ...mediaTools], session: session.get, log });
+
+  let stopping = false;
+  const stop = async () => {
+    if (stopping) return;
+    stopping = true;
+    trace().event("mcp.stop");
+    await session.close();
+    process.exit(0);
+  };
+  // The harness ends the server by closing stdin or by a signal; both end the session and its emulator.
+  server.onclose = () => void stop();
+  process.stdin.once("end", () => void stop());
+  process.once("SIGINT", () => void stop());
+  process.once("SIGTERM", () => void stop());
+
+  await server.connect(new StdioServerTransport());
+}
+
+await main();

package/src/mcp/output.ts

@@ -0,0 +1,32 @@
+// Tool results written to a project file instead of the context (D39). The
+// MCP server runs on the agent's machine with the project as its working
+// directory, so it writes the file itself; the host never sees the path.
+
+import { createHash } from "node:crypto";
+
+import { z } from "zod";
+
+import { writeProjectFile } from "../host-client/transfer.ts";
+
+export const OutInput = z.string().min(1).describe("write the result to this file, relative to the project directory, in place of returning it. An existing file is overwritten");
+
+/** What a result says in place of the bytes it wrote. */
+export interface Written {
+  out: string;
+  bytes: number;
+  sha256: string;
+}
+
+/** The fields of a result with out, optional in an output schema that also has the inline form. */
+export const WrittenOutput = {
+  out: z.string().optional(),
+  bytes: z.number().int().min(0).optional(),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),
+};
+
+/** Writes `data` to the project file `path` and gives what the result shows in its place. */
+export function writeOut(path: string, data: Uint8Array | string, root?: string): Written {
+  const bytes = typeof data === "string" ? Buffer.from(data, "utf8") : data;
+  writeProjectFile(path, bytes, { what: "out", ...(root === undefined ? {} : { root }) });
+  return { out: path, bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex") };
+}

package/src/mcp/server.ts

@@ -0,0 +1,316 @@
+// MCP server creation, tool registration and the one place where failures
+// become MCP results. Tool groups live in tools/; nothing here knows VICE.
+
+import { createRequire } from "node:module";
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, type CallToolResult, type Tool as McpTool } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+
+import { formatC64Address, parseC64Address } from "../c64.ts";
+import { LostBeforeAnswer, type ViceSessionClient } from "../host-client/vice-session.ts";
+import { shownMessage, WireFailure, type WireError } from "../protocol/messages.ts";
+import { COMPARISONS, CONDITION_REGISTERS, MEMORY_VIEWS, SPACES, type Condition } from "../protocol/vice.ts";
+import { elapsedMs, trace, type TraceFields } from "../trace.ts";
+
+/** The session operations tools may call. */
+export type ViceSessionApi = Pick<
+  ViceSessionClient,
+  | "status"
+  | "memoryRead"
+  | "registersGet"
+  | "memoryWrite"
+  | "memorySearch"
+  | "memoryCompare"
+  | "disassemble"
+  | "registersSet"
+  | "execution"
+  | "reset"
+  | "warp"
+  | "window"
+  | "programLoad"
+  | "autostart"
+  | "diskAttach"
+  | "keyboard"
+  | "joystick"
+  | "screenCapture"
+  | "screenCompare"
+  | "screenBaselines"
+  | "screenDiscard"
+  | "snapshot"
+  | "snapshotExport"
+  | "snapshotRestore"
+  | "cpuHistory"
+  | "backtrace"
+  | "timing"
+  | "profile"
+  | "memmap"
+  | "vicii"
+  | "sprites"
+  | "cia"
+  | "sid"
+  | "observe"
+  | "breakpoint"
+  | "watchpoint"
+  | "runUntil"
+>;
+
+/** Resolves the session, opening it on first use when the start-up attempt failed. */
+export type SessionSource = () => Promise<ViceSessionApi>;
+
+type JsonObject = Record<string, unknown>;
+
+// ---------------------------------------------------------------------------
+// Public schema primitives shared by the tool groups
+
+/** Input address: "$" and four hex digits, either case. Parses to a number. */
+export const AddressInput = z
+  .string()
+  .regex(/^\$[0-9a-fA-F]{4}$/, "must be $ followed by four hex digits, for example $c000")
+  .transform((value) => parseC64Address(value))
+  .describe("C64 address, $0000 to $ffff");
+
+/** Output address: "$" and four lowercase hex digits. */
+export const AddressOutput = z.string().regex(/^\$[0-9a-f]{4}$/).describe("C64 address, $0000 to $ffff");
+
+export const Byte = z.number().int().min(0).max(255);
+
+export const HexData = z.string().regex(/^(?:[0-9a-f]{2})*$/).describe("bytes as lowercase hex, two digits per byte, no separators");
+
+/** Input bytes: hex in either case, two digits per byte, at least one byte. Parses to lowercase. */
+export const HexDataInput = z
+  .string()
+  .regex(/^(?:[0-9a-fA-F]{2})+$/, "must be hex bytes, two digits per byte, no separators, for example a9008d20d0")
+  .transform((value) => value.toLowerCase());
+
+export const SpaceInput = z.enum(SPACES).default("c64").describe("c64 is the computer. drive8 is the 1541 disk drive CPU");
+
+export const MemoryViewInput = z
+  .enum(MEMORY_VIEWS)
+  .default("cpu")
+  .describe("cpu reads what the CPU sees now (ROM and I/O where banked in). ram reads the RAM underneath (c64 only)");
+
+/** A name the agent gives to something the session keeps, such as a screen baseline or a snapshot. */
+export const TransientName = z
+  .string()
+  .regex(/^[A-Za-z0-9._-]{1,64}$/, "must be 1 to 64 letters, digits, dots, underscores or hyphens")
+  .describe("a name you choose: 1 to 64 letters, digits, dots, underscores or hyphens");
+
+/**
+ * Checks the fields of one action of a multi-action tool: a field that the
+ * action does not use, or a missing required field, is an invalid-input error.
+ */
+export function requireFields(action: string, given: Record<string, unknown>, allowed: readonly string[], required: readonly string[] = []): void {
+  for (const [field, value] of Object.entries(given)) {
+    if (value !== undefined && !allowed.includes(field)) throw new WireFailure("invalid-input", `${field} is not used with action ${action}.`);
+  }
+  for (const field of required) {
+    if (given[field] === undefined) throw new WireFailure("invalid-input", `Action ${action} needs ${field}.`);
+  }
+}
+
+/** A tool result that carries content blocks (for example an image) beside its structured result. */
+export class ToolOutput<T> {
+  readonly structured: T;
+  readonly content: CallToolResult["content"];
+
+  constructor(structured: T, content: CallToolResult["content"]) {
+    this.structured = structured;
+    this.content = content;
+  }
+}
+
+export interface ToolDefinition<I extends z.ZodObject = z.ZodObject, O extends z.ZodObject = z.ZodObject> {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: I;
+  outputSchema: O;
+  /** True for operations that only observe the machine. */
+  readOnly: boolean;
+  run(input: z.output<I>, session: ViceSessionApi): Promise<z.input<O> | ToolOutput<z.input<O>>>;
+}
+
+/** A typed condition: register, memory or raster. No expression language. */
+export const ConditionInput = z
+  .discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z.literal("register"),
+        register: z.enum(CONDITION_REGISTERS),
+        operator: z.enum(COMPARISONS),
+        value: Byte,
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("memory"),
+        address: AddressInput,
+        operator: z.enum(COMPARISONS),
+        value: Byte,
+        space: SpaceInput,
+        view: MemoryViewInput,
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("raster"),
+        line: z.number().int().min(0).describe("raster line: PAL 0-311, NTSC 0-262"),
+        cycle: z.number().int().min(0).optional().describe("cycle in the line: PAL 0-62, NTSC 0-64. True from this cycle on"),
+      })
+      .strict(),
+  ])
+  .describe("register: a CPU register compared to a byte. memory: a byte in memory compared to a byte. raster: the raster position");
+
+/** A condition as a result shows it: the input form, with the memory address as "$xxxx". */
+export const ConditionOutput = z
+  .discriminatedUnion("kind", [
+    z.object({ kind: z.literal("register"), register: z.enum(CONDITION_REGISTERS), operator: z.enum(COMPARISONS), value: Byte }),
+    z.object({ kind: z.literal("memory"), address: AddressOutput, operator: z.enum(COMPARISONS), value: Byte, space: z.enum(SPACES), view: z.enum(MEMORY_VIEWS) }),
+    z.object({ kind: z.literal("raster"), line: z.number().int().min(0), cycle: z.number().int().min(0).optional() }),
+  ])
+  .describe("the condition given at add");
+
+/** A protocol condition in its result form. */
+export function showCondition(condition: Condition): z.input<typeof ConditionOutput> {
+  return condition.kind === "memory" ? { ...condition, address: formatC64Address(condition.address) } : condition;
+}
+
+/** Removes keys whose value is undefined, so optional fields stay absent. */
+export function defined<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+/** A parsed condition input as the protocol type. */
+export function toCondition(input: z.output<typeof ConditionInput>): Condition {
+  return defined(input) as Condition;
+}
+
+/** Keeps a tool's handler typed against its own schemas. */
+export function defineTool<I extends z.ZodObject, O extends z.ZodObject>(tool: ToolDefinition<I, O>): ToolDefinition {
+  return tool as unknown as ToolDefinition;
+}
+
+function jsonSchema(schema: z.ZodObject, io: "input" | "output"): McpTool["inputSchema"] {
+  const { $schema: _ignored, ...rest } = z.toJSONSchema(schema, { io }) as JsonObject;
+  return rest as McpTool["inputSchema"];
+}
+
+export function toolListing(tool: ToolDefinition): McpTool {
+  return {
+    name: tool.name,
+    title: tool.title,
+    description: tool.description,
+    inputSchema: jsonSchema(tool.inputSchema, "input"),
+    outputSchema: jsonSchema(tool.outputSchema, "output"),
+    annotations: { title: tool.title, readOnlyHint: tool.readOnly, openWorldHint: false },
+  };
+}
+
+function errorResult(error: WireError): CallToolResult {
+  return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: error.code, message: shownMessage(error) }) }] };
+}
+
+/** "address: Invalid string: must match ..." style messages, one sentence per problem. */
+function describeIssues(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const where = issue.path.length === 0 ? "input" : issue.path.join(".");
+      return `${where}: ${issue.message}`;
+    })
+    .join(". ");
+}
+
+const INTERNAL_FAILURE: WireError = { code: "operation-failed", message: "The operation failed inside the c64-re-tools MCP server." };
+
+/** Runs one tool call and translates every outcome into an MCP result. The trace gets the call, its time and its outcome. */
+export async function callTool(
+  tools: ReadonlyMap<string, ToolDefinition>,
+  name: string,
+  args: unknown,
+  session: SessionSource,
+  log: (line: string) => void = () => {},
+): Promise<CallToolResult> {
+  const started = performance.now();
+  const result = await runCall(tools, name, args, session, log);
+  trace().event("tool.call", { name, args, ms: elapsedMs(started), ...outcome(result) });
+  return result;
+}
+
+/** What the trace records of a result: the structured result, or the code and message of the error. */
+function outcome(result: CallToolResult): TraceFields {
+  if (result.isError !== true) return { ok: true, result: result.structuredContent };
+  const first = result.content[0];
+  const text = first?.type === "text" ? first.text : "";
+  try {
+    return { ok: false, ...(JSON.parse(text) as WireError) };
+  } catch {
+    return { ok: false, message: text };
+  }
+}
+
+async function runCall(
+  tools: ReadonlyMap<string, ToolDefinition>,
+  name: string,
+  args: unknown,
+  session: SessionSource,
+  log: (line: string) => void,
+): Promise<CallToolResult> {
+  const tool = tools.get(name);
+  if (tool === undefined) return errorResult({ code: "invalid-input", message: `There is no tool named ${name}.` });
+  const parsed = tool.inputSchema.safeParse(args ?? {});
+  if (!parsed.success) return errorResult({ code: "invalid-input", message: describeIssues(parsed.error) });
+  try {
+    let output: unknown;
+    try {
+      output = await tool.run(parsed.data, await session());
+    } catch (error) {
+      // A session that the emulator never answered had no machine state: the call goes again on a new session (D57).
+      if (!(error instanceof LostBeforeAnswer)) throw error;
+      output = await tool.run(parsed.data, await session());
+    }
+    // The result goes out in the shape that the tool listing advertises: keys
+    // that the output schema does not name are removed, and a result that does
+    // not fit the schema is an internal failure.
+    const checked = tool.outputSchema.safeParse(output instanceof ToolOutput ? output.structured : output);
+    if (!checked.success) {
+      log(`${name} gave a result outside its output schema: ${describeIssues(checked.error)}`);
+      return errorResult(INTERNAL_FAILURE);
+    }
+    const result = checked.data as JsonObject;
+    const extra = output instanceof ToolOutput ? output.content : [];
+    return { content: [{ type: "text", text: JSON.stringify(result) }, ...extra], structuredContent: result };
+  } catch (error) {
+    if (error instanceof WireFailure) return errorResult(error.toWire());
+    log(`${name} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+    return errorResult(INTERNAL_FAILURE);
+  }
+}
+
+/** The version of this package. A package.json without a version is a broken installation. */
+function packageVersion(): string {
+  const { version } = createRequire(import.meta.url)("../../package.json") as { version?: unknown };
+  if (typeof version !== "string" || version === "") {
+    throw new Error("The package.json of c64-re-tools has no version. Install c64-re-tools again.");
+  }
+  return version;
+}
+
+const INSTRUCTIONS =
+  "These tools control one live Commodore 64 emulator that belongs to this session. " +
+  "Addresses are four hex digits after a dollar sign, for example $c000. " +
+  "Memory data is lowercase hex without separators. " +
+  "A read does not change the run state of the machine.";
+
+export function createMcpServer(options: { tools: readonly ToolDefinition[]; session: SessionSource; log?: (line: string) => void }): Server {
+  const tools = new Map(options.tools.map((tool) => [tool.name, tool]));
+  const server = new Server(
+    { name: "c64-re-tools", version: packageVersion() },
+    { capabilities: { tools: {} }, instructions: INSTRUCTIONS },
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: options.tools.map(toolListing) }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) =>
+    callTool(tools, request.params.name, request.params.arguments, options.session, options.log),
+  );
+  return server;
+}