@payloadcms/plugin-mcp 3.86.0-internal.ac46214 → 4.0.0-canary.1

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`, `userCollection`, etc.
+ * 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/localAPIDefaults.ts

@@ -0,0 +1,22 @@
+import type { AuthorizedMCP } from '../types.js'
+
+/**
+ * Returns the `user` and `overrideAccess` arguments every Payload local API call
+ * should receive when initiated from an MCP request. Spread the result into the
+ * call's arg object so the two pieces of caller state can't drift apart.
+ *
+ * @example
+ * ```ts
+ * await req.payload.create({
+ *   collection: 'posts',
+ *   data,
+ *   ...localAPIDefaults(authorizedMCP),
+ * })
+ * ```
+ */
+export const localAPIDefaults = (
+  authorizedMCP: AuthorizedMCP,
+): { overrideAccess: boolean; user: AuthorizedMCP['user'] } => ({
+  overrideAccess: authorizedMCP.overrideAccess,
+  user: authorizedMCP.user,
+})

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/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/removeVirtualFieldsFromSchema.ts

@@ -1,13 +1,13 @@
-import type { JSONSchema4 } from 'json-schema'
+import type { JsonSchemaType } from '../../types.js'
 
 /**
  * Removes virtual fields from a JSON Schema by name so they don't appear
  * in the generated MCP tool input schema.
  */
 export function removeVirtualFieldsFromSchema(
-  schema: JSONSchema4,
+  schema: JsonSchemaType,
   virtualFieldNames: string[],
-): JSONSchema4 {
+): JsonSchemaType {
   if (virtualFieldNames.length === 0) {
     return schema
   }

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' } },
+              },
+            },
+          },
+        },
+      },
+    })
+  })
+})