@capacms/mcp 0.2.0

package/lib/rest-tools.mjs

@@ -0,0 +1,176 @@
+/**
+ * rest-tools.mjs — reading entries over REST, where GraphQL does not.
+ *
+ * `CAPA_API_GRAPHQL=off` takes `/api/graphql` away and leaves `/api/entries`
+ * serving, so a key that reads content still can. The GraphQL tools are not
+ * registered there (registry.mjs), and without this tool an assistant would
+ * lose every read for as long as GraphQL is off. It is registered then, and
+ * where GraphQL leaves some of the key's models out (N1: their type names
+ * collide), for those. Elsewhere capa_graphql_build writes the same REST read
+ * and checks it, and a second way to read would only cost context.
+ *
+ * It takes REST's parameters as docs/api/entries.md writes them and passes
+ * them through, so the API's own grammar, limits and refusals apply. The
+ * answer is bounded like every other (lib/bound.mjs), and a cut page stays
+ * pageable: its `next` is null, with how to read on, since the uncut page's
+ * cursor would skip every entry cut.
+ */
+import { reads } from "./annotations.mjs";
+import { answerSchema, BOUNDED, MAX_CHARS, READ_WITH_KEYS, readWith } from "./answers.mjs";
+import { boundAnswer, DEFAULT_MAX_CHARS } from "./bound.mjs";
+import { apiNextGet, CapaApiError } from "./client.mjs";
+import { didYouMean } from "./suggest.mjs";
+
+/** What a cut read tells the agent. */
+const READ_HINT = "Pass select for fewer fields, or a smaller limit.";
+/** How to use the tool, whichever reason it is registered for. */
+const USAGE =
+  "With model: a page of entries, or one entry by id. select, where, sort, limit, after, before and " +
+  'count take REST\'s grammar, e.g. select "title,author(name)", where { "views": { "gte": 10 } }, sort ["-views"]; ' +
+  "follow page.next with after. A large answer is cut from the end and says where; a cut page's next is null, with " +
+  "how to read on. capa_explain_error explains a refusal.";
+/** The parameters that read a list, which a read of one entry by id does not take. */
+const LIST_PARAMETERS = ["where", "sort", "limit", "after", "before", "count"];
+
+/** Encoded as the API prints a REST request: commas, colons and a system key's `$` stay readable. */
+const encode = (value) => encodeURIComponent(value).replace(/%2C/g, ",").replace(/%3A/g, ":").replace(/%24/g, "$");
+
+/** The REST request `args` make: its path, its parameters in the API's order, and the two as one URL. */
+export function restRead(args) {
+  const path = `/api/entries/${encodeURIComponent(args.model)}${args.id === undefined ? "" : `/${encodeURIComponent(args.id)}`}`;
+  const params = [];
+  if (args.select !== undefined) params.push(["select", args.select]);
+  if (args.where !== undefined) params.push(["where", JSON.stringify(args.where)]);
+  if (args.sort !== undefined) params.push(["sort", Array.isArray(args.sort) ? args.sort.join(",") : args.sort]);
+  if (args.limit !== undefined) params.push(["limit", String(args.limit)]);
+  if (args.after !== undefined) params.push(["after", args.after]);
+  if (args.before !== undefined) params.push(["before", args.before]);
+  if (args.count) params.push(["count", "true"]);
+  const url = params.length ? `${path}?${params.map(([key, value]) => `${key}=${encode(value)}`).join("&")}` : path;
+  return { path, params, url };
+}
+
+/** A REST page's cursor keys, read forward (`next`) or back (`prev`), as bound.mjs repairs a connection's. */
+const pageKeys = (backward) =>
+  backward
+    ? { hasNextPage: [], hasPreviousPage: ["hasPrev"], startCursor: ["prev"], endCursor: [] }
+    : { hasNextPage: ["hasNext"], hasPreviousPage: [], startCursor: [], endCursor: ["next"] };
+
+/**
+ * The pages in a REST answer, keyed by where each sits, for boundAnswer: the
+ * entry list itself (`data`, with `page`), and every expanded relation list
+ * (`{ items, pageInfo }`) inside it. A cut one gets its `next` set to null,
+ * with how to read on in REST's words.
+ */
+export function restPages(answer, { backward = false } = {}) {
+  const pages = {};
+  if (Array.isArray(answer.data)) {
+    pages[""] = {
+      nodes: ["data"],
+      edges: [],
+      pageInfo: [{ key: "page", fields: pageKeys(backward) }],
+      backward,
+      resume: (kept) =>
+        backward
+          ? `page.prev is null because entries were cut; the uncut page's would skip them. Read again with limit: ${kept} and the same before for a prev before the first entry shown.`
+          : `page.next is null because entries were cut; the uncut page's would skip them. Read again with limit: ${kept} for a next after the last entry shown.`,
+    };
+  }
+  const walk = (value, shape) => {
+    if (Array.isArray(value)) {
+      for (const item of value) walk(item, shape);
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value.items) && value.pageInfo && typeof value.pageInfo === "object") {
+      pages[shape] = {
+        nodes: ["items"],
+        edges: [],
+        pageInfo: [{ key: "pageInfo", fields: pageKeys(false) }],
+        backward: false,
+        resume: (kept) =>
+          `pageInfo.next is null because items were cut; the uncut list's would skip them. Read the entry again with limit:${kept} on this relation for a next after the last item shown.`,
+      };
+    }
+    for (const [key, inner] of Object.entries(value)) walk(inner, shape ? `${shape}.${key}` : key);
+  };
+  walk(answer.data, "data");
+  return pages;
+}
+
+/** The models this key reads, from `/api/me`, or null where the deployment does not list them (`CAPA_KEY_SCOPES=off`). */
+async function readableModels(config) {
+  const { data } = await apiNextGet(config, "/api/me");
+  if (!Array.isArray(data?.models)) return { environment: data?.environment, models: null };
+  const models = data.models.filter((m) => m.can?.includes("read")).map((m) => m.namespace);
+  return { environment: data.environment, models };
+}
+
+export const REST_TOOLS = [
+  {
+    name: "capa_read_entries",
+    ...reads("Read entries over REST"),
+    ...BOUNDED,
+    surface: "api",
+    scopePrefix: "instance:read",
+    // Registered where the deployment serves no GraphQL, or where GraphQL leaves models out (registry.mjs).
+    whenOff: "graphql",
+    description: `Read entries over REST (GET /api/entries/<model>): this deployment serves no GraphQL. Without model: the models this key reads. ${USAGE}`,
+    /** The description where GraphQL is served and leaves models out, which this tool is then registered to read. */
+    besideGraphQL:
+      "Read entries over REST (GET /api/entries/<model>) of the models GraphQL leaves out, which capa_graphql_schema " +
+      `lists as readable over REST only; read every other model with capa_graphql_build. ${USAGE}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        model: { type: "string", description: 'Namespace, e.g. "articles".' },
+        id: { type: "string", description: "Entry UUID: reads one entry." },
+        select: { type: "string" },
+        where: { type: "object" },
+        sort: { type: ["string", "array"], items: { type: "string" } },
+        limit: { type: "integer", minimum: 1, maximum: 200 },
+        after: { type: "string" },
+        before: { type: "string" },
+        count: { type: "boolean" },
+        maxChars: MAX_CHARS,
+      },
+      additionalProperties: false,
+    },
+    outputSchema: answerSchema({
+      models: { type: "array", items: { type: "string" } },
+      data: { type: ["array", "object"] },
+      page: { type: "object", description: "limit, hasNext, next, hasPrev, prev, and total with count." },
+      rest: { type: "string", description: "The request read." },
+      ...READ_WITH_KEYS,
+    }),
+    handler: async (config, args) => {
+      if (args.model === undefined) {
+        const { environment, models } = await readableModels(config);
+        if (!models) {
+          return { error: "This deployment does not list the models a key reads (CAPA_KEY_SCOPES is off). Pass model with a namespace from the Capa admin." };
+        }
+        return { models, ...readWith(environment), next: "Pass model to read its entries." };
+      }
+      if (args.id !== undefined) {
+        const listOnly = LIST_PARAMETERS.filter((key) => args[key] !== undefined);
+        if (listOnly.length) return { error: `id reads one entry, so ${listOnly.join(", ")} do not apply: leave id out to list entries.` };
+      }
+      const read = restRead(args);
+      let body;
+      try {
+        body = await apiNextGet(config, read.path, Object.fromEntries(read.params));
+      } catch (error) {
+        if (!(error instanceof CapaApiError) || error.code !== "model_not_found") throw error;
+        // A wrong namespace comes back with the nearest, from the models this key reads.
+        const { models } = await readableModels(config).catch(() => ({ models: null }));
+        if (!models) throw error;
+        return { error: `This key reads no model ${args.model}.`, didYouMean: didYouMean(args.model, models), available: models };
+      }
+      const answer = { data: body.data ?? null };
+      if (body.page) answer.page = body.page;
+      Object.assign(answer, readWith(body.meta?.environment), { rest: read.url });
+      const connections = restPages(answer, { backward: args.before !== undefined });
+      return boundAnswer(answer, args.maxChars ?? DEFAULT_MAX_CHARS, { hint: READ_HINT, connections });
+    },
+  },
+];

package/lib/server.mjs

@@ -0,0 +1,194 @@
+/**
+ * server.mjs — MCP stdio protocol, implemented directly.
+ *
+ * Newline-delimited JSON-RPC 2.0: one message per line on stdin/stdout, and
+ * LOGS TO STDERR ONLY. A stray console.log on stdout corrupts the stream and
+ * the client sees a parse error rather than anything useful, which is the
+ * single easiest way to break one of these.
+ *
+ * `dispatch` is pure over ({ config, tools }) so the protocol is unit-testable
+ * without wiring real stdio. It returns a response object for requests (those
+ * with an `id`) and `null` for notifications (no `id`) — the caller writes
+ * non-null responses back.
+ *
+ * `ctx.tools` IS THE REGISTERED SET, not every tool that exists. It is computed
+ * once at startup by `selectTools` in registry.mjs, because which tools work
+ * depends on the key's family and scopes. There is deliberately no fallback to
+ * the full list: a caller that forgot to select would otherwise advertise the
+ * legacy tools to a `cap_` key, which is the exact thing the registry exists to
+ * stop, and a loud failure beats a quiet over-advertisement.
+ */
+import { checkArguments } from "./arguments.mjs";
+import { boundAnswer, DEFAULT_MAX_CHARS } from "./bound.mjs";
+import { CapaApiError } from "./client.mjs";
+import { availablePrompts, renderPrompt } from "./prompts.mjs";
+import { availableTemplates, listResources, readResource, ResourceNotFound } from "./resources.mjs";
+import { instructionsFor } from "./instructions.mjs";
+
+const PROTOCOL_VERSION = "2025-06-18";
+const SUPPORTED = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
+
+export const SERVER_INFO = { name: "capa-mcp", version: "0.2.0" };
+
+const ok = (id, result) => ({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
+
+/**
+ * `args` with each of the tool's `aliases` read as the name it stands for:
+ * the legacy tools call a model `namespace` (or `modelId`), and an agent that
+ * learnt `model` from the GraphQL tools is understood. An alias passed beside
+ * its name is left as it is, and refused by the check as the unknown argument
+ * it then is.
+ */
+function withAliases(tool, args) {
+  if (!tool.aliases || !args || typeof args !== "object" || Array.isArray(args)) return args;
+  const out = { ...args };
+  for (const [alias, name] of Object.entries(tool.aliases)) {
+    if (!(alias in out) || name in out) continue;
+    out[name] = out[alias];
+    delete out[alias];
+  }
+  return out;
+}
+
+/**
+ * `config` as a handler gets it: with the call's `signal`, which every
+ * request the call makes honours (client.mjs), so a call the client cancels
+ * stops reaching Capa.
+ */
+const configFor = (ctx, signal) => (signal ? { ...ctx.config, signal } : ctx.config);
+
+async function callTool(ctx, params, signal) {
+  const name = params?.name;
+  const tools = ctx.tools;
+  const tool = name ? tools.find((t) => t.name === name) : undefined;
+  if (!tool) {
+    // Unknown tool is an in-band tool error per MCP, not a protocol error —
+    // the model should see it and pick a different tool, not get a JSON-RPC
+    // failure it cannot reason about.
+    //
+    // The alternatives named are the REGISTERED ones. Listing a tool this key
+    // cannot reach would answer "that one does not exist" with a suggestion
+    // that is equally unusable.
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Unknown tool: ${String(name)}\n` +
+            `Available: ${tools.map((t) => t.name).join(", ")}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+  // Checked against the schema the tool advertised, so a misspelled or
+  // mistyped argument is refused by name instead of silently ignored.
+  const args = withAliases(tool, params.arguments);
+  const problem = checkArguments(tool.inputSchema, args);
+  if (problem) {
+    return { content: [{ type: "text", text: `Invalid arguments for ${name}: ${problem}` }], isError: true };
+  }
+  try {
+    const answer = await tool.handler(configFor(ctx, signal), args ?? {});
+    // Every answer fits its budget and says how to ask for less (lib/bound.mjs),
+    // except a document an agent edits and writes back: a cut copy written back
+    // would lose what was cut. A tool that bounds its own answer (`bounded`) is
+    // not cut again: only it knows which parts are never cut (a built query's
+    // document and REST twin) and how a connection pages on once cut.
+    const data = tool.whole || tool.bounded ? answer : boundAnswer(answer, args?.maxChars ?? DEFAULT_MAX_CHARS, { hint: tool.cutHint });
+    // Compact: indentation is a third of the characters and tells a model nothing.
+    const content = [{ type: "text", text: JSON.stringify(data) }];
+    // A tool with an output schema also answers the object itself, for a
+    // client that reads results as data; the text stays for one that does not.
+    return tool.outputSchema ? { content, structuredContent: data } : { content };
+  } catch (error) {
+    // Same reasoning: an API failure is reported to the MODEL so it can adapt
+    // (retry narrower, pick another tool), rather than surfaced as a transport
+    // error that ends the turn.
+    //
+    // The API's OWN hint wins when there is one. `/api/` answers the fix in
+    // this deployment's real values ("this key needs instance:read"), and
+    // replacing that with the generic sentence below would throw away the only
+    // part of the error a model can act on without guessing.
+    const text =
+      error instanceof CapaApiError
+        ? `${error.message}\n${
+            error.hint ??
+            "(the Capa API rejected this call; a 401 means the key or tenant is wrong, a 404 means the model or id does not exist)"
+          }`
+        : String(error?.message ?? error);
+    return { content: [{ type: "text", text }], isError: true };
+  }
+}
+
+/**
+ * One message's answer. `signal` is the call's own, aborted when the client
+ * cancels it (session.mjs); a message that never reaches Capa has none.
+ */
+export async function dispatch(ctx, msg, { signal } = {}) {
+  const { id, method, params } = msg ?? {};
+  const isNotification = id === undefined || id === null;
+
+  switch (method) {
+    case "initialize": {
+      const asked = params?.protocolVersion;
+      return ok(id, {
+        protocolVersion: SUPPORTED.has(asked) ? asked : PROTOCOL_VERSION,
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        serverInfo: SERVER_INFO,
+        instructions: instructionsFor(ctx.tools),
+      });
+    }
+    case "notifications/initialized":
+      return null;
+    case "ping":
+      return ok(id, {});
+    case "tools/list":
+      return ok(id, {
+        tools: ctx.tools.map(({ name, title, description, inputSchema, outputSchema, annotations }) => ({
+          name,
+          title,
+          description,
+          inputSchema,
+          ...(outputSchema ? { outputSchema } : {}),
+          annotations,
+        })),
+      });
+    case "tools/call":
+      return ok(id, await callTool(ctx, params, signal));
+    case "resources/list":
+      return ok(id, { resources: await listResources(configFor(ctx, signal), ctx.tools) });
+    case "resources/templates/list":
+      return ok(id, {
+        resourceTemplates: availableTemplates(ctx.tools).map(({ uriTemplate, name, description, mimeType }) => ({
+          uriTemplate,
+          name,
+          description,
+          mimeType,
+        })),
+      });
+    case "resources/read": {
+      try {
+        const { resource, text } = await readResource(configFor(ctx, signal), ctx.tools, params?.uri);
+        return ok(id, { contents: [{ uri: resource.uri, mimeType: resource.mimeType, text }] });
+      } catch (error) {
+        // -32002 is MCP's "resource not found".
+        if (error instanceof ResourceNotFound) return fail(id, -32002, error.message);
+        return fail(id, -32603, `Could not read ${String(params?.uri)}: ${String(error?.message ?? error)}`);
+      }
+    }
+    case "prompts/list":
+      return ok(id, {
+        prompts: availablePrompts(ctx.tools).map(({ name, description, arguments: args }) => ({ name, description, arguments: args })),
+      });
+    case "prompts/get": {
+      const rendered = renderPrompt(params?.name, params?.arguments ?? {}, ctx.tools);
+      // -32602: invalid params, which an unknown name or a missing argument is.
+      return rendered.error ? fail(id, -32602, rendered.error) : ok(id, rendered);
+    }
+    default:
+      if (isNotification) return null;
+      return fail(id, -32601, `Method not found: ${String(method)}`);
+  }
+}

package/lib/session.mjs

@@ -0,0 +1,90 @@
+/**
+ * session.mjs — one client's stream of messages: which wait their turn, which
+ * answer at once, and which the client called off.
+ *
+ * A message that reaches Capa (a tool that calls the API, a resource) waits
+ * for the one before it: those share the schema cache, and an agent's calls
+ * come one after another anyway. Everything else answers at once, beside a
+ * call in flight: `ping`, `initialize`, the lists and prompts, and a tool that
+ * answers offline (`capa_explain_error`). A client pings to see whether the
+ * server is alive, and one call to a slow host must not make it look dead.
+ *
+ * `notifications/cancelled` aborts the call it names, running or still
+ * waiting, and that call is never answered, as MCP requires: the client has
+ * stopped listening for it.
+ */
+import { dispatch } from "./server.mjs";
+
+/** Whether answering `msg` reaches Capa: a registered tool that is not offline, or a resource. */
+function reachesCapa(ctx, msg) {
+  if (msg.method === "resources/list" || msg.method === "resources/read") return true;
+  if (msg.method !== "tools/call") return false;
+  const tool = ctx.tools.find((t) => t.name === msg.params?.name);
+  return Boolean(tool) && tool.surface !== "local";
+}
+
+/**
+ * `receive(line)` takes one line of the stream; `write(message)` sends an
+ * answer; `log(text)` reports to the person running the server (stderr).
+ * `drain()` settles once every message received so far has been answered or
+ * called off.
+ */
+export function createSession(ctx, { write, log }) {
+  let turn = Promise.resolve();
+  const unsettled = new Set();
+  /** The call each request id names, while it waits or runs. */
+  const calls = new Map();
+
+  const track = (promise) => {
+    unsettled.add(promise);
+    promise.finally(() => unsettled.delete(promise));
+  };
+
+  const answer = async (msg, signal) => {
+    try {
+      const res = await dispatch(ctx, msg, { signal });
+      if (res && !signal?.aborted) write(res);
+    } catch (error) {
+      // A handler bug must not end the stream: the client would wait forever.
+      log(`capa-mcp: dispatch threw: ${String(error?.stack ?? error)}`);
+      if (!signal?.aborted && msg.id !== undefined && msg.id !== null) {
+        write({ jsonrpc: "2.0", id: msg.id, error: { code: -32603, message: "Internal error" } });
+      }
+    }
+  };
+
+  const receive = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      log(`capa-mcp: unparseable line ignored: ${trimmed.slice(0, 120)}`);
+      return;
+    }
+    if (msg?.method === "notifications/cancelled") {
+      calls.get(msg.params?.requestId)?.abort();
+      return;
+    }
+    if (!reachesCapa(ctx, msg ?? {})) {
+      track(answer(msg));
+      return;
+    }
+    const call = new AbortController();
+    const id = msg.id;
+    if (id !== undefined && id !== null) calls.set(id, call);
+    const run = turn.then(async () => {
+      if (!call.signal.aborted) await answer(msg, call.signal);
+      if (calls.get(id) === call) calls.delete(id);
+    });
+    turn = run;
+    track(run);
+  };
+
+  const drain = async () => {
+    while (unsettled.size) await Promise.allSettled([...unsettled]);
+  };
+
+  return { receive, drain };
+}

package/lib/suggest.mjs

@@ -0,0 +1,32 @@
+/**
+ * suggest.mjs — "did you mean": the names nearest a misspelled one.
+ *
+ * Shared by the query builder (a field, model or sort value) and the tool
+ * argument check (an argument name), so a typo gets the same answer wherever
+ * an agent makes it.
+ */
+
+function levenshtein(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let previous = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const current = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+      previous = current;
+    }
+  }
+  return row[b.length];
+}
+
+/** Names within two edits of `wanted`, nearest first then by name, at most three. */
+export function didYouMean(wanted, candidates) {
+  const needle = String(wanted).toLowerCase();
+  return [...new Set(candidates)]
+    .map((name) => ({ name, distance: levenshtein(needle, name.toLowerCase()) }))
+    .filter((c) => c.distance <= 2)
+    .sort((a, b) => a.distance - b.distance || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+    .slice(0, 3)
+    .map((c) => c.name);
+}