@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/mcp/src/network.ts

@@ -0,0 +1,122 @@
+// `--network ic|local|<url>` and `--root-key`: one choice, given both to the
+// client that makes calls and to the agent that reads interfaces. Ported from
+// examples/node-agent-tool.
+//
+// The root key is what every certificate is checked against, so it is never
+// taken from a replica that is not on this machine:
+//
+// - `ic`: mainnet through https://icp-api.io, with the root key the agent
+//   ships with. Nothing is fetched.
+// - `local`: icp-cli's local network, http://127.0.0.1:8000. Its key is
+//   fetched from it.
+// - a local <url> (localhost, *.localhost, 127.0.0.0/8, [::1]): its key is
+//   fetched from it.
+// - any other <url>: the key must be given as `--root-key <hex>`. Without one
+//   the server refuses to start: a key fetched from a remote host would be
+//   whatever that host chose to send.
+import type { Network } from "@ic-reactor/core"
+import type { ReadAgentOptions } from "./interface/read-candid.ts"
+import { UsageError } from "./usage.ts"
+
+const IC_HOST = "https://icp-api.io"
+const LOCAL_HOST = "http://127.0.0.1:8000"
+
+export interface NetworkChoice {
+  /** What `createClient({ network })` is given. */
+  readonly network: Network
+  /** The same network for the agent that reads canister interfaces. */
+  readonly read: ReadAgentOptions
+  /** The network and where its root key comes from, for a person to read. */
+  readonly label: string
+  /**
+   * How long a loaded interface is used before its module hash is read
+   * again: 0 on this machine, where a redeploy is a moment away and a
+   * read_state costs nothing; the loader's default elsewhere.
+   */
+  readonly recheckMs?: number
+}
+
+/** Whether a URL's host is this machine: the same rule the client applies. */
+export function isLocalHost(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname) ||
+    hostname === "[::1]"
+  )
+}
+
+/**
+ * The network `--network` and `--root-key` name; mainnet when neither is given.
+ *
+ * @throws UsageError for a value that is not `ic`, `local` or an http(s) URL,
+ * a remote URL without a root key, or a root key given for `ic` or `local`.
+ */
+export function networkFrom(
+  flag: string | undefined,
+  rootKeyHex: string | undefined
+): NetworkChoice {
+  const name = flag ?? "ic"
+  if (name === "ic" || name === "local") {
+    if (rootKeyHex !== undefined) {
+      throw new UsageError(
+        `--root-key goes with a --network <url>: "${name}" has its root key already`
+      )
+    }
+    return name === "ic"
+      ? {
+          network: "ic",
+          read: { host: IC_HOST, fetchRootKey: false },
+          label: `ic (mainnet, ${IC_HOST}; root key built into the agent)`,
+        }
+      : {
+          network: "local",
+          read: { host: LOCAL_HOST, fetchRootKey: true },
+          label: `local (${LOCAL_HOST}; root key fetched from this machine's replica)`,
+          recheckMs: 0,
+        }
+  }
+
+  let url: URL
+  try {
+    url = new URL(name)
+  } catch {
+    throw new UsageError(
+      `--network ${JSON.stringify(name)} is not ic, local or a URL such as http://127.0.0.1:8000`
+    )
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new UsageError(`--network ${name}: the URL is http or https`)
+  }
+  const host = url.origin
+
+  if (rootKeyHex !== undefined) {
+    const rootKey = hexBytes(rootKeyHex, "--root-key")
+    return {
+      network: { host, rootKey },
+      read: { host, rootKey, fetchRootKey: false },
+      label: `${host} (root key given with --root-key)`,
+    }
+  }
+  if (isLocalHost(url.hostname)) {
+    return {
+      network: { host },
+      read: { host, fetchRootKey: true },
+      label: `${host} (root key fetched from it, as it is on this machine)`,
+      recheckMs: 0,
+    }
+  }
+  throw new UsageError(
+    `--network ${host} is not on this machine, so its root key is never fetched from it: ` +
+      `pass the replica's root key as --root-key <hex> (DER), or use --network ic for mainnet`
+  )
+}
+
+function hexBytes(text: string, what: string): Uint8Array {
+  if (text === "" || !/^(?:[0-9a-fA-F]{2})*$/.test(text)) {
+    throw new UsageError(`${what} is not hex: give the key's DER bytes as hex`)
+  }
+  return Uint8Array.from(text.match(/../g) ?? [], (pair) =>
+    Number.parseInt(pair, 16)
+  )
+}

