@capacms/mcp 0.2.0

package/bin/capa-mcp.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * capa-mcp — stdio MCP server for Capa. Mostly reads; two tools write.
+ *
+ * Usage (Claude Code / Codex / any MCP client), on Node 20 or later:
+ *   CAPA_API_URL=https://api.capacms.com \   # or CAPA_BASE_URL
+ *   CAPA_KEY=<tenant api key> \              # or CAPA_API_KEY
+ *   CAPA_TENANT_ID=<tenant id> \             # legacy pk_/sk_ keys only
+ *   CAPA_API_VERSION=2026-10-01 \            # optional
+ *     npx -y @capacms/mcp
+ *
+ * From a checkout of this repository, `node packages/mcp/bin/capa-mcp.mjs`
+ * runs the same server.
+ *
+ * A `cap_` key needs no tenant id: `/api/` resolves the tenant from the key,
+ * and the mounts that read `X-Tenant-Key` are the ones a `cap_` key is refused
+ * on anyway.
+ *
+ * THE TOOL LIST DEPENDS ON THE KEY, and is decided once, here, before the
+ * loop starts. A `cap_` key gets the `/api/` tools it holds the scopes for; a
+ * `pk_`/`sk_` key gets those plus every legacy tool. The GraphQL tools need
+ * only some `instance:read` scope, a one-model key's included, and
+ * `capa_explain_error` is offline and always there. `lib/registry.mjs` carries
+ * the rule and the reason. README.md lists what each tool answers.
+ *
+ * Still absent rather than stubbed: tools that edit or publish CONTENT. They
+ * want their own shaping against the write surface, and a tool that always
+ * fails teaches an agent to stop trying.
+ */
+import { createInterface } from "node:readline";
+import { loadConfig } from "../lib/client.mjs";
+import { loadMe, probeGraphQL, probePages, probeRestOnly, scopeNote, selectTools } from "../lib/registry.mjs";
+import { createSession } from "../lib/session.mjs";
+
+// Every request is bounded with AbortSignal.any (Node 20.3), and Node 18's
+// fetch tried only ::1 for localhost, so an API listening on IPv4 looked down.
+if (typeof AbortSignal.any !== "function") {
+  process.stderr.write(`capa-mcp: needs Node 20 or later (20.3 at least); this is Node ${process.versions.node}.\n`);
+  process.exit(1);
+}
+
+let config;
+try {
+  config = loadConfig();
+} catch (e) {
+  process.stderr.write(String(e.message) + "\n");
+  process.exit(1);
+}
+
+// One `/api/me` call, before any client message is read. It is what turns the
+// key's family and scopes into the advertised list, and a client reads that
+// list once at startup — deciding later would mean advertising tools and then
+// changing our mind about them mid-session.
+const [me, pages, graphql, restOnly] = await Promise.all([loadMe(config), probePages(config), probeGraphQL(config), probeRestOnly(config)]);
+if (!me.ok) process.stderr.write(`capa-mcp: ${me.reason}\n`);
+// Only an answering /api/ says anything about its features: without one, every /api/ tool registers and reports the real error.
+const deployment = { pages: me.ok ? pages : null, graphql: me.ok ? graphql : null, restOnly };
+if (deployment.pages === false) {
+  process.stderr.write("capa-mcp: this deployment does not serve /api/pages (CAPA_SITE_PREVIEW is off), so the page tools are not registered.\n");
+}
+const tools = selectTools(config, me.me, deployment);
+const scoped = scopeNote(config, me.me, deployment);
+if (scoped) process.stderr.write(`${scoped}\n`);
+if (deployment.graphql === false) {
+  const instead = tools.some((tool) => tool.name === "capa_read_entries") ? " capa_read_entries reads the same entries over REST instead." : "";
+  process.stderr.write(`capa-mcp: this deployment does not serve /api/graphql (CAPA_API_GRAPHQL is off), so the GraphQL tools are not registered.${instead}\n`);
+}
+if (deployment.graphql !== false && restOnly.length && tools.some((tool) => tool.name === "capa_read_entries")) {
+  process.stderr.write(`capa-mcp: GraphQL leaves out ${restOnly.join(", ")} (their type names collide), so capa_read_entries is registered to read them over REST.\n`);
+}
+const ctx = { config: me.apiMissing ? { ...config, apiMissing: true } : config, tools };
+
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+const session = createSession(ctx, {
+  write: (message) => process.stdout.write(JSON.stringify(message) + "\n"),
+  log: (text) => process.stderr.write(`${text}\n`),
+});
+rl.on("line", session.receive);
+
+// Drain before exiting. `close` fires as soon as stdin ends, which for a piped
+// or scripted client is right after the last line, while a call may still be
+// mid-fetch: exiting there would leave it unanswered, with nothing on stderr.
+// A long-lived client holds stdin open, so only a pipe meets this.
+rl.on("close", async () => {
+  try {
+    await session.drain();
+  } catch (e) {
+    process.stderr.write(`capa-mcp: drain failed: ${String(e?.stack ?? e)}\n`);
+  }
+  // Exit once stdout has flushed, not before. process.exit() drops what stdout
+  // still buffers, and on macOS a write to a pipe is asynchronous: the answer
+  // to one tools/list came back cut at 8,192 bytes ("Unterminated string in
+  // JSON at position 8192", graphql-tools.test.mjs on Node 22.13). The empty
+  // write's callback runs after every earlier write has gone out.
+  process.stdout.write("", () => process.exit(0));
+});

