@usegraft/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1357 @@
+// src/index.ts
+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 {
+  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 { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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";
+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";
+var ERROR_KNOWLEDGE = {
+  SCHEMA_VALIDATION_FAILED: {
+    code: "SCHEMA_VALIDATION_FAILED",
+    meaning: "A document's frontmatter does not satisfy its collection's Zod schema.",
+    typicalCauses: [
+      "A required field is missing from the frontmatter",
+      "A field has the wrong type (e.g. a string where a number is expected)",
+      "The schema changed in graft.config.ts and existing documents were not updated"
+    ],
+    howToRecover: "Call describe_schema to see the exact fields the collection expects, fix the frontmatter (the error's `details.issues` lists every violation), then retry the write or re-run compile."
+  },
+  COLLECTION_NOT_FOUND: {
+    code: "COLLECTION_NOT_FOUND",
+    meaning: "Content referenced a collection that is not registered in the schema.",
+    typicalCauses: [
+      "A typo in the collection name",
+      "A document placed in a folder that has no matching defineCollection",
+      "The collection exists in code but was not passed to compile()/the MCP server"
+    ],
+    howToRecover: "Call list_collections to see what is registered. Either use one of those names, move the file into a registered collection folder, or add a defineCollection for it in graft.config.ts."
+  },
+  CONFIG_NOT_FOUND: {
+    code: "CONFIG_NOT_FOUND",
+    meaning: "No graft.config.{ts,js} was found in the working directory or any parent.",
+    typicalCauses: [
+      "The command was run outside a Graft project",
+      "The project has not been initialized yet"
+    ],
+    howToRecover: "cd into the project root (the directory holding graft.config.ts) and retry, or scaffold a new project with `graft init`."
+  },
+  CONFIG_INVALID: {
+    code: "CONFIG_INVALID",
+    meaning: "graft.config exists but could not be loaded, or it does not export a valid `collections` record.",
+    typicalCauses: [
+      "A syntax or import error in graft.config.ts",
+      "Missing `export const collections = { \u2026 }`",
+      "A collections entry that was not created with defineCollection"
+    ],
+    howToRecover: "Fix graft.config.ts so it imports defineCollection/field from @usegraft/core and exports `collections` as a record of defineCollection results \u2014 the error message names exactly what failed to load or validate."
+  },
+  ALREADY_INITIALIZED: {
+    code: "ALREADY_INITIALIZED",
+    meaning: "`graft init` was run in a directory that already has a graft.config.",
+    typicalCauses: [
+      "Re-running init in an existing project",
+      "Pointing init at the wrong directory"
+    ],
+    howToRecover: "This is already a Graft project \u2014 evolve it by editing the existing graft.config.ts (add collections or fields there), or run `graft init <dir>` against an empty directory."
+  },
+  ENV_VAR_MISSING: {
+    code: "ENV_VAR_MISSING",
+    meaning: "A required environment variable is not set.",
+    typicalCauses: [
+      "The project has no .env file yet",
+      "The variable exists in a different environment (e.g. CI but not local)"
+    ],
+    howToRecover: "Add the variable named in `details.variable` to the project's .env (the CLI walks parent directories to find one) or export it in the environment, then retry."
+  },
+  CONTENT_DIR_NOT_FOUND: {
+    code: "CONTENT_DIR_NOT_FOUND",
+    meaning: "The configured content directory does not exist on disk.",
+    typicalCauses: [
+      "The project has no content/ directory yet",
+      "compile() was pointed at the wrong path"
+    ],
+    howToRecover: "Create the directory (documents live at <contentDir>/<collection>/<slug>.mdx) or correct the contentDir passed to compile()/the MCP server. write_content creates folders automatically."
+  },
+  CONTENT_REFERENCE_NOT_FOUND: {
+    code: "CONTENT_REFERENCE_NOT_FOUND",
+    meaning: "A document references another document that does not exist.",
+    typicalCauses: [
+      "The referenced document was deleted or renamed",
+      "A slug typo in the reference"
+    ],
+    howToRecover: "Create the missing document, or update the reference to point at an existing collection/slug (list_content shows what exists)."
+  },
+  DOCUMENT_NOT_FOUND: {
+    code: "DOCUMENT_NOT_FOUND",
+    meaning: "No document with the requested slug exists in that collection's files.",
+    typicalCauses: [
+      "A slug typo",
+      "The document lives in a different collection",
+      "The document was deleted (git is authoritative \u2014 the files are the truth)"
+    ],
+    howToRecover: "Call list_content for the collection to see every slug that exists, then retry with a real one \u2014 or author the document with write_content."
+  },
+  FUNCTION_NOT_FOUND: {
+    code: "FUNCTION_NOT_FOUND",
+    meaning: "The invoked function name is not registered in the functions runtime.",
+    typicalCauses: [
+      "A typo in the function name (the last path segment of the POST URL)",
+      "The function exists in code but was not included in the exported `functions` record"
+    ],
+    howToRecover: "The error's `details.available` lists every registered function \u2014 call one of those, or add a defineFunction to graft.config.ts and include it in the exported `functions`."
+  },
+  INPUT_VALIDATION_FAILED: {
+    code: "INPUT_VALIDATION_FAILED",
+    meaning: "A function invocation's input does not satisfy the function's Zod input schema.",
+    typicalCauses: [
+      "The request body is not a JSON object",
+      "A required input field is missing or has the wrong type"
+    ],
+    howToRecover: "Fix the fields listed in `details.issues` and retry. describe_schema shows each function's exact input fields; an empty body is treated as {}."
+  },
+  FUNCTION_EXECUTION_FAILED: {
+    code: "FUNCTION_EXECUTION_FAILED",
+    meaning: "The function's handler threw an unexpected (non-Graft) error \u2014 a bug in the handler or its environment, not in the caller's input.",
+    typicalCauses: [
+      "A runtime error inside the handler code",
+      "The database is unreachable or a required env var is missing on the server"
+    ],
+    howToRecover: "Retrying with the same input will fail again. Find the invocation in the server logs via `details.correlationId`, fix the handler code or the server environment, then retry."
+  },
+  METHOD_NOT_ALLOWED: {
+    code: "METHOD_NOT_ALLOWED",
+    meaning: "The endpoint was called with an HTTP method it does not serve.",
+    typicalCauses: [
+      "GETting a function endpoint (functions are RPC over POST)",
+      "A client following a redirect that downgraded the method"
+    ],
+    howToRecover: "Use the method named in the `Allow` response header \u2014 for Graft functions, POST a JSON object body to the same URL."
+  },
+  ROUTE_NOT_FOUND: {
+    code: "ROUTE_NOT_FOUND",
+    meaning: "The Graft server (`graft serve`) has nothing mounted at the requested path \u2014 the request reached the right process but the wrong URL.",
+    typicalCauses: [
+      "A typo in the endpoint path (e.g. /api/fns instead of /api/fn/<name>)",
+      "Expecting the frontend app's routes on the headless runtime \u2014 graft serve hosts only the function, MCP, and health endpoints"
+    ],
+    howToRecover: "Use POST /api/fn/<name> for typed functions, POST /api/mcp for the MCP Streamable HTTP surface, or GET /healthz for liveness. The error's details carry the path that missed."
+  },
+  AUTHORITY_MISMATCH: {
+    code: "AUTHORITY_MISMATCH",
+    meaning: "An operation used the wrong interface for a collection's authority: files/write_content on a db-authoritative collection, or record helpers on a file-authoritative one.",
+    typicalCauses: [
+      "Authoring an MDX file for a collection whose rows live in Postgres",
+      "Calling insertRecord/listRecords on a collection whose documents are files"
+    ],
+    howToRecover: "Check the collection's authority with describe_schema. File-authoritative \u2192 author MDX (write_content / files + compile). Db-authoritative \u2192 go through its functions (POST /api/fn/<name>); the rows are operational data Postgres owns."
+  },
+  INDEX_OWNERSHIP: {
+    code: "INDEX_OWNERSHIP",
+    meaning: "A projection would soft-delete every document in collections this project's schema doesn't know \u2014 the signature of two projects pointing at one DATABASE_URL. Nothing was written; the transaction rolled back.",
+    typicalCauses: [
+      "DATABASE_URL points at another project's database (e.g. a shared repo-root .env)",
+      "A collection was renamed or deleted in graft.config.ts, so its old rows look foreign"
+    ],
+    howToRecover: "Each project needs its own database or branch: set DATABASE_URL in a .env next to graft.config.ts (it overrides parent .envs). If the schema really did drop or rename a collection, a human runs `graft compile --prune-unknown` once \u2014 the override is CLI-only by design."
+  },
+  NEEDS_DATABASE: {
+    code: "NEEDS_DATABASE",
+    meaning: 'This project runs in static index mode (index = "static" in graft.config), and the requested feature is Postgres-tier: db-authoritative collections, typed functions, or database branching.',
+    typicalCauses: [
+      "A db-authoritative collection or a defineFunction was added to a static-mode project",
+      "graft compile --branch <name> was run in static mode (branches are git branches there)"
+    ],
+    howToRecover: 'Either stay static (content-only: use git branches for previews) or upgrade: set DATABASE_URL in .env and switch graft.config to `export const index = "postgres"`, then re-run `graft compile`.'
+  },
+  CONTENT_TREE_READ_ONLY: {
+    code: "CONTENT_TREE_READ_ONLY",
+    meaning: "A write reached the content tree, but the filesystem refused it. Authored content is files, so writing requires a writable checkout \u2014 serverless platforms deploy a read-only filesystem.",
+    typicalCauses: [
+      "Studio or an MCP write served from a serverless deployment (Vercel, Netlify, Cloudflare)",
+      "A container with the project mounted read-only",
+      "File permissions on the content directory"
+    ],
+    howToRecover: "Run the writing surface where the checkout is writable \u2014 local `graft studio` / `graft mcp`, or a self-hosted container with the project mounted read-write \u2014 and let the deployment serve reads only. Writes then arrive as git commits, which is the model: git is authoritative for authored content."
+  },
+  GIT_UNAVAILABLE: {
+    code: "GIT_UNAVAILABLE",
+    meaning: "An operation needed git and could not reach it: either the `git` binary is not on PATH, or the content directory is not inside a git work tree.",
+    typicalCauses: [
+      "The project was scaffolded but `git init` was never run",
+      "Studio or the CLI running in a container image that ships no git binary",
+      "The content directory lives outside the repository (a mount, a symlink target)"
+    ],
+    howToRecover: "Run `git init` at the project root and make a first commit, or install git. Nothing else in Graft requires it \u2014 content still compiles and serves \u2014 but the change history, `graft compile`'s recorded SHA, and reverting all depend on it."
+  },
+  COMMIT_FAILED: {
+    code: "COMMIT_FAILED",
+    meaning: "git refused to record the commit. The working tree is untouched by the refusal.",
+    typicalCauses: [
+      "No committer identity configured (user.name / user.email)",
+      "A pre-commit or commit-msg hook rejected the change",
+      "Nothing to commit \u2014 the selected paths match the last commit already",
+      "The repository is mid-merge or mid-rebase"
+    ],
+    howToRecover: 'The error\'s `details.stderr` carries git\'s own words. For an unset identity, run `git config user.name "\u2026"` and `git config user.email "\u2026"`. Selected files may already be staged; `git status` shows the current state, and committing from a terminal always remains available.'
+  },
+  STATIC_INDEX_NOT_FOUND: {
+    code: "STATIC_INDEX_NOT_FOUND",
+    meaning: "A read tried to open the static index artifact (.graft/index.db by default), but the file does not exist \u2014 the project has not been compiled yet.",
+    typicalCauses: [
+      "graft compile has never run in this checkout",
+      "The artifact path in graft.config's `index` setting does not match where compile wrote it",
+      "A deploy shipped the app without running graft compile in the build step"
+    ],
+    howToRecover: "Run `graft compile` (or add it before the framework build in the deploy's build command). The artifact must be deployed with the app."
+  },
+  STATIC_INDEX_UNSUPPORTED: {
+    code: "STATIC_INDEX_UNSUPPORTED",
+    meaning: "Static index mode needs the node:sqlite built-in with FTS5, which this Node runtime does not provide (FTS5 ships in the bundled SQLite only from Node 22.16).",
+    typicalCauses: ["Node older than 22.16 running the CLI or the app server"],
+    howToRecover: 'Upgrade Node to 22.16+ (24 LTS recommended), or switch the project to the Postgres index (DATABASE_URL + `export const index = "postgres"`).'
+  },
+  SLUG_NOT_UNIQUE: {
+    code: "SLUG_NOT_UNIQUE",
+    meaning: "Two documents in the same collection resolve to the same slug.",
+    typicalCauses: [
+      "Two files share a filename-derived slug",
+      "A frontmatter `slug` duplicates another file's slug"
+    ],
+    howToRecover: "The error's details list both files. Give one of them a unique slug (frontmatter `slug:` wins over the filename) and re-run compile."
+  },
+  INVALID_SLUG: {
+    code: "INVALID_SLUG",
+    meaning: "A slug is not URL-safe kebab-case.",
+    typicalCauses: [
+      "Uppercase letters, spaces, or punctuation in the slug or filename",
+      "Leading/trailing/double hyphens"
+    ],
+    howToRecover: 'Use lowercase letters, digits, and single hyphens only (e.g. "getting-started"). Set a valid `slug` in frontmatter or rename the file.'
+  },
+  MIGRATION_REQUIRED: {
+    code: "MIGRATION_REQUIRED",
+    meaning: "The schema and the stored content/data have drifted; a migration must run first.",
+    typicalCauses: [
+      "graft.config.ts changed shape while documents still use the old shape",
+      "A database schema change is pending"
+    ],
+    howToRecover: "Run the pending migration (content migrations update the files; DB migrations via @usegraft/db), then retry the operation."
+  },
+  MIGRATION_FAILED: {
+    code: "MIGRATION_FAILED",
+    meaning: "A content or data migration could not be applied; nothing was written (runs are all-or-nothing).",
+    typicalCauses: [
+      "The transform's output does not satisfy the collection's current schema",
+      "The transform threw for some documents/rows",
+      "A file's frontmatter is not parseable YAML"
+    ],
+    howToRecover: "Read details.failures \u2014 each entry names the file/row and why it failed. Fix the transform (or the listed files) in migrations/<id>.ts, then re-run `graft migrate --apply`. Dry-run first with `graft migrate` to see what would change."
+  },
+  UNAUTHORIZED: {
+    code: "UNAUTHORIZED",
+    meaning: "The caller's token does not permit this operation.",
+    typicalCauses: [
+      "A missing or expired agent token",
+      "A token scoped to reads used for a write",
+      "An anonymous call to a mutation that is not marked `public: true` (the secure default)"
+    ],
+    howToRecover: "Obtain a token with the required scope from the project owner; do not retry with the same credentials. If the function is meant to accept anonymous callers, its definition needs `public: true`."
+  },
+  TOKEN_INVALID: {
+    code: "TOKEN_INVALID",
+    meaning: "A bearer token was sent but could not be verified \u2014 different from sending no token (which makes the caller anonymous).",
+    typicalCauses: [
+      "An expired or not-yet-valid JWT",
+      "A token issued by an issuer this deployment does not trust",
+      "A wrong audience claim, a bad signature, or a malformed token"
+    ],
+    howToRecover: "Mint a fresh token from a trusted issuer (details.reason states what failed). Do not strip the Authorization header to fall back to anonymous \u2014 fix the token instead."
+  },
+  RATE_LIMITED: {
+    code: "RATE_LIMITED",
+    meaning: "This caller has invoked the function more times than its per-window limit allows. Every attempt counts, including rejected ones.",
+    typicalCauses: [
+      "A retry loop hammering a function after failures",
+      "Many calls from one actor (or one IP, for anonymous callers) in a short window"
+    ],
+    howToRecover: "Wait out the window (the Retry-After header says how long) before retrying, and fix whatever caused the burst \u2014 the limit is per caller per function, so backing off actually works."
+  },
+  DESTRUCTIVE_OP_REQUIRES_APPROVAL: {
+    code: "DESTRUCTIVE_OP_REQUIRES_APPROVAL",
+    meaning: "The operation is human-gated: a pending approval request was filed (details.approvalId) and the call will not run until a human approves it. Destructive functions are always gated; under the 'human' approval policy every mutation is.",
+    typicalCauses: [
+      "Calling a function marked `destructive: true` (deletes or irreversibly overwrites data)",
+      "Calling any mutation on a deployment whose approvalPolicy is 'human'"
+    ],
+    howToRecover: "Ask a human operator to run `graft approve <approvalId>` (they can also `graft deny` it). Once approved, retry the EXACT same call carrying the approval id \u2014 over MCP pass it as the `approval` tool argument; over raw HTTP send the `x-graft-approval: <approvalId>` header. Approvals are one-shot and bound to the exact input \u2014 never work around the gate."
+  },
+  APPROVAL_INVALID: {
+    code: "APPROVAL_INVALID",
+    meaning: "An approval id was supplied (the `approval` argument over MCP, the x-graft-approval header over raw HTTP), but it cannot authorize this call \u2014 details.reason says why (pending, denied, already_consumed, mismatch, or not_found).",
+    typicalCauses: [
+      "Retrying before a human has decided (pending)",
+      "Reusing an approval \u2014 they are one-shot (already_consumed)",
+      "Changing the input or function between request and retry (mismatch)",
+      "A human refused the operation (denied)"
+    ],
+    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_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.",
+    typicalCauses: [
+      "An agent (or a wrapper acting for it) running `graft approve` on an approval it filed itself",
+      "Passing the requester's identity as the decider (e.g. reusing the same dev-token id)"
+    ],
+    howToRecover: "A DIFFERENT operator must review it: they run `graft approve <id>` (or `graft deny <id>`) under their own identity. Do not retry as the requester and do not switch identities to impersonate a reviewer \u2014 the gate exists so a second party sees the exact function + input before it runs."
+  },
+  BRANCH_NOT_FOUND: {
+    code: "BRANCH_NOT_FOUND",
+    meaning: "An operation referenced a branch that is not registered in the topology.",
+    typicalCauses: [
+      "A typo in the branch name",
+      "Forking from or dropping a branch that was never created",
+      "Expecting a branch to exist that a teammate has not created yet"
+    ],
+    howToRecover: 'List the registered branches (graft branch) to see valid names. "main" is always seeded; create previews off it before forking from or merging them.'
+  },
+  BRANCH_EXISTS: {
+    code: "BRANCH_EXISTS",
+    meaning: "A branch with that name is already registered.",
+    typicalCauses: [
+      "Re-running a create for a branch that already exists",
+      "Two previews competing for the same name"
+    ],
+    howToRecover: "Use the existing branch, pick a different name, or drop the existing one first. Registering a branch is idempotent only if you check first \u2014 names are unique."
+  },
+  BRANCH_INVALID: {
+    code: "BRANCH_INVALID",
+    meaning: "A branch operation was rejected because the name or the topology change is not allowed.",
+    typicalCauses: [
+      "A branch name that is not URL-safe (uppercase, spaces, punctuation)",
+      "Making a branch its own parent, or dropping main",
+      "Dropping a branch that still has child branches"
+    ],
+    howToRecover: 'Use lowercase kebab names with optional "/" segments (e.g. "preview/checkout"). Fork previews from main; drop child branches before their parent; main is the root and cannot be dropped.'
+  },
+  BRANCH_BACKEND_FAILED: {
+    code: "BRANCH_BACKEND_FAILED",
+    meaning: "The branch backend's control plane (the Neon API for `neon` branches) rejected or failed an operation, so the branch's physical state may not match the registry.",
+    typicalCauses: [
+      "An invalid or expired NEON_API_KEY, or one scoped to a different project",
+      "A wrong GRAFT_NEON_PROJECT_ID",
+      "Neon-side limits (max branches) or a transient API outage",
+      "The branch's compute endpoint never became reachable after create"
+    ],
+    howToRecover: "Check NEON_API_KEY and GRAFT_NEON_PROJECT_ID in the environment, then retry. If a create failed partway, the error says whether a Neon branch was left behind \u2014 delete it in the Neon console (or retry the drop) before recreating. Overlay branches never hit this: they need no external API."
+  },
+  REGISTRY_ITEM_NOT_FOUND: {
+    code: "REGISTRY_ITEM_NOT_FOUND",
+    meaning: "`graft add` was asked for a registry item (a copy-in primitive) that does not exist.",
+    typicalCauses: [
+      "A typo in the item name",
+      "Expecting a community/remote item \u2014 only the bundled Tier-1 registry ships today",
+      "The item was renamed or removed"
+    ],
+    howToRecover: "The error's `details.available` lists every item you can add. Run `graft add <name>` with one of those, or build the primitive by hand as owned code under graft/."
+  },
+  REGISTRY_ITEM_INVALID: {
+    code: "REGISTRY_ITEM_INVALID",
+    meaning: "A registry item's manifest is malformed, or the item requires a different @usegraft/core version than the one installed.",
+    typicalCauses: [
+      "registry.item.json does not match the manifest schema",
+      "The item's `graftVersion` range does not include the installed core version",
+      "A file the manifest lists is missing from the item directory"
+    ],
+    howToRecover: "The error names what failed (a manifest field or the version mismatch). For a version mismatch, move @usegraft/core to the range the item needs; a malformed manifest is a registry bug \u2014 fix the item or report it."
+  },
+  REGISTRY_FILE_EXISTS: {
+    code: "REGISTRY_FILE_EXISTS",
+    meaning: "`graft add` would overwrite a file that already exists in the project, so it wrote nothing (adds are all-or-nothing).",
+    typicalCauses: [
+      "The item (or one of its dependencies) was already added",
+      "A project file happens to share a target path with the item"
+    ],
+    howToRecover: "Inspect the listed file(s). If replacing them is intended, re-run with `--overwrite`; otherwise move/rename your file first. `graft add --dry-run <name>` previews every path an item would write."
+  },
+  ASSET_EXISTS: {
+    code: "ASSET_EXISTS",
+    meaning: "An asset upload targeted a key that already holds a binary. The store has no version history, so an overwrite would irreversibly replace it \u2014 uploads refuse unless overwrite is explicit.",
+    typicalCauses: [
+      "Re-uploading with the same key instead of picking a new one",
+      "Two documents' assets colliding on a generic key like assets/hero.png"
+    ],
+    howToRecover: "Pick a distinct key (e.g. prefix it with the document: pages/pricing/hero.png) \u2014 that is almost always right. Only pass `overwrite: true` when replacing the existing binary is the actual intent; every document referencing that key will show the new bytes."
+  },
+  NOT_IMPLEMENTED: {
+    code: "NOT_IMPLEMENTED",
+    meaning: "The capability is planned but not built yet.",
+    typicalCauses: ["Calling a placeholder API from a later phase"],
+    howToRecover: "Use the documented alternative (the error's `fix` names it if one exists), or accomplish the task by editing files directly \u2014 git is always a valid interface."
+  }
+};
+function explainCode(code) {
+  return code in ErrorCodes ? ERROR_KNOWLEDGE[code] : void 0;
+}
+
+// src/server.ts
+function ok(payload) {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+}
+function fail(error) {
+  const explanation = ERROR_KNOWLEDGE[error.code];
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(
+          { ...error.toJSON(), howToRecover: explanation.howToRecover },
+          null,
+          2
+        )
+      }
+    ]
+  };
+}
+async function guarded(body) {
+  try {
+    return ok(await body());
+  } catch (error) {
+    if (error instanceof GraftError2) 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"
+  });
+  server.registerTool(
+    "list_collections",
+    {
+      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(() => ({
+      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(
+    "describe_schema",
+    {
+      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: {}
+    },
+    () => 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_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",
+    {
+      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: {
+        name: z.string().describe("Function name as returned by list_functions")
+      }
+    },
+    ({ 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()] }
+        });
+      }
+      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>`)."
+        )
+      }
+    },
+    ({ 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: [] }
+        });
+      }
+      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()] }
+        });
+      }
+      return invokeFunction(getFunctionsHandler(), name, input ?? {}, {
+        credential: authorization ?? options.defaultAuthorization,
+        approval
+      });
+    })
+  );
+  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(
+    "describe_item",
+    {
+      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: {
+        name: z.string().describe("Item name as returned by list_registry")
+      }
+    },
+    ({ name }) => guarded(() => describeItem(loadItem(name, options.registryRoot)))
+  );
+  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: name }) => guarded(() => {
+      const collection = requireCollection(collections, name);
+      const docs = readCollectionDocs(contentDir, name, collection);
+      return {
+        collection: name,
+        documents: docs.map((doc) => ({
+          slug: doc.slug,
+          sourcePath: doc.sourcePath,
+          data: doc.data
+        }))
+      };
+    })
+  );
+  server.registerTool(
+    "get_content",
+    {
+      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: name, slug }) => guarded(() => {
+      const collection = requireCollection(collections, name);
+      const doc = findDoc(contentDir, name, collection, slug);
+      return {
+        collection: name,
+        slug: doc.slug,
+        sourcePath: doc.sourcePath,
+        data: doc.data,
+        body: doc.body
+      };
+    })
+  );
+  server.registerTool(
+    "search_content",
+    {
+      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, collection: name, limit }) => guarded(async () => {
+      if (name !== void 0) requireCollection(collections, name);
+      assertSearchQuery(query);
+      const collectionNames = name === void 0 ? Object.keys(collections) : [name];
+      const chain = staticIndexPath === void 0 ? scopeChain(await getScope()) : [branchId];
+      const hits = await searchIndex({ query, chain, collections: collectionNames, limit });
+      return {
+        branch: branchId,
+        chain,
+        query,
+        hits: hits.map(({ row, rank, snippet }) => ({
+          collection: row.collection,
+          slug: row.slug,
+          sourcePath: row.sourcePath,
+          rank,
+          snippet,
+          data: row.data
+        }))
+      };
+    })
+  );
+  server.registerTool(
+    "write_content",
+    {
+      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: name, slug, data, body }) => guarded(async () => {
+      const collection = requireCollection(collections, name);
+      if (collection.authority === "db-authoritative") {
+        throw new GraftError2({
+          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.`,
+          details: { collection: name, authority: collection.authority }
+        });
+      }
+      const frontmatterSlug = data.slug;
+      if (frontmatterSlug !== void 0 && frontmatterSlug !== slug) {
+        throw new GraftError2({
+          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.",
+          details: { slug, frontmatterSlug }
+        });
+      }
+      const sourcePath = `${name}/${slug}.mdx`;
+      const fullPath = join2(contentDir, ...sourcePath.split("/"));
+      const existingRaw = existsSync2(fullPath) ? readFileSync2(fullPath, "utf8") : void 0;
+      const raw = composeDocument(existingRaw, data, body ?? "");
+      parseDocument2(raw, collection, sourcePath);
+      assertSlugFree(contentDir, name, collection, slug, sourcePath);
+      writeDocumentFile(fullPath, raw);
+      const result = await projectContent();
+      return {
+        written: sourcePath,
+        branch: branchId,
+        gitSha: result.gitSha,
+        changes: result.changes
+      };
+    })
+  );
+  server.registerTool(
+    "delete_content",
+    {
+      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(
+          "Approval id from a prior DESTRUCTIVE_OP_REQUIRES_APPROVAL response, after a human ran `graft approve <id>`."
+        )
+      }
+    },
+    ({ collection: name, slug, approval }) => guarded(async () => {
+      const collection = requireCollection(collections, name);
+      if (collection.authority === "db-authoritative") {
+        throw new GraftError2({
+          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.",
+          details: { collection: name, authority: collection.authority }
+        });
+      }
+      findDoc(contentDir, name, collection, slug);
+      const { data, correlationId } = await invokeFunction(
+        getDeleteHandler(),
+        "delete_content",
+        { collection: name, slug },
+        { credential: options.defaultAuthorization, approval }
+      );
+      return { ...data, correlationId };
+    })
+  );
+  server.registerTool(
+    "put_asset",
+    {
+      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.",
+      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.")
+      }
+    },
+    ({ 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) {
+        try {
+          bytes = readFileSync2(path);
+        } 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 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 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 }
+        });
+      }
+      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`
+      };
+    })
+  );
+  server.registerTool(
+    "list_branches",
+    {
+      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(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(
+    "list_compilations",
+    {
+      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)")
+      }
+    },
+    ({ 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()
+      }))
+    }))
+  );
+  server.registerTool(
+    "list_approvals",
+    {
+      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(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(
+    "decide_approval",
+    {
+      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.",
+      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)")
+      }
+    },
+    ({ 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 }
+        });
+      }
+      return {
+        id: row.id,
+        status: row.status,
+        decidedBy: row.decidedBy,
+        functionName: row.functionName
+      };
+    })
+  );
+  server.registerTool(
+    "explain_error",
+    {
+      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: {
+        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")
+      }
+    },
+    ({ 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)
+    })
+  );
+  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 GraftError2({
+        code: json.error,
+        message: json.message,
+        fix: toMcpFix(json.fix),
+        details: {
+          ...json.details,
+          ...correlationId ? { correlationId } : {}
+        }
+      });
+    }
+  }
+  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 }
+  });
+}
+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;
+    }
+    let existingSlug;
+    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 }
+      });
+    }
+  }
+}
+
+// src/http.ts
+import { GraftError as GraftError3 } 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;
+  return async (request) => {
+    if (request.method !== "POST") {
+      return jsonRpcError(405, -32e3, "Method not allowed: this server is stateless (POST only)", {
+        allow: "POST"
+      });
+    }
+    if (resolveActor) {
+      let actor;
+      try {
+        actor = await resolveActor(request);
+      } catch (err) {
+        const message = err instanceof GraftError3 ? `${err.message} ${err.fix ?? ""}`.trim() : "Unauthorized";
+        return jsonRpcError(401, -32001, message);
+      }
+      if (requireActor && 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,
+      defaultAuthorization: request.headers.get("authorization") ?? serverOptions.defaultAuthorization
+    });
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
+    try {
+      await server.connect(transport);
+      return await transport.handleRequest(request);
+    } finally {
+      void server.close().catch(() => void 0);
+    }
+  };
+}
+
+// src/index.ts
+async function serveStdio(server) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  await new Promise((resolve) => {
+    const prior = transport.onclose;
+    transport.onclose = () => {
+      prior?.();
+      resolve();
+    };
+  });
+}
+export {
+  ERROR_KNOWLEDGE,
+  createGraftMcp,
+  createGraftMcpHandler,
+  explainCode,
+  serveStdio
+};