@forumone/throughline 0.0.0 → 1.0.0-next.1

package/dist/mcp/audit-server.js

@@ -0,0 +1,68 @@
+import { AUDIT_MCP_SERVERS } from '../audit/types.js';
+/*
+The collector's server names are not the audit log's server names, and one pair
+disagrees.
+
+`collector.ts` takes a `serverName` for its error messages — the string a
+plugin passes to `declare` and `add`. The audit collection takes an
+`mcpServer`, a Postgres enum (`enum_audit_events_mcp_server`). Six of the seven
+names line up. The seventh does not:
+
+    collector          audit enum
+    approvals          approvals
+    audit              audit
+    components   ->    component      <- singular
+    forms              forms
+    integrations       integrations
+    publishing         publishing
+    -                  payload
+
+So `mcpServer: serverName as AuditMcpServer` compiles and is wrong for the
+components server. It would be wrong *silently*: Payload rejects a select value
+outside the options, `createAuditWriter` swallows every write failure by design
+— "never let audit failures break the original action" — and the result is one
+server whose rows are missing from the log with a `logger.error` nobody reads.
+
+Hence a map, and hence `auditServerFor` refusing rather than guessing. The
+refusal happens where the map is consulted, which is `add` — config time, once,
+at boot — rather than inside a request.
+*/
+const AUDIT_SERVER_BY_COLLECTOR_NAME = {
+    approvals: 'approvals',
+    audit: 'audit',
+    components: 'component',
+    forms: 'forms',
+    integrations: 'integrations',
+    payload: 'payload',
+    publishing: 'publishing',
+};
+/**
+ * The audit log's name for a collector server name, or `undefined` if there
+ * isn't one.
+ *
+ * `undefined` rather than a fallback: a row attributed to the wrong server is
+ * worse than a boot that stops and says which two lists to reconcile. The
+ * caller is `collector.add`, which throws — see `mcpServerRefusal`.
+ */
+export function auditServerFor(serverName) {
+    /*
+    `hasOwn` rather than a bare index, because a bare index into an object
+    literal answers for `constructor` and `toString` — and the return type says
+    `AuditMcpServer | undefined`, so `auditServerFor('constructor')` would hand
+    back `Object` typed as a Postgres enum value and pass every check between
+    here and the insert.
+    */
+    return Object.hasOwn(AUDIT_SERVER_BY_COLLECTOR_NAME, serverName)
+        ? AUDIT_SERVER_BY_COLLECTOR_NAME[serverName]
+        : undefined;
+}
+/** The message `collector.add` throws with when a server has no audit name. */
+export function mcpServerRefusal(serverName) {
+    return (`MCP server "${serverName}" passed an audit writer but has no name in the audit log's ` +
+        `mcpServer enum, so a \`system.error\` row for its tools could not be written. ` +
+        `Known collector names: ${Object.keys(AUDIT_SERVER_BY_COLLECTOR_NAME).join(', ')}. ` +
+        `Audit enum values: ${AUDIT_MCP_SERVERS.join(', ')}. Add "${serverName}" to the map in ` +
+        `core/src/mcp/audit-server.ts, and — if the enum needs a new value — to AUDIT_MCP_SERVERS ` +
+        `with a migration in the host that adds it to enum_audit_events_mcp_server.`);
+}
+//# sourceMappingURL=audit-server.js.map

package/dist/mcp/audit-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-server.js","sourceRoot":"","sources":["../../src/mcp/audit-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAuB,MAAM,mBAAmB,CAAA;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BE;AACF,MAAM,8BAA8B,GAA6C;IAC/E,SAAS,EAAE,WAAW;IACtB,KAAK,EAAE,OAAO;IACd,UAAU,EAAE,WAAW;IACvB,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,cAAc;IAC5B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,YAAY;CACzB,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C;;;;;;MAME;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,8BAA8B,EAAE,UAAU,CAAC;QAC9D,CAAC,CAAC,8BAA8B,CAAC,UAAU,CAAC;QAC5C,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,OAAO,CACL,eAAe,UAAU,8DAA8D;QACvF,gFAAgF;QAChF,0BAA0B,MAAM,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACpF,sBAAsB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,UAAU,kBAAkB;QACxF,2FAA2F;QAC3F,4EAA4E,CAC7E,CAAA;AACH,CAAC"}

