payload-mcp-toolkit 0.3.3 → 0.7.0

package/dist/tools/versions.js

@@ -1,13 +1,17 @@
 import { z } from 'zod';
 import { errorMessage, getDocDisplayName, jsonResponse, requireDraftCollection, stampMcpContext, textResponse } from './_helpers';
 const DEFAULT_LIST_LIMIT = 10;
-/**
- * Lists recent saved versions of a draft document. Returns id, _status,
- * updatedAt, and a compact display name per version so an LLM can pick one
- * to restore.
+/**
+ * Lists recent saved versions of a draft document. Returns id, _status,
+ * updatedAt, and a compact display name per version so an LLM can pick one
+ * to restore.
  */ export function createListVersionsTool(draftCollections) {
     return {
         name: 'listVersions',
+        routing: {
+            kind: 'collection',
+            action: 'read'
+        },
         description: 'List recent saved versions of a document on a draft-enabled collection. ' + 'Use before restoreVersion to pick the right point in time. ' + `Draft-enabled collections: ${[
             ...draftCollections
         ].join(', ') || 'none'}`,
@@ -61,12 +65,16 @@ const DEFAULT_LIST_LIMIT = 10;
         }
     };
 }
-/**
- * Restoring a version creates a new version on top — the previous current
- * state is preserved so the operation is itself reversible.
+/**
+ * Restoring a version creates a new version on top — the previous current
+ * state is preserved so the operation is itself reversible.
  */ export function createRestoreVersionTool(draftCollections) {
     return {
         name: 'restoreVersion',
+        routing: {
+            kind: 'collection',
+            action: 'update'
+        },
         description: 'Restore a document to a previously saved version. ' + 'Use listVersions first to find the version ID. ' + 'Restoring creates a new version on top, so the previous current state is also recoverable. ' + `Draft-enabled collections: ${[
             ...draftCollections
         ].join(', ') || 'none'}`,

package/dist/tools/versions.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tools/versions.ts"],"sourcesContent":["import { z } from 'zod'\nimport type { PayloadRequest } from 'payload'\nimport {\n  errorMessage,\n  getDocDisplayName,\n  jsonResponse,\n  requireDraftCollection,\n  stampMcpContext,\n  textResponse,\n} from './_helpers'\n\nconst DEFAULT_LIST_LIMIT = 10\n\n/**\n * Lists recent saved versions of a draft document. Returns id, _status,\n * updatedAt, and a compact display name per version so an LLM can pick one\n * to restore.\n */\nexport function createListVersionsTool(draftCollections: Set<string>) {\n  return {\n    name: 'listVersions',\n    description:\n      'List recent saved versions of a document on a draft-enabled collection. ' +\n      'Use before restoreVersion to pick the right point in time. ' +\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\n    parameters: {\n      collection: z\n        .string()\n        .describe(\n          `The collection slug. Must be one of: ${[...draftCollections].join(', ') || 'none'}`,\n        ),\n      documentId: z.string().describe('The ID of the document whose versions you want to list'),\n      limit: z\n        .number()\n        .optional()\n        .default(DEFAULT_LIST_LIMIT)\n        .describe(`Maximum number of versions to return (default ${DEFAULT_LIST_LIMIT})`),\n    },\n    handler: async (\n      args: { collection: string; documentId: string; limit?: number },\n      req: PayloadRequest,\n      _extra: unknown,\n    ) => {\n      const { collection, documentId, limit = DEFAULT_LIST_LIMIT } = args\n\n      const guard = requireDraftCollection(collection, draftCollections, 'versions')\n      if (guard) return guard\n\n      stampMcpContext(req)\n\n      try {\n        const result = await req.payload.findVersions({\n          collection: collection as any,\n          where: { parent: { equals: documentId } },\n          sort: '-updatedAt',\n          limit,\n          req,\n          overrideAccess: false,\n          user: req.user,\n        })\n\n        const versions = result.docs.map((v: any) => {\n          const snapshot = v.version || {}\n          return {\n            id: v.id,\n            updatedAt: v.updatedAt,\n            createdAt: v.createdAt,\n            status: snapshot._status ?? 'unknown',\n            displayName: getDocDisplayName(snapshot, `${collection}#${documentId}`),\n            autosave: v.autosave === true,\n          }\n        })\n\n        return jsonResponse({\n          collection,\n          documentId,\n          totalDocs: result.totalDocs,\n          returned: versions.length,\n          versions,\n        })\n      } catch (error) {\n        return textResponse(\n          `Error listing versions for ${collection}#${documentId}: ${errorMessage(error)}`,\n        )\n      }\n    },\n  }\n}\n\n/**\n * Restoring a version creates a new version on top — the previous current\n * state is preserved so the operation is itself reversible.\n */\nexport function createRestoreVersionTool(draftCollections: Set<string>) {\n  return {\n    name: 'restoreVersion',\n    description:\n      'Restore a document to a previously saved version. ' +\n      'Use listVersions first to find the version ID. ' +\n      'Restoring creates a new version on top, so the previous current state is also recoverable. ' +\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\n    parameters: {\n      collection: z\n        .string()\n        .describe(\n          `The collection slug. Must be one of: ${[...draftCollections].join(', ') || 'none'}`,\n        ),\n      versionId: z\n        .string()\n        .describe('The version ID returned by listVersions (NOT the document ID)'),\n    },\n    handler: async (\n      args: { collection: string; versionId: string },\n      req: PayloadRequest,\n      _extra: unknown,\n    ) => {\n      const { collection, versionId } = args\n\n      const guard = requireDraftCollection(collection, draftCollections, 'versions')\n      if (guard) return guard\n\n      stampMcpContext(req)\n\n      try {\n        const restored = await req.payload.restoreVersion({\n          collection: collection as any,\n          id: versionId,\n          req,\n          overrideAccess: false,\n          user: req.user,\n        })\n\n        const restoredId = String((restored as any).id)\n        const displayName = getDocDisplayName(restored, restoredId)\n\n        return textResponse(\n          `Restored ${collection} document \"${displayName}\" (ID: ${restoredId}) ` +\n            `from version ${versionId}. The document is now in draft status — ` +\n            `use publishDraft to make the restored content live.`,\n        )\n      } catch (error) {\n        return textResponse(\n          `Error restoring ${collection} from version ${versionId}: ${errorMessage(error)}`,\n        )\n      }\n    },\n  }\n}\n"],"names":["z","errorMessage","getDocDisplayName","jsonResponse","requireDraftCollection","stampMcpContext","textResponse","DEFAULT_LIST_LIMIT","createListVersionsTool","draftCollections","name","description","join","parameters","collection","string","describe","documentId","limit","number","optional","default","handler","args","req","_extra","guard","result","payload","findVersions","where","parent","equals","sort","overrideAccess","user","versions","docs","map","v","snapshot","version","id","updatedAt","createdAt","status","_status","displayName","autosave","totalDocs","returned","length","error","createRestoreVersionTool","versionId","restored","restoreVersion","restoredId","String"],"mappings":"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"}
+{"version":3,"sources":["../../src/tools/versions.ts"],"sourcesContent":["import { z } from 'zod'\r\nimport type { PayloadRequest } from 'payload'\r\nimport {\r\n  errorMessage,\r\n  getDocDisplayName,\r\n  jsonResponse,\r\n  requireDraftCollection,\r\n  stampMcpContext,\r\n  textResponse,\r\n} from './_helpers'\r\n\r\nconst DEFAULT_LIST_LIMIT = 10\r\n\r\n/**\r\n * Lists recent saved versions of a draft document. Returns id, _status,\r\n * updatedAt, and a compact display name per version so an LLM can pick one\r\n * to restore.\r\n */\r\nexport function createListVersionsTool(draftCollections: Set<string>) {\r\n  return {\r\n    name: 'listVersions',\r\n    routing: { kind: 'collection', action: 'read' } as const,\r\n    description:\r\n      'List recent saved versions of a document on a draft-enabled collection. ' +\r\n      'Use before restoreVersion to pick the right point in time. ' +\r\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\r\n    parameters: {\r\n      collection: z\r\n        .string()\r\n        .describe(\r\n          `The collection slug. Must be one of: ${[...draftCollections].join(', ') || 'none'}`,\r\n        ),\r\n      documentId: z.string().describe('The ID of the document whose versions you want to list'),\r\n      limit: z\r\n        .number()\r\n        .optional()\r\n        .default(DEFAULT_LIST_LIMIT)\r\n        .describe(`Maximum number of versions to return (default ${DEFAULT_LIST_LIMIT})`),\r\n    },\r\n    handler: async (\r\n      args: Record<string, unknown>,\r\n      req: PayloadRequest,\r\n      _extra: unknown,\r\n    ) => {\r\n      const { collection, documentId, limit = DEFAULT_LIST_LIMIT } = args as {\r\n        collection: string\r\n        documentId: string\r\n        limit?: number\r\n      }\r\n\r\n      const guard = requireDraftCollection(collection, draftCollections, 'versions')\r\n      if (guard) return guard\r\n\r\n      stampMcpContext(req)\r\n\r\n      try {\r\n        const result = await req.payload.findVersions({\r\n          collection: collection as any,\r\n          where: { parent: { equals: documentId } },\r\n          sort: '-updatedAt',\r\n          limit,\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })\r\n\r\n        const versions = result.docs.map((v: any) => {\r\n          const snapshot = v.version || {}\r\n          return {\r\n            id: v.id,\r\n            updatedAt: v.updatedAt,\r\n            createdAt: v.createdAt,\r\n            status: snapshot._status ?? 'unknown',\r\n            displayName: getDocDisplayName(snapshot, `${collection}#${documentId}`),\r\n            autosave: v.autosave === true,\r\n          }\r\n        })\r\n\r\n        return jsonResponse({\r\n          collection,\r\n          documentId,\r\n          totalDocs: result.totalDocs,\r\n          returned: versions.length,\r\n          versions,\r\n        })\r\n      } catch (error) {\r\n        return textResponse(\r\n          `Error listing versions for ${collection}#${documentId}: ${errorMessage(error)}`,\r\n        )\r\n      }\r\n    },\r\n  }\r\n}\r\n\r\n/**\r\n * Restoring a version creates a new version on top — the previous current\r\n * state is preserved so the operation is itself reversible.\r\n */\r\nexport function createRestoreVersionTool(draftCollections: Set<string>) {\r\n  return {\r\n    name: 'restoreVersion',\r\n    routing: { kind: 'collection', action: 'update' } as const,\r\n    description:\r\n      'Restore a document to a previously saved version. ' +\r\n      'Use listVersions first to find the version ID. ' +\r\n      'Restoring creates a new version on top, so the previous current state is also recoverable. ' +\r\n      `Draft-enabled collections: ${[...draftCollections].join(', ') || 'none'}`,\r\n    parameters: {\r\n      collection: z\r\n        .string()\r\n        .describe(\r\n          `The collection slug. Must be one of: ${[...draftCollections].join(', ') || 'none'}`,\r\n        ),\r\n      versionId: z\r\n        .string()\r\n        .describe('The version ID returned by listVersions (NOT the document ID)'),\r\n    },\r\n    handler: async (\r\n      args: Record<string, unknown>,\r\n      req: PayloadRequest,\r\n      _extra: unknown,\r\n    ) => {\r\n      const { collection, versionId } = args as { collection: string; versionId: string }\r\n\r\n      const guard = requireDraftCollection(collection, draftCollections, 'versions')\r\n      if (guard) return guard\r\n\r\n      stampMcpContext(req)\r\n\r\n      try {\r\n        const restored = await req.payload.restoreVersion({\r\n          collection: collection as any,\r\n          id: versionId,\r\n          req,\r\n          overrideAccess: false,\r\n          user: req.user,\r\n        })\r\n\r\n        const restoredId = String((restored as any).id)\r\n        const displayName = getDocDisplayName(restored, restoredId)\r\n\r\n        return textResponse(\r\n          `Restored ${collection} document \"${displayName}\" (ID: ${restoredId}) ` +\r\n            `from version ${versionId}. The document is now in draft status — ` +\r\n            `use publishDraft to make the restored content live.`,\r\n        )\r\n      } catch (error) {\r\n        return textResponse(\r\n          `Error restoring ${collection} from version ${versionId}: ${errorMessage(error)}`,\r\n        )\r\n      }\r\n    },\r\n  }\r\n}\r\n"],"names":["z","errorMessage","getDocDisplayName","jsonResponse","requireDraftCollection","stampMcpContext","textResponse","DEFAULT_LIST_LIMIT","createListVersionsTool","draftCollections","name","routing","kind","action","description","join","parameters","collection","string","describe","documentId","limit","number","optional","default","handler","args","req","_extra","guard","result","payload","findVersions","where","parent","equals","sort","overrideAccess","user","versions","docs","map","v","snapshot","version","id","updatedAt","createdAt","status","_status","displayName","autosave","totalDocs","returned","length","error","createRestoreVersionTool","versionId","restored","restoreVersion","restoredId","String"],"mappings":"AAAA,SAASA,CAAC,QAAQ,MAAK;AAEvB,SACEC,YAAY,EACZC,iBAAiB,EACjBC,YAAY,EACZC,sBAAsB,EACtBC,eAAe,EACfC,YAAY,QACP,aAAY;AAEnB,MAAMC,qBAAqB;AAE3B;;;;CAIC,GACD,OAAO,SAASC,uBAAuBC,gBAA6B;IAClE,OAAO;QACLC,MAAM;QACNC,SAAS;YAAEC,MAAM;YAAcC,QAAQ;QAAO;QAC9CC,aACE,6EACA,gEACA,CAAC,2BAA2B,EAAE;eAAIL;SAAiB,CAACM,IAAI,CAAC,SAAS,QAAQ;QAC5EC,YAAY;YACVC,YAAYjB,EACTkB,MAAM,GACNC,QAAQ,CACP,CAAC,qCAAqC,EAAE;mBAAIV;aAAiB,CAACM,IAAI,CAAC,SAAS,QAAQ;YAExFK,YAAYpB,EAAEkB,MAAM,GAAGC,QAAQ,CAAC;YAChCE,OAAOrB,EACJsB,MAAM,GACNC,QAAQ,GACRC,OAAO,CAACjB,oBACRY,QAAQ,CAAC,CAAC,8CAA8C,EAAEZ,mBAAmB,CAAC,CAAC;QACpF;QACAkB,SAAS,OACPC,MACAC,KACAC;YAEA,MAAM,EAAEX,UAAU,EAAEG,UAAU,EAAEC,QAAQd,kBAAkB,EAAE,GAAGmB;YAM/D,MAAMG,QAAQzB,uBAAuBa,YAAYR,kBAAkB;YACnE,IAAIoB,OAAO,OAAOA;YAElBxB,gBAAgBsB;YAEhB,IAAI;gBACF,MAAMG,SAAS,MAAMH,IAAII,OAAO,CAACC,YAAY,CAAC;oBAC5Cf,YAAYA;oBACZgB,OAAO;wBAAEC,QAAQ;4BAAEC,QAAQf;wBAAW;oBAAE;oBACxCgB,MAAM;oBACNf;oBACAM;oBACAU,gBAAgB;oBAChBC,MAAMX,IAAIW,IAAI;gBAChB;gBAEA,MAAMC,WAAWT,OAAOU,IAAI,CAACC,GAAG,CAAC,CAACC;oBAChC,MAAMC,WAAWD,EAAEE,OAAO,IAAI,CAAC;oBAC/B,OAAO;wBACLC,IAAIH,EAAEG,EAAE;wBACRC,WAAWJ,EAAEI,SAAS;wBACtBC,WAAWL,EAAEK,SAAS;wBACtBC,QAAQL,SAASM,OAAO,IAAI;wBAC5BC,aAAahD,kBAAkByC,UAAU,GAAG1B,WAAW,CAAC,EAAEG,YAAY;wBACtE+B,UAAUT,EAAES,QAAQ,KAAK;oBAC3B;gBACF;gBAEA,OAAOhD,aAAa;oBAClBc;oBACAG;oBACAgC,WAAWtB,OAAOsB,SAAS;oBAC3BC,UAAUd,SAASe,MAAM;oBACzBf;gBACF;YACF,EAAE,OAAOgB,OAAO;gBACd,OAAOjD,aACL,CAAC,2BAA2B,EAAEW,WAAW,CAAC,EAAEG,WAAW,EAAE,EAAEnB,aAAasD,QAAQ;YAEpF;QACF;IACF;AACF;AAEA;;;CAGC,GACD,OAAO,SAASC,yBAAyB/C,gBAA6B;IACpE,OAAO;QACLC,MAAM;QACNC,SAAS;YAAEC,MAAM;YAAcC,QAAQ;QAAS;QAChDC,aACE,uDACA,oDACA,gGACA,CAAC,2BAA2B,EAAE;eAAIL;SAAiB,CAACM,IAAI,CAAC,SAAS,QAAQ;QAC5EC,YAAY;YACVC,YAAYjB,EACTkB,MAAM,GACNC,QAAQ,CACP,CAAC,qCAAqC,EAAE;mBAAIV;aAAiB,CAACM,IAAI,CAAC,SAAS,QAAQ;YAExF0C,WAAWzD,EACRkB,MAAM,GACNC,QAAQ,CAAC;QACd;QACAM,SAAS,OACPC,MACAC,KACAC;YAEA,MAAM,EAAEX,UAAU,EAAEwC,SAAS,EAAE,GAAG/B;YAElC,MAAMG,QAAQzB,uBAAuBa,YAAYR,kBAAkB;YACnE,IAAIoB,OAAO,OAAOA;YAElBxB,gBAAgBsB;YAEhB,IAAI;gBACF,MAAM+B,WAAW,MAAM/B,IAAII,OAAO,CAAC4B,cAAc,CAAC;oBAChD1C,YAAYA;oBACZ4B,IAAIY;oBACJ9B;oBACAU,gBAAgB;oBAChBC,MAAMX,IAAIW,IAAI;gBAChB;gBAEA,MAAMsB,aAAaC,OAAO,AAACH,SAAiBb,EAAE;gBAC9C,MAAMK,cAAchD,kBAAkBwD,UAAUE;gBAEhD,OAAOtD,aACL,CAAC,SAAS,EAAEW,WAAW,WAAW,EAAEiC,YAAY,OAAO,EAAEU,WAAW,EAAE,CAAC,GACrE,CAAC,aAAa,EAAEH,UAAU,wCAAwC,CAAC,GACnE,CAAC,mDAAmD,CAAC;YAE3D,EAAE,OAAOF,OAAO;gBACd,OAAOjD,aACL,CAAC,gBAAgB,EAAEW,WAAW,cAAc,EAAEwC,UAAU,EAAE,EAAExD,aAAasD,QAAQ;YAErF;QACF;IACF;AACF"}

package/dist/types.d.ts

@@ -62,6 +62,32 @@ export interface ContentToolkitOptions {
         /** Media collection slug (default: 'media') */
         collectionSlug?: string;
     };
+    /**
+     * MCP transport / auth configuration. Mostly safe to leave unset;
+     * defaults to no-CORS server-to-server use only.
+     */
+    auth?: {
+        /**
+         * Origins permitted on the `Origin` header. Empty / unset means
+         * server-to-server callers only (no browser-based MCP clients).
+         * `*` is intentionally not honoured.
+         */
+        allowedOrigins?: string[];
+    };
+    /**
+     * Override API-key collection settings. Slug defaults to
+     * `payload-mcp-api-keys` for zero-touch upgrade compatibility with
+     * `@payloadcms/plugin-mcp` v0.3.x rows.
+     */
+    apiKeyCollection?: {
+        slug?: string;
+        /**
+         * Override the user collection that API keys link to. By default
+         * the toolkit reuses the same `userCollection` resolution as elsewhere
+         * (`options.userCollection`, then `incomingConfig.admin.user`).
+         */
+        userCollection?: string;
+    };
 }
 /** A domain prompt that teaches the AI site-specific vocabulary */
 export interface DomainPrompt {
@@ -101,6 +127,13 @@ export interface CollectionSchema {
     }>;
     searchableFields: string[];
 }
+/** Introspected global metadata. Globals are singletons — no relationships or searchable-fields graph. */
+export interface GlobalSchema {
+    slug: string;
+    fields: FieldSchema[];
+    hasDrafts: boolean;
+    hasLivePreview: boolean;
+}
 /**
  * One block in the catalog. Flat — no section/leaf distinction. Whether a
  * block can nest other blocks is encoded in the `BlockNestingMap` keyed by
@@ -125,10 +158,10 @@ export interface BlockCatalog {
  * us pre-classifying anything as a "section" or "leaf".
  */
 export interface BlockNestingEdge {
-    /** Owner of the blocks field — either a collection slug or a block slug */
+    /** Owner of the blocks field — a collection slug, a block slug, or a global slug. */
     owner: string;
-    /** Whether the owner is a collection or a block */
-    ownerType: 'collection' | 'block';
+    /** Whether the owner is a collection, a block, or a global */
+    ownerType: 'collection' | 'block' | 'global';
     /** Dotted path to the blocks field within the owner (e.g. `layout`, `hero.content`) */
     fieldPath: string;
     /** Block slugs that this field accepts */
@@ -145,3 +178,23 @@ export interface RelationshipEdge {
     toCollection: string | string[];
     hasMany: boolean;
 }
+export type CollectionAction = 'read' | 'create' | 'update' | 'delete';
+export type GlobalAction = 'read' | 'update';
+export type ScopePreset = 'read-only' | 'editor' | 'admin';
+/**
+ * Runtime scope shape consumed by `registry.assertScopeAllows`.
+ *
+ * - `collections` / `globals` are whitelists when present: a resource not
+ *   listed there is denied for this key.
+ * - `tools.allow` / `tools.deny` are per-tool overrides that take precedence
+ *   over the preset / resource maps.
+ */
+export interface KeyScopes {
+    preset?: ScopePreset;
+    collections?: Record<string, CollectionAction[]>;
+    globals?: Record<string, GlobalAction[]>;
+    tools?: {
+        allow?: string[];
+        deny?: string[];
+    };
+}

package/dist/types.js

@@ -1,8 +1,15 @@
-/**
- * payload-mcp-toolkit configuration.
- *
- * The plugin works with zero options — every field below is an escape hatch
- * for the cases where Payload's own config doesn't carry enough signal.
- */ /** Relationship edge in the collection graph */ export { };
+/**
+ * payload-mcp-toolkit configuration.
+ *
+ * The plugin works with zero options — every field below is an escape hatch
+ * for the cases where Payload's own config doesn't carry enough signal.
+ */ /**
+ * Runtime scope shape consumed by `registry.assertScopeAllows`.
+ *
+ * - `collections` / `globals` are whitelists when present: a resource not
+ *   listed there is denied for this key.
+ * - `tools.allow` / `tools.deny` are per-tool overrides that take precedence
+ *   over the preset / resource maps.
+ */ export { };
 
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * payload-mcp-toolkit configuration.\n *\n * The plugin works with zero options — every field below is an escape hatch\n * for the cases where Payload's own config doesn't carry enough signal.\n */\nexport interface ContentToolkitOptions {\n  /**\n   * Preview URL behavior. The toolkit reads `collection.admin.livePreview.url`\n   * (or `collection.admin.preview` as a fallback) when generating preview links\n   * for draft documents. Provide this object only to override what Payload\n   * already knows.\n   */\n  preview?: {\n    /**\n     * Absolute base URL prepended to relative preview paths. Defaults to\n     * `incomingConfig.serverURL`, then `process.env.NEXT_PUBLIC_SERVER_URL`,\n     * then `process.env.SITE_URL`. If none of those resolve and your preview\n     * URL function returns a relative path, no preview URL is appended.\n     */\n    siteUrl?: string\n\n    /**\n     * Disable preview URL injection entirely.\n     */\n    disabled?: boolean\n  }\n\n  /**\n   * Per-collection draft behavior overrides. The default behavior is inferred\n   * from each collection's `versions.drafts` setting:\n   * - drafts enabled  → `'always-draft'` (raw `update` is locked; clients go\n   *   through `publishDraft` / `patchLayout` / `updateDocument` which preserve\n   *   draft semantics)\n   * - drafts disabled → `'always-publish'`\n   *\n   * Override per slug only if you need to allow raw publish on a draftable\n   * collection.\n   */\n  draftBehavior?: Record<string, 'always-draft' | 'always-publish'>\n\n  /**\n   * Override the auth collection used for API key linkage. By default the\n   * toolkit scans `incomingConfig.collections` for the first collection with\n   * `auth: true`, preferring one named `'users'`.\n   */\n  userCollection?: string\n\n  /**\n   * Hide collections or globals from the MCP surface. Useful for internal\n   * bookkeeping collections that should not be exposed to AI clients.\n   */\n  exclude?: {\n    collections?: string[]\n    globals?: string[]\n  }\n\n  /**\n   * Site-specific domain prompts that teach the AI business vocabulary.\n   * Merged with the auto-generated prompts.\n   */\n  domainPrompts?: DomainPrompt[]\n\n  /** Media upload configuration */\n  mediaUpload?: {\n    /** Maximum file size in bytes (default: 10MB) */\n    maxFileSize?: number\n    /** Media collection slug (default: 'media') */\n    collectionSlug?: string\n  }\n}\n\n/** A domain prompt that teaches the AI site-specific vocabulary */\nexport interface DomainPrompt {\n  /** Unique name for the prompt */\n  name: string\n  /** Display title */\n  title: string\n  /** Description of what this prompt teaches */\n  description: string\n  /** The prompt content */\n  content: string\n}\n\n/** Introspected field metadata */\nexport interface FieldSchema {\n  name: string\n  type: string\n  required?: boolean\n  hasMany?: boolean\n  relationTo?: string | string[]\n  options?: Array<{ label: string; value: string }>\n  fields?: FieldSchema[]\n  maxRows?: number\n}\n\n/** Introspected collection metadata */\nexport interface CollectionSchema {\n  slug: string\n  fields: FieldSchema[]\n  hasDrafts: boolean\n  hasLivePreview: boolean\n  relationships: Array<{ fieldName: string; relationTo: string | string[]; hasMany: boolean }>\n  searchableFields: string[]\n}\n\n/**\n * One block in the catalog. Flat — no section/leaf distinction. Whether a\n * block can nest other blocks is encoded in the `BlockNestingMap` keyed by\n * the path to its `blocks` field.\n */\nexport interface BlockSchema {\n  slug: string\n  fields: FieldSchema[]\n}\n\n/**\n * Flat catalog of every block referenced by the schema.\n */\nexport interface BlockCatalog {\n  blocks: BlockSchema[]\n}\n\n/**\n * One entry per `blocks`-typed field anywhere in the schema.\n *\n * `path` is `<owner>.<dottedFieldPath>` where owner is the collection or\n * block slug that contains the field. Values list the slugs that field\n * accepts. The AI uses this to compose blocks at any nesting depth without\n * us pre-classifying anything as a \"section\" or \"leaf\".\n */\nexport interface BlockNestingEdge {\n  /** Owner of the blocks field — either a collection slug or a block slug */\n  owner: string\n  /** Whether the owner is a collection or a block */\n  ownerType: 'collection' | 'block'\n  /** Dotted path to the blocks field within the owner (e.g. `layout`, `hero.content`) */\n  fieldPath: string\n  /** Block slugs that this field accepts */\n  acceptedBlockSlugs: string[]\n  /** Optional row cap from the field config */\n  maxRows?: number\n}\n\n/** Map of every blocks-field in the schema to the slugs it accepts */\nexport type BlockNestingMap = BlockNestingEdge[]\n\n/** Relationship edge in the collection graph */\nexport interface RelationshipEdge {\n  fromCollection: string\n  fieldName: string\n  toCollection: string | string[]\n  hasMany: boolean\n}\n"],"names":[],"mappings":"AAAA;;;;;CAKC,GA8ID,8CAA8C,GAC9C,WAKC"}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\r\n * payload-mcp-toolkit configuration.\r\n *\r\n * The plugin works with zero options — every field below is an escape hatch\r\n * for the cases where Payload's own config doesn't carry enough signal.\r\n */\r\nexport interface ContentToolkitOptions {\r\n  /**\r\n   * Preview URL behavior. The toolkit reads `collection.admin.livePreview.url`\r\n   * (or `collection.admin.preview` as a fallback) when generating preview links\r\n   * for draft documents. Provide this object only to override what Payload\r\n   * already knows.\r\n   */\r\n  preview?: {\r\n    /**\r\n     * Absolute base URL prepended to relative preview paths. Defaults to\r\n     * `incomingConfig.serverURL`, then `process.env.NEXT_PUBLIC_SERVER_URL`,\r\n     * then `process.env.SITE_URL`. If none of those resolve and your preview\r\n     * URL function returns a relative path, no preview URL is appended.\r\n     */\r\n    siteUrl?: string\r\n\r\n    /**\r\n     * Disable preview URL injection entirely.\r\n     */\r\n    disabled?: boolean\r\n  }\r\n\r\n  /**\r\n   * Per-collection draft behavior overrides. The default behavior is inferred\r\n   * from each collection's `versions.drafts` setting:\r\n   * - drafts enabled  → `'always-draft'` (raw `update` is locked; clients go\r\n   *   through `publishDraft` / `patchLayout` / `updateDocument` which preserve\r\n   *   draft semantics)\r\n   * - drafts disabled → `'always-publish'`\r\n   *\r\n   * Override per slug only if you need to allow raw publish on a draftable\r\n   * collection.\r\n   */\r\n  draftBehavior?: Record<string, 'always-draft' | 'always-publish'>\r\n\r\n  /**\r\n   * Override the auth collection used for API key linkage. By default the\r\n   * toolkit scans `incomingConfig.collections` for the first collection with\r\n   * `auth: true`, preferring one named `'users'`.\r\n   */\r\n  userCollection?: string\r\n\r\n  /**\r\n   * Hide collections or globals from the MCP surface. Useful for internal\r\n   * bookkeeping collections that should not be exposed to AI clients.\r\n   */\r\n  exclude?: {\r\n    collections?: string[]\r\n    globals?: string[]\r\n  }\r\n\r\n  /**\r\n   * Site-specific domain prompts that teach the AI business vocabulary.\r\n   * Merged with the auto-generated prompts.\r\n   */\r\n  domainPrompts?: DomainPrompt[]\r\n\r\n  /** Media upload configuration */\r\n  mediaUpload?: {\r\n    /** Maximum file size in bytes (default: 10MB) */\r\n    maxFileSize?: number\r\n    /** Media collection slug (default: 'media') */\r\n    collectionSlug?: string\r\n  }\r\n\r\n  /**\r\n   * MCP transport / auth configuration. Mostly safe to leave unset;\r\n   * defaults to no-CORS server-to-server use only.\r\n   */\r\n  auth?: {\r\n    /**\r\n     * Origins permitted on the `Origin` header. Empty / unset means\r\n     * server-to-server callers only (no browser-based MCP clients).\r\n     * `*` is intentionally not honoured.\r\n     */\r\n    allowedOrigins?: string[]\r\n  }\r\n\r\n  /**\r\n   * Override API-key collection settings. Slug defaults to\r\n   * `payload-mcp-api-keys` for zero-touch upgrade compatibility with\r\n   * `@payloadcms/plugin-mcp` v0.3.x rows.\r\n   */\r\n  apiKeyCollection?: {\r\n    slug?: string\r\n    /**\r\n     * Override the user collection that API keys link to. By default\r\n     * the toolkit reuses the same `userCollection` resolution as elsewhere\r\n     * (`options.userCollection`, then `incomingConfig.admin.user`).\r\n     */\r\n    userCollection?: string\r\n  }\r\n}\r\n\r\n/** A domain prompt that teaches the AI site-specific vocabulary */\r\nexport interface DomainPrompt {\r\n  /** Unique name for the prompt */\r\n  name: string\r\n  /** Display title */\r\n  title: string\r\n  /** Description of what this prompt teaches */\r\n  description: string\r\n  /** The prompt content */\r\n  content: string\r\n}\r\n\r\n/** Introspected field metadata */\r\nexport interface FieldSchema {\r\n  name: string\r\n  type: string\r\n  required?: boolean\r\n  hasMany?: boolean\r\n  relationTo?: string | string[]\r\n  options?: Array<{ label: string; value: string }>\r\n  fields?: FieldSchema[]\r\n  maxRows?: number\r\n}\r\n\r\n/** Introspected collection metadata */\r\nexport interface CollectionSchema {\r\n  slug: string\r\n  fields: FieldSchema[]\r\n  hasDrafts: boolean\r\n  hasLivePreview: boolean\r\n  relationships: Array<{ fieldName: string; relationTo: string | string[]; hasMany: boolean }>\r\n  searchableFields: string[]\r\n}\r\n\r\n/** Introspected global metadata. Globals are singletons — no relationships or searchable-fields graph. */\r\nexport interface GlobalSchema {\r\n  slug: string\r\n  fields: FieldSchema[]\r\n  hasDrafts: boolean\r\n  hasLivePreview: boolean\r\n}\r\n\r\n/**\r\n * One block in the catalog. Flat — no section/leaf distinction. Whether a\r\n * block can nest other blocks is encoded in the `BlockNestingMap` keyed by\r\n * the path to its `blocks` field.\r\n */\r\nexport interface BlockSchema {\r\n  slug: string\r\n  fields: FieldSchema[]\r\n}\r\n\r\n/**\r\n * Flat catalog of every block referenced by the schema.\r\n */\r\nexport interface BlockCatalog {\r\n  blocks: BlockSchema[]\r\n}\r\n\r\n/**\r\n * One entry per `blocks`-typed field anywhere in the schema.\r\n *\r\n * `path` is `<owner>.<dottedFieldPath>` where owner is the collection or\r\n * block slug that contains the field. Values list the slugs that field\r\n * accepts. The AI uses this to compose blocks at any nesting depth without\r\n * us pre-classifying anything as a \"section\" or \"leaf\".\r\n */\r\nexport interface BlockNestingEdge {\r\n  /** Owner of the blocks field — a collection slug, a block slug, or a global slug. */\r\n  owner: string\r\n  /** Whether the owner is a collection, a block, or a global */\r\n  ownerType: 'collection' | 'block' | 'global'\r\n  /** Dotted path to the blocks field within the owner (e.g. `layout`, `hero.content`) */\r\n  fieldPath: string\r\n  /** Block slugs that this field accepts */\r\n  acceptedBlockSlugs: string[]\r\n  /** Optional row cap from the field config */\r\n  maxRows?: number\r\n}\r\n\r\n/** Map of every blocks-field in the schema to the slugs it accepts */\r\nexport type BlockNestingMap = BlockNestingEdge[]\r\n\r\n/** Relationship edge in the collection graph */\r\nexport interface RelationshipEdge {\r\n  fromCollection: string\r\n  fieldName: string\r\n  toCollection: string | string[]\r\n  hasMany: boolean\r\n}\r\n\r\n// ─── Scope shapes ─────────────────────────────────────────────────────\r\n//\r\n// Canonical scope types live here so the auth strategy, registry, and admin\r\n// API-keys collection all import from the same surface. Globals support\r\n// only `read` / `update` — they don't have `create` / `delete` semantics.\r\n\r\nexport type CollectionAction = 'read' | 'create' | 'update' | 'delete'\r\nexport type GlobalAction = 'read' | 'update'\r\nexport type ScopePreset = 'read-only' | 'editor' | 'admin'\r\n\r\n/**\r\n * Runtime scope shape consumed by `registry.assertScopeAllows`.\r\n *\r\n * - `collections` / `globals` are whitelists when present: a resource not\r\n *   listed there is denied for this key.\r\n * - `tools.allow` / `tools.deny` are per-tool overrides that take precedence\r\n *   over the preset / resource maps.\r\n */\r\nexport interface KeyScopes {\r\n  preset?: ScopePreset\r\n  collections?: Record<string, CollectionAction[]>\r\n  globals?: Record<string, GlobalAction[]>\r\n  tools?: { allow?: string[]; deny?: string[] }\r\n}\r\n"],"names":[],"mappings":"AAAA;;;;;CAKC,GAoMD;;;;;;;CAOC,GACD,WAKC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "payload-mcp-toolkit",
-  "version": "0.3.3",
-  "description": "Schema-aware MCP toolkit for Payload CMS — wraps the official @payloadcms/plugin-mcp with introspected prompts, resources, draft workflow, and AI-friendly tools so non-technical editors can manage content via AI chat.",
+  "version": "0.7.0",
+  "description": "Standalone schema-aware MCP plugin for Payload CMS v3 — owns the /api/mcp endpoint, scoped API keys, draft workflow, and AI-friendly tools so non-technical editors can manage content via AI chat.",
   "license": "MIT",
   "author": "jon8800",
   "homepage": "https://github.com/jon8800/payload-mcp-toolkit#readme",
@@ -28,6 +28,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "import": "./dist/components/index.js",
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -36,15 +41,17 @@
     "dist"
   ],
   "sideEffects": false,
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "mcp-handler": "^1.1.0"
+  },
   "peerDependencies": {
-    "@payloadcms/plugin-mcp": "^3.0.0",
     "payload": "^3.0.0",
     "zod": "^3.0.0"
   },
   "devDependencies": {
     "@payloadcms/db-sqlite": "3.82.1",
     "@payloadcms/next": "3.82.1",
-    "@payloadcms/plugin-mcp": "3.82.1",
     "@payloadcms/richtext-lexical": "3.82.1",
     "@payloadcms/ui": "3.82.1",
     "@swc/cli": "0.6.0",