@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/mcp/src/cli.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// The `ic-reactor-mcp` command: an MCP server on stdio.
+//
+// stdout carries the protocol, so everything for the person goes to stderr,
+// which MCP clients keep in their server log.
+import { readFileSync, statSync } from "node:fs"
+import { createRequire } from "node:module"
+import { createClient } from "@ic-reactor/core"
+import type { HttpAgent } from "@icp-sdk/core/agent"
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio"
+import { callerFrom, type KeyFiles } from "./identity.ts"
+import { createInterfaceLoader } from "./interface/loader.ts"
+import {
+  agentCandidSource,
+  createReadAgent,
+  type CandidSource,
+} from "./interface/read-candid.ts"
+import { parseOptions } from "./options.ts"
+import { createMcpServer } from "./server/server.ts"
+import { USAGE, UsageError } from "./usage.ts"
+
+const VERSION = (
+  createRequire(import.meta.url)("../package.json") as { version: string }
+).version
+
+const log = (line: string): void => {
+  process.stderr.write(`[ic-reactor-mcp] ${line}\n`)
+}
+
+const nodeKeyFiles: KeyFiles = {
+  mode: (path) =>
+    process.platform === "win32" ? undefined : statSync(path).mode,
+  read: (path) => readFileSync(path, "utf8"),
+}
+
+/**
+ * The agent that reads interfaces, made on first use: a local replica that is
+ * not up yet when the server starts is tried again on the next read.
+ */
+function lazySource(make: () => Promise<HttpAgent>): CandidSource {
+  let source: Promise<CandidSource> | undefined
+  const get = (): Promise<CandidSource> => {
+    source ??= make().then(agentCandidSource, (error: unknown) => {
+      source = undefined
+      throw error
+    })
+    return source
+  }
+  return {
+    readCandidAndHash: async (id) => (await get()).readCandidAndHash(id),
+    readModuleHash: async (id) => (await get()).readModuleHash(id),
+    readTmpHack: async (id) => (await get()).readTmpHack(id),
+  }
+}
+
+async function main(argv: readonly string[]): Promise<void> {
+  let options
+  let caller
+  try {
+    options = parseOptions(argv)
+    if (options.help) {
+      process.stdout.write(USAGE)
+      return
+    }
+    if (options.version) {
+      process.stdout.write(`${VERSION}\n`)
+      return
+    }
+    caller = callerFrom(options.identityPath, nodeKeyFiles)
+  } catch (error) {
+    if (!(error instanceof UsageError)) throw error
+    process.stderr.write(`ic-reactor-mcp: ${error.message}\n`)
+    process.exitCode = 2
+    return
+  }
+
+  const { network } = options
+  const client = createClient({
+    network: network.network,
+    identity: caller.identity,
+  })
+  // Certified reads are replicated calls, so they never carry the key.
+  const anonymousClient =
+    caller.identity === "anonymous"
+      ? client
+      : createClient({ network: network.network, identity: "anonymous" })
+  const loader = createInterfaceLoader({
+    source: lazySource(() => createReadAgent(network.read)),
+    files: options.didFiles,
+    ...(network.recheckMs === undefined
+      ? {}
+      : { recheckMs: network.recheckMs }),
+  })
+  const server = createMcpServer({
+    client,
+    anonymousClient,
+    loader,
+    canisters: options.canisters,
+    callerSource: caller.source,
+    networkLabel: network.label,
+    version: VERSION,
+    log,
+  })
+
+  let closed = false
+  const shutdown = async (): Promise<void> => {
+    if (closed) return
+    closed = true
+    await server.close().catch(() => {})
+    await loader.close().catch(() => {})
+    client.dispose()
+    if (anonymousClient !== client) anonymousClient.dispose()
+  }
+  // The client closing stdin ends the session.
+  server.onclose = () => void shutdown()
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.once(signal, () => {
+      void shutdown().finally(() => process.exit(0))
+    })
+  }
+
+  await server.connect(new StdioServerTransport())
+  log(
+    `${VERSION} serving on stdio: caller ${client.caller()} (${caller.source}); network ${network.label}; ` +
+      (options.canisters.length === 0
+        ? "no listed canisters"
+        : `canisters ${options.canisters.map((c) => `${c.name}=${c.id}`).join(", ")}`)
+  )
+}
+
+main(process.argv.slice(2)).catch((error: unknown) => {
+  log(error instanceof Error ? (error.stack ?? error.message) : String(error))
+  process.exitCode = 1
+})