package/dist/mcp/collector.d.ts

@@ -0,0 +1,51 @@
+import type { McpToolDefinition } from '../plugin-contract/index.js';
+import { type PayloadMcpTool, type ToPayloadMcpToolOptions } from './payload-mcp.js';
+/** What `plugin-mcp` needs about a tool while the config is being built. */
+export interface McpToolDescriptor {
+    name: string;
+    description: string;
+}
+export interface McpToolCollector {
+    /**
+     * The array to hand `mcpPlugin`. Filled by `declare` at config time and
+     * completed by `add` at `onInit` — and the same array throughout, so do not
+     * copy or spread it, or the tools will be added to something nobody reads.
+     */
+    readonly tools: PayloadMcpTool[];
+    /**
+     * Called by a plugin as the config is built, with its tools' names and
+     * descriptions. This is what `plugin-mcp` turns into per-key checkboxes.
+     */
+    declare(descriptors: readonly McpToolDescriptor[], options?: DeclareToolsOptions): void;
+    /** Called by a plugin at `onInit`, once it can build its handlers. */
+    add(tools: McpToolDefinition[], options?: AddToolsOptions): void;
+    /** Which servers have declared, in the order they did. */
+    readonly servers: string[];
+    /**
+     * Tools declared and never bound. Empty after every server's `onInit` has
+     * run; anything left is a server that declared a tool it does not build.
+     */
+    readonly unbound: string[];
+}
+export interface DeclareToolsOptions {
+    /**
+     * Which server these came from — `'publishing'`, `'approvals'`. Used to name
+     * both sides of a duplicate-name collision, which is the only thing that
+     * makes that error actionable.
+     */
+    serverName?: string;
+}
+export interface AddToolsOptions extends ToPayloadMcpToolOptions, DeclareToolsOptions {
+}
+export type CreateMcpToolCollectorOptions = ToPayloadMcpToolOptions;
+/**
+ * Somewhere for the plugins to put their tools, that the host can pass to
+ * Payload's MCP plugin before they exist.
+ *
+ * Duplicate names are refused rather than silently shadowed. Six servers that
+ * each named their own `publish` were fine while each had its own endpoint; one
+ * server means one namespace, and an MCP client offered two tools with one name
+ * gets whichever registered last.
+ */
+export declare function createMcpToolCollector(options?: CreateMcpToolCollectorOptions): McpToolCollector;
+//# sourceMappingURL=collector.d.ts.map

package/dist/mcp/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/mcp/collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAEpE,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AA4CvG,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,CAAA;IAChC;;;OAGG;IACH,OAAO,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACvF,sEAAsE;IACtE,GAAG,CAAC,KAAK,EAAE,iBAAiB,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;IAChE,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,eAAgB,SAAQ,uBAAuB,EAAE,mBAAmB;CAAG;AAExF,MAAM,MAAM,6BAA6B,GAAG,uBAAuB,CAAA;AAEnE;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,6BAAkC,GAC1C,gBAAgB,CAkGlB"}

package/dist/mcp/collector.js

