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

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

@@ -0,0 +1,68 @@
+import type { StandardSchemaWithJSON } from '@modelcontextprotocol/server'
+
+import { z } from 'zod'
+
+import type { JsonSchemaType } from '../../types.js'
+
+/**
+ * Builds a create/update tool's `input`: a `data` field (the document's fields) plus controls like
+ * `depth` and `draft`. Using just `z.fromJSONSchema(ourJSONSchema)` has a few problems which are mitigated
+ * in this function. z.fromJSONSchema is both bigger and lossier (≈40% larger on the lexical schema).
+ * Each example below is `what we publish` => `what a plain zod round-trip would publish instead`.
+ *
+ * @example
+ * Bigger - zod inlines shared defs instead of keeping our `$ref`s (and adds junk integer bounds), so a
+ * reused def is duplicated at every use:
+ * `{ $ref: '#/$defs/author' }` => `{ type: 'object', properties: { id, name }, additionalProperties: false }`
+ *
+ * @example
+ * Lossier - zod drops the `description` on `enum`/`const` fields:
+ * `{ enum: ['draft', 'published'], description: 'Publish state' }` → `{ enum: ['draft', 'published'] }`
+ */
+export const buildToolInput = <TControls extends z.ZodRawShape>({
+  controls,
+  dataDescription,
+  dataSchema,
+}: {
+  /** Tool options alongside `data` (depth, draft, where, …) as plain zod - inferred into `input`. */
+  controls: TControls
+  dataDescription: string
+  dataSchema: JsonSchemaType
+}) => {
+  // `sanitizeEntitySchema` already emits draft 2020-12 with `$defs`, which is what zod's `fromJSONSchema`
+  // and MCP clients both expect. Drop only the root `$schema` keyword, redundant once it's a sub-schema.
+  const { $schema: _schema, ...entitySchema } = dataSchema as Record<string, unknown>
+
+  const schema = z.object({
+    data: z.fromJSONSchema(entitySchema as unknown as z.core.JSONSchema.JSONSchema),
+    ...controls,
+  })
+  const standard = (schema as unknown as StandardSchemaWithJSON)['~standard']
+
+  return {
+    '~standard': {
+      ...standard,
+      jsonSchema: {
+        ...standard.jsonSchema,
+        input: (options) => {
+          // Start from zod's JSON Schema for the whole input, then replace its lossy `data` schema with
+          // the sanitized entity schema. The entity's `$defs` move to the root so the `$ref`s resolve.
+          const generated = standard.jsonSchema.input(options)
+          const { $defs, ...entityBody } = entitySchema
+          ;(generated.properties as Record<string, unknown>).data = {
+            ...entityBody,
+            description: dataDescription,
+          }
+          if ($defs) {
+            generated.$defs = $defs as object
+          } else {
+            delete generated.$defs
+          }
+          return generated
+        },
+      },
+    },
+  } as StandardSchemaWithJSON<
+    { data: Record<string, unknown> } & Omit<z.output<typeof schema>, 'data'>
+  >
+}

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