package/lib/annotations.mjs

@@ -0,0 +1,27 @@
+/**
+ * annotations.mjs — what a client may know about a tool before it calls it.
+ *
+ * MCP tool annotations (protocol 2025-03-26 and later): whether the tool only
+ * reads, whether a write can replace what is there, and whether calling it
+ * twice with the same arguments changes anything more. A client uses them to
+ * run reads without asking and to confirm before a write. Every tool here
+ * talks to this Capa deployment and nothing else, so none is open-world.
+ *
+ * `title` is the name a client shows a person. It is set at the top level
+ * (2025-06-18) and inside `annotations` (2025-03-26), which is where the
+ * older protocol reads it.
+ */
+
+/** A tool that changes nothing. */
+export function reads(title) {
+  return { title, annotations: { title, readOnlyHint: true, openWorldHint: false } };
+}
+
+/**
+ * A tool that writes. `idempotent`: the same arguments a second time leave
+ * the same result. Every writer here can replace what is there, so each is
+ * destructive.
+ */
+export function writes(title, { idempotent }) {
+  return { title, annotations: { title, readOnlyHint: false, destructiveHint: true, idempotentHint: idempotent, openWorldHint: false } };
+}

package/lib/answers.mjs

@@ -0,0 +1,69 @@
+/**
+ * answers.mjs — what every `/api/` tool's answer shares: the keys its output
+ * schema allows, the answer budget it takes, and what it says about the key
+ * that read it.
+ *
+ * Output schemas are for a client that reads results as data
+ * (`structuredContent`). Every key an answer can carry is listed and no other
+ * is allowed, so a key added to an answer and not to its schema fails the
+ * test that checks real answers against these. A description only where the
+ * name does not say it.
+ */
+
+/** A tool that bounds its own answer, keeping what must never be cut, so the server does not cut it again (server.mjs). */
+export const BOUNDED = { bounded: true };
+
+/** The `maxChars` argument of every tool that answers with content. */
+export const MAX_CHARS = { type: "integer", minimum: 1000, maximum: 100000, description: "Default 20000." };
+
+/** What boundAnswer adds to a cut answer, or answers in its place (lib/bound.mjs). */
+const CUT_KEYS = {
+  truncated: { type: "array" },
+  truncatedMore: { type: "integer" },
+  clipped: { type: "array" },
+  clippedMore: { type: "integer" },
+  hint: { type: "string" },
+  note: { type: "string" },
+};
+/** A name the key's schema does not have, or a spec it cannot build, refused in band. */
+const REFUSAL_KEYS = {
+  error: { type: "string" },
+  didYouMean: { type: "array" },
+  available: { type: "array" },
+  next: { type: "string" },
+};
+/** What an answer the API ran says about the key that read it (`readWith`). */
+export const READ_WITH_KEYS = { environment: { type: "string" }, drafts: { type: "string" }, notFound: { type: "string" } };
+
+/** An output schema: `properties` beside the keys every answer may carry. */
+export const answerSchema = (properties) => ({
+  type: "object",
+  properties: { ...REFUSAL_KEYS, ...CUT_KEYS, ...properties },
+  additionalProperties: false,
+});
+
+/** What a development key's answer says: it holds what a site does not show. */
+export const DRAFTS_NOTE = "A development key reads drafts and unpublished changes; a production key reads published entries only.";
+
+/**
+ * What an answer says about the key that read it: `environment`, and for a
+ * development key the one line that the entries include drafts, so an agent
+ * never describes a draft title as what the site shows. For a production key,
+ * a root field of `data` that reads one entry and answered null
+ * (`data.article`, with no error of its own) could be a wrong id or a
+ * draft-only entry, and the answer says so.
+ */
+export function readWith(environment, data, errors = []) {
+  if (!environment) return {};
+  if (environment === "development") return { environment, drafts: DRAFTS_NOTE };
+  const unread = new Set(errors.map((e) => e.path?.[0]));
+  const missing = Object.entries(data ?? {})
+    .filter(([key, value]) => value === null && !unread.has(key))
+    .map(([key]) => key);
+  if (!missing.length) return { environment };
+  const names = missing.length === 1 ? `${missing[0]} is` : `${missing.slice(0, -1).join(", ")} and ${missing.at(-1)} are`;
+  return {
+    environment,
+    notFound: `${names} null: no entry this key reads has that id. A production key reads published entries only, so an entry that exists only as a draft reads as null too.`,
+  };
+}

package/lib/arguments.mjs

