@payloadcms/plugin-mcp 4.0.0-canary.0 → 4.0.0-canary.2

package/src/translations/languages/ta.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const taTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'MCP கிளையன்ட்கள் எந்த collections, resources, tools மற்றும் prompts-ஐ அணுகலாம் என்பதை API விசைகள் கட்டுப்படுத்துகின்றன.',
+    apiKeys: 'API விசைகள்',
+    authentication: 'அங்கீகாரம்',
+    description: 'விளக்கம்',
+    descriptionDescription: 'API விசையின் நோக்கத்தை விளக்குங்கள்.',
+    dismiss: 'மூடு',
+    keepKeyPrivate: 'உங்கள் விசையை தனிப்பட்டதாக வைத்திருங்கள்.',
+    keyPrivateDescription: 'இந்த விசை MCP-க்கு உங்கள் உள்ளடக்கத்தை அணுக அனுமதிக்கிறது. இதை பிறருடன் பகிர வேண்டாம்!',
+    lastUsed: 'கடைசியாக பயன்படுத்தியது',
+    manageAPIKeys: 'API விசைகளை நிர்வகி',
+    mcp: 'MCP',
+    noAPIKeys: 'API விசைகள் இல்லை',
+    operations: 'செயல்பாடுகள்',
+    overrideAccess: 'அணுகல் கட்டுப்பாட்டை மீறு',
+    overrideAccessDescription: 'இது தேர்ந்தெடுக்கப்பட்டால், இந்த விசை மேற்கொள்ளும் ஒவ்வொரு செயல்பாட்டிலும் Payload அணுகல் கட்டுப்பாட்டை மீறும். குறிப்பிட்ட காரணம் இல்லையெனில் தேர்வு செய்ய வேண்டாம்.',
+    permissions: 'அனுமதிகள்',
+    permissionsDescription: 'MCP கிளையன்ட்களுக்கு பின்வரும் collections, tools, resources மற்றும் prompts-ஐ அணுக அனுமதிக்கவும்.',
+    prompts: 'Prompts',
+    resources: 'Resources',
+    server: 'சேவையகம்',
+    title: 'தலைப்பு',
+    titleDescription: 'API விசைக்கு உதவும் ஒரு குறுநாமம்.',
+    tools: 'Tools',
+    userDescription: 'MCP செயல்படும் பயனர்.',
+  },
+}
+
+export const ta: PluginLanguage = {
+  dateFNSKey: 'ta',
+  translations: taTranslations,
+}

package/src/translations/languages/th.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const thTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'คีย์ API ควบคุมว่าลูกค้า MCP สามารถเข้าถึงคอลเลกชัน ทรัพยากร เครื่องมือ และพรอมป์ใดได้บ้าง',
+    apiKeys: 'คีย์ API',
+    authentication: 'การยืนยันตัวตน',
+    description: 'คำอธิบาย',
+    descriptionDescription: 'อธิบายวัตถุประสงค์ของคีย์ API',
+    dismiss: 'ปิด',
+    keepKeyPrivate: 'เก็บคีย์ของคุณไว้เป็นความลับ',
+    keyPrivateDescription: 'คีย์นี้ให้ MCP เข้าถึงเนื้อหาของคุณ อย่าแชร์กับผู้อื่น!',
+    lastUsed: 'ใช้ล่าสุด',
+    manageAPIKeys: 'จัดการคีย์ API',
+    mcp: 'MCP',
+    noAPIKeys: 'ไม่มีคีย์ API',
+    operations: 'การดำเนินการ',
+    overrideAccess: 'ข้ามการควบคุมการเข้าถึง',
+    overrideAccessDescription: 'เมื่อเลือก คีย์นี้จะข้ามการควบคุมการเข้าถึงของ Payload ในทุกการดำเนินการ เว้นไว้หากไม่มีเหตุผลเฉพาะ',
+    permissions: 'สิทธิ์',
+    permissionsDescription: 'อนุญาตให้ลูกค้า MCP เข้าถึงคอลเลกชัน เครื่องมือ ทรัพยากร และพรอมป์ต่อไปนี้',
+    prompts: 'พรอมป์',
+    resources: 'ทรัพยากร',
+    server: 'เซิร์ฟเวอร์',
+    title: 'ชื่อ',
+    titleDescription: 'ชื่อเล่นที่ช่วยจำสำหรับคีย์ API',
+    tools: 'เครื่องมือ',
+    userDescription: 'ผู้ใช้ที่ MCP จะดำเนินการแทน',
+  },
+}
+
+export const th: PluginLanguage = {
+  dateFNSKey: 'th',
+  translations: thTranslations,
+}

