@payloadcms/plugin-mcp 4.0.0-internal.38b7f1d → 4.0.0-internal.40de3ec

package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'vitest';
+import { sanitizeEntitySchema } from './sanitizeEntitySchema.js';
+describe('sanitizeEntitySchema', ()=>{
+    it('keeps a Lexical node union strict (oneOf) while simplifying relationship values to IDs', ()=>{
+        // Shaped like the schema the MCP server prepares for a collection with a Lexical richText field:
+        // a `$defs` node union (a `oneOf` of node shapes) where a relationship node's `value` is either
+        // an ID or a `$ref` to the populated related collection.
+        const standalone = {
+            type: 'object',
+            $defs: {
+                LexicalNodes_ABCDEF12: {
+                    oneOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'paragraph'
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'relationship'
+                                },
+                                value: {
+                                    oneOf: [
+                                        {
+                                            type: 'string'
+                                        },
+                                        {
+                                            $ref: '#/$defs/posts'
+                                        }
+                                    ]
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        }
+                    ]
+                },
+                posts: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        id: {
+                            type: 'string'
+                        },
+                        title: {
+                            type: 'string'
+                        }
+                    }
+                }
+            },
+            properties: {
+                id: {
+                    type: 'string'
+                },
+                content: {
+                    type: 'object',
+                    properties: {
+                        root: {
+                            type: 'object',
+                            properties: {
+                                children: {
+                                    type: 'array',
+                                    items: {
+                                        $ref: '#/$defs/LexicalNodes_ABCDEF12'
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        };
+        expect(sanitizeEntitySchema(standalone)).toStrictEqual({
+            type: 'object',
+            $defs: {
+                // The node union is renamed to a short, readable `node`, and stays a strict discriminated
+                // `oneOf` - not loosened to `anyOf`...
+                node: {
+                    oneOf: [
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'paragraph'
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        },
+                        {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                type: {
+                                    const: 'relationship'
+                                },
+                                // ...while the relationship `value` is simplified to a bare ID (the populated-doc `$ref` is dropped).
+                                value: {
+                                    type: 'string',
+                                    description: 'The ID of the related "posts" document.'
+                                }
+                            },
+                            required: [
+                                'type'
+                            ]
+                        }
+                    ]
+                },
+                posts: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        id: {
+                            type: 'string'
+                        },
+                        title: {
+                            type: 'string'
+                        }
+                    }
+                }
+            },
+            properties: {
+                // `id` is dropped - it's a Payload-managed field MCP clients never set.
+                content: {
+                    type: 'object',
+                    properties: {
+                        root: {
+                            type: 'object',
+                            properties: {
+                                children: {
+                                    type: 'array',
+                                    items: {
+                                        $ref: '#/$defs/node'
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+    });
+});
+
+//# sourceMappingURL=sanitizeEntitySchema.spec.js.map

package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/utils/schemaConversion/sanitizeEntitySchema.spec.ts"],"sourcesContent":["import { describe, expect, it } from 'vitest'\n\nimport type { JsonSchemaType } from '../../types.js'\n\nimport { sanitizeEntitySchema } from './sanitizeEntitySchema.js'\n\ndescribe('sanitizeEntitySchema', () => {\n  it('keeps a Lexical node union strict (oneOf) while simplifying relationship values to IDs', () => {\n    // Shaped like the schema the MCP server prepares for a collection with a Lexical richText field:\n    // a `$defs` node union (a `oneOf` of node shapes) where a relationship node's `value` is either\n    // an ID or a `$ref` to the populated related collection.\n    const standalone: JsonSchemaType = {\n      type: 'object',\n      $defs: {\n        LexicalNodes_ABCDEF12: {\n          oneOf: [\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: { type: { const: 'paragraph' } },\n              required: ['type'],\n            },\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: {\n                type: { const: 'relationship' },\n                value: { oneOf: [{ type: 'string' }, { $ref: '#/$defs/posts' }] },\n              },\n              required: ['type'],\n            },\n          ],\n        },\n        posts: {\n          type: 'object',\n          additionalProperties: false,\n          properties: { id: { type: 'string' }, title: { type: 'string' } },\n        },\n      },\n      properties: {\n        id: { type: 'string' },\n        content: {\n          type: 'object',\n          properties: {\n            root: {\n              type: 'object',\n              properties: {\n                children: { type: 'array', items: { $ref: '#/$defs/LexicalNodes_ABCDEF12' } },\n              },\n            },\n          },\n        },\n      },\n    }\n\n    expect(sanitizeEntitySchema(standalone)).toStrictEqual({\n      type: 'object',\n      $defs: {\n        // The node union is renamed to a short, readable `node`, and stays a strict discriminated\n        // `oneOf` - not loosened to `anyOf`...\n        node: {\n          oneOf: [\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: { type: { const: 'paragraph' } },\n              required: ['type'],\n            },\n            {\n              type: 'object',\n              additionalProperties: false,\n              properties: {\n                type: { const: 'relationship' },\n                // ...while the relationship `value` is simplified to a bare ID (the populated-doc `$ref` is dropped).\n                value: { type: 'string', description: 'The ID of the related \"posts\" document.' },\n              },\n              required: ['type'],\n            },\n          ],\n        },\n        posts: {\n          type: 'object',\n          additionalProperties: false,\n          properties: { id: { type: 'string' }, title: { type: 'string' } },\n        },\n      },\n      properties: {\n        // `id` is dropped - it's a Payload-managed field MCP clients never set.\n        content: {\n          type: 'object',\n          properties: {\n            root: {\n              type: 'object',\n              properties: {\n                children: { type: 'array', items: { $ref: '#/$defs/node' } },\n              },\n            },\n          },\n        },\n      },\n    })\n  })\n})\n"],"names":["describe","expect","it","sanitizeEntitySchema","standalone","type","$defs","LexicalNodes_ABCDEF12","oneOf","additionalProperties","properties","const","required","value","$ref","posts","id","title","content","root","children","items","toStrictEqual","node","description"],"mappings":"AAAA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAI7C,SAASC,oBAAoB,QAAQ,4BAA2B;AAEhEH,SAAS,wBAAwB;IAC/BE,GAAG,0FAA0F;QAC3F,iGAAiG;QACjG,gGAAgG;QAChG,yDAAyD;QACzD,MAAME,aAA6B;YACjCC,MAAM;YACNC,OAAO;gBACLC,uBAAuB;oBACrBC,OAAO;wBACL;4BACEH,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCAAEL,MAAM;oCAAEM,OAAO;gCAAY;4BAAE;4BAC3CC,UAAU;gCAAC;6BAAO;wBACpB;wBACA;4BACEP,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCACVL,MAAM;oCAAEM,OAAO;gCAAe;gCAC9BE,OAAO;oCAAEL,OAAO;wCAAC;4CAAEH,MAAM;wCAAS;wCAAG;4CAAES,MAAM;wCAAgB;qCAAE;gCAAC;4BAClE;4BACAF,UAAU;gCAAC;6BAAO;wBACpB;qBACD;gBACH;gBACAG,OAAO;oBACLV,MAAM;oBACNI,sBAAsB;oBACtBC,YAAY;wBAAEM,IAAI;4BAAEX,MAAM;wBAAS;wBAAGY,OAAO;4BAAEZ,MAAM;wBAAS;oBAAE;gBAClE;YACF;YACAK,YAAY;gBACVM,IAAI;oBAAEX,MAAM;gBAAS;gBACrBa,SAAS;oBACPb,MAAM;oBACNK,YAAY;wBACVS,MAAM;4BACJd,MAAM;4BACNK,YAAY;gCACVU,UAAU;oCAAEf,MAAM;oCAASgB,OAAO;wCAAEP,MAAM;oCAAgC;gCAAE;4BAC9E;wBACF;oBACF;gBACF;YACF;QACF;QAEAb,OAAOE,qBAAqBC,aAAakB,aAAa,CAAC;YACrDjB,MAAM;YACNC,OAAO;gBACL,0FAA0F;gBAC1F,uCAAuC;gBACvCiB,MAAM;oBACJf,OAAO;wBACL;4BACEH,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCAAEL,MAAM;oCAAEM,OAAO;gCAAY;4BAAE;4BAC3CC,UAAU;gCAAC;6BAAO;wBACpB;wBACA;4BACEP,MAAM;4BACNI,sBAAsB;4BACtBC,YAAY;gCACVL,MAAM;oCAAEM,OAAO;gCAAe;gCAC9B,sGAAsG;gCACtGE,OAAO;oCAAER,MAAM;oCAAUmB,aAAa;gCAA0C;4BAClF;4BACAZ,UAAU;gCAAC;6BAAO;wBACpB;qBACD;gBACH;gBACAG,OAAO;oBACLV,MAAM;oBACNI,sBAAsB;oBACtBC,YAAY;wBAAEM,IAAI;4BAAEX,MAAM;wBAAS;wBAAGY,OAAO;4BAAEZ,MAAM;wBAAS;oBAAE;gBAClE;YACF;YACAK,YAAY;gBACV,wEAAwE;gBACxEQ,SAAS;oBACPb,MAAM;oBACNK,YAAY;wBACVS,MAAM;4BACJd,MAAM;4BACNK,YAAY;gCACVU,UAAU;oCAAEf,MAAM;oCAASgB,OAAO;wCAAEP,MAAM;oCAAe;gCAAE;4BAC7D;wBACF;oBACF;gBACF;YACF;QACF;IACF;AACF"}

package/dist/utils/toStandardSchema.d.ts

@@ -0,0 +1,5 @@
+import { type StandardSchemaWithJSON } from '@modelcontextprotocol/server';
+import type { ToolInputSchema } from '../types.js';
+/** Normalize a tool/prompt input to a Standard Schema. Raw JSON Schema gets wrapped; Standard Schema instances pass through. */
+export declare const toStandardSchema: (schema: ToolInputSchema) => StandardSchemaWithJSON;
+//# sourceMappingURL=toStandardSchema.d.ts.map

package/dist/utils/toStandardSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toStandardSchema.d.ts","sourceRoot":"","sources":["../../src/utils/toStandardSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAE1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,gIAAgI;AAChI,eAAO,MAAM,gBAAgB,GAAI,QAAQ,eAAe,KAAG,sBAG/B,CAAA"}

package/dist/utils/toStandardSchema.js

@@ -0,0 +1,4 @@
+import { fromJsonSchema } from '@modelcontextprotocol/server';
+/** Normalize a tool/prompt input to a Standard Schema. Raw JSON Schema gets wrapped; Standard Schema instances pass through. */ export const toStandardSchema = (schema)=>typeof schema === 'object' && schema !== null && '~standard' in schema ? schema : fromJsonSchema(schema);
+
+//# sourceMappingURL=toStandardSchema.js.map

package/dist/utils/toStandardSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/toStandardSchema.ts"],"sourcesContent":["import { fromJsonSchema, type StandardSchemaWithJSON } from '@modelcontextprotocol/server'\n\nimport type { ToolInputSchema } from '../types.js'\n\n/** Normalize a tool/prompt input to a Standard Schema. Raw JSON Schema gets wrapped; Standard Schema instances pass through. */\nexport const toStandardSchema = (schema: ToolInputSchema): StandardSchemaWithJSON =>\n  typeof schema === 'object' && schema !== null && '~standard' in schema\n    ? (schema as StandardSchemaWithJSON)\n    : fromJsonSchema(schema)\n"],"names":["fromJsonSchema","toStandardSchema","schema"],"mappings":"AAAA,SAASA,cAAc,QAAqC,+BAA8B;AAI1F,8HAA8H,GAC9H,OAAO,MAAMC,mBAAmB,CAACC,SAC/B,OAAOA,WAAW,YAAYA,WAAW,QAAQ,eAAeA,SAC3DA,SACDF,eAAeE,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/plugin-mcp",
-  "version": "4.0.0-internal.38b7f1d",
+  "version": "4.0.0-internal.40de3ec",
   "description": "MCP (Model Context Protocol) capabilities with Payload",
   "keywords": [
     "plugin",
@@ -21,34 +21,59 @@
       "url": "https://payloadcms.com"
     }
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "*.css"
+  ],
   "type": "module",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "import": "./dist/exports/client.js",
+      "types": "./dist/exports/client.d.ts",
+      "default": "./dist/exports/client.js"
+    },
+    "./stdio": {
+      "import": "./dist/stdio.js",
+      "types": "./dist/stdio.d.ts",
+      "default": "./dist/stdio.js"
     }
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "payload-mcp": "./bin.js"
+  },
   "files": [
     "src",
-    "dist"
+    "dist",
+    "bin.js"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.27.1",
-    "@types/json-schema": "7.0.15",
-    "json-schema-to-zod": "2.6.1",
-    "mcp-handler": "^1.0.7",
-    "zod": "^3.25.50"
+    "@cfworker/json-schema": "^4.1.1",
+    "@modelcontextprotocol/server": "2.0.0-alpha.2",
+    "tsx": "4.22.4",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@types/react": "19.2.14",
+    "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
     "@payloadcms/eslint-config": "3.28.0",
-    "payload": "4.0.0-internal.38b7f1d"
+    "@payloadcms/ui": "4.0.0-internal.40de3ec",
+    "payload": "4.0.0-internal.40de3ec"
   },
   "peerDependencies": {
-    "payload": "4.0.0-internal.38b7f1d"
+    "react": "^19.0.1 || ^19.1.2 || ^19.2.1",
+    "payload": "4.0.0-internal.40de3ec",
+    "@payloadcms/ui": "4.0.0-internal.40de3ec"
+  },
+  "//deps_notes": {
+    "zod": "zod is a hard dependency of @modelcontextprotocol/server, thus we can safely use it without it impacting bundle size. Make extra sure the zod version here matches exactly what's defined in the dependencies of @modelcontextprotocol/server to avoid duplicate versions being installed.",
+    "@cfworker/json-schema": "Should be able to remove in next @modelcontextprotocol/server alpha release. Marked as an optional peer of @modelcontextprotocol/server, but its bundle does an eager top-level `import { Validator } from '@cfworker/json-schema'`, so it must be installed even when only zod-registered tools are used. Drop once upstream lazy-loads the validator. See: https://github.com/modelcontextprotocol/typescript-sdk",
+    "tsx": "Required by the `bin.js` stdio mcp. Keep the version pinned to whatever `payload` ships to avoid duplicate installs."
   },
   "homepage:": "https://payloadcms.com",
   "scripts": {

package/src/@types/assets.d.ts

@@ -0,0 +1,3 @@
+declare module '*.css'
+
+declare module '*.scss'

package/src/collection/getAccessField.ts

@@ -0,0 +1,64 @@
+import type { JSONField } from 'payload'
+
+import type { ClientMCPPluginConfig, MCPItem, SanitizedMCPPluginConfig } from '../types.js'
+
+/**
+ * Returns the API key collection's `access` field — a JSON field whose value
+ * is the `MCPAPIKeysDocAccessTree` the endpoint consults. The actual UI is
+ * a custom client component (`AccessField`) which renders a permissions
+ * matrix; the field's stored shape is just the runtime access tree.
+ */
+export const getAccessField = ({
+  pluginConfig,
+}: {
+  pluginConfig: SanitizedMCPPluginConfig
+}): JSONField => {
+  const clientPluginConfig = sanitizeClientPluginConfig(pluginConfig)
+
+  return {
+    name: 'access',
+    type: 'json',
+    admin: {
+      components: {
+        Field: {
+          clientProps: { pluginConfig: clientPluginConfig },
+          path: '@payloadcms/plugin-mcp/client#AccessField',
+        },
+      },
+      // TODO: needs i18n once design is finalized
+      description: 'Access for this API key — uncheck to revoke individual tools.',
+      position: 'sidebar',
+    },
+    defaultValue: {},
+    // TODO: needs i18n once design is finalized
+    label: 'Access',
+  }
+}
+
+/**
+ * Strips the non-serializable parts of `SanitizedMCPPluginConfig` (handlers,
+ * input/argsSchema functions, etc.) so the result is safe to thread to a
+ * client component via `clientProps`.
+ */
+const sanitizeClientPluginConfig = (
+  pluginConfig: SanitizedMCPPluginConfig,
+): ClientMCPPluginConfig => ({
+  items: pluginConfig.items.map((item) => ({
+    ...(item.type === 'collectionTool' ? { collectionSlug: item.collectionSlug } : {}),
+    ...(item.type === 'globalTool' ? { globalSlug: item.globalSlug } : {}),
+    type: item.type,
+    description: itemDescription(item),
+    key: item.key,
+    label: item.label,
+  })),
+})
+
+const itemDescription = (item: MCPItem): string => {
+  if (item.type === 'prompt') {
+    return item.prompt.description
+  }
+  if (item.type === 'resource') {
+    return item.resource.description
+  }
+  return item.tool.description
+}

package/src/collection/index.ts

@@ -0,0 +1,64 @@
+import type { CollectionConfig } from 'payload'
+
+import type { SanitizedMCPPluginConfig } from '../types.js'
+
+import { getAccessField } from './getAccessField.js'
+
+export const getAPIKeysCollection = ({
+  pluginConfig,
+}: {
+  pluginConfig: SanitizedMCPPluginConfig
+}): CollectionConfig => {
+  const collection: CollectionConfig = {
+    slug: 'payload-mcp-api-keys',
+    admin: {
+      description:
+        'API keys control which collections, resources, tools, and prompts MCP clients can access',
+      group: 'MCP',
+      useAsTitle: 'label',
+    },
+    auth: {
+      disableLocalStrategy: true,
+      useAPIKey: true,
+    },
+    fields: [
+      {
+        name: 'user',
+        type: 'relationship',
+        admin: { description: 'The user that the API key is associated with.' },
+        relationTo: pluginConfig.userCollection,
+        required: true,
+      },
+      {
+        name: 'label',
+        type: 'text',
+        admin: { description: 'A useful label for the API key.' },
+      },
+      {
+        name: 'description',
+        type: 'text',
+        admin: { description: 'The purpose of the API key.' },
+      },
+      {
+        name: 'overrideAccess',
+        type: 'checkbox',
+        admin: {
+          description:
+            'When checked, this key bypasses Payload access control on every operation it performs. Leave unchecked unless you have a specific reason.',
+        },
+        defaultValue: false,
+        label: 'Override access control',
+      },
+      getAccessField({ pluginConfig }),
+    ],
+    labels: {
+      plural: 'API Keys',
+      singular: 'API Key',
+    },
+    versions: false,
+  }
+
+  return pluginConfig.overrideApiKeyCollection
+    ? pluginConfig.overrideApiKeyCollection(collection)
+    : collection
+}