@@ -0,0 +1,96 @@
+import { auditServerFor, mcpServerRefusal } from './audit-server.js';
+import { toPayloadMcpTools } from './payload-mcp.js';
+/**
+ * Somewhere for the plugins to put their tools, that the host can pass to
+ * Payload's MCP plugin before they exist.
+ *
+ * Duplicate names are refused rather than silently shadowed. Six servers that
+ * each named their own `publish` were fine while each had its own endpoint; one
+ * server means one namespace, and an MCP client offered two tools with one name
+ * gets whichever registered last.
+ */
+export function createMcpToolCollector(options = {}) {
+    const tools = [];
+    const servers = [];
+    const declaredBy = new Map();
+    const slots = new Map();
+    const bound = new Set();
+    return {
+        tools,
+        servers,
+        get unbound() {
+            return [...declaredBy.keys()].filter(name => !bound.has(name));
+        },
+        declare(descriptors, declareOptions = {}) {
+            const { serverName = 'an unnamed server' } = declareOptions;
+            for (const descriptor of descriptors) {
+                const existing = declaredBy.get(descriptor.name);
+                if (existing !== undefined) {
+                    throw new Error(`Two MCP tools are called "${descriptor.name}" — one from ${existing}, one from ` +
+                        `${serverName}. Under a single MCP server a tool name is a namespace, and a client ` +
+                        `offered both gets whichever registered last. Rename one.`);
+                }
+                declaredBy.set(descriptor.name, serverName);
+                /*
+                A slot, not a tool. `name` and `description` are everything the plugin
+                reads now; `parameters` and `handler` arrive at `onInit`, on this same
+                object, because the array identity is what the host handed over.
+                */
+                const slot = {
+                    name: descriptor.name,
+                    description: descriptor.description,
+                    parameters: {},
+                    handler: () => {
+                        throw new Error(`MCP tool "${descriptor.name}" was declared by ${serverName} and never bound. ` +
+                            `A server declares its tools as the config is built and binds their handlers at ` +
+                            `onInit; this one did not reach the second step, so the tool is advertised and ` +
+                            `cannot run.`);
+                    },
+                };
+                slots.set(descriptor.name, slot);
+                tools.push(slot);
+            }
+            servers.push(serverName);
+        },
+        add(incoming, addOptions = {}) {
+            const { serverName = 'an unnamed server', ...toolOptions } = addOptions;
+            /*
+            Which `mcpServer` this server's `system.error` rows carry, resolved once
+            per server at `onInit` rather than per request — and refused rather than
+            guessed, because the collector's names and the audit enum's names are two
+            lists that already disagree about one entry. See `audit-server.ts`.
+      
+            Only when a writer was actually passed. A host wiring tools by hand
+            supplies no `audit`, and it should not have to invent a server name to do
+            that.
+            */
+            const auditServer = auditServerFor(serverName);
+            if (toolOptions.audit && !auditServer) {
+                throw new Error(mcpServerRefusal(serverName));
+            }
+            for (const tool of toPayloadMcpTools(incoming, {
+                ...options,
+                ...toolOptions,
+                ...(auditServer ? { auditServer } : {}),
+            })) {
+                const slot = slots.get(tool.name);
+                if (!slot) {
+                    throw new Error(`${serverName} built an MCP tool called "${tool.name}" that it never declared. ` +
+                        `Add it to that package's tool descriptors: a tool the collector does not know ` +
+                        `about while the config is built gets no per-key checkbox, and \`plugin-mcp\` ` +
+                        `then denies it to every key with no error anywhere.`);
+                }
+                /*
+                Mutated rather than replaced. `mcpPlugin` was handed this array at config
+                time and reads it per request; swapping the element would leave the
+                checkbox pointing at an object nobody serves.
+                */
+                slot.description = tool.description;
+                slot.parameters = tool.parameters;
+                slot.handler = tool.handler;
+                bound.add(tool.name);
+            }
+        },
+    };
+}
+//# sourceMappingURL=collector.js.map

package/dist/mcp/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/mcp/collector.ts"],"names":[],"mappings":"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"}