package/src/translations/languages/tr.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const trTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'API anahtarları, MCP istemcilerinin hangi koleksiyonlara, kaynaklara, araçlara ve promptlara erişebileceğini kontrol eder.',
+    apiKeys: 'API anahtarları',
+    authentication: 'Kimlik doğrulama',
+    description: 'Açıklama',
+    descriptionDescription: 'API anahtarının amacını açıklayın.',
+    dismiss: 'Kapat',
+    keepKeyPrivate: 'Anahtarınızı gizli tutun.',
+    keyPrivateDescription: 'Bu anahtar MCP’ye içeriğinize erişim verir. Başkalarıyla paylaşmayın!',
+    lastUsed: 'Son kullanım',
+    manageAPIKeys: 'API anahtarlarını yönet',
+    mcp: 'MCP',
+    noAPIKeys: 'API anahtarı yok',
+    operations: 'İşlemler',
+    overrideAccess: 'Erişim kontrolünü geçersiz kıl',
+    overrideAccessDescription: 'İşaretlendiğinde bu anahtar, gerçekleştirdiği her işlemde Payload erişim kontrolünü atlar. Belirli bir nedeniniz yoksa işaretlemeyin.',
+    permissions: 'İzinler',
+    permissionsDescription: 'MCP istemcilerinin aşağıdaki koleksiyonlara, araçlara, kaynaklara ve promptlara erişmesine izin verin.',
+    prompts: 'Promptlar',
+    resources: 'Kaynaklar',
+    server: 'Sunucu',
+    title: 'Başlık',
+    titleDescription: 'API anahtarı için kullanışlı bir takma ad.',
+    tools: 'Araçlar',
+    userDescription: 'MCP’nin adına işlem yapacağı kullanıcı.',
+  },
+}
+
+export const tr: PluginLanguage = {
+  dateFNSKey: 'tr',
+  translations: trTranslations,
+}

package/src/translations/languages/uk.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const ukTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'API-ключі керують тим, до яких колекцій, ресурсів, інструментів і промптів можуть мати доступ MCP-клієнти.',
+    apiKeys: 'API-ключі',
+    authentication: 'Автентифікація',
+    description: 'Опис',
+    descriptionDescription: 'Опишіть призначення API-ключа.',
+    dismiss: 'Закрити',
+    keepKeyPrivate: 'Зберігайте ключ приватним.',
+    keyPrivateDescription: 'Цей ключ надає MCP доступ до вашого контенту. Не діліться ним з іншими!',
+    lastUsed: 'Останнє використання',
+    manageAPIKeys: 'Керувати API-ключами',
+    mcp: 'MCP',
+    noAPIKeys: 'Немає API-ключів',
+    operations: 'Операції',
+    overrideAccess: 'Перевизначити контроль доступу',
+    overrideAccessDescription: 'Якщо увімкнено, цей ключ обходить контроль доступу Payload під час кожної операції. Залиште вимкненим, якщо немає конкретної причини.',
+    permissions: 'Дозволи',
+    permissionsDescription: 'Дозвольте MCP-клієнтам доступ до таких колекцій, інструментів, ресурсів і промптів.',
+    prompts: 'Промпти',
+    resources: 'Ресурси',
+    server: 'Сервер',
+    title: 'Назва',
+    titleDescription: 'Зручна назва для API-ключа.',
+    tools: 'Інструменти',
+    userDescription: 'Користувач, від імені якого діятиме MCP.',
+  },
+}
+
+export const uk: PluginLanguage = {
+  dateFNSKey: 'uk',
+  translations: ukTranslations,
+}