package/packages/mcp/src/identity.ts

@@ -0,0 +1,188 @@
+// Who the server calls as. Ported from examples/node-agent-tool.
+//
+// An MCP server runs under an agent and has no sign-in flow: it is handed a
+// key, or it only reads.
+//
+// - `--identity <file>`: an Ed25519 or secp256k1 private key in PEM form, as
+//   `icp identity export` or `dfx identity export` prints it. The file must be
+//   readable by its owner only, as ssh asks of a key: anyone else who can read
+//   it can sign as this principal.
+// - else `identity: "anonymous"`. That client reads, and refuses every update
+//   before sending it. It is never a `new AnonymousIdentity()`, which would
+//   sign and send writes anonymously.
+//
+// A key is never generated here, and no message quotes a key's bytes.
+import { createPrivateKey } from "node:crypto"
+import type { Identity } from "@icp-sdk/core/agent"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import { Secp256k1KeyIdentity } from "@icp-sdk/core/identity/secp256k1"
+import { UsageError } from "./usage.ts"
+
+/** Who calls, and how they were chosen. */
+export interface Caller {
+  /** What `createClient({ identity })` is given. */
+  readonly identity: Identity | "anonymous"
+  /** The key's algorithm, or `null` for the anonymous caller. */
+  readonly algorithm: "ed25519" | "secp256k1" | null
+  /** Where the key came from, for a person to read. */
+  readonly source: string
+}
+
+/** The anonymous caller: reads only. */
+export const ANONYMOUS_CALLER: Caller = Object.freeze({
+  identity: "anonymous",
+  algorithm: null,
+  source: "anonymous (no --identity): reads only",
+})
+
+/** What the identity file is read through: `node:fs`, or a fake in tests. */
+export interface KeyFiles {
+  /** The file's permission bits, or `undefined` where they mean nothing (Windows). */
+  mode(path: string): number | undefined
+  read(path: string): string
+}
+
+/**
+ * The caller `--identity` names, or the anonymous one.
+ *
+ * @throws UsageError for a key file others can read, or one that cannot be read.
+ */
+export function callerFrom(path: string | undefined, files: KeyFiles): Caller {
+  if (path === undefined) return ANONYMOUS_CALLER
+  const what = `--identity ${path}`
+  let pem: string
+  try {
+    const mode = files.mode(path)
+    if (mode !== undefined && (mode & 0o077) !== 0) {
+      throw new UsageError(
+        `${what} can be read or changed by other users of this machine (mode ${(mode & 0o777).toString(8).padStart(3, "0")}): ` +
+          `run chmod 600 ${path}, so that only you can sign with it`
+      )
+    }
+    pem = files.read(path)
+  } catch (error) {
+    if (error instanceof UsageError) throw error
+    throw new UsageError(
+      `${what}: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+  const { identity, algorithm } = identityFromPem(pem, what)
+  return { identity, algorithm, source: `${what} (${algorithm})` }
+}
+
+/**
+ * The private key of a PEM file as an Identity.
+ *
+ * - Ed25519 comes as PKCS#8 (`BEGIN PRIVATE KEY`). dfx writes the form that
+ *   also carries the public key, which OpenSSL (and so `node:crypto`) refuses,
+ *   so the 32-byte seed is read from the DER here, and a public key next to it
+ *   must match.
+ * - secp256k1 comes as SEC1 (`BEGIN EC PRIVATE KEY`, possibly after an
+ *   `EC PARAMETERS` block) or PKCS#8; `node:crypto` reads both.
+ *
+ * @throws UsageError for anything else, an encrypted key included.
+ */
+export function identityFromPem(
+  pem: string,
+  what: string
+): { identity: Identity; algorithm: "ed25519" | "secp256k1" } {
+  const labels = [...pem.matchAll(/-----BEGIN ([A-Z0-9 ]+)-----/g)].map(
+    (match) => match[1]
+  )
+  if (labels.includes("ENCRYPTED PRIVATE KEY")) {
+    throw new UsageError(
+      `${what} is encrypted: export the key unencrypted (icp identity export <name>)`
+    )
+  }
+  const der = derOf(pem, "PRIVATE KEY")
+  const seed = der === undefined ? undefined : ed25519SeedOf(der)
+  if (der !== undefined && seed !== undefined) {
+    const identity = Ed25519KeyIdentity.fromSecretKey(seed)
+    const stated = ed25519PublicKeyOf(der)
+    const actual = new Uint8Array(identity.getPublicKey().toRaw())
+    if (stated !== undefined && !sameBytes(stated, actual)) {
+      throw new UsageError(
+        `${what}: the public key in the file is not the private key's`
+      )
+    }
+    return { identity, algorithm: "ed25519" }
+  }
+
+  let jwk: { kty?: string; crv?: string; d?: string }
+  try {
+    jwk = createPrivateKey(pem).export({ format: "jwk" })
+  } catch {
+    throw new UsageError(
+      `${what} holds no private key this server can read: it reads Ed25519 and secp256k1 keys in PEM form`
+    )
+  }
+  if (jwk.kty !== "EC" || jwk.crv !== "secp256k1" || jwk.d === undefined) {
+    throw new UsageError(
+      `${what} holds a ${jwk.crv ?? jwk.kty ?? "different"} key: this server signs with Ed25519 or secp256k1 keys`
+    )
+  }
+  const secret = new Uint8Array(Buffer.from(jwk.d, "base64url"))
+  let identity: Identity
+  try {
+    identity = Secp256k1KeyIdentity.fromSecretKey(secret)
+  } catch {
+    // OpenSSL reads a private value of n or more; the signer does not. The
+    // signer's message is left out: it could quote the key.
+    throw new UsageError(
+      `${what} holds a secp256k1 private key that is not valid: its value is not below the curve's order`
+    )
+  }
+  return { identity, algorithm: "secp256k1" }
+}
+
+/** The DER bytes of the first `label` block of a PEM text. */
+function derOf(pem: string, label: string): Uint8Array | undefined {
+  const match = new RegExp(
+    `-----BEGIN ${label}-----([A-Za-z0-9+/=\\s]+)-----END ${label}-----`
+  ).exec(pem)
+  return match?.[1] === undefined
+    ? undefined
+    : new Uint8Array(Buffer.from(match[1].replace(/\s+/g, ""), "base64"))
+}
+
+/**
+ * PKCS#8 for Ed25519 (RFC 8410): SEQUENCE { version 0 or 1, the algorithm
+ * 1.3.101.112, OCTET STRING { OCTET STRING (32-byte seed) } [, public key] }.
+ */
+const ED25519_ALGORITHM_AND_SEED = [
+  0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]
+
+function ed25519SeedOf(der: Uint8Array): Uint8Array | undefined {
+  const version = der[4]
+  const prefixed =
+    der[0] === 0x30 &&
+    der[1] === der.length - 2 &&
+    der[2] === 0x02 &&
+    der[3] === 0x01 &&
+    (version === 0 || version === 1) &&
+    ED25519_ALGORITHM_AND_SEED.every((byte, i) => der[5 + i] === byte)
+  if (!prefixed) return undefined
+  const start = 5 + ED25519_ALGORITHM_AND_SEED.length
+  const seed = der.slice(start, start + 32)
+  return seed.length === 32 ? seed : undefined
+}
+
+/** The public key a version 1 key carries after its seed, in either tagging dfx and OpenSSL use. */
+function ed25519PublicKeyOf(der: Uint8Array): Uint8Array | undefined {
+  const rest = der.slice(5 + ED25519_ALGORITHM_AND_SEED.length + 32)
+  const explicit = [0xa1, 0x23, 0x03, 0x21, 0x00]
+  const implicit = [0x81, 0x21, 0x00]
+  for (const tag of [explicit, implicit]) {
+    if (
+      rest.length === tag.length + 32 &&
+      tag.every((byte, i) => rest[i] === byte)
+    ) {
+      return rest.slice(tag.length)
+    }
+  }
+  return undefined
+}
+
+const sameBytes = (a: Uint8Array, b: Uint8Array): boolean =>
+  a.length === b.length && a.every((byte, i) => byte === b[i])

