@usegraft/mcp 0.1.0

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/dist/index.d.ts

@@ -0,0 +1,137 @@
+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 { ErrorCode } from '@usegraft/contracts';
+
+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>;
+    /** 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>;
+    /** Forwarded to createFunctionsHandler for run_function. */
+    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;
+    /**
+     * 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>);
+}
+declare function createGraftMcp(options: GraftMcpOptions): 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>;
+    /**
+     * Reject anonymous callers with 401. Off by default (a dev server on
+     * localhost); turn it on for anything reachable from outside.
+     */
+    requireActor?: boolean;
+}
+type GraftMcpHandler = (request: Request) => Promise<Response>;
+declare function createGraftMcpHandler(options: GraftMcpHandlerOptions): 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.
+ * 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 { ERROR_KNOWLEDGE, type ErrorExplanation, type GraftMcpHandler, type GraftMcpHandlerOptions, type GraftMcpOptions, createGraftMcp, createGraftMcpHandler, explainCode, serveStdio };