package/src/translations/languages/vi.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const viTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'Khóa API kiểm soát các bộ sưu tập, tài nguyên, công cụ và prompt mà client MCP có thể truy cập.',
+    apiKeys: 'Khóa API',
+    authentication: 'Xác thực',
+    description: 'Mô tả',
+    descriptionDescription: 'Mô tả mục đích của khóa API.',
+    dismiss: 'Đóng',
+    keepKeyPrivate: 'Giữ khóa của bạn riêng tư.',
+    keyPrivateDescription: 'Khóa này cấp cho MCP quyền truy cập nội dung của bạn. Đừng chia sẻ với người khác!',
+    lastUsed: 'Lần dùng cuối',
+    manageAPIKeys: 'Quản lý khóa API',
+    mcp: 'MCP',
+    noAPIKeys: 'Không có khóa API',
+    operations: 'Thao tác',
+    overrideAccess: 'Ghi đè kiểm soát truy cập',
+    overrideAccessDescription: 'Khi bật, khóa này bỏ qua kiểm soát truy cập của Payload trong mọi thao tác. Hãy để tắt trừ khi bạn có lý do cụ thể.',
+    permissions: 'Quyền',
+    permissionsDescription: 'Cho phép client MCP truy cập các bộ sưu tập, công cụ, tài nguyên và prompt sau.',
+    prompts: 'Prompt',
+    resources: 'Tài nguyên',
+    server: 'Máy chủ',
+    title: 'Tiêu đề',
+    titleDescription: 'Tên gợi nhớ hữu ích cho khóa API.',
+    tools: 'Công cụ',
+    userDescription: 'Người dùng mà MCP sẽ đại diện để hành động.',
+  },
+}
+
+export const vi: PluginLanguage = {
+  dateFNSKey: 'vi',
+  translations: viTranslations,
+}

package/src/translations/languages/zh.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const zhTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'API 密钥控制 MCP 客户端可以访问哪些集合、资源、工具和提示词。',
+    apiKeys: 'API 密钥',
+    authentication: '身份验证',
+    description: '描述',
+    descriptionDescription: '描述 API 密钥的用途。',
+    dismiss: '关闭',
+    keepKeyPrivate: '请妥善保管你的密钥。',
+    keyPrivateDescription: '此密钥会让 MCP 访问你的内容。不要与他人共享！',
+    lastUsed: '上次使用',
+    manageAPIKeys: '管理 API 密钥',
+    mcp: 'MCP',
+    noAPIKeys: '没有 API 密钥',
+    operations: '操作',
+    overrideAccess: '覆盖访问控制',
+    overrideAccessDescription: '启用后，此密钥执行的每个操作都会绕过 Payload 访问控制。除非有明确原因，否则请保持关闭。',
+    permissions: '权限',
+    permissionsDescription: '允许 MCP 客户端访问以下集合、工具、资源和提示词。',
+    prompts: '提示词',
+    resources: '资源',
+    server: '服务器',
+    title: '标题',
+    titleDescription: 'API 密钥的易识别名称。',
+    tools: '工具',
+    userDescription: 'MCP 将代表其操作的用户。',
+  },
+}
+
+export const zh: PluginLanguage = {
+  dateFNSKey: 'zh-CN',
+  translations: zhTranslations,
+}

package/src/translations/languages/zhTw.ts

@@ -0,0 +1,35 @@
+import type { PluginLanguage } from '../types.js'
+
+export const zhTwTranslations = {
+  'plugin-mcp': {
+    apiKeyDescription: 'API 金鑰控制 MCP 用戶端可以存取哪些集合、資源、工具和提示詞。',
+    apiKeys: 'API 金鑰',
+    authentication: '驗證',
+    description: '描述',
+    descriptionDescription: '描述 API 金鑰的用途。',
+    dismiss: '關閉',
+    keepKeyPrivate: '請妥善保管你的金鑰。',
+    keyPrivateDescription: '此金鑰會讓 MCP 存取你的內容。不要與他人分享！',
+    lastUsed: '上次使用',
+    manageAPIKeys: '管理 API 金鑰',
+    mcp: 'MCP',
+    noAPIKeys: '沒有 API 金鑰',
+    operations: '操作',
+    overrideAccess: '覆寫存取控制',
+    overrideAccessDescription: '啟用後，此金鑰執行的每個操作都會略過 Payload 存取控制。除非有明確原因，否則請保持關閉。',
+    permissions: '權限',
+    permissionsDescription: '允許 MCP 用戶端存取以下集合、工具、資源和提示詞。',
+    prompts: '提示詞',
+    resources: '資源',
+    server: '伺服器',
+    title: '標題',
+    titleDescription: 'API 金鑰的易識別名稱。',
+    tools: '工具',
+    userDescription: 'MCP 將代表其操作的使用者。',
+  },
+}
+
+export const zhTw: PluginLanguage = {
+  dateFNSKey: 'zh-TW',
+  translations: zhTwTranslations,
+}