package/dist/mcp/envelope.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A tool's refusal, in the shape every tool in the suite already returns.
+ *
+ * Three identical copies of this existed, one per server that has an access
+ * predicate. A refusal is a *result*, not an exception: the MCP handler turns a
+ * thrown error into a JSON-RPC error with no room for a reason a caller can act
+ * on, and an agent reading `{ error: … }` can tell the user what happened.
+ *
+ * The role predicates stay with their servers. What counts as an audit reader is
+ * not what counts as a forms author, and collapsing them would put one package's
+ * policy in another's file.
+ *
+ * **`error` is reserved for a refusal.** `toPayloadMcpTool` reads it to set
+ * MCP's `isError` flag, so a *success* result must report failure some other
+ * way — the healthy shapes in this suite use `ok`, `healthy`, `message` and
+ * `details`. A success payload carrying an `error` string would reach the
+ * caller flagged as an error.
+ */
+export declare function deniedEnvelope(reason: string): {
+    error: string;
+};
+//# sourceMappingURL=envelope.d.ts.map

package/dist/mcp/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../../src/mcp/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAEhE"}

package/dist/mcp/envelope.js

@@ -0,0 +1,22 @@
+/**
+ * A tool's refusal, in the shape every tool in the suite already returns.
+ *
+ * Three identical copies of this existed, one per server that has an access
+ * predicate. A refusal is a *result*, not an exception: the MCP handler turns a
+ * thrown error into a JSON-RPC error with no room for a reason a caller can act
+ * on, and an agent reading `{ error: … }` can tell the user what happened.
+ *
+ * The role predicates stay with their servers. What counts as an audit reader is
+ * not what counts as a forms author, and collapsing them would put one package's
+ * policy in another's file.
+ *
+ * **`error` is reserved for a refusal.** `toPayloadMcpTool` reads it to set
+ * MCP's `isError` flag, so a *success* result must report failure some other
+ * way — the healthy shapes in this suite use `ok`, `healthy`, `message` and
+ * `details`. A success payload carrying an `error` string would reach the
+ * caller flagged as an error.
+ */
+export function deniedEnvelope(reason) {
+    return { error: reason };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/mcp/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../src/mcp/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AAC1B,CAAC"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,12 @@
+export { McpMetaSchema, withMeta } from './meta.js';
+export type { McpMeta } from './meta.js';
+export { auditContext } from './audit-context.js';
+export type { AuditContextFields } from './audit-context.js';
+export { toPayloadMcpTool, toPayloadMcpTools } from './payload-mcp.js';
+export type { PayloadMcpRequest, PayloadMcpTool, ToPayloadMcpToolOptions, } from './payload-mcp.js';
+export { createMcpToolCollector } from './collector.js';
+export type { AddToolsOptions, CreateMcpToolCollectorOptions, DeclareToolsOptions, McpToolCollector, McpToolDescriptor, } from './collector.js';
+export { deniedEnvelope } from './envelope.js';
+export { auditServerFor, mcpServerRefusal } from './audit-server.js';
+export { MCP_API_KEYS_SLUG, isMcpApiKeyPrincipal, isSignedIn, mcpApiKeyAccess, signedIn, } from './api-key-access.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACnD,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAE5D,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACtE,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,uBAAuB,GACxB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EACV,eAAe,EACf,6BAA6B,EAC7B,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,QAAQ,GACT,MAAM,qBAAqB,CAAA"}

package/dist/mcp/index.js

@@ -0,0 +1,8 @@
+export { McpMetaSchema, withMeta } from './meta.js';
+export { auditContext } from './audit-context.js';
+export { toPayloadMcpTool, toPayloadMcpTools } from './payload-mcp.js';
+export { createMcpToolCollector } from './collector.js';
+export { deniedEnvelope } from './envelope.js';
+export { auditServerFor, mcpServerRefusal } from './audit-server.js';
+export { MCP_API_KEYS_SLUG, isMcpApiKeyPrincipal, isSignedIn, mcpApiKeyAccess, signedIn, } from './api-key-access.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGjD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAOtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AASvD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AAEpE,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,QAAQ,GACT,MAAM,qBAAqB,CAAA"}

package/dist/mcp/meta.d.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+/**
+ * Optional `_meta` payload Claude can attach to consequential tool calls.
+ * The audit writer reads `userPrompt`, `reasoning`, and `changesSummary`
+ * to give audit log entries narrative context.
+ */
+export declare const McpMetaSchema: z.ZodOptional<z.ZodObject<{
+    userPrompt: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodOptional<z.ZodString>;
+    changesSummary: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    userPrompt?: string | undefined;
+    reasoning?: string | undefined;
+    changesSummary?: string | undefined;
+}, {
+    userPrompt?: string | undefined;
+    reasoning?: string | undefined;
+    changesSummary?: string | undefined;
+}>>;
+export type McpMeta = z.infer<typeof McpMetaSchema>;
+/**
+ * Wraps a Zod object shape in a schema that also accepts an optional `_meta`
+ * field. Plugin authors use this for any tool whose input belongs in the
+ * audit log:
+ *
+ * ```ts
+ * const inputSchema = withMeta({ pageId: z.string() })
+ * type Input = z.infer<typeof inputSchema>  // { pageId: string; _meta?: McpMeta }
+ * ```
+ */
+export declare function withMeta<Shape extends z.ZodRawShape>(shape: Shape): z.ZodObject<Shape & {
+    _meta: z.ZodOptional<z.ZodObject<{
+        userPrompt: z.ZodOptional<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodString>;
+        changesSummary: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        userPrompt?: string | undefined;
+        reasoning?: string | undefined;
+        changesSummary?: string | undefined;
+    }, {
+        userPrompt?: string | undefined;
+        reasoning?: string | undefined;
+        changesSummary?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<Shape & {
+    _meta: z.ZodOptional<z.ZodObject<{
+        userPrompt: z.ZodOptional<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodString>;
+        changesSummary: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        userPrompt?: string | undefined;
+        reasoning?: string | undefined;
+        changesSummary?: string | undefined;
+    }, {
+        userPrompt?: string | undefined;
+        reasoning?: string | undefined;
+        changesSummary?: string | undefined;
+    }>>;
+}>, any> extends infer T ? { [k in keyof T]: T[k]; } : never, z.baseObjectInputType<Shape & {
+    _meta: z.ZodOptional<z.ZodObject<{
+        userPrompt: z.ZodOptional<z.ZodString>;
+        reasoning: z.ZodOptional<z.ZodString>;
+        changesSummary: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        userPrompt?: string | undefined;
+        reasoning?: string | undefined;
+        changesSummary?: string | undefined;
+    }, {
+        userPrompt?: string | undefined;
+        reasoning?: string | undefined;
+        changesSummary?: string | undefined;
+    }>>;
+}> extends infer T_1 ? { [k_1 in keyof T_1]: T_1[k_1]; } : never>;
+//# sourceMappingURL=meta.d.ts.map

package/dist/mcp/meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/mcp/meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;GAMb,CAAA;AAEb,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAA;AAEnD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,CAAC,CAAC,WAAW,EAAE,KAAK,EAAE,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kEAEjE"}

package/dist/mcp/meta.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+/**
+ * Optional `_meta` payload Claude can attach to consequential tool calls.
+ * The audit writer reads `userPrompt`, `reasoning`, and `changesSummary`
+ * to give audit log entries narrative context.
+ */
+export const McpMetaSchema = z
+    .object({
+    userPrompt: z.string().optional(),
+    reasoning: z.string().optional(),
+    changesSummary: z.string().optional(),
+})
+    .optional();
+/**
+ * Wraps a Zod object shape in a schema that also accepts an optional `_meta`
+ * field. Plugin authors use this for any tool whose input belongs in the
+ * audit log:
+ *
+ * ```ts
+ * const inputSchema = withMeta({ pageId: z.string() })
+ * type Input = z.infer<typeof inputSchema>  // { pageId: string; _meta?: McpMeta }
+ * ```
+ */
+export function withMeta(shape) {
+    return z.object({ ...shape, _meta: McpMetaSchema });
+}
+//# sourceMappingURL=meta.js.map

package/dist/mcp/meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/mcp/meta.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC;KAC3B,MAAM,CAAC;IACN,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACtC,CAAC;KACD,QAAQ,EAAE,CAAA;AAIb;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAA8B,KAAY;IAChE,OAAO,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAA;AACrD,CAAC"}

package/dist/mcp/payload-mcp.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import type { Logger, McpToolDefinition } from '../plugin-contract/index.js';
+import type { AuditMcpServer } from '../audit/types.js';
+import type { AuditWriter } from '../audit/writer.js';
+/** The tool shape `plugin-mcp` accepts under its `mcp.tools` option. */
+export interface PayloadMcpTool {
+    name: string;
+    description: string;
+    parameters: z.ZodRawShape;
+    handler: (args: Record<string, unknown>, req: PayloadMcpRequest, extra: unknown) => Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+/**
+ * The half of `PayloadRequest` this adapter reads.
+ *
+ * Declared structurally rather than imported so `core` keeps `payload` a peer
+ * it does not name in a type position — and because `payloadAPI` is a module
+ * augmentation `plugin-mcp` adds, which is only present when that package is
+ * installed.
+ */
+export interface PayloadMcpRequest {
+    user?: {
+        id?: unknown;
+        email?: unknown;
+        name?: unknown;
+        roles?: unknown;
+        groups?: unknown;
+    } | null;
+    payloadAPI?: string;
+    payload?: {
+        logger?: Logger;
+    };
+}
+export interface ToPayloadMcpToolOptions {
+    /**
+     * What to record as the calling key's name.
+     *
+     * `plugin-mcp` authenticates against its own key collection and puts the user
+     * on the request, not the key — so unlike this package's handler, the key's
+     * own name is not recoverable from the request. Pass one if the audit trail
+     * should name something more useful than the strategy.
+     */
+    apiKeyName?: string;
+    logger?: Logger;
+    /**
+     * Where a tool's unhandled throw is recorded, as `system.error`.
+     *
+     * Optional, and absent means the previous behaviour: the throw reaches
+     * `plugin-mcp`, becomes a JSON-RPC error, and leaves no trace. Every server
+     * in the suite passes one; a host wiring a tool by hand need not.
+     */
+    audit?: AuditWriter;
+    /**
+     * Which `mcpServer` those rows are attributed to. Derived from the collector's
+     * `serverName` by `auditServerFor`, which is not the identity function — see
+     * `audit-server.ts`.
+     */
+    auditServer?: AuditMcpServer;
+}
+export declare function toPayloadMcpTool(tool: McpToolDefinition, options?: ToPayloadMcpToolOptions): PayloadMcpTool;
+/** Every tool in a server, in one call. */
+export declare function toPayloadMcpTools(tools: McpToolDefinition[], options?: ToPayloadMcpToolOptions): PayloadMcpTool[];
+//# sourceMappingURL=payload-mcp.d.ts.map

package/dist/mcp/payload-mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-mcp.d.ts","sourceRoot":"","sources":["../../src/mcp/payload-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,MAAM,EAAkB,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAC5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AA0BrD,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,CAAC,CAAC,WAAW,CAAA;IACzB,OAAO,EAAE,CACP,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,OAAO,KACX,OAAO,CAAC;QAAE,OAAO,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CACpF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;IAClG,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,cAAc,CAAA;CAC7B;AAqDD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,iBAAiB,EACvB,OAAO,GAAE,uBAA4B,GACpC,cAAc,CAqBhB;AA0ED,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,iBAAiB,EAAE,EAC1B,OAAO,GAAE,uBAA4B,GACpC,cAAc,EAAE,CAElB"}