@capacms/mcp 0.2.1 → 0.3.0

package/lib/entry-tools.mjs

@@ -0,0 +1,425 @@
+/**
+ * entry-tools.mjs — writing entries, through `/v2/agent/model-instances`.
+ *
+ * The content half of the agent surface. `DESIGN.md` kept these out until
+ * they had a shape of their own, and the shape is this:
+ *
+ *   - A write is a DRAFT. `capa_create_entry` and `capa_update_entry` never
+ *     publish, whatever the key may do: what a site shows changes only when
+ *     something publishes, and that is a separate act with its own scope.
+ *   - An entry is named by its id and a model by its namespace, the words the
+ *     read tools answer with, so a read's answer feeds a write unchanged.
+ *   - `data` is flat, `{ "<field namespace>": <value> }`, as the API takes it.
+ *     The API stores each value as `{ type, value, sortOrder }`; the answer
+ *     unwraps them, so an agent reads back what it wrote.
+ *   - A key of `data` the model has no field for is refused before anything
+ *     is written. The API builds what it stores from the model's own fields,
+ *     so it drops such a key without a word and answers 200: a misspelt
+ *     `titel` saved an identical version and read as a success. The check
+ *     needs the model's fields, so a key without model:read (or, for an
+ *     update, without instance:read) writes unchecked, and the answer says so.
+ *   - An update MERGES: a field `data` leaves out keeps its value (the API's
+ *     PUT merges). There is no way to clear a field by leaving it out; send
+ *     it with null.
+ *   - A refusal is the API's own words plus the next step, in band, so the
+ *     model fixes the field the API named instead of guessing.
+ *   - Publishing is its own tool, `capa_publish_entry`, with its own scope
+ *     (`instance:publish`), and so is `capa_unpublish_entry`. Both change what
+ *     every visitor reads, so both are marked destructive: a client asks its
+ *     person before each call unless told not to, which is where "what may an
+ *     agent do unattended" is answered, per client and per person.
+ *
+ * All four are `surface: "agent"` and `capOnly`: registered for a `cap_` key
+ * where `/api/me` lists `/v2/agent` and the key holds the scope, and never
+ * for a legacy key, whose tool list stays the one it had before these
+ * existed (registry.mjs).
+ * Any key holding the scope writes, whatever its environment. What the key
+ * READS back differs: a development or draft key reads drafts, so the entry
+ * it just made; a production key reads published entries only, so a draft it
+ * made shows up in its reads once something publishes it. The answer says so.
+ *
+ * The names, descriptions and input schemas here are provisional: the tool
+ * calls lane owns them. `@capacms/cli` reads them from this module, so a
+ * rename moves its commands with it.
+ */
+import { writes } from "./annotations.mjs";
+import { apiGet, apiWrite, CapaApiError } from "./client.mjs";
+import { didYouMean } from "./suggest.mjs";
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** A stored value `{ type, value, sortOrder }` as its value; anything else as it is. */
+const unwrap = (v) => (v && typeof v === "object" && !Array.isArray(v) && "value" in v ? v.value : v ?? null);
+
+/** The model's fields, by namespace, which is how `data` names them. */
+const FIELD_HINT = "capa_get_model { namespace } lists the model's fields: their namespaces, types and which are required.";
+
+/** What a write answers when the model's fields could not be read, so `data`'s names went unchecked. */
+const UNCHECKED =
+  "The field names in data were not checked: reading the model's fields takes model:read (and instance:read for an " +
+  "update), which this key lacks. The API drops a name the model has no field for without saying so: entry.data is " +
+  "what was stored.";
+
+/** A model detail's field namespaces, or null when it lists none to check against. */
+function fieldNamespaces(detail) {
+  if (!Array.isArray(detail?.fields)) return null;
+  return detail.fields.map((f) => f?.namespace).filter((n) => typeof n === "string");
+}
+
+const quoted = (names) => (names.length === 1 ? `"${names[0]}"` : `${names.slice(0, -1).map((n) => `"${n}"`).join(", ")} and "${names.at(-1)}"`);
+
+/**
+ * The refusal for keys of `data` the model has no field for, or null when
+ * every key is a field. Nothing is written: the API would drop them and
+ * answer success.
+ */
+function unknownFields(data, namespaces, model) {
+  const unknown = Object.keys(data ?? {}).filter((key) => !namespaces.includes(key));
+  if (!unknown.length) return null;
+  const near = [...new Set(unknown.flatMap((key) => didYouMean(key, namespaces)))];
+  return {
+    error: `${model ? `The model "${model}"` : "This entry's model"} has no field${unknown.length === 1 ? "" : "s"} ${quoted(unknown)}.`,
+    ...(near.length ? { didYouMean: near } : {}),
+    available: namespaces,
+    next: `Nothing was written. Name each field by a namespace from available and send it again. ${FIELD_HINT}`,
+  };
+}
+
+/**
+ * One entry as a write answers it: the instance row the API sends back,
+ * reduced to what an agent reads next. `status` is the CURRENT version's,
+ * `draft` after every write here; `live` says whether some version is
+ * published, which a draft saved over a published entry leaves in place.
+ */
+/**
+ * A model's namespace from its id, or null. The create and update answers
+ * carry `modelId` only, and an agent reads the entry back by namespace. A key
+ * without model:read, or a model gone since, answers null rather than failing
+ * a write that already succeeded.
+ */
+async function namespaceOf(config, modelId) {
+  if (!modelId) return null;
+  try {
+    const detail = await apiGet(config, `/v2/agent/models/${encodeURIComponent(modelId)}`);
+    return typeof detail?.namespace === "string" ? detail.namespace : null;
+  } catch {
+    return null;
+  }
+}
+
+export function entryOf(row, namespace) {
+  const version = row?.currentVersion ?? null;
+  const stored = version?.data ?? row?.data ?? {};
+  const data = {};
+  for (const [key, value] of Object.entries(stored)) data[key] = unwrap(value);
+  return {
+    id: row?.id ?? null,
+    model: namespace ?? row?.dataModel?.namespace ?? null,
+    title: row?.title ?? version?.title ?? null,
+    status: version?.status ?? null,
+    live: Boolean(row?.publishedVersionId),
+    versionId: version?.id ?? row?.currentVersionId ?? null,
+    versionNumber: version?.versionNumber ?? null,
+    data,
+  };
+}
+
+/** The API's own message from a refusal body, `{ error }` or text. */
+function apiMessage(error) {
+  try {
+    const body = JSON.parse(error.body);
+    if (typeof body?.error === "string") return body.error;
+  } catch {
+    // Not JSON: the status line is the message.
+  }
+  return error.message;
+}
+
+/** What a key that lacks the write is told: the API's words and the scope it needs. */
+function forbidden(error, scope, act = "writes entries") {
+  return {
+    error: apiMessage(error),
+    hint: `This tool ${act}, so it needs a key holding ${scope}: the "Content writer" preset under Developers > Keys has it.`,
+  };
+}
+
+/** A missing entry, in band, with where ids come from. */
+const noEntry = (id) => ({ error: `No entry ${id} here.`, next: "Read entries with capa_read_entries or capa_graphql_query to find the id." });
+
+/**
+ * What a publish tool's description says before anything else: it changes
+ * what a site serves. Both are marked destructive, so a client asks its
+ * person before each call unless told otherwise; the description asks the
+ * agent to do the same.
+ */
+const PUBLIC =
+  "It changes what the public API serves, and sites, to every visitor, so publish only what the person asked to " +
+  "publish, or after they agreed.";
+
+/** What a write's answer says about reading the draft back, whichever key made it. */
+const READ_BACK =
+  "Saved as a draft. A development or draft key reads it now with capa_read_entries { model, id }; a production key reads published entries only, so it sees this once the entry is published (capa_publish_entry).";
+
+/**
+ * The model's id, namespace and field namespaces, from a namespace or an id.
+ * A miss answers in band with the near names and the list, as
+ * `capa_get_model` does. An answer without a string id is a miss too: "." or
+ * ".." reaches the model LIST route, which answers 200 with no model in it.
+ *
+ * Reading a model needs model:read. Without it an id is taken as it is, with
+ * `fields` null (the write goes unchecked); a namespace cannot be turned into
+ * an id, so it is refused with the two ways forward.
+ */
+async function resolveModel(config, model) {
+  let detail = null;
+  try {
+    detail = await apiGet(config, `/v2/agent/models/${encodeURIComponent(model)}`);
+  } catch (error) {
+    if (error instanceof CapaApiError && error.status === 403) {
+      if (UUID_RE.test(model)) return { id: model, namespace: null, fields: null };
+      return {
+        refusal: {
+          error: apiMessage(error),
+          hint: `Finding the model "${model}" by its namespace needs a key holding model:read. Pass the model's id instead, or use a key with model:read: the "Content writer" preset has it.`,
+        },
+      };
+    }
+    if (!(error instanceof CapaApiError && error.status === 404)) throw error;
+  }
+  if (typeof detail?.id === "string") {
+    return { id: detail.id, namespace: typeof detail.namespace === "string" ? detail.namespace : null, fields: fieldNamespaces(detail) };
+  }
+  let available = null;
+  try {
+    const list = await apiGet(config, "/v2/agent/models", { limit: 250, includeFields: "false" });
+    available = (list.data ?? []).map((m) => m.namespace);
+  } catch {
+    available = null;
+  }
+  return {
+    refusal: {
+      error: `No model "${model}" here.`,
+      // Omitted, not empty, when the list call failed too: `[]` would claim there are no models.
+      ...(available === null ? {} : { didYouMean: didYouMean(model, available), available }),
+      next: "Pass model with a namespace from available, or read the models with capa_graphql_schema.",
+    },
+  };
+}
+
+/**
+ * An entry's model, for checking an update's `data` before it is written:
+ * `{ namespace, fields }`, or null when it cannot be read (no instance:read or
+ * model:read, or any other refusal), and the update then goes ahead
+ * unchecked. A missing entry is left to the write, which answers 404.
+ */
+async function modelOfEntry(config, id) {
+  try {
+    const row = await apiGet(config, `/v2/agent/model-instances/${encodeURIComponent(id)}`);
+    if (typeof row?.modelId !== "string") return null;
+    const detail = await apiGet(config, `/v2/agent/models/${encodeURIComponent(row.modelId)}`);
+    return { namespace: typeof detail?.namespace === "string" ? detail.namespace : null, fields: fieldNamespaces(detail) };
+  } catch (error) {
+    // Any refusal leaves the check undone, never the write: the PUT answers for itself.
+    if (error instanceof CapaApiError) return null;
+    throw error;
+  }
+}
+
+/** A 400 from a write: the API names the field and the rule. */
+function invalid(error) {
+  return { error: apiMessage(error), hint: `Fix the value the error names and send it again. ${FIELD_HINT}` };
+}
+
+const DATA = {
+  type: "object",
+  description:
+    'Field values by field namespace, e.g. { "title": "Hello", "views": 3 }. A relation is the related entry\'s id ' +
+    "(a list of ids for a list); an image, video or file field takes the whole file object an upload answered.",
+  additionalProperties: true,
+};
+
+export const ENTRY_TOOLS = [
+  {
+    name: "capa_create_entry",
+    ...writes("Create a draft entry", { idempotent: false }),
+    cutHint: "The entry is created; capa_read_entries reads it whole by id.",
+    surface: "agent",
+    capOnly: true,
+    scope: "instance:create",
+    aliases: { namespace: "model" },
+    description:
+      "Create one entry in a model, as a DRAFT: nothing a site reads changes until it is published. data takes " +
+      `field values by namespace; required fields must be in it. ${FIELD_HINT} Answers the new entry's id and ` +
+      "what was stored. WRITES: it needs a key holding instance:create.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        model: { type: "string", description: 'The model\'s namespace (or id), e.g. "articles".' },
+        data: DATA,
+      },
+      required: ["model", "data"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const model = await resolveModel(config, args.model);
+      if (model.refusal) return model.refusal;
+      if (model.fields) {
+        const unknown = unknownFields(args.data, model.fields, model.namespace);
+        if (unknown) return unknown;
+      }
+      try {
+        const row = await apiWrite(config, "POST", "/v2/agent/model-instances", { modelId: model.id, data: args.data, publish: false });
+        return {
+          created: true,
+          entry: entryOf(row, model.namespace ?? (await namespaceOf(config, row?.modelId ?? model.id))),
+          next: READ_BACK,
+          ...(model.fields ? {} : { unchecked: UNCHECKED }),
+        };
+      } catch (error) {
+        if (error instanceof CapaApiError && error.status === 400) return invalid(error);
+        if (error instanceof CapaApiError && error.status === 403) return forbidden(error, "instance:create");
+        if (error instanceof CapaApiError && error.status === 404) return (await resolveModel(config, args.model)).refusal ?? { error: apiMessage(error) };
+        throw error;
+      }
+    },
+  },
+
+  {
+    name: "capa_update_entry",
+    // Not idempotent: every call saves a new draft version, the same values included.
+    ...writes("Update an entry as a draft", { idempotent: false }),
+    cutHint: "The update is saved; capa_read_entries reads the entry whole by id.",
+    surface: "agent",
+    capOnly: true,
+    scope: "instance:update",
+    description:
+      "Change fields of one entry, saved as a new DRAFT version: a published entry keeps serving its published " +
+      "version until it is published again. data MERGES: a field it leaves out keeps its value, and null clears " +
+      `one. ${FIELD_HINT} WRITES: it needs a key holding instance:update.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The entry's id." },
+        data: DATA,
+      },
+      required: ["id", "data"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      const model = await modelOfEntry(config, args.id);
+      if (model?.fields) {
+        const unknown = unknownFields(args.data, model.fields, model.namespace);
+        if (unknown) return unknown;
+      }
+      try {
+        const row = await apiWrite(config, "PUT", `/v2/agent/model-instances/${encodeURIComponent(args.id)}`, { data: args.data, publish: false });
+        return {
+          updated: true,
+          entry: entryOf(row, model?.namespace ?? (await namespaceOf(config, row?.modelId))),
+          next: READ_BACK,
+          ...(model?.fields ? {} : { unchecked: UNCHECKED }),
+        };
+      } catch (error) {
+        if (error instanceof CapaApiError && error.status === 400) return invalid(error);
+        if (error instanceof CapaApiError && error.status === 403) return forbidden(error, "instance:update");
+        if (error instanceof CapaApiError && error.status === 404) return noEntry(args.id);
+        throw error;
+      }
+    },
+  },
+
+  {
+    name: "capa_publish_entry",
+    ...writes("Publish an entry", { idempotent: true }),
+    cutHint: "The publish is done; capa_read_entries reads the entry.",
+    surface: "agent",
+    capOnly: true,
+    scope: "instance:publish",
+    description:
+      `Publish one entry: its newest draft becomes the version sites read. ${PUBLIC} An entry already published ` +
+      "with nothing newer answers skipped. versionId publishes an older version instead. WRITES: it needs a key " +
+      "holding instance:publish.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string", description: "The entry's id." },
+        versionId: { type: "string", description: "A version to publish instead of the newest; from the entry's history." },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      try {
+        const res = await apiWrite(
+          config,
+          "POST",
+          `/v2/agent/model-instances/${encodeURIComponent(args.id)}/publish`,
+          args.versionId === undefined ? {} : { versionId: args.versionId },
+        );
+        const outcome = res?.outcome ?? {};
+        return {
+          published: !outcome.skipped,
+          id: outcome.instanceId ?? args.id,
+          versionId: outcome.versionId ?? null,
+          versionNumber: outcome.versionNumber ?? null,
+          ...(outcome.skipped ? { skipped: outcome.skipped, note: "Nothing changed: that version is already the one sites read." } : {}),
+        };
+      } catch (error) {
+        if (error instanceof CapaApiError && error.status === 403) return forbidden(error, "instance:publish", "publishes");
+        if (error instanceof CapaApiError && error.status === 404) return noEntry(args.id);
+        if (error instanceof CapaApiError && error.status === 400) return { error: apiMessage(error), hint: "The entry was not published. Fix what the error names and publish again." };
+        throw error;
+      }
+    },
+  },
+
+  {
+    name: "capa_unpublish_entry",
+    ...writes("Unpublish an entry", { idempotent: true }),
+    cutHint: "The unpublish is done; capa_read_entries reads the entry.",
+    surface: "agent",
+    capOnly: true,
+    scope: "instance:publish",
+    description:
+      `Unpublish one entry: sites stop reading it, and its content stays as a draft. ${PUBLIC} An entry with ` +
+      "nothing published answers skipped. WRITES: it needs a key holding instance:publish.",
+    inputSchema: {
+      type: "object",
+      properties: { id: { type: "string", description: "The entry's id." } },
+      required: ["id"],
+      additionalProperties: false,
+    },
+    handler: async (config, args) => {
+      let res;
+      try {
+        // The agent mount's one-entry unpublish is the bulk route with one id:
+        // POST /:id/unpublish is mounted for people only.
+        res = await apiWrite(config, "POST", "/v2/agent/model-instances/bulk-unpublish", { instanceIds: [args.id] });
+      } catch (error) {
+        if (error instanceof CapaApiError && error.status === 403) return forbidden(error, "instance:publish", "unpublishes");
+        throw error;
+      }
+      const result = (res?.results ?? []).find((r) => r.id === args.id);
+      if (!result) {
+        // 202: more than the inline limit, which one id never is; said rather than guessed at.
+        return { unpublished: false, id: args.id, note: "The API queued the unpublish instead of answering it.", poll: res?.poll ?? null };
+      }
+      if (!result.ok) {
+        if (result.code === "not_found" || result.code === "deleted") return noEntry(args.id);
+        return {
+          unpublished: false,
+          id: args.id,
+          error: result.message ?? "The entry was not unpublished.",
+          code: result.code ?? null,
+          note: "Nothing changed: the entry is still published, and sites keep reading it.",
+          next:
+            result.code === "forbidden"
+              ? "This key may not unpublish this model's entries: it needs instance:publish for the model."
+              : "Try capa_unpublish_entry again. If it fails the same way, tell the person: the entry can be unpublished in the admin.",
+        };
+      }
+      if (result.skipped) return { unpublished: false, id: args.id, skipped: result.skipped, note: "Nothing changed: no version of this entry is published." };
+      return { unpublished: true, id: args.id, versionId: result.versionId ?? null, versionNumber: result.versionNumber ?? null };
+    },
+  },
+];

package/lib/error-guide.mjs

@@ -144,7 +144,7 @@ const GUIDE = {
     // answer of a path the API does not serve has none. Only without one can
     // the request have been a query sent where GraphQL is off.
     fix: (error) =>
-      "Send a query instead; nothing here can write. Content is edited in the Capa admin." +
+      "Send a query instead; GraphQL here cannot write. To save an entry, capa_create_entry and capa_update_entry write drafts where this key is offered them; otherwise content is edited in the Capa admin." +
       (error.hint
         ? ""
         : " If it was already a query, GraphQL is off on this deployment: read over REST instead, GET /api/entries/<model>."),

package/lib/explore.mjs

@@ -214,8 +214,9 @@ export function listRequests(model, fields, storedById, ids) {
 }
 
 /** The exploration query for `fields` of `model`, paged by `$after`. `status` is always the system field (N5 renames a field called status). */
-export function exploreQuery(model, fields, first) {
-  const selections = ["id", "status", ...fields.map(selectionFor)].join(" ");
+export function exploreQuery(model, fields, first, label = null) {
+  const named = label && !fields.some((field) => field.name === label.name) ? [label.name] : [];
+  const selections = ["id", "status", ...named, ...fields.map(selectionFor)].join(" ");
   return (
     `query CapaExplore($after: String) { ${model.listField}(first: ${first}, after: $after) ` +
     `{ nodes { ${selections} } pageInfo { hasNextPage endCursor } totalCount } }`
@@ -455,10 +456,24 @@ export function statusCounts(nodes) {
   return counts;
 }
 
-/** The first `count` entries, long strings clipped, relations as ids. */
-export function samples(nodes, fields, count) {
+/**
+ * The text field a person knows an entry by, `title` else `name`, or null.
+ * Samples carry it beside the id: an agent that explored one field and found
+ * an empty one in the samples answered with the UUID (scripts/tool-evals, M10).
+ */
+export function labelField(model) {
+  for (const name of ["title", "name"]) {
+    const field = model.fields?.find((f) => f.name === name && f.kind === "scalar" && !f.arrayType && scalarKind(f) === "string");
+    if (field) return field;
+  }
+  return null;
+}
+
+/** The first `count` entries, each named by its label field, long strings clipped, relations as ids. */
+export function samples(nodes, fields, count, label = null) {
   return nodes.slice(0, count).map((node) => {
     const out = { id: node.id };
+    if (label && !fields.some((field) => field.name === label.name)) out[label.name] = clip(node[label.name], SAMPLE_CHARS);
     for (const field of fields) {
       const value = node[field.name];
       if (field.kind === "relation") out[field.name] = value?.id ?? null;

package/lib/graphql/schema.mjs

@@ -216,7 +216,11 @@ export function summarizeIntrospection(introspection) {
  */
 export async function loadSchema(config, { now = Date.now() } = {}) {
   const key = `${config.baseUrl}|${config.apiKey}|${config.apiVersion}`;
-  const hit = cache.get(key);
+  // A config may carry its own cache (`config.schemaCache`, a Map). The hosted
+  // server gives each request one: its callers share a base URL and send no
+  // key, so this process-wide key would hand one person's schema to another.
+  const store = config.schemaCache ?? cache;
+  const hit = store.get(key);
   if (hit && now - hit.at < SCHEMA_TTL_MS) return hit.value;
   let body;
   try {
@@ -232,6 +236,6 @@ export async function loadSchema(config, { now = Date.now() } = {}) {
     );
   }
   const value = { introspection: body.data, summary: summarizeIntrospection(body.data) };
-  cache.set(key, { at: now, value });
+  store.set(key, { at: now, value });
   return value;
 }

package/lib/graphql/served.mjs

@@ -27,8 +27,9 @@ export function graphqlNotServed(error) {
 
 /**
  * The error every GraphQL tool answers on such a deployment. It names the
- * switch and what can still read content: over REST with the same key, and
- * for a legacy `pk_`/`sk_` key the legacy content tools it is also offered.
+ * switch and what can still read content: over REST with the same key, the
+ * legacy content tools a legacy `pk_`/`sk_` key is also offered, and
+ * capa_read_entries, which a `cap_` key is always offered.
  *
  * Where `GET /api/me` found no `/api/` surface at all at startup
  * (`config.apiMissing`), GraphQL being off is not the likely cause: the
@@ -46,7 +47,13 @@ function graphqlOff(config, error) {
     `This deployment does not serve GraphQL: POST /api/graphql answered ${error.status} ${error.code} as a path it does not serve, ` +
     "which is what CAPA_API_GRAPHQL=off does. No GraphQL tool can answer until it is switched back on.\n" +
     "Next: tell the person running Capa that GraphQL is off here. " +
-    (config.family === "legacy" ? "To read entries meanwhile, capa_list_content and capa_get_content use the legacy API. " : "") +
+    // A cap_ key is offered capa_read_entries beside every GraphQL tool it has (registry.mjs); a legacy key
+    // is offered it only where the startup probe saw GraphQL off, which is not this case.
+    (config.family === "cap"
+      ? "To read entries meanwhile, capa_read_entries reads them over REST with this key. "
+      : config.family === "legacy"
+        ? "To read entries meanwhile, capa_list_content and capa_get_content use the legacy API. "
+        : "") +
     "Code can read the same content over REST with this key: GET /api/entries/<model>."
   );
 }

package/lib/graphql-tools.mjs

@@ -39,7 +39,7 @@ import { splitOutside } from "./graphql/names.mjs";
 import { printSDL } from "./graphql/sdl.mjs";
 import { modelSDLUri } from "./resources.mjs";
 import { budgetOf, explainOne, hintedFix, nextSteps, nextTool, normalizeErrors } from "./error-guide.mjs";
-import { COUNTS_LEGEND, exploreQuery, fieldStats, hiddenValueRequests, listRequests, measurableFields, nullListRequests, pageSizeFor, samples, statusCounts, storedRequest } from "./explore.mjs";
+import { COUNTS_LEGEND, exploreQuery, fieldStats, hiddenValueRequests, labelField, listRequests, measurableFields, nullListRequests, pageSizeFor, samples, statusCounts, storedRequest } from "./explore.mjs";
 
 /** Every tool here but capa_explain_error reads through /api/graphql, which a deployment can switch off (registry.mjs). */
 const SCOPE = { surface: "api", scopePrefix: "instance:read", feature: "graphql" };
@@ -473,6 +473,13 @@ function modelDetail(summary, model, introspection) {
       // Operators take a value; hops are fields of the related model, each taking operators of its own.
       const operators = f.filterOps.filter((op) => !isHop(f, op));
       const hops = f.filterOps.filter((op) => isHop(f, op));
+      // How to read a relation: a list one is a connection, read through nodes.
+      // Agents wrote `faqs { title }` and got a validation error back.
+      if (f.kind === "relation" || f.kind === "relationList") {
+        const readable = hops.includes("title") ? "title" : hops.find((hop) => hop !== "id");
+        const inner = ["id", ...(readable ? [readable] : [])].join(" ");
+        out.select = f.kind === "relationList" ? `${f.name} { nodes { ${inner} } }` : `${f.name} { ${inner} }`;
+      }
       if (operators.length) out.filter = operators;
       const deprecatedFilter = deprecations.operators(f.name);
       if (deprecatedFilter) out.deprecatedFilter = deprecatedFilter;
@@ -783,6 +790,27 @@ function sliceOf(answer, { path, offset = 0 }, maxChars) {
   return piece(low);
 }
 
+/**
+ * The sentence for a filter that asked text fields to have no value and
+ * matched nothing, or null. Blank text ("") is a value, so `{ null: true }`
+ * and `{ exists: false }` skip it: asked which services had no description,
+ * an agent filtered `{ description: { null: true } }`, got no entries, and
+ * said every service had one (scripts/tool-evals, M11).
+ */
+function blankIsNotNull(model, filter) {
+  if (!filter || typeof filter !== "object" || Array.isArray(filter)) return null;
+  const asked = Object.entries(filter).filter(([, cond]) => cond && typeof cond === "object" && (cond.null === true || cond.exists === false));
+  const text = asked
+    .map(([name, cond]) => ({ field: model.fields.find((f) => f.name === name), op: cond.null === true ? "{ null: true }" : "{ exists: false }" }))
+    .filter(({ field }) => field && field.kind === "scalar" && !field.arrayType && field.graphqlType.replace(/!/g, "") === "String");
+  if (!text.length) return null;
+  const names = text.map(({ field }) => field.name).join(" or ");
+  return (
+    `No entry matched. ${text[0].op} matches ${names} only where it has no value at all; blank text ("") is a value, ` +
+    `so a blank ${names} is not counted here. capa_explore_data with field ${text[0].field.name} counts empty and missing apart.`
+  );
+}
+
 export const GRAPHQL_TOOLS = [
   {
     name: "capa_graphql_schema",
@@ -912,7 +940,7 @@ export const GRAPHQL_TOOLS = [
       const built = printGraphQL(plan);
       const rest = printRest(summary, plan);
       const sdk = sdkCode(code, sdkSnippets(config, summary, plan, built, rest));
-      const answer = { ...built, rest: rest.url, ...(sdk ? { sdk } : {}) };
+      let answer = { ...built, rest: rest.url, ...(sdk ? { sdk } : {}) };
       // Only the result is ever cut; the SDK code asked for goes whole first, as it comes back from a call without run.
       // The run selects each list's cursors and every relation list's pageInfo (runWithCursors), so a cut list
       // pages on from its last entry kept, and a relation list that holds more than it shows can say so.
@@ -956,6 +984,10 @@ export const GRAPHQL_TOOLS = [
       }
       const serverRest = result.rest?.[0]?.url;
       if (serverRest && decodeURIComponent(serverRest) !== decodeURIComponent(rest.url)) answer.restFromApi = serverRest;
+      const listed = plan.mode === "single" || result.errors ? null : (result.data?.[plan.model.listField]?.nodes?.length ?? null);
+      // First, in `note`: an answer with no entries is never cut, so nothing else writes that key here.
+      const note = listed === 0 ? blankIsNotNull(plan.model, spec.filter) : null;
+      if (note) answer = { note, ...answer };
       // A relation list that holds more than it shows is named, with the read that goes on (bin-250: 100 of 250).
       // With run, it is read from the answer as cut; without, from the run the check made.
       const listsIn = (data) =>
@@ -1086,7 +1118,8 @@ export const GRAPHQL_TOOLS = [
       }
       const { measured: fields, skipped } = measurableFields(wanted);
       const maxEntries = args.maxEntries ?? 200;
-      const query = exploreQuery(model, fields, Math.min(pageSizeFor(fields), maxEntries));
+      const label = labelField(model);
+      const query = exploreQuery(model, fields, Math.min(pageSizeFor(fields), maxEntries), label);
       const nodes = [];
       const stored = new Map();
       const hidden = new Map();
@@ -1122,7 +1155,7 @@ export const GRAPHQL_TOOLS = [
         statuses: statusCounts(scanned),
         counts: COUNTS_LEGEND,
         fields: fields.map((f) => fieldStats(f, scanned, stored, hidden.get(f.namespace), nullLists.get(f.namespace), lists.get(f.namespace) ?? new Set())),
-        samples: samples(scanned, fields, args.sample ?? 3),
+        samples: samples(scanned, fields, args.sample ?? 3, label),
       };
       if (skipped.length) {
         answer.skipped = {

package/lib/index.mjs

@@ -0,0 +1,27 @@
+/**
+ * index.mjs — @capacms/mcp as a module, for a front end that runs these tools
+ * without being an MCP client: the `capa` CLI (@capacms/cli), whose content
+ * commands are these tools by name, with the same arguments and the same
+ * errors, and whose `capa mcp` serves them over stdio.
+ *
+ * The bin (`capa-mcp`) is a dozen lines over the same three calls:
+ *
+ *   const config = loadConfig(env);              // CAPA_API_URL, CAPA_KEY, ...
+ *   const { ctx, notes } = await connect(config); // /api/me and the probes
+ *   await serveStdio(ctx);                       // or runTool(ctx, name, args)
+ *
+ * `ctx.tools` is the list this key is offered (registry.mjs), and `runTool`
+ * answers only from it: a front end never runs a tool the MCP server would
+ * not have offered the same key.
+ */
+export { loadConfig, keyFamily, apiNextGet, CapaApiError, CapaTimeout, CapaUnreachable, DEFAULT_API_VERSION } from "./client.mjs";
+export { connect } from "./connect.mjs";
+export { runTool, callTool, dispatch, SERVER_INFO } from "./server.mjs";
+export { serveStdio } from "./stdio.mjs";
+export { createSession } from "./session.mjs";
+export { selectTools, scopeNote, probeUploads } from "./registry.mjs";
+export { checkArguments } from "./arguments.mjs";
+export { TOOLS, TOOLS_BY_NAME } from "./tools.mjs";
+// The hosted server (apps/api/src/routes/mcp.ts) builds its own MCP server
+// over these tools and gives it the same instructions the stdio one sends.
+export { instructionsFor } from "./instructions.mjs";

package/lib/instructions.mjs

@@ -15,6 +15,8 @@ export function instructionsFor(tools) {
       "Capa is a headless CMS, and these tools read its content with one API key.",
       "Start with capa_graphql_schema: it names every model and field this key can read. Never guess a model, field or sort name it has not shown; a wrong one comes back with the nearest names.",
       "capa_explore_data measures real values before you filter, capa_graphql_build writes and checks a query, and capa_graphql_query runs one.",
+      "Run a query before you hand it to anyone; capa_graphql_build with run: true writes and runs one.",
+      "A list relation is read through nodes: faqs { nodes { id title } }.",
       "A production key reads published entries only; a development key also reads drafts, and every answer says which key read it.",
       "The resource capa://guide/querying has the call order, the filter and sort grammar, and the limits.",
     );