@@ -0,0 +1,140 @@
+/**
+ * arguments.mjs — check a tool call's arguments against the tool's own
+ * `inputSchema` before the handler sees them.
+ *
+ * A model that misspells an argument (`frist`, `filters`) must hear about it.
+ * Without this check the handler reads only the keys it knows, the typo is
+ * dropped, and a query runs unfiltered while the answer says it worked.
+ *
+ * The subset of JSON Schema checked is the subset these tools declare: `type`
+ * (one or several), `enum`, `required`, `properties`, `additionalProperties:
+ * false`, `items`, `anyOf`, `minimum`, `maximum`, `minLength`, `minItems` and
+ * `maxItems`. A keyword outside it is ignored rather than guessed at.
+ */
+import { didYouMean } from "./suggest.mjs";
+
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+
+function matchesType(value, type) {
+  const actual = typeOf(value);
+  return actual === type || (type === "number" && actual === "integer");
+}
+
+const label = (path) => path || "the arguments";
+
+/**
+ * Names one tool of this server takes for what another calls by a different
+ * name, and the words REST uses for GraphQL's arguments: an agent that learnt
+ * `model` from the GraphQL tools, or `limit` from a REST URL, is pointed at
+ * the name this tool takes, which edit distance cannot find.
+ */
+const SYNONYMS = {
+  model: ["namespace", "modelId"],
+  namespace: ["model", "modelId"],
+  modelId: ["model", "namespace"],
+  limit: ["first"],
+  first: ["limit"],
+  where: ["filter"],
+  filter: ["where"],
+  select: ["fields"],
+  fields: ["select"],
+  orderBy: ["sort"],
+  order: ["sort"],
+  cursor: ["after"],
+  q: ["query"],
+  query: ["q"],
+};
+
+/** The allowed names nearest `key`: by spelling, then by meaning. */
+function nearestNames(key, allowed) {
+  const near = didYouMean(key, allowed);
+  for (const synonym of SYNONYMS[key] ?? []) if (allowed.includes(synonym) && !near.includes(synonym)) near.push(synonym);
+  return near;
+}
+
+/** A short description of what a schema accepts, for an `anyOf` refusal. */
+function describe(schema) {
+  if (schema.type === "object" && schema.properties) return `an object with ${Object.keys(schema.properties).join(", ")}`;
+  return Array.isArray(schema.type) ? schema.type.join(" or ") : schema.type ?? "a value";
+}
+
+/** The first problem with `value` under `schema`, as a sentence, or null. */
+function check(schema, value, path) {
+  if (!schema || typeof schema !== "object") return null;
+
+  if (schema.anyOf) {
+    if (schema.anyOf.some((option) => check(option, value, path) === null)) return null;
+    // One option of the right type explains the failure better than a list.
+    const sameType = schema.anyOf.filter((option) => option.type && matchesType(value, option.type));
+    if (sameType.length === 1) return check(sameType[0], value, path);
+    return `${label(path)} must be ${schema.anyOf.map(describe).join(", or ")}.`;
+  }
+
+  if (schema.type) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((type) => matchesType(value, type))) {
+      return `${label(path)} must be ${types.join(" or ")}, not ${typeOf(value)}.`;
+    }
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    return `${label(path)} must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}.`;
+  }
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum) return `${label(path)} must be at least ${schema.minimum}.`;
+    if (schema.maximum !== undefined && value > schema.maximum) return `${label(path)} must be at most ${schema.maximum}.`;
+  }
+  if (typeof value === "string" && schema.minLength !== undefined && value.length < schema.minLength) {
+    return schema.minLength === 1 ? `${label(path)} must not be empty.` : `${label(path)} must be at least ${schema.minLength} characters.`;
+  }
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) return `${label(path)} needs at least ${schema.minItems} items.`;
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) return `${label(path)} takes at most ${schema.maxItems} items.`;
+    if (schema.items) {
+      for (let i = 0; i < value.length; i++) {
+        const problem = check(schema.items, value[i], `${path}[${i}]`);
+        if (problem) return problem;
+      }
+    }
+  }
+  if (typeOf(value) === "object") return checkObject(schema, value, path);
+  return null;
+}
+
+function checkObject(schema, value, path) {
+  const properties = schema.properties ?? {};
+  const allowed = Object.keys(properties);
+  const where = path ? ` in ${path}` : "";
+  if (schema.additionalProperties === false) {
+    for (const key of Object.keys(value)) {
+      if (Object.hasOwn(properties, key)) continue;
+      const near = nearestNames(key, allowed);
+      return (
+        `Unknown argument ${key}${where}.` +
+        (near.length ? ` Did you mean ${near.join(" or ")}?` : "") +
+        ` Allowed: ${allowed.join(", ") || "none"}.`
+      );
+    }
+  }
+  for (const key of schema.required ?? []) {
+    if (value[key] === undefined) return `Missing argument ${key}${where}.`;
+  }
+  for (const key of allowed) {
+    if (value[key] === undefined) continue;
+    const problem = check(properties[key], value[key], path ? `${path}.${key}` : key);
+    if (problem) return problem;
+  }
+  return null;
+}
+
+/**
+ * `null` when `args` satisfies `schema`, else one sentence naming the first
+ * problem and the fix. `args` of `null` or `undefined` is checked as `{}`.
+ */
+export function checkArguments(schema, args) {
+  return check(schema, args ?? {}, "");
+}