package/src/translations/types.ts

@@ -0,0 +1,34 @@
+import type { Language } from '@payloadcms/translations'
+
+import type { enTranslations } from './languages/en.js'
+
+export type PluginLanguage = Language<{
+  'plugin-mcp': {
+    apiKeyDescription: string
+    apiKeys: string
+    authentication: string
+    description: string
+    descriptionDescription: string
+    dismiss: string
+    keepKeyPrivate: string
+    keyPrivateDescription: string
+    lastUsed: string
+    manageAPIKeys: string
+    mcp: string
+    noAPIKeys: string
+    operations: string
+    overrideAccess: string
+    overrideAccessDescription: string
+    permissions: string
+    permissionsDescription: string
+    prompts: string
+    resources: string
+    server: string
+    title: string
+    titleDescription: string
+    tools: string
+    userDescription: string
+  }
+}>
+
+export type PluginDefaultTranslationsObject = typeof enTranslations

package/src/types.ts

@@ -46,9 +46,11 @@ export type ToolInputSchema = JsonSchemaType | StandardSchemaWithJSON
 export type ClientMCPPluginConfig = {
   items: Array<{
     collectionSlug?: string
-    description: string
+    configKey: string
+    description?: string
     globalSlug?: string
-    key: string
+    /** Admin-UI bucket for collection/global tools: built-in CRUD, auth, or custom. */
+    group?: 'auth' | 'custom' | 'operations'
     label: string
     type: 'collectionTool' | 'globalTool' | 'prompt' | 'resource' | 'tool'
   }>
@@ -105,22 +107,17 @@ export type Tool<TSchema extends ToolInputSchema | undefined = ToolInputSchema |
   overrideResponse?: MCPResponseOverride
 }
 
