@usegraft/mcp 0.1.1 → 1.0.0-beta.0

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

@@ -2,8 +2,16 @@ 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;
@@ -27,6 +35,13 @@ interface GraftMcpOptions {
      * 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;
     /**
@@ -46,7 +61,45 @@ interface GraftMcpOptions {
      * createFunctionsHandler / createGraftMcpHandler. Defaults to anonymous.
      */
     actor?: (request: Request) => FunctionActor | Promise<FunctionActor>;
-    /** Forwarded to createFunctionsHandler for run_function. */
+    /**
+     * 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 `approvalPolicy` in graft.config.ts on
+     * `graft serve`'s /api/fn routes. It just does not reach the tool surface.
+     */
     approvalPolicy?: "none" | "human";
     rateLimit?: RateLimit;
     gitSha?: string;
@@ -58,6 +111,36 @@ interface GraftMcpOptions {
      * 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.
@@ -76,7 +159,26 @@ interface GraftMcpOptions {
      */
     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 {
     /**
@@ -86,13 +188,36 @@ interface GraftMcpHandlerOptions extends GraftMcpOptions {
      */
     actor?: (request: Request) => FunctionActor | Promise<FunctionActor>;
     /**
-     * Reject anonymous callers with 401. Off by default (a dev server on
-     * localhost); turn it on for anything reachable from outside.
+     * 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.
      */
-    requireActor?: boolean;
+    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.
@@ -120,6 +245,12 @@ declare function explainCode(code: string): ErrorExplanation | undefined;
  * `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.
  */
 
@@ -134,4 +265,4 @@ declare function explainCode(code: string): ErrorExplanation | undefined;
  */
 declare function serveStdio(server: McpServer): Promise<void>;
 
-export { ERROR_KNOWLEDGE, type ErrorExplanation, type GraftMcpHandler, type GraftMcpHandlerOptions, type GraftMcpOptions, createGraftMcp, createGraftMcpHandler, explainCode, serveStdio };
+export { type DocsMcpOptions, ERROR_KNOWLEDGE, type ErrorExplanation, type GraftMcpHandler, type GraftMcpHandlerOptions, type GraftMcpOptions, createDocsMcp, createDocsMcpHandler, createGraftMcp, createGraftMcpHandler, explainCode, serveStdio };