package/packages/mcp/src/options.ts

@@ -0,0 +1,149 @@
+// The command line, read once at start. Everything a person can get wrong is
+// refused here, before the server answers its first request.
+import { homedir } from "node:os"
+import { parseArgs } from "node:util"
+import { checkCanisterId } from "./interface/ids.ts"
+import { networkFrom, type NetworkChoice } from "./network.ts"
+import { UsageError } from "./usage.ts"
+
+/** A canister named with `--canister`: it gets typed tools and takes updates. */
+export interface ListedCanister {
+  /** The name its tools start with, such as `ledger` in `ledger_icrc1_transfer`. */
+  readonly name: string
+  readonly id: string
+}
+
+export interface Options {
+  readonly help: boolean
+  readonly version: boolean
+  readonly network: NetworkChoice
+  readonly identityPath: string | undefined
+  readonly canisters: readonly ListedCanister[]
+  /** Canister id to the .did path given with `--did`. */
+  readonly didFiles: ReadonlyMap<string, string>
+}
+
+/** A name is short and plain, so that `<name>_<method>` stays a valid tool name. */
+const NAME = /^[A-Za-z0-9_]{1,20}$/
+
+/**
+ * The options of `argv` (without the node and script paths).
+ *
+ * @throws UsageError for anything the server cannot start with.
+ */
+export function parseOptions(
+  argv: readonly string[],
+  home: () => string = homedir
+): Options {
+  let values: {
+    canister?: string[]
+    did?: string[]
+    identity?: string
+    network?: string
+    "root-key"?: string
+    help?: boolean
+    version?: boolean
+  }
+  try {
+    ;({ values } = parseArgs({
+      args: [...argv],
+      options: {
+        canister: { type: "string", multiple: true },
+        did: { type: "string", multiple: true },
+        identity: { type: "string" },
+        network: { type: "string" },
+        "root-key": { type: "string" },
+        help: { type: "boolean" },
+        version: { type: "boolean" },
+      },
+      strict: true,
+      allowPositionals: false,
+    }))
+  } catch (error) {
+    throw new UsageError(
+      `${error instanceof Error ? error.message : String(error)} (see --help)`
+    )
+  }
+
+  const network = networkFrom(values.network, values["root-key"])
+  const canisters = listedCanisters(values.canister ?? [])
+  return {
+    help: values.help === true,
+    version: values.version === true,
+    network,
+    identityPath:
+      values.identity === undefined
+        ? undefined
+        : expandHome(values.identity, home),
+    canisters,
+    didFiles: didFiles(values.did ?? [], canisters, home),
+  }
+}
+
+function listedCanisters(flags: readonly string[]): ListedCanister[] {
+  const byName = new Map<string, ListedCanister>()
+  const ids = new Set<string>()
+  for (const flag of flags) {
+    const equals = flag.indexOf("=")
+    const idText = equals === -1 ? flag : flag.slice(equals + 1)
+    const checked = checkCanisterId(idText.trim())
+    if (!checked.ok)
+      throw new UsageError(`--canister ${flag}: ${checked.message}`)
+    const name = equals === -1 ? checked.id.slice(0, 5) : flag.slice(0, equals)
+    if (!NAME.test(name)) {
+      throw new UsageError(
+        `--canister ${flag}: the name is 1 to 20 letters, digits or _, such as ledger=${checked.id}`
+      )
+    }
+    if (byName.has(name)) {
+      throw new UsageError(
+        `--canister ${flag}: the name ${name} is taken; give each canister its own, such as ${name}2=${checked.id}`
+      )
+    }
+    if (ids.has(checked.id)) {
+      throw new UsageError(`--canister ${flag}: ${checked.id} is listed twice`)
+    }
+    byName.set(name, { name, id: checked.id })
+    ids.add(checked.id)
+  }
+  return [...byName.values()]
+}
+
+function didFiles(
+  flags: readonly string[],
+  canisters: readonly ListedCanister[],
+  home: () => string
+): Map<string, string> {
+  const files = new Map<string, string>()
+  for (const flag of flags) {
+    const equals = flag.indexOf("=")
+    if (equals <= 0 || equals === flag.length - 1) {
+      throw new UsageError(
+        `--did ${flag}: write <name or id>=<path>, such as ledger=./ledger.did`
+      )
+    }
+    const target = flag.slice(0, equals)
+    const listed = canisters.find((canister) => canister.name === target)
+    let id: string
+    if (listed !== undefined) {
+      id = listed.id
+    } else {
+      const checked = checkCanisterId(target)
+      if (!checked.ok) {
+        throw new UsageError(
+          `--did ${flag}: ${target} is neither a --canister name nor a canister id (${checked.message})`
+        )
+      }
+      id = checked.id
+    }
+    if (files.has(id))
+      throw new UsageError(`--did ${flag}: ${id} has a .did already`)
+    files.set(id, expandHome(flag.slice(equals + 1), home))
+  }
+  return files
+}
+
+/** `~/x` as a shell would read it: an MCP client starts the server without a shell. */
+function expandHome(path: string, home: () => string): string {
+  return path === "~" || path.startsWith("~/") ? home() + path.slice(1) : path
+}

