@capacms/mcp 0.2.0

package/lib/guide.mjs

@@ -0,0 +1,55 @@
+/**
+ * guide.mjs — the querying cheat sheet served as an MCP resource.
+ *
+ * Written for an agent, not a person: the order to call the tools in, the
+ * filter and sort grammar, and the limits, in as few tokens as that takes.
+ * The person-facing version is docs/api/ai-assistants.md.
+ */
+import { MAX_RELATION_DEPTH } from "./graphql/build.mjs";
+
+export const QUERY_GUIDE = `# Querying Capa content
+
+## Order of calls
+1. capa_graphql_schema: the models this key can read and their fields.
+2. capa_graphql_schema { model }: filter operators, sort values, an example. Add sdl: true for SDL.
+3. capa_explore_data { model }: real values, so filters match what exists.
+4. capa_graphql_build { model, fields, filter, sort, first, run: true }: GraphQL, REST URL, SDK code, data.
+5. capa_graphql_query { query, variables }: run or adjust a document.
+6. A refused call says the fix and the next tool per error code; for an error from elsewhere, capa_explain_error { error }.
+
+## Shapes
+- List: articles(first, after, last, before, sort, filter) { nodes { id ... } pageInfo { hasNextPage endCursor } totalCount }
+- One: article(id: ID!) { id ... }; any model: entry(id: ID!) { id model ... on Articles { title } }
+- Relation: author { id name }. List relation: coauthors(first: 10, sort: name_ASC) { nodes { id name } pageInfo { hasNextPage endCursor } }
+- A list relation that holds more than it shows is named in the answer's more. Page it in a read of one entry only:
+  article(id: ID!) { coauthors(after: <its endCursor>) { ... } }; capa_graphql_build's more[].next is that read.
+- Media, single or a list: hero { id url alt type width height }; type is image, video, audio, document or file.
+- Next page: pass pageInfo.endCursor as after, with the same sort.
+- Previous page: last with before, pageInfo.startCursor as before; first with before is refused.
+  capa_graphql_build takes before with first, and writes last for you.
+- End of the list: last with no before (REST before=end); in capa_graphql_build, before: "end".
+- REST twin of each root field: rest in capa_graphql_query's answer, /api/entries/<model>?select=...&where=<JSON>&sort=...
+  A system key a field of the model shadows is written with $ there: $tags, $createdAt, author.$id.
+  A namespace holding , ( ) : . " * [ ] or a space, or starting with -, is quoted: "price.usd", "at.place"."zip.code".
+
+## Filters (the model's <Type>Filter)
+- Text: eq ne in nin contains startsWith endsWith exists null
+- Number and date: eq ne lt lte gt gte (numbers also in nin) exists null
+- True/false: eq ne exists null. Lists: has hasAny hasAll exists null, with values of the list's item type:
+  { has: true } on true/false, { has: "news" } on text, ISO dates on dates
+- Relation: eq ne in nin exists null, or one hop: { author: { name: { eq: "Ada Vale" } } }
+- Combine: { and: [...] }, { or: [...] }, { not: {...} }. Keys in one object must all match.
+
+## Sort
+- Values of <Type>Sort: views_DESC, title_ASC, author__name_ASC (one relation hop). Up to 3.
+
+## Limits
+- first 1 to 200 (default 25; nested default 100). Depth 8, 10 root fields, 25 connections,
+  5,000 nodes, 1,000 fields, 32 KB per document.
+- Up to ${MAX_RELATION_DEPTH} nested relations below an entry, ${MAX_RELATION_DEPTH + 1} levels of entries with it
+  (author { books { publisher { country { id } } } }), and at most 12 relation fields expanded per root field.
+- A production key reads published entries; a development key also reads drafts, and every answer
+  says which (environment, and drafts for a development key).
+- A refusal over a budget states what the query measured and the limit, and its Next line quotes the
+  change the API's hint names; capa_graphql_build's check also gives the root first that fits.
+`;

package/lib/instructions.mjs

