@usegraft/mcp 0.1.0 → 0.2.0

package/dist/index.js

@@ -2,98 +2,35 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync2, unlinkSync } from "fs";
-import { existsSync as existsSync2 } from "fs";
-import { join as join2 } from "path";
-import {
-  contentTypeFor,
-  createStorage,
-  defaultKeyFor,
-  storageConfigFromEnv
-} from "@usegraft/assets";
-import {
-  compile,
-  compileStatic,
-  composeDocument,
-  parseDocument as parseDocument2,
-  writeDocumentFile
-} from "@usegraft/compiler";
-import {
-  GraftError as GraftError2
-} from "@usegraft/contracts";
+import { unlinkSync } from "fs";
+import { join as join3 } from "path";
+import { createStorage, storageConfigFromEnv } from "@usegraft/assets";
+import { compile, compileStatic } from "@usegraft/compiler";
+import { GraftError as GraftError8 } from "@usegraft/contracts";
 import {
-  APPROVAL_HEADER,
-  AssetRef,
   createFunctionsHandler,
   defineFunction,
   field
 } from "@usegraft/core";
-import {
-  assertSearchQuery,
-  decideApproval,
-  listBranches,
-  listCompilations,
-  listPendingApprovals,
-  openStaticIndex,
-  resolveBranchScope,
-  scopeChain,
-  searchContent
-} from "@usegraft/db";
-import { describeItem, listItems, loadItem } from "@usegraft/registry";
+import { openStaticIndex, resolveBranchScope, searchContent } from "@usegraft/db";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/content-hints.ts
+import { findDoc as findDocIn, requireCollection as requireCollectionIn } from "@usegraft/compiler";
+var MCP_HINTS = {
+  listCollections: "see list_collections",
+  authorDocument: "or author it with write_content."
+};
+var requireCollection = (collections, name) => requireCollectionIn(collections, name, MCP_HINTS);
+var findDoc = (contentDir, collectionName, collection, slug) => findDocIn(contentDir, collectionName, collection, slug, MCP_HINTS);
+
+// src/tools/approvals.ts
+import { GraftError as GraftError2 } from "@usegraft/contracts";
+import { decideApproval, listPendingApprovals } from "@usegraft/db";
 import { z } from "zod";
 
-// src/content-files.ts
-import { existsSync, readdirSync, readFileSync, statSync } from "fs";
-import { join, relative, sep } from "path";
-import { parseDocument } from "@usegraft/compiler";
+// src/tool-result.ts
 import { GraftError } from "@usegraft/contracts";
-function requireCollection(collections, name) {
-  const collection = collections[name];
-  if (!collection) {
-    const known = Object.keys(collections).join(", ") || "(none registered)";
-    throw new GraftError({
-      code: "COLLECTION_NOT_FOUND",
-      message: `No collection named "${name}" is registered`,
-      fix: `Use one of the registered collections: ${known} (see list_collections), or add defineCollection({ name: "${name}", \u2026 }) to the schema.`,
-      details: { collection: name, registered: Object.keys(collections) }
-    });
-  }
-  return collection;
-}
-function readCollectionDocs(contentDir, collectionName, collection) {
-  const dir = join(contentDir, collectionName);
-  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
-  const docs = [];
-  for (const file of walk(dir)) {
-    const sourcePath = relative(contentDir, file).split(sep).join("/");
-    docs.push(parseDocument(readFileSync(file, "utf8"), collection, sourcePath));
-  }
-  return docs.sort((a, b) => a.slug.localeCompare(b.slug));
-}
-function findDoc(contentDir, collectionName, collection, slug) {
-  const docs = readCollectionDocs(contentDir, collectionName, collection);
-  const doc = docs.find((candidate) => candidate.slug === slug);
-  if (!doc) {
-    const slugs = docs.map((candidate) => candidate.slug);
-    throw new GraftError({
-      code: "DOCUMENT_NOT_FOUND",
-      message: `No document with slug "${slug}" in collection "${collectionName}"`,
-      fix: slugs.length > 0 ? `Existing slugs: ${slugs.join(", ")}. Use one of those, or author the document with write_content.` : `Collection "${collectionName}" has no documents yet \u2014 author the first one with write_content.`,
-      details: { collection: collectionName, slug, existing: slugs }
-    });
-  }
-  return doc;
-}
-function walk(dir) {
-  const out = [];
-  for (const name of readdirSync(dir)) {
-    const full = join(dir, name);
-    if (statSync(full).isDirectory()) out.push(...walk(full));
-    else if (/\.mdx?$/.test(name)) out.push(full);
-  }
-  return out.sort();
-}
 
 // src/explain.ts
 import { ErrorCodes } from "@usegraft/contracts";
@@ -388,6 +325,16 @@ var ERROR_KNOWLEDGE = {
     ],
     howToRecover: "pending \u2192 wait for the human decision; denied \u2192 do not retry, ask the operator; already_consumed or not_found \u2192 call again without the approval id to file a fresh request; mismatch \u2192 retry with exactly the approved input."
   },
