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

package/src/mcp/builtinTools.ts

@@ -1,4 +1,4 @@
-import type { CollectionTool, GlobalTool } from '../types.js'
+import type { CollectionTool, GlobalTool, Tool } from '../types.js'
 
 import {
   authCollectionTool,
@@ -8,62 +8,72 @@ import {
   unlockCollectionTool,
   verifyCollectionTool,
 } from './builtin/collections/authTools.js'
-import { createCollectionTool } from './builtin/collections/createTool.js'
-import { deleteCollectionTool } from './builtin/collections/deleteTool.js'
-import { findCollectionTool } from './builtin/collections/findTool.js'
-import { updateCollectionTool } from './builtin/collections/updateTool.js'
+import { createDocumentTool } from './builtin/collections/createTool.js'
+import { deleteDocumentsTool } from './builtin/collections/deleteTool.js'
+import { findDocumentsTool } from './builtin/collections/findTool.js'
+import { getCollectionSchemaTool } from './builtin/collections/getCollectionSchemaTool.js'
+import { updateDocumentTool } from './builtin/collections/updateTool.js'
+import { getConfigInfoTool } from './builtin/getConfigInfoTool.js'
 import { findGlobalTool } from './builtin/globals/findTool.js'
+import { getGlobalSchemaTool } from './builtin/globals/getGlobalSchemaTool.js'
 import { updateGlobalTool } from './builtin/globals/updateTool.js'
 
+export const TOOL_BUILTINS = {
+  getConfigInfo: { label: 'Config Info', mcpName: 'getConfigInfo', tool: getConfigInfoTool },
+} satisfies Record<string, { label: string; mcpName: string; tool: Tool }>
+
 /**
  * The static built-in collection CRUD tools. Keys here are the source of truth
  * for `MCPCollectionBuiltinName` — adding/removing an entry updates the type
  * automatically.
  */
-export const COLLECTION_BUILTINS: Record<MCPCollectionBuiltinName, CollectionTool> = {
-  create: createCollectionTool,
-  delete: deleteCollectionTool,
-  find: findCollectionTool,
-  update: updateCollectionTool,
-}
+export const COLLECTION_BUILTINS = {
+  create: { mcpName: 'createDocument', tool: createDocumentTool },
+  delete: { mcpName: 'deleteDocuments', tool: deleteDocumentsTool },
+  find: { mcpName: 'findDocuments', tool: findDocumentsTool },
+  getCollectionSchema: { mcpName: 'getCollectionSchema', tool: getCollectionSchemaTool },
+  update: { mcpName: 'updateDocument', tool: updateDocumentTool },
+} satisfies Record<string, { mcpName: string; tool: CollectionTool }>
 
 /**
  * The static auth tools surfaced under auth-enabled collections. Each entry
  * carries the admin-UI label alongside the tool. Keys are the source of truth
  * for `MCPCollectionAuthToolName`.
  */
-export const COLLECTION_AUTH_BUILTINS: Record<
-  MCPCollectionAuthToolName,
-  { label: string; tool: CollectionTool }
-> = {
-  auth: { label: 'Check Auth Status', tool: authCollectionTool },
-  forgotPassword: { label: 'Forgot Password', tool: forgotPasswordCollectionTool },
-  login: { label: 'User Login', tool: loginCollectionTool },
-  resetPassword: { label: 'Reset Password', tool: resetPasswordCollectionTool },
-  unlock: { label: 'Unlock Account', tool: unlockCollectionTool },
-  verify: { label: 'Email Verification', tool: verifyCollectionTool },
-}
+export const COLLECTION_AUTH_BUILTINS = {
+  auth: { label: 'Check Auth Status', mcpName: 'auth', tool: authCollectionTool },
+  forgotPassword: {
+    label: 'Forgot Password',
+    mcpName: 'forgotPassword',
+    tool: forgotPasswordCollectionTool,
+  },
+  login: { label: 'User Login', mcpName: 'login', tool: loginCollectionTool },
+  resetPassword: {
+    label: 'Reset Password',
+    mcpName: 'resetPassword',
+    tool: resetPasswordCollectionTool,
+  },
+  unlock: { label: 'Unlock Account', mcpName: 'unlock', tool: unlockCollectionTool },
+  verify: { label: 'Email Verification', mcpName: 'verify', tool: verifyCollectionTool },
+} satisfies Record<string, { label: string; mcpName: string; tool: CollectionTool }>
 
 /**
  * The static built-in global tools. Keys are the source of truth for
  * `MCPGlobalBuiltinName`.
  */
-export const GLOBAL_BUILTINS: Record<MCPGlobalBuiltinName, GlobalTool> = {
-  find: findGlobalTool,
-  update: updateGlobalTool,
-}
+export const GLOBAL_BUILTINS = {
+  find: { mcpName: 'findGlobal', tool: findGlobalTool },
+  getGlobalSchema: { mcpName: 'getGlobalSchema', tool: getGlobalSchemaTool },
+  update: { mcpName: 'updateGlobal', tool: updateGlobalTool },
+} satisfies Record<string, { mcpName: string; tool: GlobalTool }>
+
+export type MCPCollectionBuiltinName = keyof typeof COLLECTION_BUILTINS
 
-export type MCPCollectionBuiltinName = 'create' | 'delete' | 'find' | 'update'
+export type MCPCollectionAuthToolName = keyof typeof COLLECTION_AUTH_BUILTINS
 
-export type MCPCollectionAuthToolName =
-  | 'auth'
-  | 'forgotPassword'
-  | 'login'
-  | 'resetPassword'
-  | 'unlock'
-  | 'verify'
+export type MCPGlobalBuiltinName = keyof typeof GLOBAL_BUILTINS
 
-export type MCPGlobalBuiltinName = 'find' | 'update'
+export type MCPTopLevelBuiltinName = keyof typeof TOOL_BUILTINS
 
 /**
  * Pre-typed `Object.entries` for each registry. The cast from `string` to the
@@ -71,14 +81,18 @@ export type MCPGlobalBuiltinName = 'find' | 'update'
  * cast — TypeScript's `Object.entries` always widens keys to `string`, which
  * defeats the narrow type lookups on `MCPCollectionToolsMap`.
  */
+export const TOOL_BUILTIN_ENTRIES = Object.entries(TOOL_BUILTINS) as Array<
+  [MCPTopLevelBuiltinName, (typeof TOOL_BUILTINS)[MCPTopLevelBuiltinName]]
+>
+
 export const COLLECTION_BUILTIN_ENTRIES = Object.entries(COLLECTION_BUILTINS) as Array<
-  [MCPCollectionBuiltinName, CollectionTool]
+  [MCPCollectionBuiltinName, (typeof COLLECTION_BUILTINS)[MCPCollectionBuiltinName]]
 >
 
 export const COLLECTION_AUTH_BUILTIN_ENTRIES = Object.entries(COLLECTION_AUTH_BUILTINS) as Array<
-  [MCPCollectionAuthToolName, { label: string; tool: CollectionTool }]
+  [MCPCollectionAuthToolName, (typeof COLLECTION_AUTH_BUILTINS)[MCPCollectionAuthToolName]]
 >
 
 export const GLOBAL_BUILTIN_ENTRIES = Object.entries(GLOBAL_BUILTINS) as Array<
-  [MCPGlobalBuiltinName, GlobalTool]
+  [MCPGlobalBuiltinName, (typeof GLOBAL_BUILTINS)[MCPGlobalBuiltinName]]
 >

package/src/mcp/sanitizeMCPConfig.ts

@@ -8,13 +8,12 @@ import type {
 } from 'payload'
 
 import type {
+  CollectionMCPItem,
   CollectionTool,
+  GlobalMCPItem,
   GlobalTool,
-  MCPBuiltInToolOverride,
   MCPItem,
-  MCPPluginCollectionConfig,
   MCPPluginConfig,
-  MCPPluginGlobalConfig,
   SanitizedMCPPluginConfig,
 } from '../types.js'
 
@@ -25,6 +24,8 @@ import {
   COLLECTION_BUILTINS,
   GLOBAL_BUILTIN_ENTRIES,
   GLOBAL_BUILTINS,
+  TOOL_BUILTIN_ENTRIES,
+  TOOL_BUILTINS,
 } from './builtinTools.js'
 
 /**
@@ -54,29 +55,45 @@ export const sanitizeMCPConfig = ({
     items.push(...sanitizeGlobalConfig({ global, pluginConfig }))
   }
 
-  for (const [key, tool] of Object.entries(pluginConfig.tools ?? {})) {
+  for (const [configKey, { label, mcpName, tool }] of TOOL_BUILTIN_ENTRIES) {
     items.push({
       type: 'tool',
-      key,
-      label: key,
+      configKey,
+      label,
+      mcpName,
       tool,
     })
   }
 
-  for (const [key, prompt] of Object.entries(pluginConfig.prompts ?? {})) {
+  for (const [configKey, tool] of Object.entries(pluginConfig.tools ?? {})) {
+    if (configKey in TOOL_BUILTINS) {
+      continue
+    }
+    items.push({
+      type: 'tool',
+      configKey,
+      label: configKey,
+      mcpName: configKey,
+      tool,
+    })
+  }
+
+  for (const [configKey, prompt] of Object.entries(pluginConfig.prompts ?? {})) {
     items.push({
       type: 'prompt',
-      key,
-      label: prompt.title ?? key,
+      configKey,
+      label: prompt.title ?? configKey,
+      mcpName: configKey,
       prompt,
     })
   }
 
-  for (const [key, resource] of Object.entries(pluginConfig.resources ?? {})) {
+  for (const [configKey, resource] of Object.entries(pluginConfig.resources ?? {})) {
     items.push({
       type: 'resource',
-      key,
-      label: resource.title ?? key,
+      configKey,
+      label: resource.title ?? configKey,
+      mcpName: configKey,
       resource,
     })
   }
@@ -101,30 +118,39 @@ const sanitizeCollectionConfig = ({
 }: {
   collection: CollectionConfig | SanitizedCollectionConfig
   pluginConfig: MCPPluginConfig
-}): MCPItem[] => {
+}): CollectionMCPItem[] => {
   if (collection.slug === 'payload-mcp-api-keys') {
     return []
   }
   const slug = collection.slug
   const collectionPluginConfig = pluginConfig.collections?.[slug]
-  const items: MCPItem[] = []
+  const items: CollectionMCPItem[] = []
 
-  for (const [toolKey, tool] of COLLECTION_BUILTIN_ENTRIES) {
+  for (const [toolKey, { mcpName, tool }] of COLLECTION_BUILTIN_ENTRIES) {
     const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
     if (matchedConfigEntry === false) {
       continue
     }
+    const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
     items.push({
       type: 'collectionTool',
       collectionSlug: slug,
-      key: toolKey,
+      configKey: toolKey,
       label: capitalize(toolKey),
-      tool: overrideBuiltinTool(tool, matchedConfigEntry, collectionPluginConfig),
+      mcpName,
+      tool: {
+        ...tool,
+        description: override?.description ?? tool.description,
+        overrideResponse:
+          override?.overrideResponse ??
+          collectionPluginConfig?.overrideResponse ??
+          tool.overrideResponse,
+      },
     })
   }
 
   if (collection.auth) {
-    for (const [authToolKey, { label, tool }] of COLLECTION_AUTH_BUILTIN_ENTRIES) {
+    for (const [authToolKey, { label, mcpName, tool }] of COLLECTION_AUTH_BUILTIN_ENTRIES) {
       const matchedConfigEntry = collectionPluginConfig?.tools?.[authToolKey]
       if (!matchedConfigEntry) {
         continue
@@ -134,9 +160,17 @@ const sanitizeCollectionConfig = ({
       items.push({
         type: 'collectionTool',
         collectionSlug: slug,
-        key: authToolKey,
+        configKey: authToolKey,
         label,
-        tool: overrideBuiltinTool(tool, override, collectionPluginConfig),
+        mcpName,
+        tool: {
+          ...tool,
+          description: override?.description ?? tool.description,
+          overrideResponse:
+            override?.overrideResponse ??
+            collectionPluginConfig?.overrideResponse ??
+            tool.overrideResponse,
+        },
       })
     }
   }
@@ -146,8 +180,8 @@ const sanitizeCollectionConfig = ({
   const customEntries = Object.entries(collectionPluginConfig?.tools ?? {}) as Array<
     [string, CollectionTool | undefined]
   >
-  for (const [key, customTool] of customEntries) {
-    if (key in COLLECTION_BUILTINS || key in COLLECTION_AUTH_BUILTINS) {
+  for (const [configKey, customTool] of customEntries) {
+    if (configKey in COLLECTION_BUILTINS || configKey in COLLECTION_AUTH_BUILTINS) {
       continue
     }
     if (!customTool) {
@@ -156,8 +190,9 @@ const sanitizeCollectionConfig = ({
     items.push({
       type: 'collectionTool',
       collectionSlug: slug,
-      key,
-      label: key,
+      configKey,
+      label: configKey,
+      mcpName: configKey,
       tool: customTool,
     })
   }
@@ -171,30 +206,39 @@ const sanitizeGlobalConfig = ({
 }: {
   global: GlobalConfig | SanitizedGlobalConfig
   pluginConfig: MCPPluginConfig
-}): MCPItem[] => {
+}): GlobalMCPItem[] => {
   const slug = global.slug
   const globalPluginConfig = pluginConfig.globals?.[slug]
-  const items: MCPItem[] = []
+  const items: GlobalMCPItem[] = []
 
-  for (const [toolKey, baseTool] of GLOBAL_BUILTIN_ENTRIES) {
+  for (const [toolKey, { mcpName, tool }] of GLOBAL_BUILTIN_ENTRIES) {
     const matchedConfigEntry = globalPluginConfig?.tools?.[toolKey]
     if (matchedConfigEntry === false) {
       continue
     }
+    const override = typeof matchedConfigEntry === 'object' ? matchedConfigEntry : undefined
     items.push({
       type: 'globalTool',
+      configKey: toolKey,
       globalSlug: slug,
-      key: toolKey,
       label: capitalize(toolKey),
-      tool: overrideBuiltinTool(baseTool, matchedConfigEntry, globalPluginConfig),
+      mcpName,
+      tool: {
+        ...tool,
+        description: override?.description ?? tool.description,
+        overrideResponse:
+          override?.overrideResponse ??
+          globalPluginConfig?.overrideResponse ??
+          tool.overrideResponse,
+      },
     })
   }
 
   const customEntries = Object.entries(globalPluginConfig?.tools ?? {}) as Array<
     [string, GlobalTool | undefined]
   >
-  for (const [key, customTool] of customEntries) {
-    if (key in GLOBAL_BUILTINS) {
+  for (const [configKey, customTool] of customEntries) {
+    if (configKey in GLOBAL_BUILTINS) {
       continue
     }
     if (!customTool) {
@@ -202,9 +246,10 @@ const sanitizeGlobalConfig = ({
     }
     items.push({
       type: 'globalTool',
+      configKey,
       globalSlug: slug,
-      key,
-      label: key,
+      label: configKey,
+      mcpName: configKey,
       tool: customTool,
     })
   }
@@ -213,27 +258,3 @@ const sanitizeGlobalConfig = ({
 }
 
 const capitalize = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1)
-
-/**
- * Spread the static built-in tool and apply consumer-side overrides.
- * Precedence: per-tool override > scope-level (collection/global) override >
- * the static tool's defaults. `toolEntry` is whatever the user put under
- * `tools: { find: ... }` — could be `true`, `false`, or an override object —
- * so it's narrowed internally.
- */
-const overrideBuiltinTool = <TTool extends CollectionTool | GlobalTool>(
-  tool: TTool,
-  toolOverride?: MCPBuiltInToolOverride,
-  entityPluginConfig?: TTool extends CollectionTool
-    ? MCPPluginCollectionConfig<any>
-    : MCPPluginGlobalConfig,
-): TTool => {
-  return {
-    ...tool,
-    description: toolOverride?.description ?? entityPluginConfig?.description ?? tool.description,
-    overrideResponse:
-      toolOverride?.overrideResponse ??
-      entityPluginConfig?.overrideResponse ??
-      tool.overrideResponse,
-  }
-}

package/src/types.ts

@@ -46,9 +46,9 @@ export type ToolInputSchema = JsonSchemaType | StandardSchemaWithJSON
 export type ClientMCPPluginConfig = {
   items: Array<{
     collectionSlug?: string
+    configKey: string
     description: string
     globalSlug?: string
-    key: string
     label: string
     type: 'collectionTool' | 'globalTool' | 'prompt' | 'resource' | 'tool'
   }>
@@ -105,22 +105,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'>
 
 /**
@@ -293,34 +288,32 @@ export type MCPAPIKeysDoc = {
 }
 
 /**
- * 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 +326,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' } },
+              },
+            },
+          },
+        },
+      },
+    })
+  })
+})