@usegraft/mcp 0.1.0 → 0.2.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/feat/core/packages/mcp/CHANGELOG.md) · [Security policy](https://github.com/AndersonDesign1/graft/blob/feat/core/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,6 +61,31 @@ interface GraftMcpOptions {
      * 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. */
     approvalPolicy?: "none" | "human";
     rateLimit?: RateLimit;
@@ -76,6 +116,7 @@ interface GraftMcpOptions {
      */
     storage?: Storage | (() => Storage | Promise<Storage>);
 }
+
 declare function createGraftMcp(options: GraftMcpOptions): McpServer;
 
 interface GraftMcpHandlerOptions extends GraftMcpOptions {
@@ -86,10 +127,19 @@ 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;