-/**
- * `TSchema` is the schema itself (Standard Schema, raw JSON Schema, or undefined).
- * The function-form variant of `input` carries a concrete `{ collectionSchema: JsonSchemaType }`
- * parameter type so callers can write `({ collectionSchema }) => …` without annotating it.
- */
 export type CollectionTool<
   TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
 > = {
   handler: (args: CollectionToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
-  input?: ((args: { collectionSchema: JsonSchemaType }) => TSchema) | TSchema
+  input?: TSchema
 } & Pick<Tool, 'description' | 'overrideResponse'>
 
 export type GlobalTool<TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined> =
   {
     handler: (args: GlobalToolHandlerArgs<TSchema>) => MaybePromise<MCPToolResponse>
-    input?: ((args: { globalSchema: JsonSchemaType }) => TSchema) | TSchema
+    input?: TSchema
   } & Pick<Tool, 'description' | 'overrideResponse'>
 
 /**
@@ -287,40 +284,41 @@ export type MCPAPIKeysDocAccessTree = {
  */
 export type MCPAPIKeysDoc = {
   access: MCPAPIKeysDocAccessTree
+  apiKey?: string
+  apiKeyIndex?: string
   id: DefaultDocumentIDType
+  lastUsed?: string
   overrideAccess?: boolean
   user: null | TypedUser
 }
 
 /**
- * One MCP primitive — tool, prompt, or resource — paired with the metadata both
- * the endpoint and the API key collection need. Built by `sanitizeMCPConfig`,
- * filtered by `getAuthorizedMCP`, registered by the MCP endpoint.
+ * One MCP primitive plus the metadata needed for access checks, admin UI, and
+ * registration.
  *
- *  - `key`: the config identifier (`find`, `echo`). Used for the API-key deny
- *    lookup and as the admin checkbox field name. For collection/global tools,
- *    the MCP wire name (`findPosts`) is derived from `key + slug` at
- *    registration time.
- *  - `label`: human-readable admin-UI display text for the checkbox.
- *  - `tool` / `prompt` / `resource`: the live primitive (its own
- *    `description` is what both MCP clients and the admin UI surface).
+ * - `configKey`: the config/API-key identifier, e.g. `find` or `echo`.
+ * - `mcpName`: the MCP wire name, e.g. `findDocuments` or `echo`.
+ * - `label`: human-readable admin checkbox text.
  */
 export type MCPItemBase = {
-  key: string
+  configKey: string
   label: string
+  mcpName: string
 }
 
+export type CollectionMCPItem = {
+  collectionSlug: CollectionSlug
+  tool: CollectionTool
+  type: 'collectionTool'
+} & MCPItemBase
+
+export type GlobalMCPItem = {
+  globalSlug: GlobalSlug
+  tool: GlobalTool
+  type: 'globalTool'
+} & MCPItemBase
+
 export type MCPItem =
-  | ({
-      collectionSlug: CollectionSlug
-      tool: CollectionTool
-      type: 'collectionTool'
-    } & MCPItemBase)
-  | ({
-      globalSlug: GlobalSlug
-      tool: GlobalTool
-      type: 'globalTool'
-    } & MCPItemBase)
   | ({
       prompt: Prompt
       type: 'prompt'
@@ -333,6 +331,8 @@ export type MCPItem =
       tool: Tool
       type: 'tool'
     } & MCPItemBase)
+  | CollectionMCPItem
+  | GlobalMCPItem
 
 /**
  * The caller's identity + the MCP items they can use for this request. Returned

package/src/utils/schemaConversion/getEntityInputSchema.ts

@@ -0,0 +1,78 @@
+import {
+  type CollectionSlug,
+  entityToStandaloneJSONSchema,
+  type GlobalSlug,
+  type PayloadRequest,
+  type SanitizedCollectionConfig,
+  type SanitizedGlobalConfig,
+} from 'payload'
+
+import type { JsonSchemaType } from '../../types.js'
+
+import {
+  getCollectionVirtualFieldNames,
+  getGlobalVirtualFieldNames,
+} from '../getVirtualFieldNames.js'
+import { removeVirtualFieldsFromSchema } from './removeVirtualFieldsFromSchema.js'
+import { sanitizeEntitySchema } from './sanitizeEntitySchema.js'
+
+export const getCollectionInputSchema = ({
+  collectionSlug,
+  req,
+}: {
+  collectionSlug: CollectionSlug
+  req: PayloadRequest
+}): JsonSchemaType | null => {
+  const collection = req.payload.collections[collectionSlug]?.config
+
+  if (!collection) {
+    return null
+  }
+
+  return buildEntityInputSchema({
+    entity: collection,
+    req,
+    virtualFieldNames: getCollectionVirtualFieldNames(req.payload.config, collectionSlug),
+  })
+}
+
+export const getGlobalInputSchema = ({
+  globalSlug,
+  req,
+}: {
+  globalSlug: GlobalSlug
+  req: PayloadRequest
+}): JsonSchemaType | null => {
+  const global = req.payload.config.globals.find((globalConfig) => globalConfig.slug === globalSlug)
+
+  if (!global) {
+    return null
+  }
+
+  return buildEntityInputSchema({
+    entity: global,
+    req,
+    virtualFieldNames: getGlobalVirtualFieldNames(req.payload.config, globalSlug),
+  })
+}
+
+const buildEntityInputSchema = ({
+  entity,
+  req,
+  virtualFieldNames,
+}: {
+  entity: SanitizedCollectionConfig | SanitizedGlobalConfig
+  req: PayloadRequest
+  virtualFieldNames: string[]
+}): JsonSchemaType =>
+  sanitizeEntitySchema(
+    removeVirtualFieldsFromSchema(
+      entityToStandaloneJSONSchema({
+        config: req.payload.config,
+        defaultIDType: req.payload.db.defaultIDType,
+        entity,
+        i18n: req.i18n,
+      }) as unknown as JsonSchemaType,
+      virtualFieldNames,
+    ),
+  )

package/src/utils/schemaConversion/sanitizeEntitySchema.spec.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest'
+
+import type { JsonSchemaType } from '../../types.js'
+
+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: JsonSchemaType = {
+      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' } },
+              },
+            },
+          },
+        },
+      },
+    })
+  })
+})