@payloadcms/plugin-mcp 4.0.0-internal.e16cf59 → 4.0.0-internal.e38d3ac

package/src/utils/getLogger.ts

@@ -0,0 +1,22 @@
+import type { Payload } from 'payload'
+
+import { getPluginConfig } from './getPluginConfig.js'
+
+/**
+ * Get the logger for the MCP plugin. Child of the main Payload logger, prefixed with `[plugin-mcp]`
+ * and tagged with a structured `plugin: 'mcp'` field. When `verboseLogs` is off, info/debug calls
+ * are silenced; warn/error still surface so operators don't lose error signal.
+ */
+export const getLogger: (args: { payload: Payload }) => Payload['logger'] = ({ payload }) => {
+  const pluginConfig = getPluginConfig({ config: payload.config })
+
+  const useVerboseLogs = pluginConfig?.mcp?.verboseLogs ?? false
+
+  const logger = payload.logger.child({ plugin: 'mcp' }, { msgPrefix: '[plugin-mcp] ' })
+
+  if (!useVerboseLogs) {
+    logger.level = 'warn'
+  }
+
+  return logger
+}

package/src/utils/getPluginConfig.ts

@@ -0,0 +1,24 @@
+import type { PluginsMap, SanitizedConfig } from 'payload'
+
+import type { SanitizedMCPPluginConfig } from '../types.js'
+
+/**
+ * Returns the sanitized plugin config — the form produced by
+ * `sanitizeMCPConfig` and stashed back on the plugin's `options` during init.
+ * Callers downstream of plugin init can rely on `items` and other defaults
+ * being fully resolved.
+ */
+export const getPluginConfig: (args: { config: SanitizedConfig }) => SanitizedMCPPluginConfig = ({
+  config,
+}) => {
+  const plugin = config.plugins?.find(
+    (plugin) => plugin.slug === '@payloadcms/plugin-mcp',
+  ) as PluginsMap['@payloadcms/plugin-mcp']
+
+  if (!plugin) {
+    throw new Error('MCP Plugin not found in config.plugins.')
+  }
+
+  // @ts-expect-error
+  return plugin.sanitizedOptions
+}

package/src/utils/resolveProjectRoot.ts

@@ -0,0 +1,17 @@
+import path from 'path'
+
+/**
+ * Returns the project root: the parent of the outermost `node_modules` segment in
+ * `fromPath`. Returns `null` when the path has no `node_modules` (e.g. running from
+ * source inside the Payload monorepo).
+ */
+export const resolveProjectRoot = (fromPath: string): null | string => {
+  const segments = fromPath.split(path.sep)
+  const nodeModulesIndex = segments.indexOf('node_modules')
+
+  if (nodeModulesIndex <= 0) {
+    return null
+  }
+
+  return segments.slice(0, nodeModulesIndex).join(path.sep) || null
+}

package/src/utils/schemaConversion/filterFieldsByAccess.ts

@@ -0,0 +1,123 @@
+import type {
+  FlattenedBlock,
+  FlattenedField,
+  Operation,
+  SanitizedDocumentPermissions,
+  SanitizedFieldsPermissions,
+} from 'payload'
+
+type FieldOperation = Exclude<Operation, 'delete'>
+type AllowedFieldOperations = Record<FieldOperation, boolean>
+
+/**
+ * Filters fields using the access results in `permissions`. `shouldExcludeField` receives the
+ * operations allowed by the entity, field, and its parents and decides whether to remove the
+ * field.
+ *
+ * Arrays, groups, named tabs, and blocks are filtered recursively. Rows and unnamed tabs are
+ * flattened by Payload, so their children are filtered at the containing level.
+ *
+ * @example Include fields writable through any collection operation the user can perform.
+ * ```ts
+ * filterFieldsByAccess({
+ *   fields,
+ *   permissions: collectionPermissions,
+ *   shouldExcludeField: ({ create, update }) => !create && !update,
+ * })
+ * ```
+ */
+export const filterFieldsByAccess = ({
+  blocks,
+  fields,
+  permissions,
+  shouldExcludeField,
+}: {
+  blocks?: FlattenedBlock[]
+  fields: FlattenedField[]
+  permissions: SanitizedDocumentPermissions
+  shouldExcludeField: (allowedOperations: AllowedFieldOperations) => boolean
+}): FlattenedField[] => {
+  const filterFields = (
+    nestedFields: FlattenedField[],
+    nestedPermissions: SanitizedFieldsPermissions | undefined,
+    parentAllowedOperations: AllowedFieldOperations,
+  ): FlattenedField[] => {
+    const accessibleFields: FlattenedField[] = []
+
+    for (const field of nestedFields) {
+      const fieldPermissions = nestedPermissions === true ? true : nestedPermissions?.[field.name]
+      const isOperationAllowed = (operation: FieldOperation): boolean =>
+        parentAllowedOperations[operation] &&
+        (fieldPermissions === true || fieldPermissions?.[operation] === true)
+      const allowedOperations: AllowedFieldOperations = {
+        create: isOperationAllowed('create'),
+        read: isOperationAllowed('read'),
+        update: isOperationAllowed('update'),
+      }
+
+      if (shouldExcludeField(allowedOperations)) {
+        continue
+      }
+
+      if (field.type === 'blocks') {
+        const accessibleBlocks: (FlattenedBlock | string)[] = []
+
+        for (const blockOrReference of field.blocks) {
+          const block =
+            typeof blockOrReference === 'string'
+              ? blocks?.find(({ slug }) => slug === blockOrReference)
+              : blockOrReference
+
+          if (!block) {
+            continue
+          }
+
+          const blockPermissions =
+            fieldPermissions === true
+              ? true
+              : fieldPermissions?.blocks === true
+                ? true
+                : fieldPermissions?.blocks?.[block.slug]
+
+          accessibleBlocks.push({
+            ...block,
+            flattenedFields: filterFields(
+              block.flattenedFields,
+              blockPermissions === true ? true : blockPermissions?.fields,
+              allowedOperations,
+            ),
+          })
+        }
+
+        if (accessibleBlocks.length === 0) {
+          continue
+        }
+
+        accessibleFields.push({ ...field, blocks: accessibleBlocks })
+        continue
+      }
+
+      if (field.type === 'array' || field.type === 'group' || field.type === 'tab') {
+        accessibleFields.push({
+          ...field,
+          flattenedFields: filterFields(
+            field.flattenedFields,
+            fieldPermissions === true ? true : fieldPermissions?.fields,
+            allowedOperations,
+          ),
+        })
+        continue
+      }
+
+      accessibleFields.push(field)
+    }
+
+    return accessibleFields
+  }
+
+  return filterFields(fields, permissions.fields, {
+    create: 'create' in permissions && permissions.create === true,
+    read: permissions.read === true,
+    update: permissions.update === true,
+  })
+}