@@ -0,0 +1,32 @@
+/**
+ * instructions.mjs — the few sentences `initialize` gives the client to put
+ * before the model: where to start, and the rules that save it calls. A
+ * client that shows them brings the heart of the querying guide to the model
+ * without it opening capa://guide/querying. They name only tools this key
+ * was given.
+ */
+
+/** The instructions for a session offered `tools`. */
+export function instructionsFor(tools) {
+  const names = new Set(tools.map((tool) => tool.name));
+  const lines = [];
+  if (names.has("capa_graphql_schema")) {
+    lines.push(
+      "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.",
+      "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.",
+    );
+  } else if (names.has("capa_read_entries")) {
+    lines.push(
+      "Capa is a headless CMS, and these tools read its content with one API key. This deployment serves no GraphQL.",
+      "Start with capa_read_entries without a model: it names every model this key reads. Never guess a model or field name it has not shown.",
+      "A production key reads published entries only; a development key also reads drafts.",
+    );
+  } else if (!tools.some((tool) => tool.surface !== "local")) {
+    lines.push("This key reads no content: its scopes hold no instance:read.");
+  }
+  if (names.has("capa_explain_error")) lines.push("capa_explain_error explains any Capa API error, offline.");
+  return lines.join(" ");
+}

package/lib/prompts.mjs

@@ -0,0 +1,68 @@
+/**
+ * prompts.mjs — ready-made starting points a person can pick in their MCP
+ * client ("Explore my content", "Write a query"). Each expands to a user
+ * message naming the tools to call in order, so the agent spends no turns
+ * working out the workflow. `tools` names every tool a prompt sends the agent
+ * to: a prompt is offered only with all of them, since one naming a tool this
+ * key was not given starts the agent on a call that cannot work.
+ */
+
+export const PROMPTS = [
+  {
+    name: "explore-content",
+    description: "Look through a model's content and summarise what is there.",
+    tools: ["capa_graphql_schema", "capa_explore_data"],
+    arguments: [{ name: "model", description: "The model to explore, e.g. articles. Omit to start from the list.", required: false }],
+    render: ({ model }) =>
+      (model
+        ? `Explore the Capa model "${model}". `
+        : "Explore the content in this Capa project. Start with capa_graphql_schema to list the models, then pick the one with the most fields. ") +
+      "Call capa_graphql_schema with the model for its fields, then capa_explore_data for real values. " +
+      "Summarise: how many entries and in which status, which fields are often empty or missing, the values enum-like fields take, and how entries relate. " +
+      "Quote numbers from the tool output; do not guess.",
+  },
+  {
+    name: "write-query",
+    description: "Turn a plain request into a working Capa query, in GraphQL, REST and SDK code.",
+    tools: ["capa_graphql_schema", "capa_explore_data", "capa_graphql_build", "capa_explain_error"],
+    arguments: [
+      { name: "goal", description: "What the query should return, e.g. the 5 most viewed articles with their author.", required: true },
+      { name: "model", description: "The model, if you know it.", required: false },
+    ],
+    render: ({ goal, model }) =>
+      `Write a Capa query that returns: ${goal}.${model ? ` The model is "${model}".` : ""} ` +
+      "Use capa_graphql_schema for exact field and sort names, capa_explore_data if a filter needs real values, " +
+      "then capa_graphql_build with run: true. If it fails, call capa_explain_error and try again. " +
+      'Once the data is right, build it a last time with code: "all" (code: "next" for a Next.js app) for the SDK code. ' +
+      "Answer with the GraphQL document and variables, the REST URL and that SDK code, and a line on what the data shows.",
+  },
+  {
+    name: "fix-query-error",
+    description: "Explain a Capa API error and correct the query that caused it.",
+    tools: ["capa_explain_error", "capa_graphql_schema", "capa_graphql_build"],
+    arguments: [{ name: "error", description: "The error as you got it: JSON or text.", required: true }],
+    render: ({ error }) =>
+      `This Capa API call failed:\n\n${error}\n\n` +
+      "Call capa_explain_error with it, follow the fix it gives (capa_graphql_schema for names), " +
+      "and rebuild the query with capa_graphql_build. Show the corrected query and why the first one failed.",
+  },
+];
+
+/** The prompts whose every tool is among `tools`, the registered set. */
+export function availablePrompts(tools) {
+  const names = new Set(tools.map((t) => t.name));
+  return PROMPTS.filter((p) => p.tools.every((tool) => names.has(tool)));
+}
+
+/** `prompts/get`: the message for one prompt offered with `tools`, or `{ error }` naming what is missing. */
+export function renderPrompt(name, args = {}, tools) {
+  const offered = availablePrompts(tools);
+  const prompt = offered.find((p) => p.name === name);
+  if (!prompt) return { error: `Unknown prompt: ${name}. Available: ${offered.map((p) => p.name).join(", ") || "none for this key"}` };
+  const missing = prompt.arguments.filter((a) => a.required && !args[a.name]).map((a) => a.name);
+  if (missing.length) return { error: `Prompt ${name} needs ${missing.join(", ")}.` };
+  return {
+    description: prompt.description,
+    messages: [{ role: "user", content: { type: "text", text: prompt.render(args) } }],
+  };
+}

