@payloadcms/plugin-mcp 4.0.0-internal.bc5cf8c → 4.0.0-internal.c7d5de4

package/src/utils/schemaConversion/sanitizeEntitySchema.ts

@@ -1,30 +1,22 @@
 import type { JsonSchemaType } from '../../types.js'
 
 /**
- * Turns the JSON Schema that Payload generates for a collection or global into the input schema for
- * an MCP create/update tool. In short, it:
- *
- * - drops fields a client can't set (`id`, `createdAt`, the draft `_status`, …),
- * - rewrites Payload-specific field shapes (points, relationships) into plain JSON the model can fill,
- * - and shrinks the result so it's cheaper for the model to read,
- *
- * while keeping every node valid JSON Schema draft 2020-12. Each step below is tagged with why it runs -
- * **Correctness** (valid input the API accepts), **Size** (equivalence-preserving shrink), or **LLM
- * ergonomics** (easier for the model to read/fill) - and carries a before/after example on its definition.
+ * Refines Payload's `input`-variant JSON Schema into an MCP create/update tool's input schema. The
+ * variant already covers correctness (ID-only relationships, no managed/virtual/join fields); the
+ * passes here are MCP-specific - reshaping fields for the model and shrinking the result - and keep
+ * every node valid JSON Schema draft 2020-12. Each is tagged **Correctness**, **Size**, or **LLM
+ * ergonomics**, with a before/after example on its definition.
  */
 export const sanitizeEntitySchema = (schema: JsonSchemaType): JsonSchemaType => {
   // Work on a copy — the caller reuses the original schema elsewhere (e.g. when listing tools).
   let result = structuredClone(schema)
 
-  // Correctness — drop the fields a client can't set (id, createdAt, updatedAt, draft _status) + collapse nullable types.
-  result = removeManagedFields(result)
+  // LLM ergonomics — drop the redundant `'null'` from optional arrays/objects (`['array','null']` → `'array'`).
+  result = collapseOptionalContainerTypes(result)
 
   // LLM ergonomics — rewrite point fields from a `[number, number]` tuple into a `{ longitude, latitude }` object.
   result = pointFieldsToObjects(result)
 
-  // Correctness — a relationship value can be an ID or a populated doc; on input only the ID is valid, so keep that.
-  result = relationshipsToIds(result)
-
   // Size — strip inert type-gen leftovers that only bloat the schema (`tsType`, block-collision notes).
   result = removeTypeGenArtifacts(result)
 
@@ -58,26 +50,20 @@ const mapNodes = (node: unknown, visit: (node: JsonSchemaType) => JsonSchemaType
   for (const [key, value] of Object.entries(node)) {
     out[key] = mapNodes(value, visit)
   }
-  return visit(out as JsonSchemaType)
+  return visit(out)
 }
 
-// Payload sets these on every document, so an MCP client never provides them when creating/updating.
-const PAYLOAD_MANAGED_FIELDS = new Set(['_status', 'createdAt', 'id', 'updatedAt'])
-
 /**
- * **Correctness.** Removes the fields a client can't set on create/update - `id`, `createdAt`, `updatedAt`, and the draft
- * `_status` - from every field object's `properties` and `required` (recursing into nested objects and
- * array items). Along the way it also collapses optional array/object types via {@link collapseNullableType}.
+ * **LLM ergonomics.** Collapses optional array/object types (`['array', 'null']` → `'array'`) via
+ * {@link collapseNullableType}, recursing through `properties` and array items. The `required` list
+ * already conveys optionality, so the `'null'` is redundant noise for the model.
  *
  * @example
- * { properties: { id: { type: 'string' }, tags: { type: ['array', 'null'], items: {} } }, required: ['id', 'tags'] }
- * → { properties: { tags: { type: 'array', items: {} } }, required: ['tags'] }
+ * { properties: { tags: { type: ['array', 'null'], items: {} } }, required: [] }
+ * → { properties: { tags: { type: 'array', items: {} } }, required: [] }
  */
-const removeManagedFields = (schema: JsonSchemaType): JsonSchemaType => {
+const collapseOptionalContainerTypes = (schema: JsonSchemaType): JsonSchemaType => {
   if (schema.properties && typeof schema.properties === 'object') {
-    for (const field of PAYLOAD_MANAGED_FIELDS) {
-      delete schema.properties[field]
-    }
     for (const key of Object.keys(schema.properties)) {
       const prop = schema.properties[key] as JsonSchemaType
       if (!prop || typeof prop !== 'object') {
@@ -86,21 +72,14 @@ const removeManagedFields = (schema: JsonSchemaType): JsonSchemaType => {
       const isRequired = Array.isArray(schema.required) && schema.required.includes(key)
       collapseNullableType(prop, isRequired)
       if (prop.properties) {
-        removeManagedFields(prop)
+        collapseOptionalContainerTypes(prop)
       }
       if (prop.items && typeof prop.items === 'object' && !Array.isArray(prop.items)) {
-        removeManagedFields(prop.items)
+        collapseOptionalContainerTypes(prop.items)
       }
     }
   }
 
-  if (Array.isArray(schema.required)) {
-    schema.required = schema.required.filter((name) => !PAYLOAD_MANAGED_FIELDS.has(name))
-    if (schema.required.length === 0) {
-      delete schema.required
-    }
-  }
-
   return schema
 }
 
@@ -193,82 +172,6 @@ const pointFieldsToObjects = (schema: JsonSchemaType): JsonSchemaType => {
   return transformed
 }
 
-/**
- * **Correctness.** Reduces relationship/upload fields to the IDs a client actually sends. Payload types the value as
- * "an ID or the full related document" - but the populated-document form only appears in read responses;
- * on create/update you always reference a relationship by its ID. So we drop that `$ref` option, leaving
- * the bare ID. A single remaining target collapses inline (with a description naming the target
- * collection); several targets become an `anyOf` of IDs.
- *
- * @example
- * { oneOf: [{ type: 'string' }, { $ref: '#/$defs/posts' }] }
- * → { type: 'string', description: 'The ID of the related "posts" document.' }
- */
-const relationshipsToIds = (schema: JsonSchemaType): JsonSchemaType => {
-  if (!schema || typeof schema !== 'object') {
-    return schema
-  }
-
-  const processed = { ...schema }
-
-  if (Array.isArray(processed.oneOf)) {
-    const isRelatedDocRef = (option: unknown): option is { $ref: string } =>
-      !!option && typeof option === 'object' && '$ref' in option
-
-    if (processed.oneOf.some(isRelatedDocRef)) {
-      // A relationship value is "an ID, or the populated related document". Keep the ID option(s) and
-      // drop the `$ref`s to the related collections, since a client only ever sends the ID.
-      const idOptions = processed.oneOf
-        .filter((option) => !isRelatedDocRef(option))
-        .map((option) => (typeof option === 'object' ? relationshipsToIds(option) : option))
-      const targetCollections = processed.oneOf
-        .filter(isRelatedDocRef)
-        .map((option) => option.$ref.replace('#/$defs/', ''))
-
-      if (idOptions.length === 1) {
-        delete processed.oneOf
-        Object.assign(processed, idOptions[0])
-        if (targetCollections.length > 0 && !processed.description) {
-          processed.description = `The ID of the related "${targetCollections.join('" or "')}" document.`
-        }
-      } else if (idOptions.length > 1) {
-        delete processed.oneOf
-        processed.anyOf = idOptions
-      }
-    } else {
-      processed.oneOf = processed.oneOf.map((option) =>
-        typeof option === 'object' ? relationshipsToIds(option) : option,
-      )
-    }
-  }
-
-  if (processed.properties && typeof processed.properties === 'object') {
-    processed.properties = Object.fromEntries(
-      Object.entries(processed.properties).map(([key, value]) => [
-        key,
-        typeof value === 'object' ? relationshipsToIds(value) : value,
-      ]),
-    )
-  }
-
-  if (processed.items && typeof processed.items === 'object' && !Array.isArray(processed.items)) {
-    processed.items = relationshipsToIds(processed.items)
-  }
-
-  // Lexical node unions and blocks live under `$defs` and have their own relationship fields, so walk
-  // those too — otherwise their `$ref`s would dangle once we don't bundle the related collections.
-  if (processed.$defs && typeof processed.$defs === 'object') {
-    processed.$defs = Object.fromEntries(
-      Object.entries(processed.$defs).map(([key, value]) => [
-        key,
-        typeof value === 'object' ? relationshipsToIds(value) : value,
-      ]),
-    )
-  }
-
-  return processed
-}
-
 /**
  * **Size.** Strips type-generation leftovers that bloat the schema without helping the model: the `tsType`
  * hint (a `json-schema-to-typescript` extension; JSON Schema validators just ignore it, they don't reject it)
@@ -448,7 +351,7 @@ const deduplicateIntoDefinitions = (schema: JsonSchemaType): JsonSchemaType => {
         if (!name) {
           name = `shared_${nameByKey.size}`
           nameByKey.set(key, name)
-          sharedEntries[name] = node as JsonSchemaType
+          sharedEntries[name] = node
         }
         return { $ref: `#/$defs/${name}` }
       }

package/dist/@types/assets.d.js

@@ -1,2 +0,0 @@
-
-//# sourceMappingURL=assets.d.js.map

package/dist/@types/assets.d.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/@types/assets.d.ts"],"names":[],"mappings":""}

package/dist/utils/localAPIDefaults.d.ts

@@ -1,20 +0,0 @@
-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 declare const localAPIDefaults: (authorizedMCP: AuthorizedMCP) => {
-    overrideAccess: boolean;
-    user: AuthorizedMCP["user"];
-};
-//# sourceMappingURL=localAPIDefaults.d.ts.map

package/dist/utils/localAPIDefaults.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"localAPIDefaults.d.ts","sourceRoot":"","sources":["../../src/utils/localAPIDefaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,GAC3B,eAAe,aAAa,KAC3B;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAGvD,CAAA"}

package/dist/utils/localAPIDefaults.js

@@ -1,19 +0,0 @@
-/**
- * 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)=>({
-        overrideAccess: authorizedMCP.overrideAccess,
-        user: authorizedMCP.user
-    });
-
-//# sourceMappingURL=localAPIDefaults.js.map

package/dist/utils/localAPIDefaults.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/utils/localAPIDefaults.ts"],"sourcesContent":["import type { AuthorizedMCP } from '../types.js'\n\n/**\n * Returns the `user` and `overrideAccess` arguments every Payload local API call\n * should receive when initiated from an MCP request. Spread the result into the\n * call's arg object so the two pieces of caller state can't drift apart.\n *\n * @example\n * ```ts\n * await req.payload.create({\n *   collection: 'posts',\n *   data,\n *   ...localAPIDefaults(authorizedMCP),\n * })\n * ```\n */\nexport const localAPIDefaults = (\n  authorizedMCP: AuthorizedMCP,\n): { overrideAccess: boolean; user: AuthorizedMCP['user'] } => ({\n  overrideAccess: authorizedMCP.overrideAccess,\n  user: authorizedMCP.user,\n})\n"],"names":["localAPIDefaults","authorizedMCP","overrideAccess","user"],"mappings":"AAEA;;;;;;;;;;;;;CAaC,GACD,OAAO,MAAMA,mBAAmB,CAC9BC,gBAC8D,CAAA;QAC9DC,gBAAgBD,cAAcC,cAAc;QAC5CC,MAAMF,cAAcE,IAAI;IAC1B,CAAA,EAAE"}

package/dist/utils/schemaConversion/removeVirtualFieldsFromSchema.d.ts

@@ -1,7 +0,0 @@
-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 declare function removeVirtualFieldsFromSchema(schema: JsonSchemaType, virtualFieldNames: string[]): JsonSchemaType;
-//# sourceMappingURL=removeVirtualFieldsFromSchema.d.ts.map

package/dist/utils/schemaConversion/removeVirtualFieldsFromSchema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"removeVirtualFieldsFromSchema.d.ts","sourceRoot":"","sources":["../../../src/utils/schemaConversion/removeVirtualFieldsFromSchema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,cAAc,EACtB,iBAAiB,EAAE,MAAM,EAAE,GAC1B,cAAc,CAiBhB"}

package/dist/utils/schemaConversion/removeVirtualFieldsFromSchema.js

@@ -1,20 +0,0 @@
-/**
- * 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, virtualFieldNames) {
-    if (virtualFieldNames.length === 0) {
-        return schema;
-    }
-    for (const name of virtualFieldNames){
-        delete schema?.properties?.[name];
-    }
-    if (Array.isArray(schema.required)) {
-        schema.required = schema.required.filter((field)=>!virtualFieldNames.includes(field));
-        if (schema.required.length === 0) {
-            delete schema.required;
-        }
-    }
-    return schema;
-}
-
-//# sourceMappingURL=removeVirtualFieldsFromSchema.js.map

package/dist/utils/schemaConversion/removeVirtualFieldsFromSchema.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../src/utils/schemaConversion/removeVirtualFieldsFromSchema.ts"],"sourcesContent":["import type { JsonSchemaType } from '../../types.js'\n\n/**\n * Removes virtual fields from a JSON Schema by name so they don't appear\n * in the generated MCP tool input schema.\n */\nexport function removeVirtualFieldsFromSchema(\n  schema: JsonSchemaType,\n  virtualFieldNames: string[],\n): JsonSchemaType {\n  if (virtualFieldNames.length === 0) {\n    return schema\n  }\n\n  for (const name of virtualFieldNames) {\n    delete schema?.properties?.[name]\n  }\n\n  if (Array.isArray(schema.required)) {\n    schema.required = schema.required.filter((field) => !virtualFieldNames.includes(field))\n    if (schema.required.length === 0) {\n      delete schema.required\n    }\n  }\n\n  return schema\n}\n"],"names":["removeVirtualFieldsFromSchema","schema","virtualFieldNames","length","name","properties","Array","isArray","required","filter","field","includes"],"mappings":"AAEA;;;CAGC,GACD,OAAO,SAASA,8BACdC,MAAsB,EACtBC,iBAA2B;IAE3B,IAAIA,kBAAkBC,MAAM,KAAK,GAAG;QAClC,OAAOF;IACT;IAEA,KAAK,MAAMG,QAAQF,kBAAmB;QACpC,OAAOD,QAAQI,YAAY,CAACD,KAAK;IACnC;IAEA,IAAIE,MAAMC,OAAO,CAACN,OAAOO,QAAQ,GAAG;QAClCP,OAAOO,QAAQ,GAAGP,OAAOO,QAAQ,CAACC,MAAM,CAAC,CAACC,QAAU,CAACR,kBAAkBS,QAAQ,CAACD;QAChF,IAAIT,OAAOO,QAAQ,CAACL,MAAM,KAAK,GAAG;YAChC,OAAOF,OAAOO,QAAQ;QACxB;IACF;IAEA,OAAOP;AACT"}

package/src/@types/assets.d.ts

@@ -1,3 +0,0 @@
-declare module '*.css'
-
-declare module '*.scss'

package/src/utils/localAPIDefaults.ts

@@ -1,22 +0,0 @@
-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/schemaConversion/removeVirtualFieldsFromSchema.ts

@@ -1,27 +0,0 @@
-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: JsonSchemaType,
-  virtualFieldNames: string[],
-): JsonSchemaType {
-  if (virtualFieldNames.length === 0) {
-    return schema
-  }
-
-  for (const name of virtualFieldNames) {
-    delete schema?.properties?.[name]
-  }
-
-  if (Array.isArray(schema.required)) {
-    schema.required = schema.required.filter((field) => !virtualFieldNames.includes(field))
-    if (schema.required.length === 0) {
-      delete schema.required
-    }
-  }
-
-  return schema
-}