package/src/utils/schemaConversion/getEntityInputSchema.ts

@@ -0,0 +1,96 @@
+import {
+  type CollectionSlug,
+  entityToStandaloneJSONSchema,
+  type FlattenedField,
+  type GlobalSlug,
+  type PayloadRequest,
+  type SanitizedCollectionConfig,
+  type SanitizedCollectionPermission,
+  type SanitizedGlobalConfig,
+  type SanitizedGlobalPermission,
+} from 'payload'
+
+import type { JsonSchemaType } from '../../types.js'
+
+import { filterFieldsByAccess } from './filterFieldsByAccess.js'
+import { sanitizeEntitySchema } from './sanitizeEntitySchema.js'
+
+export const getCollectionInputSchema = ({
+  collectionSlug,
+  permissions,
+  req,
+}: {
+  collectionSlug: CollectionSlug
+  permissions?: SanitizedCollectionPermission
+  req: PayloadRequest
+}): JsonSchemaType | null => {
+  const collection = req.payload.collections[collectionSlug]?.config
+
+  if (!collection) {
+    return null
+  }
+
+  if (!permissions) {
+    return buildEntityInputSchema({ entity: collection, req })
+  }
+
+  const fieldsAllowedByAccess = filterFieldsByAccess({
+    blocks: req.payload.config.blocks,
+    fields: collection.flattenedFields,
+    permissions,
+    shouldExcludeField: ({ create, update }) => !create && !update,
+  })
+
+  return buildEntityInputSchema({ entity: collection, fields: fieldsAllowedByAccess, req })
+}
+
+export const getGlobalInputSchema = ({
+  globalSlug,
+  permissions,
+  req,
+}: {
+  globalSlug: GlobalSlug
+  permissions?: SanitizedGlobalPermission
+  req: PayloadRequest
+}): JsonSchemaType | null => {
+  const global = req.payload.config.globals.find((globalConfig) => globalConfig.slug === globalSlug)
+
+  if (!global) {
+    return null
+  }
+
+  if (!permissions) {
+    return buildEntityInputSchema({ entity: global, req })
+  }
+
+  const fieldsAllowedByAccess = filterFieldsByAccess({
+    blocks: req.payload.config.blocks,
+    fields: global.flattenedFields,
+    permissions,
+    shouldExcludeField: ({ create, update }) => !create && !update,
+  })
+
+  return buildEntityInputSchema({ entity: global, fields: fieldsAllowedByAccess, req })
+}
+
+const buildEntityInputSchema = ({
+  entity,
+  fields = entity.flattenedFields,
+  req,
+}: {
+  entity: SanitizedCollectionConfig | SanitizedGlobalConfig
+  fields?: FlattenedField[]
+  req: PayloadRequest
+}): JsonSchemaType => {
+  // The core schema generator reads flattenedFields from the entity and has no fields argument.
+  const entityForSchema = { ...entity, flattenedFields: fields }
+  const schema = entityToStandaloneJSONSchema({
+    config: req.payload.config,
+    defaultIDType: req.payload.db.defaultIDType,
+    entity: entityForSchema,
+    i18n: req.i18n,
+    variant: 'input',
+  }) as unknown as JsonSchemaType
+
+  return sanitizeEntitySchema(schema)
+}

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

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+
+import type { JsonSchemaType } from '../../types.js'
+
+import { sanitizeEntitySchema } from './sanitizeEntitySchema.js'
+
+describe('sanitizeEntitySchema', () => {
+  it('renames the Lexical node-union definition to a short name and keeps it a strict oneOf', () => {
+    // Shaped like the schema the MCP server prepares for a collection with a Lexical richText field
+    // (Payload's `input` variant): a `$defs` node union (a `oneOf` of node shapes). The input variant
+    // already types the relationship node's `value` as a bare ID - there is no populated-doc `$ref` to
+    // reduce here (the variant did that upstream), so sanitize leaves the value untouched.
+    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: { type: 'string', description: 'The related document ID.' },
+              },
+              required: ['type'],
+            },
+          ],
+        },
+      },
+      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' },
+                // The value is already ID-only from the input variant - left as-is.
+                value: { type: 'string', description: 'The related document ID.' },
+              },
+              required: ['type'],
+            },
+          ],
+        },
+      },
+      properties: {
+        // Managed timestamps are excluded upstream by the `input` variant. `id` stays because it's
+        // a valid optional input (a client may supply a custom ID).
+        id: { type: 'string' },
+        content: {
+          type: 'object',
+          properties: {
+            root: {
+              type: 'object',
+              properties: {
+                children: { type: 'array', items: { $ref: '#/$defs/node' } },
+              },
+            },
+          },
+        },
+      },
+    })
+  })
+})