package/lib/registry.mjs

@@ -0,0 +1,235 @@
+/**
+ * registry.mjs — which tools THIS key actually gets, decided once at startup.
+ *
+ * The server used to advertise every tool in `tools.mjs` regardless of the key
+ * it was given. That was true enough while one key family existed and every
+ * tool spoke to it. It stopped being true when scoped `cap_` keys arrived:
+ * a `cap_` key is refused on every legacy mount before the lookup even runs, so
+ * a server offering `capa_list_models` to one is offering a tool that cannot
+ * work, and an agent learns that from a failed call rather than from the list.
+ *
+ * THE RULE, in one sentence per family:
+ *
+ *   cap_        `/api/` only. The legacy tools are not registered at all,
+ *               because the surface they call refuses the prefix.
+ *   pk_ / sk_   both. Every legacy tool registers as before, and the `/api/`
+ *               tools register too, because `/api/` accepts a legacy key and
+ *               derives its scope list from the key's bundle.
+ *
+ * Then the scope filter, which applies to `/api/` tools only: `GET /api/me`
+ * reports the scopes a key holds, and a tool whose `scope` is not among them is
+ * left out. A tool that is registered and always answers 403 teaches an agent
+ * to stop trying, which is the same reasoning that keeps unbuilt write tools
+ * absent rather than stubbed.
+ *
+ * Then the deployment filter, for the two features a deployment can switch
+ * off. `/api/pages` and its siblings sit behind `CAPA_SITE_PREVIEW`, which is
+ * off by default and does not launch with Capa, and a deployment without them
+ * answers every page path `route_not_found`. `/api/graphql` is on by default
+ * and `CAPA_API_GRAPHQL=off` unregisters it. `probePages` and `probeGraphQL`
+ * ask once at startup, and a tool whose `feature` the deployment does not
+ * serve is left out, for the same reason a tool that always answers 403 is.
+ * A tool that stands in for a feature (`whenOff`, capa_read_entries for
+ * GraphQL) is registered only where the probe found the feature off, or,
+ * with a description of its own (`besideGraphQL`), where GraphQL is served
+ * and leaves some of the key's models out: REST is the only way to read them.
+ *
+ * WHEN `/api/me` DOES NOT ANSWER, THE TOOLS REGISTER ANYWAY. Two real cases
+ * produce that: a deployment with the `/api/` surface switched off answers 404
+ * on every path under it, and a machine with no route to the host answers
+ * nothing at all. Neither is evidence about what the key may do. Dropping the
+ * tools there would turn a reachability problem into "Capa has no page tools",
+ * which is the wrong thing for an agent to conclude and an impossible one for a
+ * person to debug from the tool list. So they register, the first call carries
+ * the real error, and the reason goes to stderr where the person running the
+ * server can read it.
+ */
+import { apiNextGet, apiNextPost, CapaApiError, CapaUnreachable } from "./client.mjs";
+import { loadSchema } from "./graphql/schema.mjs";
+import { graphqlNotServed } from "./graphql/served.mjs";
+import { TOOLS } from "./tools.mjs";
+
+/**
+ * How long the startup `/api/me` call may take before it counts as a failure.
+ *
+ * It is bounded because it runs BEFORE the first client message is read: a
+ * host that accepts the connection and then goes quiet would otherwise leave
+ * the client waiting on `initialize` with nothing on stderr, which looks like a
+ * broken server rather than an unreachable Capa. Five seconds is long enough
+ * for a cold serverless start and short enough that a person notices the
+ * stderr line rather than the silence.
+ */
+const ME_TIMEOUT_MS = 5000;
+
+/**
+ * Ask `/api/me` what this key is and what it holds.
+ *
+ * Never throws: every failure is an answer here, because the caller's job is to
+ * register tools rather than to decide whether Capa is up.
+ *
+ * Returns `{ ok: true, me }` with the `/api/me` body, or `{ ok: false, reason,
+ * apiMissing }` with a sentence naming what happened and what it means for the
+ * tool list, and whether the address serves no `/api/` route at all.
+ */
+export async function loadMe(config, { timeoutMs = ME_TIMEOUT_MS } = {}) {
+  try {
+    const { data } = await apiNextGet(config, "/api/me", {}, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    return { ok: true, me: data ?? null };
+  } catch (error) {
+    const why =
+      error instanceof CapaApiError
+        ? `GET /api/me answered ${error.status}${error.code ? ` ${error.code}` : ""}` +
+          (error.status === 404
+            ? " (the address does not serve the /api/ surface: check that CAPA_API_URL is the Capa API's address, with no route after it)"
+            : "")
+        : // Named separately because "aborted" reads like something this server
+          // chose to do, and the person running it needs to know the host went
+          // quiet rather than that a request was cancelled.
+          error?.name === "TimeoutError"
+          ? `GET /api/me did not answer within ${timeoutMs}ms`
+          : error instanceof CapaUnreachable
+            ? `GET /api/me could not be reached at ${error.origin} (${error.reason})`
+            : `GET /api/me could not be reached (${String(error?.message ?? error)})`;
+    return {
+      ok: false,
+      me: null,
+      // A 404 on /api/me: nothing at this address serves /api/, so every /api/ tool's error names the address.
+      apiMissing: error instanceof CapaApiError && error.status === 404,
+      reason:
+        `${why}. The /api/ tools are registered anyway, so a call to one reports the real ` +
+        `error instead of the tool silently not existing.`,
+    };
+  }
+}
+
+/**
+ * Whether this deployment serves the page routes: `true`, `false`, or `null`
+ * when the probe could not tell (no answer in time, or no route to the host).
+ *
+ * Asked with `GET /api/preview` and no token, the cheapest of the three: where
+ * the routes are registered it runs the key check and then refuses the
+ * missing token before any query; where they are not, the path falls through
+ * to `route_not_found`, whatever the key. Any other answer, a 401 included,
+ * means the route matched.
+ */
+export async function probePages(config, { timeoutMs = ME_TIMEOUT_MS } = {}) {
+  try {
+    await apiNextGet(config, "/api/preview", {}, { signal: AbortSignal.timeout(timeoutMs) });
+    return true;
+  } catch (error) {
+    if (!(error instanceof CapaApiError)) return null;
+    return !(error.status === 404 && error.code === "route_not_found");
+  }
+}
+
+/**
+ * Whether this deployment serves `/api/graphql`: `true`, `false`, or `null`
+ * when the probe could not tell (no answer in time, or no route to the host).
+ *
+ * Asked with a POST of `{ __typename }`, the cheapest document there is, and a
+ * POST because that is what every GraphQL tool sends: an admin-role host
+ * answers GraphQL by POST only, so a GET would call it off when it is not.
+ * Only the answer of a path the API does not serve (served.mjs) means no; any
+ * answer from the GraphQL handler, a refusal included, means the route is there.
+ */
+export async function probeGraphQL(config, { timeoutMs = ME_TIMEOUT_MS } = {}) {
+  try {
+    await apiNextPost(config, "/api/graphql", { query: "{ __typename }" }, { signal: AbortSignal.timeout(timeoutMs) });
+    return true;
+  } catch (error) {
+    if (!(error instanceof CapaApiError)) return null;
+    return !graphqlNotServed(error);
+  }
+}
+
+/**
+ * The models this key reads that GraphQL leaves out (N1: their type names
+ * collide), from the key's schema, which the GraphQL tools' first call then
+ * reads from the cache. Empty when there are none, and when the schema could
+ * not be read in time: a GraphQL tool's call then reports why.
+ */
+export async function probeRestOnly(config, { timeoutMs = ME_TIMEOUT_MS } = {}) {
+  let timer;
+  const late = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ summary: { restOnly: [] } }), timeoutMs);
+    timer.unref?.();
+  });
+  try {
+    const { summary } = await Promise.race([loadSchema(config), late]);
+    return summary.restOnly ?? [];
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The tools this key gets.
+ *
+ * Pure over `(config, me, deployment)` so the rule above is a tested property
+ * rather than something only a running server exercises. `me` is the
+ * `/api/me` body, or null when the call did not answer; `deployment.pages` and
+ * `deployment.graphql` are what the probes found, and only `false` drops the
+ * tools of that feature, and adds the tool that stands in for it.
+ * `deployment.restOnly` lists the models GraphQL leaves out, which the
+ * stand-in reads beside GraphQL.
+ */
+export function selectTools(config, me, deployment = {}) {
+  const family = config?.family === "cap" ? "cap" : "legacy";
+  // An ARRAY or nothing. `CAPA_KEY_SCOPES=off` hides `scopes` from `/api/me`
+  // while leaving enforcement of stored scopes on, so the field's absence means
+  // "this deployment is not telling", not "this key holds none". Filtering on
+  // an empty list there would drop every `/api/` tool on a stack where they all
+  // work.
+  const scopes = Array.isArray(me?.scopes) ? me.scopes : null;
+  const besideGraphQL = (tool) => Boolean(tool.besideGraphQL) && deployment[tool.whenOff] !== false && deployment.restOnly?.length > 0;
+  const registered = TOOLS.filter((tool) => {
+    // Answers from this package alone, so every key gets it.
+    if (tool.surface === "local") return true;
+    if (tool.surface === "legacy") return family === "legacy";
+    if (tool.feature && deployment[tool.feature] === false) return false;
+    if (tool.whenOff && deployment[tool.whenOff] !== false && !besideGraphQL(tool)) return false;
+    // Compared WHOLE, not by prefix: the page routes ask for unscoped
+    // `instance:read`, and a key holding only `instance:read:<modelId>` is
+    // refused there because a page list spans every model a page touches.
+    if (tool.scope && scopes) return scopes.includes(tool.scope);
+    // By prefix, for the GraphQL tools: `/api/graphql` serves any key that can
+    // read at least one model, and shows it only those models, so a one-model
+    // `instance:read:<modelId>` key gets them and sees one model.
+    if (tool.scopePrefix && scopes) {
+      return scopes.some((s) => s === tool.scopePrefix || s.startsWith(`${tool.scopePrefix}:`));
+    }
+    return true;
+  });
+  return registered.map((tool) => (besideGraphQL(tool) ? { ...tool, description: tool.besideGraphQL } : tool));
+}
+
+/** `a`, `a and b`, `a, b and c`. */
+const inWords = (names) => (names.length < 2 ? names.join("") : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`);
+
+/**
+ * One line for the person running the server when the key's scopes leave
+ * tools out, naming the scope those tools need, or null when they leave none
+ * out. A key holding only `media:read` would otherwise start with
+ * capa_explain_error alone and nothing to say why.
+ */
+export function scopeNote(config, me, deployment = {}) {
+  const scopes = Array.isArray(me?.scopes) ? me.scopes : null;
+  if (!scopes) return null;
+  const offered = selectTools(config, me, deployment);
+  const offeredNames = new Set(offered.map((tool) => tool.name));
+  const left = selectTools(config, { ...me, scopes: null }, deployment).filter((tool) => !offeredNames.has(tool.name));
+  if (!left.length) return null;
+  const needed = inWords([...new Set(left.map((tool) => tool.scope ?? tool.scopePrefix))]);
+  const shown = scopes.length > 4 ? [...scopes.slice(0, 4), `${scopes.length - 4} more`] : scopes;
+  const held = scopes.length ? `holds ${inWords(shown)}` : "holds no scope";
+  if (offered.every((tool) => tool.surface === "local")) {
+    const local = inWords(offered.map((tool) => tool.name));
+    return `capa-mcp: this key ${held}, and every tool that reads Capa needs ${needed}, so only ${local} ${offered.length === 1 ? "is" : "are"} offered.`;
+  }
+  const names = inWords(left.map((tool) => tool.name));
+  return `capa-mcp: this key ${held}, so ${names} ${left.length === 1 ? "is" : "are"} not offered: ${left.length === 1 ? "it needs" : "they need"} ${needed}.`;
+}

package/lib/resources.mjs

@@ -0,0 +1,134 @@
+/**
+ * resources.mjs — what the server offers to READ rather than to call.
+ *
+ * Two resources: the key's GraphQL schema as SDL (for a client that attaches
+ * schemas as context) and the querying guide; and one template, a single
+ * model's SDL. All are offered only when the GraphQL tools are registered:
+ * the schema is read with the same key and scope, and the guide is the order
+ * to call those tools in.
+ *
+ * The whole schema grows with the models a key reads (about 240 KB for a
+ * 44-model project), and a client may let the model read a resource on its
+ * own, so the list gives each resource's size and the schema's description
+ * says what to read instead: one model's SDL.
+ */
+import { BuildError, findModel } from "./graphql/build.mjs";
+import { loadSchema } from "./graphql/schema.mjs";
+import { printSDL } from "./graphql/sdl.mjs";
+import { QUERY_GUIDE } from "./guide.mjs";
+
+/** A resource URI that names nothing this key can read: MCP's "resource not found". */
+export class ResourceNotFound extends Error {}
+
+const MODEL_SDL = "capa://graphql/schema/{model}.graphql";
+const ONE_MODEL = /^capa:\/\/graphql\/schema\/([^/]+)\.graphql$/;
+
+/** One model's SDL resource, e.g. `capa://graphql/schema/articles.graphql`. */
+export const modelSDLUri = (namespace) => MODEL_SDL.replace("{model}", encodeURIComponent(namespace));
+
+/** A size as a person reads it: `23 KB`, `under 1 KB`. */
+const kilobytes = (bytes) => (bytes < 1024 ? "under 1 KB" : `${Math.round(bytes / 1024).toLocaleString("en-US")} KB`);
+
+export const RESOURCES = [
+  {
+    uri: "capa://graphql/schema.graphql",
+    name: "GraphQL schema",
+    describe: (bytes) =>
+      `The whole GraphQL SDL for this key: every model it can read, with filters and sorts${bytes === undefined ? "" : `, ${kilobytes(bytes)}`}. ` +
+      `For one model, read ${MODEL_SDL} or call capa_graphql_schema with model and sdl: true.`,
+    mimeType: "application/graphql",
+    requiresTool: "capa_graphql_schema",
+    read: async (config) => {
+      const { introspection, summary } = await loadSchema(config);
+      return printSDL(introspection, summary).sdl;
+    },
+  },
+  {
+    uri: "capa://guide/querying",
+    name: "How to query Capa",
+    describe: () => "The order to call the tools in, the filter and sort grammar, and the limits.",
+    mimeType: "text/markdown",
+    requiresTool: "capa_graphql_schema",
+    read: async () => QUERY_GUIDE,
+  },
+];
+
+export const RESOURCE_TEMPLATES = [
+  {
+    uriTemplate: MODEL_SDL,
+    name: "One model's GraphQL schema",
+    description:
+      "One model's SDL: its type, connection, filter and sort, and the shared types they use. " +
+      "{model} is a namespace or type name, e.g. articles.",
+    mimeType: "application/graphql",
+    requiresTool: "capa_graphql_schema",
+    /** The model a URI names, or undefined when it is not one of this template's. */
+    match: (uri) => {
+      const found = ONE_MODEL.exec(uri);
+      return found ? decodeURIComponent(found[1]) : undefined;
+    },
+    read: async (config, wanted) => {
+      const { introspection, summary } = await loadSchema(config);
+      let model;
+      try {
+        model = findModel(summary, wanted);
+      } catch (error) {
+        if (!(error instanceof BuildError)) throw error;
+        const near = error.didYouMean.length ? ` Did you mean ${error.didYouMean.map(modelSDLUri).join(" or ")}?` : "";
+        throw new ResourceNotFound(`${error.message}.${near}`);
+      }
+      return printSDL(introspection, summary, [model.namespace]).sdl;
+    },
+  },
+];
+
+const offeredWith = (tools) => {
+  const names = new Set(tools.map((t) => t.name));
+  return (item) => !item.requiresTool || names.has(item.requiresTool);
+};
+
+/** The resources this server offers with the tools it registered. */
+export function availableResources(tools) {
+  return RESOURCES.filter(offeredWith(tools));
+}
+
+/** The resource templates this server offers with the tools it registered. */
+export function availableTemplates(tools) {
+  return RESOURCE_TEMPLATES.filter(offeredWith(tools));
+}
+
+/**
+ * `resources/list`: each resource with its size in bytes, read with this key.
+ * A resource that cannot be read now (Capa unreachable) is still listed,
+ * without a size: reading it reports why.
+ */
+export async function listResources(config, tools) {
+  const listed = [];
+  for (const resource of availableResources(tools)) {
+    let bytes;
+    try {
+      bytes = Buffer.byteLength(await resource.read(config), "utf8");
+    } catch {
+      bytes = undefined;
+    }
+    listed.push({
+      uri: resource.uri,
+      name: resource.name,
+      description: resource.describe(bytes),
+      mimeType: resource.mimeType,
+      ...(bytes === undefined ? {} : { size: bytes }),
+    });
+  }
+  return listed;
+}
+
+/** `resources/read`: the text at `uri`, or `ResourceNotFound`. */
+export async function readResource(config, tools, uri) {
+  const resource = availableResources(tools).find((r) => r.uri === uri);
+  if (resource) return { resource, text: await resource.read(config) };
+  for (const template of availableTemplates(tools)) {
+    const wanted = template.match(String(uri));
+    if (wanted !== undefined) return { resource: { uri, mimeType: template.mimeType }, text: await template.read(config, wanted) };
+  }
+  throw new ResourceNotFound(`Resource not found: ${String(uri)}`);
+}