@usegraft/mcp 0.0.0-canary-20260831153011

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Joseph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @usegraft/mcp
+
+> An MCP server over your content, schema, and typed functions, with errors an agent can act on.
+
+Part of [Graft](https://github.com/AndersonDesign1/graft), a CMS built so an AI agent is the primary operator.
+
+## Install
+
+```bash
+npm i @usegraft/mcp
+```
+
+## Serve on stdio
+
+For `.mcp.json` and local agents. `graft mcp` does this for you.
+
+```ts
+import { createGraftMcp, serveStdio } from "@usegraft/mcp";
+
+const server = createGraftMcp({ contentDir, collections, functions, db });
+await serveStdio(server);
+```
+
+## Serve over HTTP
+
+```ts
+import { createGraftMcpHandler } from "@usegraft/mcp";
+
+export const POST = createGraftMcpHandler({
+  contentDir,
+  collections,
+  db,
+  actor: resolveActor,
+  connectionActor: resolveConnectionActor,
+});
+```
+
+`connectionActor` is not optional in practice. Without it every write-tool scope check is silently disabled, so pass it whenever a tool can write.
+
+## Tools
+
+Content: `list_content`, `read_content`, `write_content`, `delete_content`, `search_content`. Introspection: `describe_schema`, `list_functions`, `describe_function`. Execution: `run_function`. Registry: `list_registry`, `describe_item`. Approvals: `list_approvals`, `decide_approval`.
+
+## Defaults that fail closed
+
+- Anonymous callers are refused unless explicitly allowed.
+- `write_content` requires the `content:write` scope, and being authenticated earns nothing on its own.
+- `delete_content` is destructive and always human-gated: the first call files an approval and fails with its id.
+- Authored MDX is refused if it contains `{…}` expressions, `import`, `export` or spread attributes, because rendering evaluates MDX as JavaScript on the server.
+
+---
+
+MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/main/packages/mcp/CHANGELOG.md) · [Security policy](https://github.com/AndersonDesign1/graft/blob/main/SECURITY.md)

package/dist/index.d.ts

@@ -0,0 +1,268 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Storage } from '@usegraft/assets';
+import { AnyCollection, AnyGraftFunction, FunctionActor, RateLimit } from '@usegraft/core';
+import { Database, BranchScope, AuditStore, ApprovalStore } from '@usegraft/db';
+import { MdxTrust } from '@usegraft/mdx-safety';
+import { ErrorCode } from '@usegraft/contracts';
+
+/**
+ * How a Graft MCP server is configured.
+ *
+ * Split out of server.ts so tool modules can name it without importing the
+ * server that hosts them.
+ */
+
+interface GraftMcpOptions {
+    /** Absolute path to the content root (documents live at <contentDir>/<collection>/<slug>.mdx). */
+    contentDir: string;
+    collections: Record<string, AnyCollection>;
+    /**
+     * The Postgres content index. Omit only when serving a static project via
+     * `staticIndexPath` — `db` wins if both are somehow set.
+     */
+    db?: Database;
+    /**
+     * Path to a compiled static index artifact (.graft/index.db) — the
+     * zero-service tier. Authoring works exactly as it does on Postgres (files
+     * are the truth, write_content recompiles), and the Postgres-tier tools
+     * (functions, branches, approvals, the gated delete) answer NEEDS_DATABASE
+     * with the upgrade rather than being silently absent.
+     */
+    staticIndexPath?: string;
+    /**
+     * Typed functions from graft.config — enables list_functions / describe_function
+     * / run_function and fills describe_schema.functions. Optional so content-only
+     * projects still work.
+     */
+    functions?: Record<string, AnyGraftFunction>;
+    /**
+     * How much of MDX authored bodies may be, from `mdxTrust` in graft.config.ts.
+     * Defaults to "restricted". Applies to the whole tree on every projection,
+     * not just to bodies arriving through write_content, because compile re-reads
+     * every authored file including the ones that came from git.
+     */
+    mdxTrust?: MdxTrust;
+    /** Content branch to project into. Defaults to "main". */
+    branchId?: string;
+    /**
+     * Resolved read scope for `branchId` (from resolveBranchHandle / resolveBranchScope)
+     * — what makes search_content overlay-aware: an overlay branch searches its full
+     * ancestor chain, so content inherited from parents is found, branch overrides
+     * win, and tombstones hide. When omitted, the server resolves the scope itself
+     * on first search (memoized per server instance, like sdk-core's per-client
+     * memo), so a bare branchId still searches the branch's effective content.
+     */
+    scope?: BranchScope;
+    /** Server identity reported to MCP clients. */
+    name?: string;
+    version?: string;
+    /**
+     * Resolve the caller for run_function (and future gated tools). Same seam as
+     * createFunctionsHandler / createGraftMcpHandler. Defaults to anonymous.
+     */
+    actor?: (request: Request) => FunctionActor | Promise<FunctionActor>;
+    /**
+     * The identity this connection authenticated as, already resolved.
+     *
+     * `actor` above resolves a *Request*, which tools do not have — they are
+     * JSON-RPC calls on an established connection. Tools that need to know who
+     * is calling (rather than merely forwarding a credential) read this instead.
+     * The HTTP handler sets it from the bearer it already verified; `graft mcp`
+     * sets it from the dev-token identity. Absent means anonymous.
+     */
+    connectionActor?: FunctionActor;
+    /**
+     * Directory `put_asset`'s `path` argument may read from, enabling that
+     * argument at all.
+     *
+     * Unset — which is every remote mount — means `put_asset` has no `path`
+     * argument: a remote agent sends bytes as base64 or nothing. It used to pass
+     * the raw string to readFileSync with no containment whatsoever, upload the
+     * result under a key of the caller's choosing, and return a fetchable URL, so
+     * `{ path: "/srv/app/.env" }` was a one-call read of DATABASE_URL, dev tokens
+     * and S3 credentials on any HTTP-mounted server.
+     *
+     * `graft mcp` sets it to the project directory: a local agent uploading a
+     * hero image from the repo is the case the argument exists for.
+     */
+    localUploadRoot?: string;
+    /**
+     * Forwarded to createFunctionsHandler for run_function.
+     *
+     * Deliberately narrower than the core option, which also accepts
+     * `"unattended"`. That policy exists for a deployment with no human to ask —
+     * a scheduled job, a CI step — and an MCP mount is the opposite of that: it
+     * exists because an agent is calling it, and the agent is the party the gate
+     * is there to stop. Allowing it here would let one option turn every
+     * destructive tool an agent can reach into an ungated one.
+     *
+     * A headless deployment that genuinely wants it still has it, on
+     * `createFunctionsHandler` and through `GRAFT_APPROVAL_POLICY` on
+     * `graft serve`'s /api/fn routes. It just does not reach the tool surface.
+     */
+    approvalPolicy?: "none" | "human";
+    rateLimit?: RateLimit;
+    gitSha?: string;
+    /**
+     * Bearer token applied to run_function when the tool call passes no
+     * `authorization` — so the credential lives with the server (env/config),
+     * not in the agent's context window or MCP transcript. An explicit
+     * `authorization` argument still wins. `graft mcp` sets this from
+     * GRAFT_DEV_TOKEN; the HTTP handler forwards the caller's own header.
+     */
+    defaultAuthorization?: string;
+    /**
+     * Ask the connected client's human to decide a pending approval in-band,
+     * instead of failing with an id and waiting for someone to run
+     * `graft approve`.
+     *
+     * **Off unless configured, and it belongs only on a mount whose human is
+     * actually present** — a local stdio server, a desktop client. A remote or
+     * public mount must never set it: there is nobody at the other end to ask,
+     * and an elicitation nobody answers is a destructive call left hanging.
+     *
+     * The reason this needs an explicit `decider` rather than reusing the
+     * connection's identity is the invariant underneath: `decideApproval`
+     * enforces `requested_by_id <> decided_by` in the UPDATE's own WHERE, so a
+     * requester deciding its own approval is refused by Postgres, not by a guard
+     * that could be forgotten. Elicitation changes *how the human is asked*, not
+     * *who is recorded as having answered*. Name the operator sitting at the
+     * machine; if that operator is also the requester, the decision is refused
+     * exactly as it would be from the CLI.
+     *
+     * Deciding is a plain UPDATE on `approvals`, which the hardened runtime role
+     * deliberately cannot perform (see `graft harden`). On such a deployment this
+     * fails, correctly and by construction.
+     */
+    approvalElicitation?: {
+        /** The operator a decision is attributed to. Never the requester. */
+        decider: {
+            kind: string;
+            id: string;
+        };
+    };
+    /**
+     * Audit / approval stores for run_function. Defaults match createFunctionsHandler
+     * (db-backed). Pass `audit: false` in unit tests that do not hit a real DB.
+     */
+    audit?: AuditStore | false;
+    approvals?: ApprovalStore;
+    /**
+     * Registry root for list_registry / describe_item. Defaults to @usegraft/registry's
+     * bundled primitives — the set `graft add` installs from. Tests point it at a fixture.
+     */
+    registryRoot?: string;
+    /**
+     * Asset store for put_asset. Defaults to S3_* env config (same rules as
+     * `graft asset put`), resolved lazily so content-only servers never need it.
+     * Tests inject a fake.
+     */
+    storage?: Storage | (() => Storage | Promise<Storage>);
+}
+
+/**
+ * What a public documentation server needs, which is much less than the full
+ * one. No `functions`, no `actor`, no asset store, no approval elicitation:
+ * omitting them from the type is what keeps them from being configured by
+ * accident on a mount that answers the internet.
+ */
+type DocsMcpOptions = Pick<GraftMcpOptions, "contentDir" | "collections" | "db" | "staticIndexPath" | "branchId" | "scope" | "name" | "version">;
+declare function createGraftMcp(options: GraftMcpOptions): McpServer;
+/**
+ * A public, read-only documentation server.
+ *
+ * A separate factory rather than a flag on `createGraftMcp`, because the
+ * safety property worth having is that the closed mount gains no new way to be
+ * opened. There is no option here that widens the surface; reaching the wider
+ * one means calling the other function.
+ *
+ * Serve it at `/mcp` on the docs domain, which is where clients look.
+ */
+declare function createDocsMcp(options: DocsMcpOptions): McpServer;
+
+interface GraftMcpHandlerOptions extends GraftMcpOptions {
+    /**
+     * Resolve the caller — the same @usegraft/auth `createActorResolver` seam the
+     * functions handler uses. A resolver that throws (TOKEN_INVALID) rejects the
+     * request with 401; per-tool authorization lands with function introspection.
+     */
+    actor?: (request: Request) => FunctionActor | Promise<FunctionActor>;
+    /**
+     * Serve callers who did not authenticate.
+     *
+     * Off by default, and deliberately phrased as an opt-*in* to insecurity: this
+     * handler is built to be embedded in a Next.js route, a self-host container,
+     * Vercel Fluid, or a Worker, and the previous `requireActor` flag defaulted to
+     * off — so forgetting it silently published write_content, put_asset,
+     * delete_content and decide_approval to anyone who found the URL.
+     *
+     * Constructing a handler with neither `actor` nor `allowAnonymous: true`
+     * throws, so a deployer who forgets gets a startup failure with a fix line
+     * rather than an open endpoint.
+     */
+    allowAnonymous?: boolean;
+}
+type GraftMcpHandler = (request: Request) => Promise<Response>;
+declare function createGraftMcpHandler(options: GraftMcpHandlerOptions): GraftMcpHandler;
+/**
+ * A public documentation MCP endpoint, over the same stateless transport.
+ *
+ * Deliberately has no `actor` and no `allowAnonymous`. The full handler refuses
+ * to start without one of them because it serves writes, uploads and approval
+ * decisions; this one serves documentation, so there is nothing to authenticate
+ * and nothing to accidentally leave open. That is the point of it being a
+ * separate function: the closed endpoint gains no new way to be opened.
+ *
+ * Mount it at `/mcp` on the docs domain, which is where clients look —
+ * Mintlify generates one there for every site it hosts, and Cloudflare runs a
+ * documentation server separately from its authenticated API server.
+ */
+declare function createDocsMcpHandler(options: DocsMcpOptions): GraftMcpHandler;
+
+/**
+ * The self-teaching error knowledge base behind the `explain_error` tool.
+ *
+ * Every ErrorCode in @usegraft/contracts has an entry: what the failure means, what
+ * usually causes it, and how to recover. A GraftError's `fix` is specific to one
+ * failure; this registry is the general lesson an agent can apply next time.
+ * A test asserts the registry stays in lockstep with ErrorCodes.
+ */
+
+interface ErrorExplanation {
+    code: ErrorCode;
+    meaning: string;
+    typicalCauses: string[];
+    howToRecover: string;
+}
+declare const ERROR_KNOWLEDGE: Record<ErrorCode, ErrorExplanation>;
+/** Explanation for a code, or undefined if the code is unknown. */
+declare function explainCode(code: string): ErrorExplanation | undefined;
+
+/**
+ * @usegraft/mcp
+ * MCP server: content ops + schema/function introspection + run_function +
+ * registry browse (list_registry / describe_item) + agent-actionable errors.
+ * `createGraftMcp` builds the server; `serveStdio`
+ * binds it to stdio for `.mcp.json` / `graft mcp`; `createGraftMcpHandler`
+ * serves it over Streamable HTTP as a stateless `Request → Response` handler.
+ *
+ * `createDocsMcp` / `createDocsMcpHandler` build the other one: a public,
+ * read-only documentation server for `/mcp` on a docs domain. It is a separate
+ * factory rather than a flag, so the authenticated endpoint gains no new way to
+ * be opened.
+ *
+ * See docs/design-notes/agent-mcp.md.
+ */
+
+/**
+ * Serve an MCP server over stdio (the transport agents' `.mcp.json` entries use).
+ * Resolves when the client disconnects (stdin EOF / transport close), NOT at
+ * connect time — callers await this for the server's whole lifetime and then
+ * clean up. Resolving at connect let `graft mcp` fall through to its
+ * process.exit right after the initialize handshake (latent P6.2 bug caught
+ * by the P6.5 live smoke; the example's `pnpm mcp` script masked it by never
+ * exiting after the await).
+ */
+declare function serveStdio(server: McpServer): Promise<void>;
+
+export { type DocsMcpOptions, ERROR_KNOWLEDGE, type ErrorExplanation, type GraftMcpHandler, type GraftMcpHandlerOptions, type GraftMcpOptions, createDocsMcp, createDocsMcpHandler, createGraftMcp, createGraftMcpHandler, explainCode, serveStdio };