@payloadcms/plugin-mcp 4.0.0-internal.5f0cd13 → 4.0.0-internal.a0ef1b8

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