package/packages/mcp/src/server/approval.ts

@@ -0,0 +1,159 @@
+// The person's approval of one update, asked through the MCP client (form
+// elicitation): the call is shown in full, and it is sent only when the person
+// ticks "Send this call" and accepts. Declining, closing the form, a timeout,
+// an error or a client that cannot ask all mean the call is not sent.
+import type {
+  ElicitRequestFormParams,
+  ServerContext,
+} from "@modelcontextprotocol/server"
+import { candidName } from "../candid/candid-text.ts"
+import type { InterfaceProvenance } from "../interface/types.ts"
+
+/** How long the person has to answer before the call is dropped. */
+export const APPROVAL_TIMEOUT_MS = 10 * 60_000
+
+/** The longest Candid argument text shown; a call whose arguments do not fit is refused, never cut. */
+export const MAX_APPROVAL_ARGS_CHARS = 20_000
+
+/**
+ * The longest method name shown, as Candid; a call to a method whose name is
+ * longer is refused, so that the arguments come near the top of the form.
+ */
+export const MAX_APPROVAL_METHOD_CHARS = 200
+
+/** The form: one box, unticked until the person ticks it. */
+export const APPROVAL_SCHEMA: ElicitRequestFormParams["requestedSchema"] = {
+  type: "object",
+  properties: {
+    approve: {
+      type: "boolean",
+      title: "Send this call",
+      description: "Tick to sign and send exactly the call shown above.",
+      default: false,
+    },
+  },
+  required: ["approve"],
+}
+
+/** Everything the person sees about the call. */
+export interface ApprovalFacts {
+  readonly canisterId: string
+  /** The `--canister` name, when the canister has one. */
+  readonly canisterName: string | undefined
+  readonly method: string
+  readonly mode: "update" | "oneway"
+  /** The principal that signs. */
+  readonly caller: string
+  /** Where its key came from. */
+  readonly callerSource: string
+  readonly network: string
+  /** The arguments as Candid text. */
+  readonly argsText: string
+  readonly argBytes: number
+  readonly argSha256: string
+  readonly provenance: InterfaceProvenance
+}
+
+/**
+ * The message of the approval form. The facts and the arguments are in a
+ * code fence: a client that renders the message as Markdown shows them as
+ * they are, and no line of them can close the fence early.
+ */
+export function approvalMessage(facts: ApprovalFacts): string {
+  const canister =
+    facts.canisterName === undefined
+      ? facts.canisterId
+      : `${facts.canisterId} (${facts.canisterName})`
+  const call = [
+    `Canister: ${canister}`,
+    `Method:   ${candidName(facts.method)}`,
+    `Caller:   ${facts.caller}, ${facts.callerSource}`,
+    `Network:  ${facts.network}`,
+    "",
+    "Arguments, in Candid:",
+    facts.argsText,
+    "",
+    `They encode to ${facts.argBytes} bytes, sha256 ${facts.argSha256}.`,
+    `Interface: ${provenanceText(facts.provenance)}.`,
+  ].join("\n")
+  const fence = fenceFor(call)
+  const lines = [
+    `Send this ${facts.mode === "oneway" ? "oneway call" : "update call"} to the Internet Computer?`,
+    "",
+    fence,
+    call,
+    fence,
+  ]
+  if (facts.mode === "oneway") {
+    lines.push(
+      "",
+      "A oneway method sends no reply, so the server cannot tell whether it ran."
+    )
+  }
+  lines.push("", "Nothing is sent unless you tick “Send this call” and accept.")
+  return lines.join("\n")
+}
+
+/**
+ * A backtick fence longer than any run of backticks that starts a line of
+ * `text` (after up to three spaces), so that no line of it closes the fence.
+ */
+function fenceFor(text: string): string {
+  let longest = 0
+  for (const match of text.matchAll(/^ {0,3}(`+)/gm)) {
+    longest = Math.max(longest, match[1]?.length ?? 0)
+  }
+  return "`".repeat(Math.max(3, longest + 1))
+}
+
+/** Where an interface came from, in a few words. */
+export function provenanceText(provenance: InterfaceProvenance): string {
+  switch (provenance.kind) {
+    case "metadata":
+      return provenance.moduleHash === null
+        ? "the canister's certified candid:service metadata"
+        : `the certified candid:service metadata of module ${provenance.moduleHash}`
+    case "tmp_hack":
+      return `the canister's own uncertified answer to __get_candid_interface_tmp_hack (its candid:service metadata is ${provenance.reason === "absent" ? "absent" : "readable by its controllers only"})`
+    case "file":
+      return `the .did file ${provenance.path}, given with --did and not checked against the canister`
+  }
+}
+
+export type ApprovalOutcome =
+  | { readonly approved: true }
+  | { readonly approved: false; readonly reason: string }
+
+/** Asks the person through the client, and says whether they approved. Never throws. */
+export async function askApproval(
+  ctx: ServerContext,
+  message: string,
+  timeoutMs: number = APPROVAL_TIMEOUT_MS
+): Promise<ApprovalOutcome> {
+  let result
+  try {
+    result = await ctx.mcpReq.elicitInput(
+      { mode: "form", message, requestedSchema: APPROVAL_SCHEMA },
+      { timeout: timeoutMs, signal: ctx.mcpReq.signal }
+    )
+  } catch (error) {
+    return {
+      approved: false,
+      reason: `the approval was not answered (${error instanceof Error ? error.message : String(error)})`,
+    }
+  }
+  switch (result.action) {
+    case "accept":
+      return result.content?.["approve"] === true
+        ? { approved: true }
+        : {
+            approved: false,
+            reason:
+              "the person accepted the form without ticking “Send this call”",
+          }
+    case "decline":
+      return { approved: false, reason: "the person declined it" }
+    default:
+      return { approved: false, reason: "the person closed the request" }
+  }
+}

package/packages/mcp/src/server/naming.ts

@@ -0,0 +1,43 @@
+// Tool names for the methods of listed canisters: `<name>_<method>`.
+//
+// A Candid method name can be any text, and MCP clients put the server's name
+// in front of a tool's (`mcp__<server>__<tool>`) under a 64-character limit,
+// so a name that is not plain or is long gets a short hash of the method in
+// place of its tail. The same canisters and methods always give the same names.
+import { createHash } from "node:crypto"
+
+/** The longest tool name written, leaving room for a client's prefix. */
+export const MAX_TOOL_NAME = 40
+
+const PLAIN = /^[A-Za-z0-9_-]+$/
+
+/**
+ * A tool name for each (canister name, method) pair, unique among them and
+ * against `taken`, in the order given.
+ */
+export function toolNames(
+  pairs: readonly { readonly canister: string; readonly method: string }[],
+  taken: Iterable<string>
+): string[] {
+  const used = new Set(taken)
+  return pairs.map(({ canister, method }) => {
+    const raw = `${canister}_${method}`
+    const safe = raw.replace(/[^A-Za-z0-9_-]/g, "_")
+    let name =
+      PLAIN.test(raw) && raw.length <= MAX_TOOL_NAME && !used.has(raw)
+        ? raw
+        : hashed(safe, `${canister}\0${method}`)
+    // A hashed name that is still taken (a method named like another's hash)
+    // gets another hash until it is free.
+    for (let extra = 0; used.has(name); extra += 1) {
+      name = hashed(safe, `${canister}\0${method}\0${extra}`)
+    }
+    used.add(name)
+    return name
+  })
+}
+
+function hashed(base: string, key: string): string {
+  const digest = createHash("sha256").update(key, "utf8").digest("hex")
+  return `${base.slice(0, MAX_TOOL_NAME - 9)}_${digest.slice(0, 8)}`
+}

package/packages/mcp/src/server/results.ts

@@ -0,0 +1,102 @@
+// What a tool call answers: text for the model, cut to a size it can read,
+// and errors that say whether a write may have run.
+import { isReactorError } from "@ic-reactor/core"
+import type { AnyFieldSchema } from "@meantjs/schema"
+import type { CallToolResult } from "@modelcontextprotocol/server"
+import { valueToJson, type Json } from "../candid/json.ts"
+
+/** The most characters of text one tool result carries. */
+export const MAX_RESULT_CHARS = 60_000
+
+export function textResult(
+  text: string,
+  options: { readonly isError?: boolean; readonly maxChars?: number } = {}
+): CallToolResult {
+  return {
+    content: [
+      { type: "text", text: cut(text, options.maxChars ?? MAX_RESULT_CHARS) },
+    ],
+    ...(options.isError === true ? { isError: true } : {}),
+  }
+}
+
+export const errorResult = (text: string): CallToolResult =>
+  textResult(text, { isError: true })
+
+/** `text`, or its first `max` characters and a line that says how much was cut. */
+export function cut(text: string, max: number): string {
+  if (text.length <= max) return text
+  // Never end on half of a surrogate pair.
+  const end = isHighSurrogate(text.charCodeAt(max - 1)) ? max - 1 : max
+  return `${text.slice(0, end)}\n… cut here: the whole text is ${text.length} characters. Ask for less, such as a smaller page.`
+}
+
+const isHighSurrogate = (code: number): boolean =>
+  code >= 0xd800 && code <= 0xdbff
+
+export const jsonText = (json: Json): string => JSON.stringify(json, null, 2)
+
+/**
+ * A reply as JSON. The client resolves a method whose one result is an
+ * Ok/Err variant with the Ok payload, so `okSchema` is that payload's schema
+ * then; otherwise the reply is `undefined` (no results), the value (one), or
+ * an array of values (several).
+ */
+export function replyJson(
+  results: readonly AnyFieldSchema[],
+  okSchema: AnyFieldSchema | undefined,
+  reply: unknown
+): Json {
+  if (okSchema !== undefined) return valueToJson(okSchema, reply)
+  if (results.length === 0) return null
+  if (results.length === 1) return valueToJson(results[0], reply)
+  const values = Array.isArray(reply) ? reply : []
+  return results.map((schema, i) => valueToJson(schema, values[i]))
+}
+
+/**
+ * Why a call failed, for the model: the canister's Err as JSON, or the
+ * client's reason, and for a write whether it may have run.
+ */
+export function failureText(
+  error: unknown,
+  write: boolean,
+  errSchema: AnyFieldSchema | undefined
+): string {
+  if (!isReactorError(error)) {
+    const reason = error instanceof Error ? error.message : String(error)
+    return write
+      ? `The call failed: ${reason}. It may have run: check the canister's state before you send it again.`
+      : `The call failed: ${reason}`
+  }
+  const reason = error.message.replace(/^\[ic-reactor\] /, "")
+  if (error.kind === "canister_err") {
+    const err =
+      errSchema === undefined
+        ? String(error.err)
+        : jsonText(valueToJson(errSchema, error.err))
+    return `The canister ran the call and answered Err:\n${err}`
+  }
+  const lines = [`${KIND_TEXT[error.kind]}: ${reason}`]
+  if (error.rejectCode !== undefined) {
+    lines.push(`Reject code: ${error.rejectCode}`)
+  }
+  if (write) {
+    lines.push(
+      error.mayHaveExecuted
+        ? "It may have run: check the canister's state before you send it again."
+        : "It did not run."
+    )
+  }
+  return lines.join("\n")
+}
+
+const KIND_TEXT: Record<string, string> = {
+  invalid_args: "Not sent: the arguments do not fit the method",
+  unauthenticated: "Not sent: this server has no identity to sign with",
+  not_delivered: "Not delivered",
+  outcome_unknown: "No answer",
+  rejected: "The canister rejected the call",
+  invalid_reply: "The reply could not be read",
+  cancelled: "Cancelled",
+}