package/packages/mcp/src/interface/cache.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest"
+import { Lru } from "./cache.ts"
+
+describe("Lru", () => {
+  it("evicts the least recently used entry past its count", () => {
+    const lru = new Lru<string, number>({ maxEntries: 2 })
+    lru.set("a", 1)
+    lru.set("b", 2)
+    // A read makes "a" the most recent, so "b" goes first.
+    expect(lru.get("a")).toBe(1)
+    lru.set("c", 3)
+    expect([lru.has("a"), lru.has("b"), lru.has("c")]).toEqual([
+      true,
+      false,
+      true,
+    ])
+  })
+
+  it("does not refresh an entry it only peeks at", () => {
+    const lru = new Lru<string, number>({ maxEntries: 2 })
+    lru.set("a", 1)
+    lru.set("b", 2)
+    expect(lru.peek("a")).toBe(1)
+    lru.set("c", 3)
+    expect(lru.has("a")).toBe(false)
+  })
+
+  it("evicts past its weight, and counts a replaced value once", () => {
+    const lru = new Lru<string, string>({
+      maxEntries: 10,
+      maxWeight: 10,
+      weigh: (value) => value.length,
+    })
+    lru.set("a", "xxxx")
+    lru.set("a", "xxxxx")
+    lru.set("b", "yyyyy")
+    expect(lru.size).toBe(2)
+    lru.set("c", "z")
+    expect([lru.has("a"), lru.has("b"), lru.has("c")]).toEqual([
+      false,
+      true,
+      true,
+    ])
+    // A value heavier than the bound is not kept at all.
+    lru.set("d", "w".repeat(11))
+    expect(lru.size).toBe(0)
+  })
+})