+  APPROVAL_UNATTRIBUTED: {
+    code: "APPROVAL_UNATTRIBUTED",
+    meaning: "The approval was filed by a caller with no stable identity, so there is nobody the request can be held to and no meaningful separation of duties to enforce. It cannot be decided by anyone.",
+    typicalCauses: [
+      "An unauthenticated caller reached a destructive function (an MCP mount or functions route serving anonymous actors)",
+      "A trusted issuer minted a token with no `sub` claim, so the actor authenticated but carried no id",
+      "A row left over from before approvals required an identified requester"
+    ],
+    howToRecover: "Fix the filing surface, not the row: require authentication where the approval was requested (an actor resolver, or a token that carries `sub`), then have the caller request the operation again so the approval records who wants it. A stale row can be resolved directly in the database."
+  },
   APPROVAL_SELF_DECISION: {
     code: "APPROVAL_SELF_DECISION",
     meaning: "The identity deciding an approval is the same identity that requested it. Separation of duties: a requester can never approve (or deny) their own destructive operation.",
@@ -486,7 +433,7 @@ function explainCode(code) {
   return code in ErrorCodes ? ERROR_KNOWLEDGE[code] : void 0;
 }
 
-// src/server.ts
+// src/tool-result.ts
 function ok(payload) {
   return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
 }
@@ -510,294 +457,385 @@ async function guarded(body) {
   try {
     return ok(await body());
   } catch (error) {
-    if (error instanceof GraftError2) return fail(error);
+    if (error instanceof GraftError) return fail(error);
     throw error;
   }
 }
-function createGraftMcp(options) {
-  const { contentDir, collections } = options;
-  const branchId = options.branchId ?? "main";
-  const staticIndexPath = options.db === void 0 ? options.staticIndexPath : void 0;
-  const maybeDb = options.db;
-  if (maybeDb === void 0 && staticIndexPath === void 0) {
-    throw new GraftError2({
-      code: "CONFIG_INVALID",
-      message: "createGraftMcp needs an index: pass `db` (Postgres) or `staticIndexPath`.",
-      fix: "Pass `db` from createDb(DATABASE_URL), or `staticIndexPath` pointing at the compiled artifact (.graft/index.db) for a static project."
-    });
-  }
-  const requireDb = (feature, insteadDo) => {
-    if (maybeDb !== void 0) return maybeDb;
-    throw new GraftError2({
-      code: "NEEDS_DATABASE",
-      message: `${feature} needs the Postgres index; this project serves a static index (${staticIndexPath}).`,
-      fix: `${insteadDo} To move this project to the Postgres tier: set DATABASE_URL, change graft.config to \`export const index = "postgres"\`, run \`graft db migrate\`, then \`graft compile\`.`,
-      details: { feature, index: "static" }
-    });
-  };
-  const projectContent = async () => staticIndexPath === void 0 ? compile({ contentDir, collections, db: requireDb("compile", ""), branchId }) : compileStatic({ contentDir, collections, indexPath: staticIndexPath });
-  const searchIndex = async (query) => {
-    if (staticIndexPath === void 0) {
-      return searchContent(requireDb("search_content", ""), query);
-    }
-    const index = await openStaticIndex(staticIndexPath);
-    try {
-      return await index.searchContent({
-        query: query.query,
-        collections: query.collections,
-        limit: query.limit
-      });
-    } finally {
-      await index.close();
-    }
-  };
-  const functions = options.functions ?? {};
-  const functionsByName = /* @__PURE__ */ new Map();
-  for (const fn of Object.values(functions)) functionsByName.set(fn.name, fn);
-  let scopePromise;
-  const getScope = () => {
-    scopePromise ??= options.scope ? Promise.resolve(options.scope) : resolveBranchScope(requireDb("Branch scope resolution", ""), branchId);
-    return scopePromise;
-  };
-  let functionsHandler;
-  const getFunctionsHandler = () => {
-    functionsHandler ??= createFunctionsHandler({
-      functions,
-      db: requireDb(
-        "run_function",
-        "Typed functions read and write operational data in Postgres, so a static project has none."
-      ),
-      branch: branchId,
-      actor: options.actor,
-      approvalPolicy: options.approvalPolicy,
-      rateLimit: options.rateLimit,
-      gitSha: options.gitSha,
-      audit: options.audit,
-      approvals: options.approvals
-    });
-    return functionsHandler;
-  };
-  const deleteContentFn = defineFunction({
-    name: "delete_content",
-    kind: "mutation",
-    destructive: true,
-    public: true,
-    description: "Delete an authored MDX document and recompile (MCP delete_content tool).",
-    returns: "{ deleted, branch, gitSha, changes }",
-    input: {
-      collection: field.string({ description: "Collection name" }),
-      slug: field.string({ description: "Document slug to delete" })
-    },
-    handler: async ({ input }) => {
-      const collection = requireCollection(collections, input.collection);
-      const doc = findDoc(contentDir, input.collection, collection, input.slug);
-      unlinkSync(join2(contentDir, ...doc.sourcePath.split("/")));
-      const result = await projectContent();
-      return {
-        deleted: doc.sourcePath,
-        branch: branchId,
-        gitSha: result.gitSha,
-        changes: result.changes
-      };
-    }
-  });
-  let deleteHandler;
-  const getDeleteHandler = () => {
-    deleteHandler ??= createFunctionsHandler({
-      // The one-shot, input-bound human approval lives in Postgres. Rather than
-      // silently downgrading to an ungated delete, a static project is told to
-      // do it the way git already makes safe: delete the file and recompile.
-      db: requireDb(
-        "delete_content",
-        "Its human approval gate is a Postgres table, and dropping the gate would make the delete ungated. In a static project, delete the file and recompile \u2014 git is authoritative, so the file IS the document and git history is the undo."
-      ),
-      functions: { delete_content: deleteContentFn },
-      branch: branchId,
-      actor: options.actor,
-      rateLimit: options.rateLimit,
-      gitSha: options.gitSha,
-      audit: options.audit,
-      approvals: options.approvals
-    });
-    return deleteHandler;
-  };
-  let storagePromise;
-  const getStorage = () => {
-    storagePromise ??= (async () => {
-      if (options.storage) {
-        return typeof options.storage === "function" ? options.storage() : options.storage;
-      }
-      try {
-        return createStorage(storageConfigFromEnv());
-      } catch (error) {
-        throw new GraftError2({
-          code: "ENV_VAR_MISSING",
-          message: error instanceof Error ? error.message : String(error),
-          fix: "Set S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, and S3_BUCKET in the MCP server's environment (.env), then retry.",
-          details: { variables: ["S3_ENDPOINT", "S3_ACCESS_KEY", "S3_SECRET_KEY", "S3_BUCKET"] }
-        });
-      }
-    })();
-    return storagePromise;
-  };
-  const server = new McpServer({
-    name: options.name ?? "graft",
-    version: options.version ?? "0.0.0"
-  });
+
+// src/tools/approvals.ts
+var registerApprovalTools = (server, deps) => {
+  const { branchId, requireDb, requireDecider, requireScope } = deps;
   server.registerTool(
-    "list_collections",
+    "list_approvals",
     {
-      title: "List collections",
-      description: "List every registered content collection (name, description, authority, field count). Start here to learn what kinds of content this project has.",
+      title: "List pending approvals",
+      description: "Pending human-gated approvals. Decide with decide_approval, Studio Approve/Deny, or `graft approve` / `graft deny`. Same data as GET /api/studio/v1/approvals.",
       inputSchema: {}
     },
-    () => guarded(() => ({
-      branch: branchId,
-      collections: Object.values(collections).map((collection) => {
-        const descriptor = collection.describe();
-        return {
-          name: descriptor.name,
-          description: descriptor.description,
-          authority: descriptor.authority,
-          fields: descriptor.fields.length
-        };
-      })
+    () => guarded(async () => ({
+      approvals: (await listPendingApprovals(
+        requireDb(
+          "list_approvals",
+          "Approvals gate destructive operations on operational data, which a static project does not have."
+        )
+      )).map((row) => ({
+        id: row.id,
+        branchId: row.branchId,
+        functionName: row.functionName,
+        input: row.input,
+        requestedByKind: row.requestedByKind,
+        requestedById: row.requestedById,
+        correlationId: row.correlationId,
+        createdAt: row.createdAt.toISOString()
+      }))
     }))
   );
   server.registerTool(
-    "describe_schema",
+    "decide_approval",
     {
-      title: "Describe the content schema",
-      description: "Full schema introspection: every collection with its typed fields (name, type, optional, description), plus every registered function (kind, args, public/destructive). Documents also accept an optional kebab-case `slug` (defaults to the filename). Prefer list_functions / describe_function when you only need the function surface.",
-      inputSchema: {}
+      title: "Approve or deny a pending approval",
+      description: "Record a decision on a pending approval (same as Studio Approve/Deny and `graft approve` / `graft deny`). The decision is attributed to the identity THIS connection authenticated as \u2014 there is no way to name a different decider \u2014 and a requester can never decide their own approval. Requires an authenticated caller and an owner DB role that can UPDATE approvals.",
+      inputSchema: {
+        id: z.string().describe("Pending approval id from list_approvals"),
+        decision: z.enum(["approved", "denied"]).describe("approved or denied")
+      }
     },
-    () => guarded(() => {
+    ({ id, decision }) => guarded(async () => {
+      requireScope("decide_approval", "approvals:decide");
+      const row = await decideApproval(
+        requireDb(
+          "decide_approval",
+          "Approvals gate destructive operations on operational data, which a static project does not have."
+        ),
+        id,
+        decision,
+        requireDecider()
+      );
+      if (!row) {
+        throw new GraftError2({
+          code: "APPROVAL_INVALID",
+          message: `No PENDING approval "${id}" exists \u2014 it may already be decided, consumed, or mistyped.`,
+          fix: "Call list_approvals and use a pending id.",
+          details: { id }
+        });
+      }
       return {
-        collections: Object.values(collections).map((collection) => {
-          const descriptor = collection.describe();
-          return { ...descriptor, fields: descriptor.fields.map(teachAssetFields) };
-        }),
-        functions: [...functionsByName.values()].map((fn) => fn.describe())
+        id: row.id,
+        status: row.status,
+        decidedBy: row.decidedBy,
+        functionName: row.functionName
       };
     })
   );
+};
+
+// src/tools/assets.ts
+import { readFileSync } from "fs";
+import { contentTypeFor, defaultKeyFor } from "@usegraft/assets";
+import { AssetRef } from "@usegraft/core";
+import { resolveContained } from "@usegraft/compiler";
+import { GraftError as GraftError3 } from "@usegraft/contracts";
+import { z as z2 } from "zod";
+var registerAssetTools = (server, deps) => {
+  const { getStorage, options, requireScope } = deps;
+  const uploadRoot = options.localUploadRoot;
   server.registerTool(
-    "list_functions",
-    {
-      title: "List functions",
-      description: "List every registered typed function (name, kind, public, destructive, short description). Use describe_function for the full input schema, then run_function to invoke. Mutations reject anonymous callers unless public: true; destructive functions always require human approval (graft approve).",
-      inputSchema: {}
-    },
-    () => guarded(() => ({
-      branch: branchId,
-      functions: [...functionsByName.values()].map((fn) => {
-        const d = fn.describe();
-        return {
-          name: d.name,
-          kind: d.kind,
-          description: d.description,
-          public: d.public,
-          destructive: d.destructive,
-          args: d.args.length
-        };
-      })
-    }))
-  );
-  server.registerTool(
-    "describe_function",
+    "put_asset",
     {
-      title: "Describe one function",
-      description: "Full introspection for one function: kind, args (name/type/optional/description), returns, public, destructive. Use this before run_function so the input object matches the schema.",
+      title: "Upload an asset (image / binary)",
+      description: (uploadRoot ? "Upload a binary to the asset store and get the frontmatter reference for an `asset` field. Pass `path` (a file inside this project) OR `base64` + `key`. " : "Upload a binary to the asset store and get the frontmatter reference for an `asset` field. Pass `base64` + `key` \u2014 this server reads no files from its own disk. ") + "Refuses to overwrite an existing key unless overwrite: true \u2014 the store keeps no version history. Then reference the returned key from an asset field via write_content.",
       inputSchema: {
-        name: z.string().describe("Function name as returned by list_functions")
+        key: z2.string().optional().describe(
+          'Asset key \u2014 a lowercase path like "pages/pricing/hero.png". Required with base64; defaults to assets/<filename> with path.'
+        ),
+        path: z2.string().optional().describe(
+          uploadRoot ? `Path to a file inside ${uploadRoot} (local/stdio agents).` : "Not available on this server \u2014 send the bytes as `base64` instead."
+        ),
+        base64: z2.string().optional().describe("The file's bytes, base64-encoded (remote/HTTP agents)."),
+        contentType: z2.string().optional().describe("MIME type. Defaults to an inference from the key/path extension."),
+        overwrite: z2.boolean().optional().describe("Replace an existing binary at this key. Off by default.")
       }
     },
-    ({ name }) => guarded(() => {
-      const fn = functionsByName.get(name);
-      if (!fn) {
-        throw new GraftError2({
-          code: "FUNCTION_NOT_FOUND",
-          message: `No function named "${name}" is registered.`,
-          fix: `Call list_functions and use one of: ${[...functionsByName.keys()].join(", ") || "(none registered)"}.`,
-          details: { requested: name, available: [...functionsByName.keys()] }
+    ({ key: keyArg, path, base64, contentType, overwrite }) => guarded(async () => {
+      requireScope("put_asset", "content:write");
+      if (path === void 0 === (base64 === void 0)) {
+        throw new GraftError3({
+          code: "INPUT_VALIDATION_FAILED",
+          message: "Pass exactly one of `path` (a file on the MCP server's machine) or `base64` (the file's bytes).",
+          fix: "Local/stdio agents: pass path. Remote/HTTP agents: read the file yourself and pass base64 + key."
         });
       }
-      return fn.describe();
-    })
-  );
-  server.registerTool(
-    "run_function",
-    {
-      title: "Run a typed function",
-      description: "Invoke a defineFunction by name with a JSON input object. Same pipeline as POST /api/fn/<name>: Zod validation, access rules, rate limits, audit log, and the human gate for destructive ops. The server may already act with a configured identity (graft mcp uses GRAFT_DEV_TOKEN; over HTTP your connection's bearer is forwarded) \u2014 only pass authorization to override it. Pass approval after a human runs `graft approve <id>` for gated calls. Success returns { data, correlationId }; failures are GraftError JSON with a fix.",
-      inputSchema: {
-        name: z.string().describe("Function name (defineFunction name, not the export key)"),
-        input: z.record(z.string(), z.unknown()).optional().describe("Input fields object; defaults to {}. See describe_function for the schema."),
-        authorization: z.string().optional().describe(
-          "Bearer token override (with or without the 'Bearer ' prefix). Usually unnecessary \u2014 the server's configured identity applies when omitted."
-        ),
-        approval: z.string().optional().describe(
-          "Approval id from a prior DESTRUCTIVE_OP_REQUIRES_APPROVAL response (after `graft approve <id>`)."
-        )
+      let bytes;
+      if (path !== void 0) {
+        if (uploadRoot === void 0) {
+          throw new GraftError3({
+            code: "UNAUTHORIZED",
+            message: "This server does not read files from its own disk.",
+            fix: "Read the file yourself and send its bytes as `base64` with a `key`. Reading server-local paths is only available to a local stdio server, which grants it explicitly.",
+            details: { tool: "put_asset" }
+          });
+        }
+        const full = resolveContained(uploadRoot, path, {
+          label: "asset source",
+          allowAbsolute: true
+        });
+        try {
+          bytes = readFileSync(full);
+        } catch {
+          throw new GraftError3({
+            code: "DOCUMENT_NOT_FOUND",
+            message: `File not found: ${path}`,
+            fix: "Pass a path to a file that exists on the machine running this MCP server, or send the bytes as base64 instead.",
+            details: { path }
+          });
+        }
+      } else {
+        if (!/^[A-Za-z0-9+/=\s]+$/.test(base64)) {
+          throw new GraftError3({
+            code: "INPUT_VALIDATION_FAILED",
+            message: "`base64` contains characters outside the base64 alphabet.",
+            fix: "Encode the file's raw bytes as standard base64 (A-Z a-z 0-9 + / =). To upload a file by its location on the server's machine, use `path` instead."
+          });
+        }
+        bytes = Buffer.from(base64, "base64");
       }
-    },
-    ({ name, input, authorization, approval }) => guarded(async () => {
-      if (functionsByName.size === 0) {
-        throw new GraftError2({
-          code: "FUNCTION_NOT_FOUND",
-          message: "This MCP server has no functions registered.",
-          fix: "Export `functions` from graft.config.ts (defineFunction results, often via mergePrimitives) and restart the MCP server / pass them to createGraftMcp({ functions }).",
-          details: { requested: name, available: [] }
+      const key = keyArg ?? (path !== void 0 ? defaultKeyFor(path) : void 0);
+      if (key === void 0) {
+        throw new GraftError3({
+          code: "INPUT_VALIDATION_FAILED",
+          message: "`key` is required when uploading via base64.",
+          fix: 'Pass a lowercase path key naming the asset, e.g. "pages/pricing/hero.png".'
         });
       }
-      if (!functionsByName.has(name)) {
-        throw new GraftError2({
-          code: "FUNCTION_NOT_FOUND",
-          message: `No function named "${name}" is registered.`,
-          fix: `Call list_functions and use one of: ${[...functionsByName.keys()].join(", ")}.`,
-          details: { requested: name, available: [...functionsByName.keys()] }
+      const keyCheck = AssetRef.shape.key.safeParse(key);
+      if (!keyCheck.success) {
+        throw new GraftError3({
+          code: "INPUT_VALIDATION_FAILED",
+          message: `"${key}" is not a valid asset key.`,
+          fix: 'Use a lowercase path of letters, digits, ".", "_", "-" with "/" separators, each segment starting alphanumeric \u2014 e.g. "pages/pricing/hero.png".',
+          details: { key }
         });
       }
-      return invokeFunction(getFunctionsHandler(), name, input ?? {}, {
-        credential: authorization ?? options.defaultAuthorization,
-        approval
-      });
+      const storage = await getStorage();
+      if (overwrite !== true && await storage.exists(key)) {
+        throw new GraftError3({
+          code: "ASSET_EXISTS",
+          message: `Asset key "${key}" already holds a binary.`,
+          fix: "Pick a distinct key (the store keeps no version history), or pass overwrite: true if replacing the existing binary is the actual intent.",
+          details: { key }
+        });
+      }
+      const type = contentType ?? contentTypeFor(key);
+      await storage.put(key, bytes, type);
+      return {
+        key,
+        contentType: type,
+        bytes: bytes.byteLength,
+        url: await storage.url(key),
+        frontmatter: `image:
+  key: ${key}
+  alt: describe the image for screen readers`
+      };
     })
   );
+};
+
+// src/tools/branches.ts
+import { listBranches, listCompilations } from "@usegraft/db";
+import { z as z3 } from "zod";
+var registerBranchTools = (server, deps) => {
+  const { branchId, requireDb } = deps;
   server.registerTool(
-    "list_registry",
+    "list_branches",
     {
-      title: "List registry items",
-      description: "List every owned primitive available to `graft add` \u2014 shadcn-style copy-in blocks / fields / access rules / bundles (name, type, one-line description, and any registry items it pulls in). Use describe_item for the full details, then install with `graft add <name>` from the CLI. MCP browses what exists; the CLI installs it.",
+      title: "List branches",
+      description: "List registered content branches (name, parent, backend, status). Same data as GET /api/studio/v1/branches and `graft branch`.",
       inputSchema: {}
     },
-    () => guarded(() => ({
-      items: listItems(options.registryRoot).map((item) => ({
-        name: item.name,
-        type: item.type,
-        description: item.description,
-        registryDependencies: item.registryDependencies
+    () => guarded(async () => ({
+      branches: (await listBranches(
+        requireDb(
+          "list_branches",
+          "Copy-on-write preview branches are a database feature; in a static project a branch is simply a git branch, and each checkout compiles its own artifact."
+        )
+      )).map((row) => ({
+        name: row.name,
+        parent: row.parent,
+        backend: row.backend,
+        status: row.status,
+        createdAt: row.createdAt.toISOString(),
+        endpointHost: row.endpointHost
       }))
     }))
   );
   server.registerTool(
-    "describe_item",
+    "list_compilations",
     {
-      title: "Describe a registry item",
-      description: "Full details for one owned primitive: type, description, the files it writes into the project, npm dependencies to install, the registry items it pulls in first, and whether it ships an llms.txt fragment. Use list_registry for names; install with `graft add <name>` (CLI). MCP does not install.",
+      title: "List compilations",
+      description: "Recent content projection trail rows (git SHA, added/changed/removed counts), newest first. Same data as GET /api/studio/v1/compilations and `graft compilations`.",
       inputSchema: {
-        name: z.string().describe("Item name as returned by list_registry")
+        branch: z3.string().optional().describe("Restrict to one branch id (default: all branches)"),
+        limit: z3.number().optional().describe("Max rows, newest first (default 20, max 100)")
       }
     },
-    ({ name }) => guarded(() => describeItem(loadItem(name, options.registryRoot)))
+    ({ branch, limit }) => guarded(async () => ({
+      compilations: (await listCompilations(
+        requireDb(
+          "list_compilations",
+          "The Postgres index keeps the full projection trail; a static artifact carries only the runs that built it."
+        ),
+        {
+          branchId: branch,
+          limit
+        }
+      )).map((row) => ({
+        id: row.id,
+        branchId: row.branchId,
+        gitSha: row.gitSha,
+        docCount: row.docCount,
+        added: row.added,
+        changed: row.changed,
+        removed: row.removed,
+        createdAt: row.createdAt.toISOString()
+      }))
+    }))
+  );
+};
+
+// src/tools/content.ts
+import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { join as join2 } from "path";
+import {
+  composeDocument,
+  parseDocument as parseDocument2,
+  readCollectionDocs,
+  writeDocumentFile
+} from "@usegraft/compiler";
+import { GraftError as GraftError5 } from "@usegraft/contracts";
+import { assertSafeMdx } from "@usegraft/mdx-safety";
+import { assertSearchQuery, scopeChain } from "@usegraft/db";
+import { z as z4 } from "zod";
+
+// src/tool-helpers.ts
+import { existsSync, readdirSync, readFileSync as readFileSync2, statSync } from "fs";
+import { join } from "path";
+import { parseDocument } from "@usegraft/compiler";
+import {
+  GraftError as GraftError4
+} from "@usegraft/contracts";
+import { APPROVAL_HEADER } from "@usegraft/core";
+async function invokeFunction(handler, name, input, identity) {
+  const headers = new Headers({ "content-type": "application/json" });
+  if (identity.credential) {
+    const token = identity.credential.trim();
+    headers.set(
+      "authorization",
+      token.toLowerCase().startsWith("bearer ") ? token : `Bearer ${token}`
+    );
+  }
+  if (identity.approval) headers.set(APPROVAL_HEADER, identity.approval);
+  const response = await handler(
+    new Request(`http://graft.local/fn/${encodeURIComponent(name)}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(input)
+    })
   );
+  const body = await response.json();
+  const correlationId = response.headers.get("x-graft-correlation-id") ?? void 0;
+  if (!response.ok) {
+    throw graftErrorFromBody(body, correlationId);
+  }
+  const data = body !== null && typeof body === "object" && "data" in body ? body.data : body;
+  return { data, correlationId, status: response.status };
+}
+var ASSET_FIELD_HINT = "Asset reference: the value is an object { key, alt? }. Upload the file with the put_asset tool first \u2014 its response includes the exact snippet to use here.";
+function teachAssetFields(fieldDescriptor) {
+  const taught = {
+    ...fieldDescriptor,
+    ...fieldDescriptor.type === "asset" ? {
+      description: fieldDescriptor.description ? `${fieldDescriptor.description} ${ASSET_FIELD_HINT}` : ASSET_FIELD_HINT
+    } : {}
+  };
+  if (fieldDescriptor.fields) taught.fields = fieldDescriptor.fields.map(teachAssetFields);
+  if (fieldDescriptor.items) taught.items = teachAssetFields(fieldDescriptor.items);
+  return taught;
+}
+function toMcpFix(fix) {
+  if (!fix) return fix;
+  return fix.replace(/the header `x-graft-approval: ([^`]+)`/g, 'the `approval` argument set to "$1"').replace(/WITHOUT the x-graft-approval header/g, "WITHOUT the `approval` argument");
+}
+function graftErrorFromBody(body, correlationId) {
+  if (body !== null && typeof body === "object") {
+    const json = body;
+    if (typeof json.error === "string" && typeof json.message === "string") {
+      return new GraftError4({
+        code: json.error,
+        message: json.message,
+        fix: toMcpFix(json.fix),
+        details: {
+          ...json.details,
+          ...correlationId ? { correlationId } : {}
+        }
+      });
+    }
+  }
+  return new GraftError4({
+    code: "FUNCTION_EXECUTION_FAILED",
+    message: "Function invocation failed with a non-GraftError response.",
+    fix: "Inspect the server logs; retry with list_functions / describe_function to confirm the name and input shape.",
+    details: { body, correlationId }
+  });
+}
+function assertSlugFree(contentDir, collectionName, collection, slug, targetSourcePath) {
+  const dir = join(contentDir, collectionName);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return;
+  for (const name of readdirSync(dir, { recursive: true, encoding: "utf8" })) {
+    const normalized = name.split("\\").join("/");
+    const sourcePath = `${collectionName}/${normalized}`;
+    const full = join(dir, name);
+    if (sourcePath === targetSourcePath || !/\.mdx?$/.test(name) || statSync(full).isDirectory()) {
+      continue;
+    }
+    let existingSlug;
+    try {
+      existingSlug = parseDocument(readFileSync2(full, "utf8"), collection, sourcePath).slug;
+    } catch {
+      continue;
+    }
+    if (existingSlug === slug) {
+      throw new GraftError4({
+        code: "SLUG_NOT_UNIQUE",
+        message: `Slug "${slug}" in collection "${collectionName}" is already used by ${sourcePath}`,
+        fix: `Update that document instead (write_content with slug "${slug}" targets ${targetSourcePath}, but ${sourcePath} owns the slug via frontmatter), or pick a different slug.`,
+        details: { slug, collection: collectionName, existing: sourcePath }
+      });
+    }
+  }
+}
+
+// src/tools/content.ts
+var registerContentTools = (server, deps) => {
+  const {
+    branchId,
+    collections,
+    contentDir,
+    functions,
+    getDeleteHandler,
+    getScope,
+    options,
+    projectContent,
+    requireScope,
+    searchIndex,
+    staticIndexPath
+  } = deps;
   server.registerTool(
     "list_content",
     {
       title: "List documents in a collection",
       description: "List every document in a collection, read from the authored MDX files (git is the source of truth). Returns slug, sourcePath, and frontmatter data.",
       inputSchema: {
-        collection: z.string().describe("Collection name, as returned by list_collections")
+        collection: z4.string().describe("Collection name, as returned by list_collections")
       }
     },
     ({ collection: name }) => guarded(() => {
@@ -819,8 +857,8 @@ function createGraftMcp(options) {
       title: "Get one document",
       description: "Read a single document by collection + slug from the authored MDX files: validated frontmatter data, MDX body, and the file path to edit.",
       inputSchema: {
-        collection: z.string().describe("Collection name"),
-        slug: z.string().describe("Document slug (kebab-case)")
+        collection: z4.string().describe("Collection name"),
+        slug: z4.string().describe("Document slug (kebab-case)")
       }
     },
     ({ collection: name, slug }) => guarded(() => {
@@ -841,9 +879,9 @@ function createGraftMcp(options) {
       title: "Full-text search across content",
       description: 'Search authored content by words, "quoted phrases", `or`, and -exclusions (websearch syntax). Searches the branch\'s effective content in the compiled Postgres index \u2014 on a preview branch that includes documents inherited from parent branches, with branch overrides winning \u2014 so results are as fresh as the last compile (write_content compiles automatically); every hit carries the sourcePath of the file to edit. Ranking weights slug matches over frontmatter over body.',
       inputSchema: {
-        query: z.string().describe('What to find, e.g. pricing "free tier" -enterprise'),
-        collection: z.string().optional().describe("Restrict to one collection (default: all registered collections)"),
-        limit: z.number().optional().describe("Max hits, best-ranked first (default 20)")
+        query: z4.string().describe('What to find, e.g. pricing "free tier" -enterprise'),
+        collection: z4.string().optional().describe("Restrict to one collection (default: all registered collections)"),
+        limit: z4.number().optional().describe("Max hits, best-ranked first (default 20)")
       }
     },
     ({ query, collection: name, limit }) => guarded(async () => {
@@ -873,16 +911,17 @@ function createGraftMcp(options) {
       title: "Write a document (create or update)",
       description: "Author or update a document: validates the data against the collection schema, writes <contentDir>/<collection>/<slug>.mdx, and compiles the content tree into the database. Returns exactly what changed. Git is the version history: commit the file afterwards if you have the server's checkout; remote callers can't and needn't \u2014 the checkout's operator owns the commit.",
       inputSchema: {
-        collection: z.string().describe("Collection name"),
-        slug: z.string().describe("Document slug \u2014 kebab-case; becomes the filename and the URL segment"),
-        data: z.record(z.string(), z.unknown()).describe("Frontmatter data; must satisfy the collection schema (see describe_schema)"),
-        body: z.string().optional().describe("MDX body (markdown). Defaults to empty.")
+        collection: z4.string().describe("Collection name"),
+        slug: z4.string().describe("Document slug \u2014 kebab-case; becomes the filename and the URL segment"),
+        data: z4.record(z4.string(), z4.unknown()).describe("Frontmatter data; must satisfy the collection schema (see describe_schema)"),
+        body: z4.string().optional().describe("MDX body (markdown). Defaults to empty.")
       }
     },
     ({ collection: name, slug, data, body }) => guarded(async () => {
+      requireScope("write_content", "content:write");
       const collection = requireCollection(collections, name);
       if (collection.authority === "db-authoritative") {
-        throw new GraftError2({
+        throw new GraftError5({
           code: "AUTHORITY_MISMATCH",
           message: `Collection "${name}" is db-authoritative \u2014 its records live in Postgres, not as MDX files.`,
           fix: `Write this data through the collection's function endpoint (POST /api/fn/<name>, see llms.txt) instead of write_content. write_content is only for file-authoritative collections.`,
@@ -891,7 +930,7 @@ function createGraftMcp(options) {
       }
       const frontmatterSlug = data.slug;
       if (frontmatterSlug !== void 0 && frontmatterSlug !== slug) {
-        throw new GraftError2({
+        throw new GraftError5({
           code: "INVALID_SLUG",
           message: `data.slug ("${String(frontmatterSlug)}") conflicts with the slug argument ("${slug}")`,
           fix: "Omit `slug` from data \u2014 the slug argument names the file and the document.",
@@ -900,7 +939,8 @@ function createGraftMcp(options) {
       }
       const sourcePath = `${name}/${slug}.mdx`;
       const fullPath = join2(contentDir, ...sourcePath.split("/"));
-      const existingRaw = existsSync2(fullPath) ? readFileSync2(fullPath, "utf8") : void 0;
+      assertSafeMdx(body ?? "", { label: `${name}/${slug}` });
+      const existingRaw = existsSync2(fullPath) ? readFileSync3(fullPath, "utf8") : void 0;
       const raw = composeDocument(existingRaw, data, body ?? "");
       parseDocument2(raw, collection, sourcePath);
       assertSlugFree(contentDir, name, collection, slug, sourcePath);
@@ -920,17 +960,18 @@ function createGraftMcp(options) {
       title: "Delete a document (human-gated)",
       description: "Delete an authored document: removes <contentDir>/<collection>/<slug>.mdx and compiles, so the index soft-deletes it. DESTRUCTIVE and always human-gated \u2014 the first call files an approval and fails with its id; a human decides with `graft approve <id>` (or deny); then retry the SAME collection+slug with `approval: <id>` (the MCP form of the x-graft-approval header). Approvals are one-shot and bound to that exact input. Git is the version history: commit the deletion afterwards if you have the server's checkout; remote callers can't and needn't \u2014 the checkout's operator owns the commit.",
       inputSchema: {
-        collection: z.string().describe("Collection name"),
-        slug: z.string().describe("Document slug to delete"),
-        approval: z.string().optional().describe(
+        collection: z4.string().describe("Collection name"),
+        slug: z4.string().describe("Document slug to delete"),
+        approval: z4.string().optional().describe(
           "Approval id from a prior DESTRUCTIVE_OP_REQUIRES_APPROVAL response, after a human ran `graft approve <id>`."
         )
       }
     },
     ({ collection: name, slug, approval }) => guarded(async () => {
+      requireScope("delete_content", "content:write");
       const collection = requireCollection(collections, name);
       if (collection.authority === "db-authoritative") {
-        throw new GraftError2({
+        throw new GraftError5({
           code: "AUTHORITY_MISMATCH",
           message: `Collection "${name}" is db-authoritative \u2014 its records live in Postgres, not as MDX files.`,
           fix: "Delete records through the collection's typed functions (a destructive defineFunction over deleteRecord \u2014 see list_functions), not delete_content. delete_content is only for file-authoritative collections.",
@@ -947,380 +988,472 @@ function createGraftMcp(options) {
       return { ...data, correlationId };
     })
   );
+  const uploadRoot = options.localUploadRoot;
+};
+
+// src/tools/errors.ts
+import { z as z5 } from "zod";
+var registerErrorTools = (server, deps) => {
+  void deps;
   server.registerTool(
-    "put_asset",
+    "explain_error",
     {
-      title: "Upload an asset (image / binary)",
-      description: "Upload a binary to the asset store and get the frontmatter reference for an `asset` field. Pass `path` (a file on the machine running this MCP server \u2014 the stdio case) OR `base64` + `key` (remote agents send the bytes). Refuses to overwrite an existing key unless overwrite: true \u2014 the store keeps no version history. Then reference the returned key from an asset field via write_content.",
+      title: "Explain a Graft error",
+      description: "Given a GraftError code or its JSON, explain what it means, its typical causes, and how to recover. Use whenever a tool call or compile fails.",
       inputSchema: {
-        key: z.string().optional().describe(
-          'Asset key \u2014 a lowercase path like "pages/pricing/hero.png". Required with base64; defaults to assets/<filename> with path.'
-        ),
-        path: z.string().optional().describe("Path to a file on the MCP server's machine (local/stdio agents)."),
-        base64: z.string().optional().describe("The file's bytes, base64-encoded (remote/HTTP agents)."),
-        contentType: z.string().optional().describe("MIME type. Defaults to an inference from the key/path extension."),
-        overwrite: z.boolean().optional().describe("Replace an existing binary at this key. Off by default.")
+        code: z5.string().optional().describe("An error code, e.g. SCHEMA_VALIDATION_FAILED"),
+        error: z5.string().optional().describe("A full GraftError JSON string, if you have one")
       }
     },
-    ({ key: keyArg, path, base64, contentType, overwrite }) => guarded(async () => {
-      if (path === void 0 === (base64 === void 0)) {
-        throw new GraftError2({
-          code: "INPUT_VALIDATION_FAILED",
-          message: "Pass exactly one of `path` (a file on the MCP server's machine) or `base64` (the file's bytes).",
-          fix: "Local/stdio agents: pass path. Remote/HTTP agents: read the file yourself and pass base64 + key."
-        });
-      }
-      let bytes;
-      if (path !== void 0) {
+    ({ code, error }) => guarded(() => {
+      let parsed;
+      if (error) {
         try {
-          bytes = readFileSync2(path);
+          parsed = JSON.parse(error);
         } catch {
-          throw new GraftError2({
-            code: "DOCUMENT_NOT_FOUND",
-            message: `File not found: ${path}`,
-            fix: "Pass a path to a file that exists on the machine running this MCP server, or send the bytes as base64 instead.",
-            details: { path }
-          });
-        }
-      } else {
-        if (!/^[A-Za-z0-9+/=\s]+$/.test(base64)) {
-          throw new GraftError2({
-            code: "INPUT_VALIDATION_FAILED",
-            message: "`base64` contains characters outside the base64 alphabet.",
-            fix: "Encode the file's raw bytes as standard base64 (A-Z a-z 0-9 + / =). To upload a file by its location on the server's machine, use `path` instead."
-          });
         }
-        bytes = Buffer.from(base64, "base64");
       }
-      const key = keyArg ?? (path !== void 0 ? defaultKeyFor(path) : void 0);
-      if (key === void 0) {
-        throw new GraftError2({
-          code: "INPUT_VALIDATION_FAILED",
-          message: "`key` is required when uploading via base64.",
-          fix: 'Pass a lowercase path key naming the asset, e.g. "pages/pricing/hero.png".'
-        });
+      const effective = code ?? parsed?.error;
+      if (!effective) {
+        return {
+          knownCodes: Object.keys(ERROR_KNOWLEDGE),
+          hint: "Pass `code` or the GraftError JSON as `error`."
+        };
       }
-      const keyCheck = AssetRef.shape.key.safeParse(key);
-      if (!keyCheck.success) {
-        throw new GraftError2({
-          code: "INPUT_VALIDATION_FAILED",
-          message: `"${key}" is not a valid asset key.`,
-          fix: 'Use a lowercase path of letters, digits, ".", "_", "-" with "/" separators, each segment starting alphanumeric \u2014 e.g. "pages/pricing/hero.png".',
-          details: { key }
+      const explanation = explainCode(effective);
+      if (!explanation) {
+        return {
+          code: effective,
+          known: false,
+          knownCodes: Object.keys(ERROR_KNOWLEDGE),
+          hint: "Not a Graft error code. If this came from another system, resolve it there."
+        };
+      }
+      return {
+        ...explanation,
+        // The specific fix from the actual error beats the general recovery advice.
+        specificFix: parsed?.fix,
+        message: parsed?.message
+      };
+    })
+  );
+};
+
+// src/tools/functions.ts
+import { GraftError as GraftError6 } from "@usegraft/contracts";
+import { z as z6 } from "zod";
+var registerFunctionTools = (server, deps) => {
+  const { functions, functionsByName, getFunctionsHandler, options } = deps;
+  server.registerTool(
+    "run_function",
+    {
+      title: "Run a typed function",
+      description: "Invoke a defineFunction by name with a JSON input object. Same pipeline as POST /api/fn/<name>: Zod validation, access rules, rate limits, audit log, and the human gate for destructive ops. The server may already act with a configured identity (graft mcp uses GRAFT_DEV_TOKEN; over HTTP your connection's bearer is forwarded) \u2014 only pass authorization to override it. Pass approval after a human runs `graft approve <id>` for gated calls. Success returns { data, correlationId }; failures are GraftError JSON with a fix.",
+      inputSchema: {
+        name: z6.string().describe("Function name (defineFunction name, not the export key)"),
+        input: z6.record(z6.string(), z6.unknown()).optional().describe("Input fields object; defaults to {}. See describe_function for the schema."),
+        authorization: z6.string().optional().describe(
+          "Bearer token override (with or without the 'Bearer ' prefix). Usually unnecessary \u2014 the server's configured identity applies when omitted."
+        ),
+        approval: z6.string().optional().describe(
+          "Approval id from a prior DESTRUCTIVE_OP_REQUIRES_APPROVAL response (after `graft approve <id>`)."
+        )
+      }
+    },
+    ({ name, input, authorization, approval }) => guarded(async () => {
+      if (functionsByName.size === 0) {
+        throw new GraftError6({
+          code: "FUNCTION_NOT_FOUND",
+          message: "This MCP server has no functions registered.",
+          fix: "Export `functions` from graft.config.ts (defineFunction results, often via mergePrimitives) and restart the MCP server / pass them to createGraftMcp({ functions }).",
+          details: { requested: name, available: [] }
         });
       }
-      const storage = await getStorage();
-      if (overwrite !== true && await storage.exists(key)) {
-        throw new GraftError2({
-          code: "ASSET_EXISTS",
-          message: `Asset key "${key}" already holds a binary.`,
-          fix: "Pick a distinct key (the store keeps no version history), or pass overwrite: true if replacing the existing binary is the actual intent.",
-          details: { key }
+      if (!functionsByName.has(name)) {
+        throw new GraftError6({
+          code: "FUNCTION_NOT_FOUND",
+          message: `No function named "${name}" is registered.`,
+          fix: `Call list_functions and use one of: ${[...functionsByName.keys()].join(", ")}.`,
+          details: { requested: name, available: [...functionsByName.keys()] }
         });
       }
-      const type = contentType ?? contentTypeFor(key);
-      await storage.put(key, bytes, type);
-      return {
-        key,
-        contentType: type,
-        bytes: bytes.byteLength,
-        url: await storage.url(key),
-        frontmatter: `image:
-  key: ${key}
-  alt: describe the image for screen readers`
-      };
+      return invokeFunction(getFunctionsHandler(), name, input ?? {}, {
+        credential: authorization ?? options.defaultAuthorization,
+        approval
+      });
     })
   );
+};
+
+// src/tools/introspection.ts
+import { GraftError as GraftError7 } from "@usegraft/contracts";
+import { z as z7 } from "zod";
+var registerIntrospectionTools = (server, deps) => {
+  const { branchId, collections, functions, functionsByName } = deps;
   server.registerTool(
-    "list_branches",
+    "list_collections",
     {
-      title: "List branches",
-      description: "List registered content branches (name, parent, backend, status). Same data as GET /api/studio/v1/branches and `graft branch`.",
+      title: "List collections",
+      description: "List every registered content collection (name, description, authority, field count). Start here to learn what kinds of content this project has.",
       inputSchema: {}
     },
-    () => guarded(async () => ({
-      branches: (await listBranches(
-        requireDb(
-          "list_branches",
-          "Copy-on-write preview branches are a database feature; in a static project a branch is simply a git branch, and each checkout compiles its own artifact."
-        )
-      )).map((row) => ({
-        name: row.name,
-        parent: row.parent,
-        backend: row.backend,
-        status: row.status,
-        createdAt: row.createdAt.toISOString(),
-        endpointHost: row.endpointHost
-      }))
+    () => guarded(() => ({
+      branch: branchId,
+      collections: Object.values(collections).map((collection) => {
+        const descriptor = collection.describe();
+        return {
+          name: descriptor.name,
+          description: descriptor.description,
+          authority: descriptor.authority,
+          fields: descriptor.fields.length
+        };
+      })
     }))
   );
   server.registerTool(
-    "list_compilations",
+    "describe_schema",
     {
-      title: "List compilations",
-      description: "Recent content projection trail rows (git SHA, added/changed/removed counts), newest first. Same data as GET /api/studio/v1/compilations and `graft compilations`.",
-      inputSchema: {
-        branch: z.string().optional().describe("Restrict to one branch id (default: all branches)"),
-        limit: z.number().optional().describe("Max rows, newest first (default 20, max 100)")
-      }
+      title: "Describe the content schema",
+      description: "Full schema introspection: every collection with its typed fields (name, type, optional, description), plus every registered function (kind, args, public/destructive). Documents also accept an optional kebab-case `slug` (defaults to the filename). Prefer list_functions / describe_function when you only need the function surface.",
+      inputSchema: {}
     },
-    ({ branch, limit }) => guarded(async () => ({
-      compilations: (await listCompilations(
-        requireDb(
-          "list_compilations",
-          "The Postgres index keeps the full projection trail; a static artifact carries only the runs that built it."
-        ),
-        {
-          branchId: branch,
-          limit
-        }
-      )).map((row) => ({
-        id: row.id,
-        branchId: row.branchId,
-        gitSha: row.gitSha,
-        docCount: row.docCount,
-        added: row.added,
-        changed: row.changed,
-        removed: row.removed,
-        createdAt: row.createdAt.toISOString()
-      }))
-    }))
+    () => guarded(() => {
+      return {
+        collections: Object.values(collections).map((collection) => {
+          const descriptor = collection.describe();
+          return { ...descriptor, fields: descriptor.fields.map(teachAssetFields) };
+        }),
+        functions: [...functionsByName.values()].map((fn) => fn.describe())
+      };
+    })
   );
   server.registerTool(
-    "list_approvals",
+    "list_functions",
     {
-      title: "List pending approvals",
-      description: "Pending human-gated approvals. Decide with decide_approval, Studio Approve/Deny, or `graft approve` / `graft deny`. Same data as GET /api/studio/v1/approvals.",
+      title: "List functions",
+      description: "List every registered typed function (name, kind, public, destructive, short description). Use describe_function for the full input schema, then run_function to invoke. Mutations reject anonymous callers unless public: true; destructive functions always require human approval (graft approve).",
       inputSchema: {}
     },
-    () => guarded(async () => ({
-      approvals: (await listPendingApprovals(
-        requireDb(
-          "list_approvals",
-          "Approvals gate destructive operations on operational data, which a static project does not have."
-        )
-      )).map((row) => ({
-        id: row.id,
-        branchId: row.branchId,
-        functionName: row.functionName,
-        input: row.input,
-        requestedByKind: row.requestedByKind,
-        requestedById: row.requestedById,
-        correlationId: row.correlationId,
-        createdAt: row.createdAt.toISOString()
-      }))
+    () => guarded(() => ({
+      branch: branchId,
+      functions: [...functionsByName.values()].map((fn) => {
+        const d = fn.describe();
+        return {
+          name: d.name,
+          kind: d.kind,
+          description: d.description,
+          public: d.public,
+          destructive: d.destructive,
+          args: d.args.length
+        };
+      })
     }))
   );
   server.registerTool(
-    "decide_approval",
+    "describe_function",
     {
-      title: "Approve or deny a pending approval",
-      description: "Record a human decision on a pending approval (same as Studio Approve/Deny and `graft approve` / `graft deny`). Requires an owner DB role that can UPDATE approvals. The requester cannot decide their own approval.",
+      title: "Describe one function",
+      description: "Full introspection for one function: kind, args (name/type/optional/description), returns, public, destructive. Use this before run_function so the input object matches the schema.",
       inputSchema: {
-        id: z.string().describe("Pending approval id from list_approvals"),
-        decision: z.enum(["approved", "denied"]).describe("approved or denied"),
-        decidedBy: z.string().optional().describe("Operator identity stamp (defaults to mcp-operator)")
+        name: z7.string().describe("Function name as returned by list_functions")
       }
     },
-    ({ id, decision, decidedBy }) => guarded(async () => {
-      const row = await decideApproval(
-        requireDb(
-          "decide_approval",
-          "Approvals gate destructive operations on operational data, which a static project does not have."
-        ),
-        id,
-        decision,
-        decidedBy?.trim() || "mcp-operator"
-      );
-      if (!row) {
-        throw new GraftError2({
-          code: "APPROVAL_INVALID",
-          message: `No PENDING approval "${id}" exists \u2014 it may already be decided, consumed, or mistyped.`,
-          fix: "Call list_approvals and use a pending id.",
-          details: { id }
+    ({ name }) => guarded(() => {
+      const fn = functionsByName.get(name);
+      if (!fn) {
+        throw new GraftError7({
+          code: "FUNCTION_NOT_FOUND",
+          message: `No function named "${name}" is registered.`,
+          fix: `Call list_functions and use one of: ${[...functionsByName.keys()].join(", ") || "(none registered)"}.`,
+          details: { requested: name, available: [...functionsByName.keys()] }
         });
       }
-      return {
-        id: row.id,
-        status: row.status,
-        decidedBy: row.decidedBy,
-        functionName: row.functionName
-      };
+      return fn.describe();
     })
   );
+};
+
+// src/tools/registry.ts
+import { describeItem, listItems, loadItem } from "@usegraft/registry";
+import { z as z8 } from "zod";
+var registerRegistryTools = (server, deps) => {
+  const { options } = deps;
+  server.registerTool(
+    "list_registry",
+    {
+      title: "List registry items",
+      description: "List every owned primitive available to `graft add` \u2014 shadcn-style copy-in blocks / fields / access rules / bundles (name, type, one-line description, and any registry items it pulls in). Use describe_item for the full details, then install with `graft add <name>` from the CLI. MCP browses what exists; the CLI installs it.",
+      inputSchema: {}
+    },
+    () => guarded(() => ({
+      items: listItems(options.registryRoot).map((item) => ({
+        name: item.name,
+        type: item.type,
+        description: item.description,
+        registryDependencies: item.registryDependencies
+      }))
+    }))
+  );
   server.registerTool(
-    "explain_error",
+    "describe_item",
     {
-      title: "Explain a Graft error",
-      description: "Given a GraftError code or its JSON, explain what it means, its typical causes, and how to recover. Use whenever a tool call or compile fails.",
+      title: "Describe a registry item",
+      description: "Full details for one owned primitive: type, description, the files it writes into the project, npm dependencies to install, the registry items it pulls in first, and whether it ships an llms.txt fragment. Use list_registry for names; install with `graft add <name>` (CLI). MCP does not install.",
       inputSchema: {
-        code: z.string().optional().describe("An error code, e.g. SCHEMA_VALIDATION_FAILED"),
-        error: z.string().optional().describe("A full GraftError JSON string, if you have one")
+        name: z8.string().describe("Item name as returned by list_registry")
       }
     },
-    ({ code, error }) => guarded(() => {
-      let parsed;
-      if (error) {
-        try {
-          parsed = JSON.parse(error);
-        } catch {
-        }
-      }
-      const effective = code ?? parsed?.error;
-      if (!effective) {
-        return {
-          knownCodes: Object.keys(ERROR_KNOWLEDGE),
-          hint: "Pass `code` or the GraftError JSON as `error`."
-        };
-      }
-      const explanation = explainCode(effective);
-      if (!explanation) {
-        return {
-          code: effective,
-          known: false,
-          knownCodes: Object.keys(ERROR_KNOWLEDGE),
-          hint: "Not a Graft error code. If this came from another system, resolve it there."
-        };
-      }
-      return {
-        ...explanation,
-        // The specific fix from the actual error beats the general recovery advice.
-        specificFix: parsed?.fix,
-        message: parsed?.message
-      };
-    })
-  );
-  return server;
-}
-async function invokeFunction(handler, name, input, identity) {
-  const headers = new Headers({ "content-type": "application/json" });
-  if (identity.credential) {
-    const token = identity.credential.trim();
-    headers.set(
-      "authorization",
-      token.toLowerCase().startsWith("bearer ") ? token : `Bearer ${token}`
-    );
-  }
-  if (identity.approval) headers.set(APPROVAL_HEADER, identity.approval);
-  const response = await handler(
-    new Request(`http://graft.local/fn/${encodeURIComponent(name)}`, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(input)
-    })
+    ({ name }) => guarded(() => describeItem(loadItem(name, options.registryRoot)))
   );
-  const body = await response.json();
-  const correlationId = response.headers.get("x-graft-correlation-id") ?? void 0;
-  if (!response.ok) {
-    throw graftErrorFromBody(body, correlationId);
+};
+
+// src/server.ts
+function createGraftMcp(options) {
+  const { contentDir, collections } = options;
+  const branchId = options.branchId ?? "main";
+  const staticIndexPath = options.db === void 0 ? options.staticIndexPath : void 0;
+  const maybeDb = options.db;
+  if (maybeDb === void 0 && staticIndexPath === void 0) {
+    throw new GraftError8({
+      code: "CONFIG_INVALID",
+      message: "createGraftMcp needs an index: pass `db` (Postgres) or `staticIndexPath`.",
+      fix: "Pass `db` from createDb(DATABASE_URL), or `staticIndexPath` pointing at the compiled artifact (.graft/index.db) for a static project."
+    });
   }
-  const data = body !== null && typeof body === "object" && "data" in body ? body.data : body;
-  return { data, correlationId, status: response.status };
-}
-var ASSET_FIELD_HINT = "Asset reference: the value is an object { key, alt? }. Upload the file with the put_asset tool first \u2014 its response includes the exact snippet to use here.";
-function teachAssetFields(fieldDescriptor) {
-  const taught = {
-    ...fieldDescriptor,
-    ...fieldDescriptor.type === "asset" ? {
-      description: fieldDescriptor.description ? `${fieldDescriptor.description} ${ASSET_FIELD_HINT}` : ASSET_FIELD_HINT
-    } : {}
+  const requireDb = (feature, insteadDo) => {
+    if (maybeDb !== void 0) return maybeDb;
+    throw new GraftError8({
+      code: "NEEDS_DATABASE",
+      message: `${feature} needs the Postgres index; this project serves a static index (${staticIndexPath}).`,
+      fix: `${insteadDo} To move this project to the Postgres tier: set DATABASE_URL, change graft.config to \`export const index = "postgres"\`, run \`graft db migrate\`, then \`graft compile\`.`,
+      details: { feature, index: "static" }
+    });
   };
-  if (fieldDescriptor.fields) taught.fields = fieldDescriptor.fields.map(teachAssetFields);
-  if (fieldDescriptor.items) taught.items = teachAssetFields(fieldDescriptor.items);
-  return taught;
-}
-function toMcpFix(fix) {
-  if (!fix) return fix;
-  return fix.replace(/the header `x-graft-approval: ([^`]+)`/g, 'the `approval` argument set to "$1"').replace(/WITHOUT the x-graft-approval header/g, "WITHOUT the `approval` argument");
-}
-function graftErrorFromBody(body, correlationId) {
-  if (body !== null && typeof body === "object") {
-    const json = body;
-    if (typeof json.error === "string" && typeof json.message === "string") {
-      return new GraftError2({
-        code: json.error,
-        message: json.message,
-        fix: toMcpFix(json.fix),
-        details: {
-          ...json.details,
-          ...correlationId ? { correlationId } : {}
-        }
+  const requireScope = (tool, scope) => {
+    const actor = options.connectionActor;
+    if (actor === void 0) {
+      if (options.actor === void 0) return;
+      throw new GraftError8({
+        code: "CONFIG_INVALID",
+        message: `${tool} cannot be authorized: this server has an actor resolver but was given no connectionActor.`,
+        fix: "Pass `connectionActor` alongside `actor` when building the server \u2014 createGraftMcpHandler does this for you from the bearer it verified. Without it every scope check passes and write tools are ungated.",
+        details: { tool, required: scope }
       });
     }
-  }
-  return new GraftError2({
-    code: "FUNCTION_EXECUTION_FAILED",
-    message: "Function invocation failed with a non-GraftError response.",
-    fix: "Inspect the server logs; retry with list_functions / describe_function to confirm the name and input shape.",
-    details: { body, correlationId }
+    if (actor.kind === "anonymous") return;
+    if ((actor.scopes ?? []).includes(scope)) return;
+    throw new GraftError8({
+      code: "UNAUTHORIZED",
+      message: `${tool} requires the "${scope}" scope, and this credential does not carry it.`,
+      fix: `Mint a token whose scope claim includes "${scope}" (for \`graft serve\`, add it to GRAFT_DEV_SCOPES). Content authoring, asset upload and approval decisions are deliberately separate from ordinary read scopes.`,
+      details: { tool, required: scope, held: actor.scopes ?? [] }
+    });
+  };
+  const requireDecider = () => {
+    const actor = options.connectionActor;
+    if (actor === void 0 || actor.kind === "anonymous" || !actor.id) {
+      throw new GraftError8({
+        code: "UNAUTHORIZED",
+        message: "decide_approval needs to know who is deciding, and this connection is not authenticated as anyone.",
+        fix: "Connect with `Authorization: Bearer <token>` from a trusted issuer (or set GRAFT_DEV_TOKEN for `graft mcp`). Deciding anonymously would make the requester-cannot-decide check meaningless, so it is refused rather than attributed to a placeholder.",
+        details: { tool: "decide_approval", actor: actor?.kind ?? "anonymous" }
+      });
+    }
+    return { kind: actor.kind, id: actor.id };
+  };
+  const projectContent = async () => staticIndexPath === void 0 ? compile({
+    contentDir,
+    collections,
+    db: requireDb("compile", ""),
+    branchId,
+    mdxTrust: options.mdxTrust
+  }) : compileStatic({
+    contentDir,
+    collections,
+    indexPath: staticIndexPath,
+    mdxTrust: options.mdxTrust
   });
-}
-function assertSlugFree(contentDir, collectionName, collection, slug, targetSourcePath) {
-  const dir = join2(contentDir, collectionName);
-  if (!existsSync2(dir) || !statSync2(dir).isDirectory()) return;
-  for (const name of readdirSync2(dir, { recursive: true, encoding: "utf8" })) {
-    const normalized = name.split("\\").join("/");
-    const sourcePath = `${collectionName}/${normalized}`;
-    const full = join2(dir, name);
-    if (sourcePath === targetSourcePath || !/\.mdx?$/.test(name) || statSync2(full).isDirectory()) {
-      continue;
+  const searchIndex = async (query) => {
+    if (staticIndexPath === void 0) {
+      return searchContent(requireDb("search_content", ""), query);
     }
-    let existingSlug;
+    const index = await openStaticIndex(staticIndexPath);
     try {
-      existingSlug = parseDocument2(readFileSync2(full, "utf8"), collection, sourcePath).slug;
-    } catch {
-      continue;
-    }
-    if (existingSlug === slug) {
-      throw new GraftError2({
-        code: "SLUG_NOT_UNIQUE",
-        message: `Slug "${slug}" in collection "${collectionName}" is already used by ${sourcePath}`,
-        fix: `Update that document instead (write_content with slug "${slug}" targets ${targetSourcePath}, but ${sourcePath} owns the slug via frontmatter), or pick a different slug.`,
-        details: { slug, collection: collectionName, existing: sourcePath }
+      return await index.searchContent({
+        query: query.query,
+        collections: query.collections,
+        limit: query.limit
       });
+    } finally {
+      await index.close();
     }
-  }
+  };
+  const functions = options.functions ?? {};
+  const functionsByName = /* @__PURE__ */ new Map();
+  for (const fn of Object.values(functions)) functionsByName.set(fn.name, fn);
+  let scopePromise;
+  const getScope = () => {
+    scopePromise ??= options.scope ? Promise.resolve(options.scope) : resolveBranchScope(requireDb("Branch scope resolution", ""), branchId);
+    return scopePromise;
+  };
+  let functionsHandler;
+  const getFunctionsHandler = () => {
+    functionsHandler ??= createFunctionsHandler({
+      functions,
+      db: requireDb(
+        "run_function",
+        "Typed functions read and write operational data in Postgres, so a static project has none."
+      ),
+      branch: branchId,
+      actor: options.actor,
+      approvalPolicy: options.approvalPolicy,
+      rateLimit: options.rateLimit,
+      gitSha: options.gitSha,
+      audit: options.audit,
+      approvals: options.approvals
+    });
+    return functionsHandler;
+  };
+  const deleteContentFn = defineFunction({
+    name: "delete_content",
+    kind: "mutation",
+    destructive: true,
+    public: true,
+    description: "Delete an authored MDX document and recompile (MCP delete_content tool).",
+    returns: "{ deleted, branch, gitSha, changes }",
+    input: {
+      collection: field.string({ description: "Collection name" }),
+      slug: field.string({ description: "Document slug to delete" })
+    },
+    handler: async ({ input }) => {
+      const collection = requireCollection(collections, input.collection);
+      const doc = findDoc(contentDir, input.collection, collection, input.slug);
+      unlinkSync(join3(contentDir, ...doc.sourcePath.split("/")));
+      const result = await projectContent();
+      return {
+        deleted: doc.sourcePath,
+        branch: branchId,
+        gitSha: result.gitSha,
+        changes: result.changes
+      };
+    }
+  });
+  let deleteHandler;
+  const getDeleteHandler = () => {
+    deleteHandler ??= createFunctionsHandler({
+      // The one-shot, input-bound human approval lives in Postgres. Rather than
+      // silently downgrading to an ungated delete, a static project is told to
+      // do it the way git already makes safe: delete the file and recompile.
+      db: requireDb(
+        "delete_content",
+        "Its human approval gate is a Postgres table, and dropping the gate would make the delete ungated. In a static project, delete the file and recompile \u2014 git is authoritative, so the file IS the document and git history is the undo."
+      ),
+      functions: { delete_content: deleteContentFn },
+      branch: branchId,
+      actor: options.actor,
+      rateLimit: options.rateLimit,
+      gitSha: options.gitSha,
+      audit: options.audit,
+      approvals: options.approvals
+    });
+    return deleteHandler;
+  };
+  let storagePromise;
+  const getStorage = () => {
+    storagePromise ??= (async () => {
+      if (options.storage) {
+        return typeof options.storage === "function" ? options.storage() : options.storage;
+      }
+      try {
+        return createStorage(storageConfigFromEnv());
+      } catch (error) {
+        throw new GraftError8({
+          code: "ENV_VAR_MISSING",
+          message: error instanceof Error ? error.message : String(error),
+          fix: "Set S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY, and S3_BUCKET in the MCP server's environment (.env), then retry.",
+          details: { variables: ["S3_ENDPOINT", "S3_ACCESS_KEY", "S3_SECRET_KEY", "S3_BUCKET"] }
+        });
+      }
+    })();
+    return storagePromise;
+  };
+  const server = new McpServer({
+    name: options.name ?? "graft",
+    version: options.version ?? "0.0.0"
+  });
+  const deps = {
+    options,
+    contentDir,
+    collections,
+    branchId,
+    staticIndexPath,
+    requireDb,
+    requireScope,
+    requireDecider,
+    projectContent,
+    searchIndex,
+    getScope,
+    functions,
+    functionsByName,
+    getFunctionsHandler,
+    getDeleteHandler,
+    getStorage
+  };
+  registerIntrospectionTools(server, deps);
+  registerFunctionTools(server, deps);
+  registerRegistryTools(server, deps);
+  registerContentTools(server, deps);
+  registerAssetTools(server, deps);
+  registerBranchTools(server, deps);
+  registerApprovalTools(server, deps);
+  registerErrorTools(server, deps);
+  return server;
 }
 
 // src/http.ts
-import { GraftError as GraftError3 } from "@usegraft/contracts";
+import { GraftError as GraftError9 } from "@usegraft/contracts";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 function jsonRpcError(status, code, message, headers) {
   return Response.json({ jsonrpc: "2.0", error: { code, message }, id: null }, { status, headers });
 }
 function createGraftMcpHandler(options) {
-  const { actor: resolveActor, requireActor, ...serverOptions } = options;
+  const { actor: resolveActor, allowAnonymous, ...serverOptions } = options;
+  if (resolveActor === void 0 && allowAnonymous !== true) {
+    throw new GraftError9({
+      code: "CONFIG_INVALID",
+      message: "createGraftMcpHandler was given no way to authenticate callers, and this endpoint serves content writes, asset uploads and approval decisions.",
+      fix: "Pass `actor` \u2014 the @usegraft/auth `createActorResolver` seam, the same one the functions route uses. For a local dev server with no auth at all, pass `allowAnonymous: true` explicitly; never do that on anything reachable from a network."
+    });
+  }
   return async (request) => {
     if (request.method !== "POST") {
       return jsonRpcError(405, -32e3, "Method not allowed: this server is stateless (POST only)", {
         allow: "POST"
       });
     }
+    let actor;
     if (resolveActor) {
-      let actor;
       try {
         actor = await resolveActor(request);
       } catch (err) {
-        const message = err instanceof GraftError3 ? `${err.message} ${err.fix ?? ""}`.trim() : "Unauthorized";
+        const message = err instanceof GraftError9 ? `${err.message} ${err.fix ?? ""}`.trim() : "Unauthorized";
         return jsonRpcError(401, -32001, message);
       }
-      if (requireActor && actor.kind === "anonymous") {
+      if (allowAnonymous !== true && actor.kind === "anonymous") {
         return jsonRpcError(
           401,
           -32001,
           "Unauthorized: this MCP endpoint requires authentication. Send `Authorization: Bearer <token>` from a trusted issuer."
         );
       }
-    } else if (requireActor) {
-      return jsonRpcError(
-        401,
-        -32001,
-        "Unauthorized: requireActor is set but no actor resolver is configured \u2014 the server cannot authenticate anyone."
-      );
     }
     const server = createGraftMcp({
       ...serverOptions,
       actor: resolveActor,
+      // Tools that need to know WHO is calling (rather than forward a
+      // credential) read this. It is the same identity the check above just
+      // verified, so a tool can never be told a different one.
+      ...actor === void 0 ? {} : { connectionActor: actor },
       defaultAuthorization: request.headers.get("authorization") ?? serverOptions.defaultAuthorization
     });
     const transport = new WebStandardStreamableHTTPServerTransport({