@usegraft/mcp 0.2.0 → 1.0.0-beta.0

package/README.md

@@ -50,4 +50,4 @@ Content: `list_content`, `read_content`, `write_content`, `delete_content`, `sea
 
 ---
 
-MIT. [Repository](https://github.com/AndersonDesign1/graft) · [Changelog](https://github.com/AndersonDesign1/graft/blob/feat/core/packages/mcp/CHANGELOG.md) · [Security policy](https://github.com/AndersonDesign1/graft/blob/feat/core/SECURITY.md)
+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

@@ -86,7 +86,20 @@ interface GraftMcpOptions {
      * hero image from the repo is the case the argument exists for.
      */
     localUploadRoot?: string;
-    /** Forwarded to createFunctionsHandler for run_function. */
+    /**
+     * 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;
@@ -98,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.
@@ -117,7 +160,25 @@ 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 {
     /**
@@ -143,6 +204,20 @@ interface GraftMcpHandlerOptions extends GraftMcpOptions {
 }
 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.
@@ -170,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.
  */
 
@@ -184,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 };