package/packages/mcp/src/interface/cache.ts

@@ -0,0 +1,68 @@
+/**
+ * A least-recently-used map with a bound on its entry count and, optionally,
+ * on the total weight of its values (for example their size in bytes).
+ * Reading an entry with `get` makes it the most recent; adding one past
+ * either bound evicts the least recent until both hold again.
+ */
+export class Lru<K, V> {
+  readonly #map = new Map<K, V>()
+  readonly #maxEntries: number
+  readonly #maxWeight: number
+  readonly #weigh: (value: V) => number
+  #weight = 0
+
+  constructor(options: {
+    maxEntries: number
+    maxWeight?: number
+    weigh?: (value: V) => number
+  }) {
+    this.#maxEntries = options.maxEntries
+    this.#maxWeight = options.maxWeight ?? Number.POSITIVE_INFINITY
+    this.#weigh = options.weigh ?? (() => 0)
+  }
+
+  get size(): number {
+    return this.#map.size
+  }
+
+  get(key: K): V | undefined {
+    if (!this.#map.has(key)) return undefined
+    const value = this.#map.get(key) as V
+    this.#map.delete(key)
+    this.#map.set(key, value)
+    return value
+  }
+
+  /** Like `get`, without making the entry the most recent. */
+  peek(key: K): V | undefined {
+    return this.#map.get(key)
+  }
+
+  has(key: K): boolean {
+    return this.#map.has(key)
+  }
+
+  set(key: K, value: V): void {
+    this.delete(key)
+    this.#map.set(key, value)
+    this.#weight += this.#weigh(value)
+    while (
+      this.#map.size > 0 &&
+      (this.#map.size > this.#maxEntries || this.#weight > this.#maxWeight)
+    ) {
+      const oldest = this.#map.keys().next().value as K
+      this.delete(oldest)
+    }
+  }
+
+  delete(key: K): boolean {
+    if (!this.#map.has(key)) return false
+    this.#weight -= this.#weigh(this.#map.get(key) as V)
+    return this.#map.delete(key)
+  }
+
+  clear(): void {
+    this.#map.clear()
+    this.#weight = 0
+  }
+}

package/packages/mcp/src/interface/cli-cache.test.ts

@@ -0,0 +1,150 @@
+// The projections `methodDid` reuses, and the refusal of a .did that ran
+// past the deadline, over the real compiler in its worker (offline).
+import { readFile } from "node:fs/promises"
+import { afterAll, describe, expect, it, vi } from "vitest"
+import { cachingCli } from "./cli-cache.ts"
+import { compileInterface, projectionOf, type CandidCli } from "./compile.ts"
+import { CompileDeadlineError, createWorkerCli } from "./compile-worker.ts"
+
+const icrc1Did = await readFile(
+  new URL("./fixtures/icrc1.did", import.meta.url),
+  "utf8"
+)
+const OTHER_DID = "service : { ping : () -> (text) query }"
+
+const worker = createWorkerCli()
+afterAll(() => worker.close())
+
+/** The real compiler (in its worker), with a count of every call. */
+function counted() {
+  const calls = {
+    didToContract: 0,
+    didToModule: 0,
+    projectDid: 0,
+    checkCompatible: 0,
+  }
+  const cli: CandidCli = {
+    didToContract: (sources) => {
+      calls.didToContract++
+      return worker.didToContract(sources)
+    },
+    didToModule: (sources) => {
+      calls.didToModule++
+      return worker.didToModule(sources)
+    },
+    projectDid: (sources, methods) => {
+      calls.projectDid++
+      return worker.projectDid(sources, methods)
+    },
+    checkCompatible: (written, live) => {
+      calls.checkCompatible++
+      return worker.checkCompatible(written, live)
+    },
+  }
+  return { cli, calls }
+}
+
+describe("cachingCli", () => {
+  it("projects a .did once per set of methods, in any order", async () => {
+    const { cli, calls } = counted()
+    const cached = cachingCli(cli)
+    const first = await projectionOf(cached, icrc1Did, [
+      "icrc1_transfer",
+      "icrc1_fee",
+    ])
+    const same = await projectionOf(cached, icrc1Did, [
+      "icrc1_fee",
+      "icrc1_transfer",
+      "icrc1_fee",
+    ])
+    expect(same).toEqual(first)
+    expect(calls.projectDid).toBe(1)
+    await projectionOf(cached, icrc1Did, ["icrc1_fee"])
+    expect(calls.projectDid).toBe(2)
+  })
+
+  it("shares a projection in flight, and keeps one that names an unknown method", async () => {
+    const { cli, calls } = counted()
+    const cached = cachingCli(cli)
+    const [a, b] = await Promise.all([
+      projectionOf(cached, icrc1Did, ["nope"]),
+      projectionOf(cached, icrc1Did, ["nope"]),
+    ])
+    await projectionOf(cached, icrc1Did, ["nope"])
+    expect(a).toMatchObject({
+      ok: false,
+      message: expect.stringMatching(/unknown_method/),
+    })
+    expect(b).toEqual(a)
+    expect(calls.projectDid).toBe(1)
+  })
+
+  it("compiles and generates on every call: the loader keeps those", async () => {
+    const { cli, calls } = counted()
+    const cached = cachingCli(cli)
+    await compileInterface(cached, `${OTHER_DID}\n// a comment`)
+    await compileInterface(cached, `${OTHER_DID}\n// a comment`)
+    expect(calls).toMatchObject({ didToContract: 2, didToModule: 2 })
+  })
+
+  it("keeps no answer that threw", async () => {
+    let fail = true
+    const projectDid = vi.fn<CandidCli["projectDid"]>(
+      async (sources, methods) => {
+        if (fail) throw new Error("the WASM trapped")
+        return worker.projectDid(sources, methods)
+      }
+    )
+    const cached = cachingCli({ ...worker, projectDid })
+    await expect(cached.projectDid(icrc1Did, ["icrc1_fee"])).rejects.toThrow(
+      /trapped/
+    )
+    fail = false
+    expect(await cached.projectDid(icrc1Did, ["icrc1_fee"])).toMatchObject({
+      ok: true,
+    })
+    expect(projectDid).toHaveBeenCalledTimes(2)
+  })
+
+  it("refuses a .did whose compile ran past the deadline, whatever the call, for a while", async () => {
+    let time = 0
+    const projectDid = vi.fn<CandidCli["projectDid"]>(async () => {
+      throw new CompileDeadlineError("stopped")
+    })
+    const cached = cachingCli(
+      { ...worker, projectDid },
+      { now: () => time, slowTtlMs: 15_000 }
+    )
+    expect(await projectionOf(cached, icrc1Did, ["icrc1_fee"])).toEqual({
+      ok: false,
+      message: "stopped",
+    })
+    // Another method list, the contract: neither reaches the worker.
+    expect(
+      await projectionOf(cached, icrc1Did, ["icrc1_symbol"])
+    ).toMatchObject({ ok: false, message: expect.stringMatching(/deadline/) })
+    expect(await compileInterface(cached, icrc1Did)).toMatchObject({
+      ok: false,
+      code: "timeout",
+    })
+    expect(projectDid).toHaveBeenCalledTimes(1)
+    // Another .did is not held up.
+    expect(await compileInterface(cached, OTHER_DID)).toMatchObject({
+      ok: true,
+    })
+
+    time += 15_000
+    await projectionOf(cached, icrc1Did, ["icrc1_symbol"])
+    expect(projectDid).toHaveBeenCalledTimes(2)
+  })
+
+  it("does not hold a .did against it when the queue was only full", async () => {
+    const projectDid = vi.fn<CandidCli["projectDid"]>(async () => {
+      throw new CompileDeadlineError("busy", { busy: true })
+    })
+    const cached = cachingCli({ ...worker, projectDid })
+    await projectionOf(cached, icrc1Did, ["icrc1_fee"])
+    await projectionOf(cached, icrc1Did, ["icrc1_fee"])
+    expect(projectDid).toHaveBeenCalledTimes(2)
+  })
+})