feat(plugin-mcp): add depth parameter support to all MCP find resource tools (#14931)

### What
Adds `depth` parameter support to MCP resource tools (find and create),
allowing MCP clients to control relationship population depth when
querying or creating documents.

### Why

MCP clients currently have no way to control how deeply relationships
are populated when retrieving or creating documents. When collections
have relationship fields, agents need the ability to either:
  - Get just the IDs (depth=0) for lightweight responses
  - Get fully populated relationship data (depth=1+) for richer context

This can significantly reduce the token count when reading documents.

### How

- Added `depth` parameter to `findResources` and `createResource`
schemas in schemas.ts
- Updated `find.ts` to pass `depth` to both `payload.find()` and
`payload.findByID()` calls
  - Updated `create.ts` to pass `depth` to `payload.create()` call
  - Parameter is an optional integer (0-10) with default of 0
  - Added integration tests

---------

Co-authored-by: Kendell Joseph <kjoseph@figma.com>

Author: jhb-dev

packages/plugin-mcp/src/mcp/getMcpHandler.ts

@@ -44,7 +44,7 @@ export const getMCPHandler = (
   req: PayloadRequest,
 ) => {
   const { payload } = req
-  const configSchema = configToJSONSchema(payload.config)
+  const configSchema = configToJSONSchema(payload.config, payload.db.defaultIDType, req.i18n)
 
   // Handler wrapper that injects req before the _extra argument
   const wrapHandler = (handler: (...args: any[]) => any) => {

packages/plugin-mcp/src/mcp/tools/resource/create.ts

@@ -20,6 +20,7 @@ export const createResourceTool = (
 ) => {
   const tool = async (
     data: string,
+    depth: number = 0,
     draft: boolean,
     locale?: string,
     fallbackLocale?: string,
@@ -58,6 +59,7 @@ export const createResourceTool = (
       const result = await payload.create({
         collection: collectionSlug,
         data: parsedData,
+        depth,
         draft,
         overrideAccess: false,
         req,
@@ -122,6 +124,14 @@ ${JSON.stringify(result, null, 2)}
     // Create a new schema that combines the converted fields with create-specific parameters
     const createResourceSchema = z.object({
       ...convertedFields.shape,
+      depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .default(0)
+        .describe('How many levels deep to populate relationships in response'),
       draft: z
         .boolean()
         .optional()
@@ -144,10 +154,11 @@ ${JSON.stringify(result, null, 2)}
       `${collections?.[collectionSlug]?.description || toolSchemas.createResource.description.trim()}`,
       createResourceSchema.shape,
       async (params: Record<string, unknown>) => {
-        const { draft, fallbackLocale, locale, ...fieldData } = params
+        const { depth, draft, fallbackLocale, locale, ...fieldData } = params
         const data = JSON.stringify(fieldData)
         return await tool(
           data,
+          depth as number,
           draft as boolean,
           locale as string | undefined,
           fallbackLocale as string | undefined,

packages/plugin-mcp/src/mcp/tools/resource/find.ts

@@ -20,6 +20,7 @@ export const findResourceTool = (
     page: number = 1,
     sort?: string,
     where?: string,
+    depth: number = 0,
     locale?: string,
     fallbackLocale?: string,
     draft?: boolean,
@@ -67,6 +68,7 @@ export const findResourceTool = (
           const doc = await payload.findByID({
             id,
             collection: collectionSlug,
+            depth,
             overrideAccess: false,
             req,
             user,
@@ -121,6 +123,7 @@ ${JSON.stringify(doc, null, 2)}`,
       // Otherwise, use find to get multiple documents
       const findOptions: Parameters<typeof payload.find>[0] = {
         collection: collectionSlug,
+        depth,
         limit,
         overrideAccess: false,
         page,
@@ -199,8 +202,8 @@ Page: ${result.page} of ${result.totalPages}
       `find${collectionSlug.charAt(0).toUpperCase() + toCamelCase(collectionSlug).slice(1)}`,
       `${collections?.[collectionSlug]?.description || toolSchemas.findResources.description.trim()}`,
       toolSchemas.findResources.parameters.shape,
-      async ({ id, draft, fallbackLocale, limit, locale, page, sort, where }) => {
-        return await tool(id, limit, page, sort, where, locale, fallbackLocale, draft)
+      async ({ id, depth, draft, fallbackLocale, limit, locale, page, sort, where }) => {
+        return await tool(id, limit, page, sort, where, depth, locale, fallbackLocale, draft)
       },
     )
   }

packages/plugin-mcp/src/mcp/tools/schemas.ts

@@ -34,6 +34,14 @@ export const toolSchemas = {
         .describe(
           'Optional: specific document ID to retrieve. If not provided, returns all documents',
         ),
+      depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .default(0)
+        .describe('How many levels deep to populate relationships (default: 0)'),
       draft: z
         .boolean()
         .optional()
@@ -82,6 +90,14 @@ export const toolSchemas = {
     description: 'Create a document in a collection.',
     parameters: z.object({
       data: z.string().describe('JSON string containing the data for the new document'),
+      depth: z
+        .number()
+        .int()
+        .min(0)
+        .max(10)
+        .optional()
+        .default(0)
+        .describe('How many levels deep to populate relationships in response (default: 0)'),
       draft: z
         .boolean()
         .optional()

packages/plugin-mcp/src/utils/convertCollectionSchemaToZod.ts

@@ -4,12 +4,70 @@ import { jsonSchemaToZod } from 'json-schema-to-zod'
 import * as ts from 'typescript'
 import { z } from 'zod'
 
+/**
+ * Recursively processes JSON schema properties to simplify relationship fields.
+ * For create/update validation we only need to accept IDs (string/number),
+ * not populated objects. This removes the $ref option from oneOf unions
+ * that represent relationship fields, leaving only the ID shape.
+ *
+ * NOTE: This function must operate on a cloned schema to avoid mutating
+ * the original JSON schema used for tool listing.
+ */
+function simplifyRelationshipFields(schema: JSONSchema4): JSONSchema4 {
+  if (!schema || typeof schema !== 'object') {
+    return schema
+  }
+
+  const processed = { ...schema }
+
+  if (Array.isArray(processed.oneOf)) {
+    const hasRef = processed.oneOf.some(
+      (option) => option && typeof option === 'object' && '$ref' in option,
+    )
+
+    processed.oneOf = processed.oneOf.map((option) => {
+      if (option && typeof option === 'object' && '$ref' in option) {
+        // Replace unresolved $ref with a permissive object schema to keep the union shape
+        return { type: 'object', additionalProperties: true }
+      }
+      return simplifyRelationshipFields(option)
+    })
+  }
+
+  if (processed.properties && typeof processed.properties === 'object') {
+    processed.properties = Object.fromEntries(
+      Object.entries(processed.properties).map(([key, value]) => [
+        key,
+        simplifyRelationshipFields(value),
+      ]),
+    )
+  }
+
+  if (processed.items && typeof processed.items === 'object' && !Array.isArray(processed.items)) {
+    processed.items = simplifyRelationshipFields(processed.items)
+  }
+
+  return processed
+}
+
 export const convertCollectionSchemaToZod = (schema: JSONSchema4) => {
+  // Clone to avoid mutating the original schema (used elsewhere for tool listing)
+  const schemaClone = JSON.parse(JSON.stringify(schema)) as JSONSchema4
+
   // Remove properties that should not be included in the Zod schema
-  delete schema?.properties?.createdAt
-  delete schema?.properties?.updatedAt
+  delete schemaClone?.properties?.id
+  delete schemaClone?.properties?.createdAt
+  delete schemaClone?.properties?.updatedAt
+  if (Array.isArray(schemaClone.required)) {
+    schemaClone.required = schemaClone.required.filter((field) => field !== 'id')
+    if (schemaClone.required.length === 0) {
+      delete schemaClone.required
+    }
+  }
+
+  const simplifiedSchema = simplifyRelationshipFields(schemaClone)
 
-  const zodSchemaAsString = jsonSchemaToZod(schema)
+  const zodSchemaAsString = jsonSchemaToZod(simplifiedSchema)
 
   // Transpile TypeScript to JavaScript
   const transpileResult = ts.transpileModule(zodSchemaAsString, {