@payloadcms/plugin-mcp 4.0.0-internal.21664f3 → 4.0.0-internal.2a3c3bc

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/bin.js +0 -7
  2. package/dist/endpoint/access.d.ts.map +1 -1
  3. package/dist/endpoint/access.js +4 -3
  4. package/dist/endpoint/access.js.map +1 -1
  5. package/dist/endpoint/index.d.ts.map +1 -1
  6. package/dist/endpoint/index.js +39 -4
  7. package/dist/endpoint/index.js.map +1 -1
  8. package/dist/endpoint/oauth.d.ts +27 -0
  9. package/dist/endpoint/oauth.d.ts.map +1 -0
  10. package/dist/endpoint/oauth.js +61 -0
  11. package/dist/endpoint/oauth.js.map +1 -0
  12. package/dist/index.d.ts +1 -0
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +7 -0
  15. package/dist/index.js.map +1 -1
  16. package/dist/mcp/buildMcpServer.d.ts +2 -2
  17. package/dist/mcp/buildMcpServer.d.ts.map +1 -1
  18. package/dist/mcp/buildMcpServer.js +36 -24
  19. package/dist/mcp/buildMcpServer.js.map +1 -1
  20. package/dist/mcp/builtin/collections/authTools.d.ts.map +1 -1
  21. package/dist/mcp/builtin/collections/authTools.js +80 -56
  22. package/dist/mcp/builtin/collections/authTools.js.map +1 -1
  23. package/dist/mcp/builtin/collections/countTool.d.ts.map +1 -1
  24. package/dist/mcp/builtin/collections/countTool.js +9 -14
  25. package/dist/mcp/builtin/collections/countTool.js.map +1 -1
  26. package/dist/mcp/builtin/collections/countVersionsTool.d.ts.map +1 -1
  27. package/dist/mcp/builtin/collections/countVersionsTool.js +9 -13
  28. package/dist/mcp/builtin/collections/countVersionsTool.js.map +1 -1
  29. package/dist/mcp/builtin/collections/createTool.d.ts +1 -1
  30. package/dist/mcp/builtin/collections/createTool.d.ts.map +1 -1
  31. package/dist/mcp/builtin/collections/createTool.js +104 -63
  32. package/dist/mcp/builtin/collections/createTool.js.map +1 -1
  33. package/dist/mcp/builtin/collections/deleteTool.d.ts.map +1 -1
  34. package/dist/mcp/builtin/collections/deleteTool.js +44 -43
  35. package/dist/mcp/builtin/collections/deleteTool.js.map +1 -1
  36. package/dist/mcp/builtin/collections/duplicateTool.d.ts.map +1 -1
  37. package/dist/mcp/builtin/collections/duplicateTool.js +31 -37
  38. package/dist/mcp/builtin/collections/duplicateTool.js.map +1 -1
  39. package/dist/mcp/builtin/collections/fileInput.d.ts +21 -13
  40. package/dist/mcp/builtin/collections/fileInput.d.ts.map +1 -1
  41. package/dist/mcp/builtin/collections/fileInput.js +52 -64
  42. package/dist/mcp/builtin/collections/fileInput.js.map +1 -1
  43. package/dist/mcp/builtin/collections/findDistinctTool.d.ts.map +1 -1
  44. package/dist/mcp/builtin/collections/findDistinctTool.js +11 -26
  45. package/dist/mcp/builtin/collections/findDistinctTool.js.map +1 -1
  46. package/dist/mcp/builtin/collections/findTool.d.ts.map +1 -1
  47. package/dist/mcp/builtin/collections/findTool.js +27 -45
  48. package/dist/mcp/builtin/collections/findTool.js.map +1 -1
  49. package/dist/mcp/builtin/collections/findVersionByIDTool.d.ts.map +1 -1
  50. package/dist/mcp/builtin/collections/findVersionByIDTool.js +17 -26
  51. package/dist/mcp/builtin/collections/findVersionByIDTool.js.map +1 -1
  52. package/dist/mcp/builtin/collections/findVersionsTool.d.ts.map +1 -1
  53. package/dist/mcp/builtin/collections/findVersionsTool.js +16 -30
  54. package/dist/mcp/builtin/collections/findVersionsTool.js.map +1 -1
  55. package/dist/mcp/builtin/collections/getCollectionSchemaTool.d.ts.map +1 -1
  56. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js +33 -16
  57. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js.map +1 -1
  58. package/dist/mcp/builtin/collections/restoreVersionTool.d.ts.map +1 -1
  59. package/dist/mcp/builtin/collections/restoreVersionTool.js +14 -26
  60. package/dist/mcp/builtin/collections/restoreVersionTool.js.map +1 -1
  61. package/dist/mcp/builtin/collections/updateTool.d.ts.map +1 -1
  62. package/dist/mcp/builtin/collections/updateTool.js +58 -90
  63. package/dist/mcp/builtin/collections/updateTool.js.map +1 -1
  64. package/dist/mcp/builtin/collections/uploadInstructionsTool.d.ts +2 -0
  65. package/dist/mcp/builtin/collections/uploadInstructionsTool.d.ts.map +1 -0
  66. package/dist/mcp/builtin/collections/uploadInstructionsTool.js +55 -0
  67. package/dist/mcp/builtin/collections/uploadInstructionsTool.js.map +1 -0
  68. package/dist/mcp/builtin/formatEntityError.d.ts +16 -0
  69. package/dist/mcp/builtin/formatEntityError.d.ts.map +1 -0
  70. package/dist/mcp/builtin/formatEntityError.js +55 -0
  71. package/dist/mcp/builtin/formatEntityError.js.map +1 -0
  72. package/dist/mcp/builtin/getConfigInfoTool.d.ts.map +1 -1
  73. package/dist/mcp/builtin/getConfigInfoTool.js +3 -2
  74. package/dist/mcp/builtin/getConfigInfoTool.js.map +1 -1
  75. package/dist/mcp/builtin/globals/countVersionsTool.d.ts.map +1 -1
  76. package/dist/mcp/builtin/globals/countVersionsTool.js +9 -13
  77. package/dist/mcp/builtin/globals/countVersionsTool.js.map +1 -1
  78. package/dist/mcp/builtin/globals/findTool.d.ts.map +1 -1
  79. package/dist/mcp/builtin/globals/findTool.js +10 -16
  80. package/dist/mcp/builtin/globals/findTool.js.map +1 -1
  81. package/dist/mcp/builtin/globals/findVersionByIDTool.d.ts.map +1 -1
  82. package/dist/mcp/builtin/globals/findVersionByIDTool.js +13 -24
  83. package/dist/mcp/builtin/globals/findVersionByIDTool.js.map +1 -1
  84. package/dist/mcp/builtin/globals/findVersionsTool.d.ts.map +1 -1
  85. package/dist/mcp/builtin/globals/findVersionsTool.js +13 -29
  86. package/dist/mcp/builtin/globals/findVersionsTool.js.map +1 -1
  87. package/dist/mcp/builtin/globals/getGlobalSchemaTool.d.ts.map +1 -1
  88. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js +29 -13
  89. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js.map +1 -1
  90. package/dist/mcp/builtin/globals/restoreVersionTool.d.ts.map +1 -1
  91. package/dist/mcp/builtin/globals/restoreVersionTool.js +15 -22
  92. package/dist/mcp/builtin/globals/restoreVersionTool.js.map +1 -1
  93. package/dist/mcp/builtin/globals/updateTool.d.ts.map +1 -1
  94. package/dist/mcp/builtin/globals/updateTool.js +27 -36
  95. package/dist/mcp/builtin/globals/updateTool.js.map +1 -1
  96. package/dist/mcp/builtinTools.d.ts +6 -0
  97. package/dist/mcp/builtinTools.d.ts.map +1 -1
  98. package/dist/mcp/builtinTools.js +9 -3
  99. package/dist/mcp/builtinTools.js.map +1 -1
  100. package/dist/mcp/sanitizeMCPConfig.d.ts.map +1 -1
  101. package/dist/mcp/sanitizeMCPConfig.js +5 -1
  102. package/dist/mcp/sanitizeMCPConfig.js.map +1 -1
  103. package/dist/stdio.d.ts.map +1 -1
  104. package/dist/stdio.js +6 -4
  105. package/dist/stdio.js.map +1 -1
  106. package/dist/types.d.ts +30 -8
  107. package/dist/types.d.ts.map +1 -1
  108. package/dist/types.js.map +1 -1
  109. package/package.json +6 -8
  110. package/src/endpoint/access.ts +4 -4
  111. package/src/endpoint/index.ts +39 -3
  112. package/src/endpoint/oauth.ts +72 -0
  113. package/src/index.ts +7 -0
  114. package/src/mcp/buildMcpServer.ts +40 -30
  115. package/src/mcp/builtin/collections/authTools.ts +80 -69
  116. package/src/mcp/builtin/collections/countTool.ts +9 -21
  117. package/src/mcp/builtin/collections/countVersionsTool.ts +9 -18
  118. package/src/mcp/builtin/collections/createTool.ts +110 -86
  119. package/src/mcp/builtin/collections/deleteTool.ts +36 -64
  120. package/src/mcp/builtin/collections/duplicateTool.ts +35 -85
  121. package/src/mcp/builtin/collections/fileInput.spec.ts +20 -6
  122. package/src/mcp/builtin/collections/fileInput.ts +64 -76
  123. package/src/mcp/builtin/collections/findDistinctTool.ts +11 -63
  124. package/src/mcp/builtin/collections/findTool.ts +23 -105
  125. package/src/mcp/builtin/collections/findVersionByIDTool.ts +15 -58
  126. package/src/mcp/builtin/collections/findVersionsTool.ts +14 -85
  127. package/src/mcp/builtin/collections/getCollectionSchemaTool.ts +28 -13
  128. package/src/mcp/builtin/collections/restoreVersionTool.ts +14 -56
  129. package/src/mcp/builtin/collections/updateTool.ts +57 -111
  130. package/src/mcp/builtin/collections/uploadInstructionsTool.ts +64 -0
  131. package/src/mcp/builtin/formatEntityError.ts +77 -0
  132. package/src/mcp/builtin/getConfigInfoTool.ts +2 -1
  133. package/src/mcp/builtin/globals/countVersionsTool.ts +9 -17
  134. package/src/mcp/builtin/globals/findTool.ts +12 -51
  135. package/src/mcp/builtin/globals/findVersionByIDTool.ts +13 -52
  136. package/src/mcp/builtin/globals/findVersionsTool.ts +14 -92
  137. package/src/mcp/builtin/globals/getGlobalSchemaTool.ts +21 -11
  138. package/src/mcp/builtin/globals/restoreVersionTool.ts +14 -45
  139. package/src/mcp/builtin/globals/updateTool.ts +37 -60
  140. package/src/mcp/builtinTools.ts +9 -2
  141. package/src/mcp/sanitizeMCPConfig.ts +5 -1
  142. package/src/stdio.ts +4 -3
  143. package/src/types.ts +31 -8
  144. package/dist/mcp/builtin/collections/fileInput.spec.js +0 -72
  145. package/dist/mcp/builtin/collections/fileInput.spec.js.map +0 -1
  146. package/dist/mcp/builtin/collections/formatCollectionError.d.ts +0 -9
  147. package/dist/mcp/builtin/collections/formatCollectionError.d.ts.map +0 -1
  148. package/dist/mcp/builtin/collections/formatCollectionError.js +0 -60
  149. package/dist/mcp/builtin/collections/formatCollectionError.js.map +0 -1
  150. package/dist/mcp/builtin/validateEntityData.d.ts +0 -14
  151. package/dist/mcp/builtin/validateEntityData.d.ts.map +0 -1
  152. package/dist/mcp/builtin/validateEntityData.js +0 -82
  153. package/dist/mcp/builtin/validateEntityData.js.map +0 -1
  154. package/dist/utils/getVirtualFieldNames.d.ts +0 -14
  155. package/dist/utils/getVirtualFieldNames.d.ts.map +0 -1
  156. package/dist/utils/getVirtualFieldNames.js +0 -35
  157. package/dist/utils/getVirtualFieldNames.js.map +0 -1
  158. package/dist/utils/schemaConversion/filterFieldsByAccess.d.ts +0 -28
  159. package/dist/utils/schemaConversion/filterFieldsByAccess.d.ts.map +0 -1
  160. package/dist/utils/schemaConversion/filterFieldsByAccess.js +0 -71
  161. package/dist/utils/schemaConversion/filterFieldsByAccess.js.map +0 -1
  162. package/dist/utils/schemaConversion/getEntityInputSchema.d.ts +0 -13
  163. package/dist/utils/schemaConversion/getEntityInputSchema.d.ts.map +0 -1
  164. package/dist/utils/schemaConversion/getEntityInputSchema.js +0 -66
  165. package/dist/utils/schemaConversion/getEntityInputSchema.js.map +0 -1
  166. package/dist/utils/schemaConversion/sanitizeEntitySchema.d.ts +0 -10
  167. package/dist/utils/schemaConversion/sanitizeEntitySchema.d.ts.map +0 -1
  168. package/dist/utils/schemaConversion/sanitizeEntitySchema.js +0 -384
  169. package/dist/utils/schemaConversion/sanitizeEntitySchema.js.map +0 -1
  170. package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js +0 -133
  171. package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js.map +0 -1
  172. package/dist/utils/transformPointDataToPayload.d.ts +0 -7
  173. package/dist/utils/transformPointDataToPayload.d.ts.map +0 -1
  174. package/dist/utils/transformPointDataToPayload.js +0 -28
  175. package/dist/utils/transformPointDataToPayload.js.map +0 -1
  176. package/dist/utils/whereSchema.d.ts +0 -9
  177. package/dist/utils/whereSchema.d.ts.map +0 -1
  178. package/dist/utils/whereSchema.js +0 -13
  179. package/dist/utils/whereSchema.js.map +0 -1
  180. package/src/mcp/builtin/collections/formatCollectionError.ts +0 -84
  181. package/src/mcp/builtin/validateEntityData.ts +0 -132
  182. package/src/utils/getVirtualFieldNames.ts +0 -53
  183. package/src/utils/schemaConversion/filterFieldsByAccess.ts +0 -123
  184. package/src/utils/schemaConversion/getEntityInputSchema.ts +0 -96
  185. package/src/utils/schemaConversion/sanitizeEntitySchema.spec.ts +0 -96
  186. package/src/utils/schemaConversion/sanitizeEntitySchema.ts +0 -432
  187. package/src/utils/transformPointDataToPayload.ts +0 -40
  188. package/src/utils/whereSchema.ts +0 -24
@@ -1,12 +1,12 @@
1
- import { getAccessResults } from 'payload'
1
+ import { getAccessResults, getGlobalInputSchema, getGlobalSchemaInputSchema } from 'payload'
2
+ import { getLLMInstructions } from 'payload/internal'
2
3
 
3
4
  import { defaultAccess } from '../../../defaultAccess.js'
4
5
  import { defineGlobalTool } from '../../../defineTool.js'
5
- import { getGlobalInputSchema } from '../../../utils/schemaConversion/getEntityInputSchema.js'
6
6
 
7
7
  export const getGlobalSchemaTool = defineGlobalTool({
8
8
  access: (args) => {
9
- const permissions = args.permissions?.globals?.[args.globalSlug]
9
+ const permissions = args.permissions?.globals?.[args.slug]
10
10
 
11
11
  return defaultAccess(args) && Boolean(permissions?.update)
12
12
  },
@@ -17,18 +17,19 @@ export const getGlobalSchemaTool = defineGlobalTool({
17
17
  readOnlyHint: true,
18
18
  title: 'Get Global Schema',
19
19
  },
20
- description: 'Get the input schema for updating a global.',
21
- }).handler(async ({ authorizedMCP, globalSlug, req }) => {
20
+ description: 'Get the input schema and LLM instructions before updating a global.',
21
+ input: getGlobalSchemaInputSchema,
22
+ }).handler(async ({ slug, authorizedMCP, req }) => {
22
23
  const permissions = authorizedMCP.overrideAccess
23
24
  ? null
24
- : (await getAccessResults({ req })).globals?.[globalSlug]
25
+ : (await getAccessResults({ req })).globals?.[slug]
25
26
 
26
27
  if (!authorizedMCP.overrideAccess && !permissions?.update) {
27
28
  return {
28
29
  content: [
29
30
  {
30
31
  type: 'text',
31
- text: `Error: MCP access to "getGlobalSchema" is not enabled for global "${globalSlug}"`,
32
+ text: `Error: MCP access to "getGlobalSchema" is not enabled for global "${slug}"`,
32
33
  },
33
34
  ],
34
35
  isError: true,
@@ -36,28 +37,37 @@ export const getGlobalSchemaTool = defineGlobalTool({
36
37
  }
37
38
 
38
39
  const inputSchema = getGlobalInputSchema({
39
- globalSlug,
40
+ globalSlug: slug,
40
41
  req,
41
42
  ...(permissions ? { permissions } : {}),
42
43
  })
43
44
 
44
45
  if (!inputSchema) {
45
46
  return {
46
- content: [{ type: 'text', text: `Error: Global "${globalSlug}" not found` }],
47
+ content: [{ type: 'text', text: `Error: Global "${slug}" not found` }],
47
48
  isError: true,
48
49
  }
49
50
  }
50
51
 
52
+ const instructions = await getLLMInstructions({
53
+ slug,
54
+ type: 'global',
55
+ overrideAccess: authorizedMCP.overrideAccess,
56
+ req,
57
+ })
58
+
51
59
  return {
52
60
  content: [
53
61
  {
54
62
  type: 'text',
55
- text: `Schema for global "${globalSlug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\``,
63
+ text: `Schema for global "${slug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\``,
56
64
  },
65
+ ...(instructions ? [{ type: 'text' as const, text: instructions }] : []),
57
66
  ],
58
67
  structuredContent: {
59
- globalSlug,
68
+ slug,
60
69
  schema: inputSchema,
70
+ ...(instructions ? { instructions } : {}),
61
71
  },
62
72
  }
63
73
  })
@@ -1,6 +1,4 @@
1
- import type { PopulateType } from 'payload'
2
-
3
- import { z } from 'zod'
1
+ import { restoreGlobalVersionInputSchema } from 'payload'
4
2
 
5
3
  import { defaultAccess } from '../../../defaultAccess.js'
6
4
  import { defineGlobalTool } from '../../../defineTool.js'
@@ -10,8 +8,7 @@ const DEFAULT_DESCRIPTION =
10
8
  'Restore a global from a previous version in any version-enabled global.'
11
9
 
12
10
  export const restoreGlobalVersionTool = defineGlobalTool({
13
- access: (args) =>
14
- defaultAccess(args) && Boolean(args.permissions?.globals?.[args.globalSlug]?.update),
11
+ access: (args) => defaultAccess(args) && Boolean(args.permissions?.globals?.[args.slug]?.update),
15
12
  annotations: {
16
13
  destructiveHint: true,
17
14
  idempotentHint: false,
@@ -20,53 +17,25 @@ export const restoreGlobalVersionTool = defineGlobalTool({
20
17
  title: 'Restore Global Version',
21
18
  },
22
19
  description: DEFAULT_DESCRIPTION,
23
- input: z.object({
24
- id: z.string().describe('The ID of the global version to restore'),
25
- depth: z
26
- .number()
27
- .int()
28
- .min(0)
29
- .max(10)
30
- .describe('How many levels deep to populate relationships in response')
31
- .optional()
32
- .default(0),
33
- fallbackLocale: z
34
- .string()
35
- .describe('Optional: fallback locale code to use when requested locale is not available')
36
- .optional(),
37
- locale: z
38
- .string()
39
- .describe('Optional: locale code to restore in (e.g., "en", "es")')
40
- .optional(),
41
- populate: z
42
- .record(z.string(), z.unknown())
43
- .describe(
44
- 'Optional: control which fields to include from populated relationship or upload documents.',
45
- )
46
- .optional(),
47
- showHiddenFields: z
48
- .boolean()
49
- .describe('Optional: include hidden fields in the restored global response')
50
- .optional(),
51
- }),
52
- }).handler(async ({ authorizedMCP, globalSlug, input, req }) => {
20
+ input: restoreGlobalVersionInputSchema,
21
+ }).handler(async ({ slug, authorizedMCP, input, req }) => {
53
22
  const payload = req.payload
54
23
  const logger = getLogger({ payload })
55
- const { id, depth, fallbackLocale, locale, populate, showHiddenFields } = input
24
+ const { id, depth, fallbackLocale, locale, populate, select } = input
56
25
 
57
- logger.info(`Restoring version for global: ${globalSlug} with ID: ${id}`)
26
+ logger.info(`Restoring version for global: ${slug} with ID: ${id}`)
58
27
 
59
28
  try {
60
29
  const result = await payload.restoreGlobalVersion({
61
- id,
62
- slug: globalSlug,
30
+ id: String(id),
31
+ slug,
63
32
  depth,
64
33
  overrideAccess: authorizedMCP.overrideAccess,
65
34
  req,
66
- ...(fallbackLocale ? { fallbackLocale } : {}),
35
+ ...(fallbackLocale !== undefined ? { fallbackLocale } : {}),
67
36
  ...(locale ? { locale } : {}),
68
- ...(populate ? { populate: populate as PopulateType } : {}),
69
- ...(showHiddenFields !== undefined ? { showHiddenFields } : {}),
37
+ ...(populate ? { populate } : {}),
38
+ ...(select ? { select } : {}),
70
39
  })
71
40
  const resultObject = result as Record<string, unknown>
72
41
  const restoredGlobal =
@@ -78,19 +47,19 @@ export const restoreGlobalVersionTool = defineGlobalTool({
78
47
  content: [
79
48
  {
80
49
  type: 'text',
81
- text: `Version "${id}" restored successfully for global "${globalSlug}"!\nRestored global:\n\`\`\`json\n${JSON.stringify(restoredGlobal)}\n\`\`\``,
50
+ text: `Version "${id}" restored successfully for global "${slug}"!\nRestored global:\n\`\`\`json\n${JSON.stringify(restoredGlobal)}\n\`\`\``,
82
51
  },
83
52
  ],
84
53
  doc: restoredGlobal,
85
54
  }
86
55
  } catch (error) {
87
56
  const errorMessage = error instanceof Error ? error.message : 'Unknown error'
88
- logger.error(`Error restoring version ${id} for global ${globalSlug}: ${errorMessage}`)
57
+ logger.error(`Error restoring version ${id} for global ${slug}: ${errorMessage}`)
89
58
  return {
90
59
  content: [
91
60
  {
92
61
  type: 'text',
93
- text: `❌ **Error restoring version "${id}" for global "${globalSlug}":** ${errorMessage}`,
62
+ text: `❌ **Error restoring version "${id}" for global "${slug}":** ${errorMessage}`,
94
63
  },
95
64
  ],
96
65
  isError: true,
@@ -1,22 +1,20 @@
1
- import type { SelectType } from 'payload'
2
-
3
- import { z } from 'zod'
1
+ import {
2
+ getGlobalVirtualFieldNames,
3
+ stripVirtualFields,
4
+ transformPointDataToPayload,
5
+ updateGlobalInputSchema,
6
+ validateGlobalData,
7
+ } from 'payload'
4
8
 
5
9
  import { defaultAccess } from '../../../defaultAccess.js'
6
10
  import { defineGlobalTool } from '../../../defineTool.js'
7
11
  import { getLogger } from '../../../utils/getLogger.js'
8
- import {
9
- getGlobalVirtualFieldNames,
10
- stripVirtualFields,
11
- } from '../../../utils/getVirtualFieldNames.js'
12
- import { transformPointDataToPayload } from '../../../utils/transformPointDataToPayload.js'
13
- import { validateGlobalData } from '../validateEntityData.js'
12
+ import { formatEntityError } from '../formatEntityError.js'
14
13
 
15
14
  const DEFAULT_DESCRIPTION = 'Update any Payload global by passing the global slug and data.'
16
15
 
17
16
  export const updateGlobalTool = defineGlobalTool({
18
- access: (args) =>
19
- defaultAccess(args) && Boolean(args.permissions?.globals?.[args.globalSlug]?.update),
17
+ access: (args) => defaultAccess(args) && Boolean(args.permissions?.globals?.[args.slug]?.update),
20
18
  annotations: {
21
19
  destructiveHint: true,
22
20
  idempotentHint: false,
@@ -25,73 +23,54 @@ export const updateGlobalTool = defineGlobalTool({
25
23
  title: 'Update Global',
26
24
  },
27
25
  description: DEFAULT_DESCRIPTION,
28
- input: z.object({
29
- data: z.record(z.string(), z.unknown()).describe('The global fields to update'),
30
- depth: z
31
- .number()
32
- .describe('Optional: Depth of relationships to populate')
33
- .optional()
34
- .default(0),
35
- draft: z
36
- .boolean()
37
- .describe('Optional: Whether to save as draft (default: false)')
38
- .optional()
39
- .default(false),
40
- fallbackLocale: z
41
- .string()
42
- .describe('Optional: fallback locale code to use when requested locale is not available')
43
- .optional(),
44
- locale: z
45
- .string()
46
- .describe(
47
- 'Optional: locale code to update data in (e.g., "en", "es"). Use "all" to update all locales for localized fields',
48
- )
49
- .optional(),
50
- select: z
51
- .record(z.string(), z.unknown())
52
- .describe(
53
- 'Optional: define exactly which fields you\'d like to return in the response, e.g., {"siteName": true}',
54
- )
55
- .optional(),
56
- }),
57
- }).handler(async ({ authorizedMCP, globalSlug, input, req }) => {
26
+ input: updateGlobalInputSchema,
27
+ }).handler(async ({ slug, authorizedMCP, input, req }) => {
58
28
  const payload = req.payload
59
29
  const logger = getLogger({ payload })
60
30
 
61
- const { data, depth, draft, fallbackLocale, locale, select } = input
31
+ const {
32
+ data,
33
+ depth,
34
+ draft,
35
+ fallbackLocale,
36
+ locale,
37
+ overrideLock,
38
+ populate,
39
+ publishAllLocales,
40
+ select,
41
+ unpublishAllLocales,
42
+ } = input
62
43
 
63
- logger.info(
64
- `Updating global: ${globalSlug}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`,
65
- )
44
+ logger.info(`Updating global: ${slug}, draft: ${draft}${locale ? `, locale: ${locale}` : ''}`)
66
45
 
67
46
  try {
68
- const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, globalSlug)
47
+ const virtualFieldNames = getGlobalVirtualFieldNames(payload.config, slug)
69
48
  const inputData = stripVirtualFields(data, virtualFieldNames)
70
- const validationError = validateGlobalData({ data: inputData, globalSlug, req })
71
-
72
- if (validationError) {
73
- return validationError
74
- }
49
+ validateGlobalData({ slug, data: inputData, req })
75
50
 
76
51
  const parsedData = transformPointDataToPayload(inputData)
77
52
 
78
53
  const updateOptions: Parameters<typeof payload.updateGlobal>[0] = {
79
- slug: globalSlug,
54
+ slug,
80
55
  data: parsedData,
81
56
  depth,
82
57
  draft,
83
58
  overrideAccess: authorizedMCP.overrideAccess,
59
+ overrideLock,
60
+ populate,
61
+ publishAllLocales,
84
62
  req,
63
+ unpublishAllLocales,
85
64
  }
86
65
 
87
66
  if (locale) {
88
67
  updateOptions.locale = locale
89
68
  }
90
- if (fallbackLocale) {
69
+ if (fallbackLocale !== undefined) {
91
70
  updateOptions.fallbackLocale = fallbackLocale
92
71
  }
93
72
  if (select) {
94
- updateOptions.select = select as SelectType
73
+ updateOptions.select = select
95
74
  }
96
75
 
97
76
  const result = await payload.updateGlobal(updateOptions)
@@ -100,16 +79,14 @@ export const updateGlobalTool = defineGlobalTool({
100
79
  content: [
101
80
  {
102
81
  type: 'text',
103
- text: `Global "${globalSlug}" updated successfully!\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
82
+ text: `Global "${slug}" updated successfully!\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
104
83
  },
105
84
  ],
106
85
  doc: result as Record<string, unknown>,
107
86
  }
108
87
  } catch (error) {
109
- const errorMessage = error instanceof Error ? error.message : 'Unknown error'
110
- logger.error(`Error updating global ${globalSlug}: ${errorMessage}`)
111
- return {
112
- content: [{ type: 'text', text: `Error updating global "${globalSlug}": ${errorMessage}` }],
113
- }
88
+ const message = error instanceof Error ? error.message : 'Unknown error'
89
+ logger.error(`Error updating global ${slug}: ${message}`)
90
+ return formatEntityError({ slug, action: 'updating', entity: 'global', error, req })
114
91
  }
115
92
  })
@@ -10,7 +10,7 @@ import {
10
10
  } from './builtin/collections/authTools.js'
11
11
  import { countDocumentsTool } from './builtin/collections/countTool.js'
12
12
  import { countVersionsTool } from './builtin/collections/countVersionsTool.js'
13
- import { createDocumentTool } from './builtin/collections/createTool.js'
13
+ import { createDocumentsTool } from './builtin/collections/createTool.js'
14
14
  import { deleteDocumentsTool } from './builtin/collections/deleteTool.js'
15
15
  import { duplicateDocumentTool } from './builtin/collections/duplicateTool.js'
16
16
  import { findDistinctTool } from './builtin/collections/findDistinctTool.js'
@@ -20,6 +20,7 @@ import { findVersionsTool } from './builtin/collections/findVersionsTool.js'
20
20
  import { getCollectionSchemaTool } from './builtin/collections/getCollectionSchemaTool.js'
21
21
  import { restoreVersionTool } from './builtin/collections/restoreVersionTool.js'
22
22
  import { updateDocumentTool } from './builtin/collections/updateTool.js'
23
+ import { getUploadInstructionsTool } from './builtin/collections/uploadInstructionsTool.js'
23
24
  import { getConfigInfoTool } from './builtin/getConfigInfoTool.js'
24
25
  import { countGlobalVersionsTool } from './builtin/globals/countVersionsTool.js'
25
26
  import { findGlobalTool } from './builtin/globals/findTool.js'
@@ -32,6 +33,7 @@ import { updateGlobalTool } from './builtin/globals/updateTool.js'
32
33
  type CollectionBuiltin = {
33
34
  mcpName: string
34
35
  requiresDuplicateEnabled?: boolean
36
+ requiresUpload?: boolean
35
37
  requiresVersions?: boolean
36
38
  tool: CollectionTool
37
39
  }
@@ -54,7 +56,7 @@ export const TOOL_BUILTINS = {
54
56
  export const COLLECTION_BUILTINS = {
55
57
  count: { mcpName: 'countDocuments', tool: countDocumentsTool },
56
58
  countVersions: { mcpName: 'countVersions', requiresVersions: true, tool: countVersionsTool },
57
- create: { mcpName: 'createDocument', tool: createDocumentTool },
59
+ create: { mcpName: 'createDocuments', tool: createDocumentsTool },
58
60
  delete: { mcpName: 'deleteDocuments', tool: deleteDocumentsTool },
59
61
  duplicate: {
60
62
  mcpName: 'duplicateDocument',
@@ -70,6 +72,11 @@ export const COLLECTION_BUILTINS = {
70
72
  },
71
73
  findVersions: { mcpName: 'findVersions', requiresVersions: true, tool: findVersionsTool },
72
74
  getCollectionSchema: { mcpName: 'getCollectionSchema', tool: getCollectionSchemaTool },
75
+ getUploadInstructions: {
76
+ mcpName: 'getUploadInstructions',
77
+ requiresUpload: true,
78
+ tool: getUploadInstructionsTool,
79
+ },
73
80
  restoreVersion: { mcpName: 'restoreVersion', requiresVersions: true, tool: restoreVersionTool },
74
81
  update: { mcpName: 'updateDocument', tool: updateDocumentTool },
75
82
  } satisfies Record<string, CollectionBuiltin>
@@ -103,6 +103,7 @@ export const sanitizeMCPConfig = ({
103
103
  hooks: pluginConfig.hooks,
104
104
  items,
105
105
  mcp: pluginConfig.mcp,
106
+ oauth: pluginConfig.oauth,
106
107
  overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
107
108
  }
108
109
  }
@@ -127,7 +128,7 @@ const sanitizeCollectionConfig = ({
127
128
 
128
129
  for (const [
129
130
  toolKey,
130
- { mcpName, requiresDuplicateEnabled, requiresVersions, tool },
131
+ { mcpName, requiresDuplicateEnabled, requiresUpload, requiresVersions, tool },
131
132
  ] of COLLECTION_BUILTIN_ENTRIES) {
132
133
  if (requiresVersions && !collection.versions) {
133
134
  continue
@@ -135,6 +136,9 @@ const sanitizeCollectionConfig = ({
135
136
  if (requiresDuplicateEnabled && isDuplicateDisabled) {
136
137
  continue
137
138
  }
139
+ if (requiresUpload && !collection.upload) {
140
+ continue
141
+ }
138
142
  const matchedConfigEntry = collectionPluginConfig?.tools?.[toolKey]
139
143
  if (matchedConfigEntry === false) {
140
144
  continue
package/src/stdio.ts CHANGED
@@ -3,8 +3,8 @@ import type { Config, Plugin, SanitizedConfig } from 'payload'
3
3
  /* eslint-disable no-console */
4
4
  import { serveStdio } from '@modelcontextprotocol/server/stdio'
5
5
  import { fileURLToPath, pathToFileURL } from 'node:url'
6
- import { createLocalReq, getPayload } from 'payload'
7
- import { findConfig } from 'payload/node'
6
+ import { createPayloadRequest, getPayload } from 'payload'
7
+ import { findConfig, loadEnv } from 'payload/node'
8
8
 
9
9
  import type { SanitizedMCPPluginConfig } from './types.js'
10
10
 
@@ -28,6 +28,7 @@ export const runMcpStdio = async (): Promise<void> => {
28
28
  process.chdir(projectRoot)
29
29
  }
30
30
 
31
+ loadEnv()
31
32
  const configPath = findConfig()
32
33
  const configModule = await import(pathToFileURL(configPath).toString())
33
34
  const config = (await (configModule.default ?? configModule)) as SanitizedConfig
@@ -90,7 +91,7 @@ export const runMcpStdio = async (): Promise<void> => {
90
91
  headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
91
92
  }
92
93
 
93
- const req = await createLocalReq({ req: { headers } }, payload)
94
+ const req = await createPayloadRequest({ payload, req: { headers } })
94
95
  req.payloadAPI = 'MCP' as const
95
96
  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
96
97
 
package/src/types.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import type {
2
2
  CallToolResult,
3
3
  ContentBlock,
4
+ Implementation,
4
5
  JsonSchemaType,
5
- McpServer,
6
+ McpServerOptions,
6
7
  ResourceTemplate,
7
8
  ServerContext,
8
9
  StandardSchemaWithJSON,
@@ -75,11 +76,11 @@ export type MCPAccessArgs = {
75
76
  }
76
77
 
77
78
  export type CollectionMCPAccessArgs = {
78
- collectionSlug: CollectionSlug
79
+ slug: CollectionSlug
79
80
  } & MCPAccessArgs
80
81
 
81
82
  export type GlobalMCPAccessArgs = {
82
- globalSlug: GlobalSlug
83
+ slug: GlobalSlug
83
84
  } & MCPAccessArgs
84
85
 
85
86
  export type ToolHandlerArgs<TSchema = undefined> = {
@@ -90,11 +91,11 @@ export type ToolHandlerArgs<TSchema = undefined> = {
90
91
  }
91
92
 
92
93
  export type CollectionToolHandlerArgs<TSchema = undefined> = {
93
- collectionSlug: CollectionSlug
94
+ slug: CollectionSlug
94
95
  } & ToolHandlerArgs<TSchema>
95
96
 
96
97
  export type GlobalToolHandlerArgs<TSchema = undefined> = {
97
- globalSlug: GlobalSlug
98
+ slug: GlobalSlug
98
99
  } & ToolHandlerArgs<TSchema>
99
100
 
100
101
  export type Tool<TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined> = {
@@ -279,9 +280,31 @@ export type MCPPluginConfig = {
279
280
  afterToolCall?: MCPAfterToolCallHook[]
280
281
  }
281
282
  mcp?: {
283
+ /**
284
+ * Largest HTTP request body, in bytes, that the MCP endpoint accepts. Larger requests
285
+ * are answered with `413`. Base64 file uploads count toward this limit.
286
+ *
287
+ * @default 4194304 (4 MiB, the MCP SDK default)
288
+ */
289
+ maxRequestBodySize?: number
282
290
  serverOptions?: MCPServerOptions
283
291
  verboseLogs?: boolean
284
292
  }
293
+ /**
294
+ * Lets MCP clients sign in through an OAuth authorization server. MCP requests without an
295
+ * authenticated user get a `401` that points to the protected resource metadata (RFC 9728),
296
+ * served by `oauthProtectedResourceHandler`. Payload's auth strategies must accept the
297
+ * issued access tokens.
298
+ */
299
+ oauth?: {
300
+ authorizationServers: string[]
301
+ /**
302
+ * The URL clients call to reach the MCP endpoint.
303
+ *
304
+ * @default the absolute URL of `/api/mcp`, based on `serverURL` or the request URL
305
+ */
306
+ resource?: string
307
+ }
285
308
  /**
286
309
  * Replace the default MCP authorization resolver.
287
310
  *
@@ -301,11 +324,11 @@ export type MCPPluginConfig = {
301
324
 
302
325
  export type SanitizedMCPPluginConfig = {
303
326
  items: MCPItem[]
304
- } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
327
+ } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'oauth' | 'overrideGetAuthorizedMCP'>
305
328
 
306
329
  export type MCPServerOptions = {
307
- options?: ConstructorParameters<typeof McpServer>[1]
308
- serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
330
+ options?: McpServerOptions
331
+ serverInfo?: Partial<Implementation>
309
332
  }
310
333
 
311
334
  /**
@@ -1,72 +0,0 @@
1
- import { describe, expect, it } from 'vitest';
2
- import { fileInputSchema, resolveFileInput } from './fileInput.js';
3
- describe('MCP file input', ()=>{
4
- it('should reject malformed MIME types', ()=>{
5
- const result = fileInputSchema.safeParse({
6
- data: 'aGVsbG8=',
7
- mimeType: 'text/plain\r\nx-test: value',
8
- name: 'hello.txt',
9
- source: 'base64'
10
- });
11
- expect(result.success).toBe(false);
12
- });
13
- it('should reject oversized base64 files', async ()=>{
14
- const req = createRequest({
15
- maxFileSize: 4
16
- });
17
- await expect(resolveFileInput({
18
- collectionSlug: 'media',
19
- input: {
20
- data: Buffer.from('hello').toString('base64'),
21
- mimeType: 'text/plain',
22
- name: 'hello.txt',
23
- source: 'base64'
24
- },
25
- req
26
- })).rejects.toThrow('File exceeds the 4 byte upload limit.');
27
- });
28
- it('should reject URLs outside the collection allowlist', async ()=>{
29
- const req = createRequest({
30
- allowList: [
31
- {
32
- hostname: 'assets.example.com',
33
- protocol: 'https'
34
- }
35
- ]
36
- });
37
- await expect(resolveFileInput({
38
- collectionSlug: 'media',
39
- input: {
40
- source: 'url',
41
- url: 'https://example.com/image.png'
42
- },
43
- req
44
- })).rejects.toThrow('The provided file URL is not allowed.');
45
- });
46
- });
47
- function createRequest({ allowList, maxFileSize }) {
48
- return {
49
- payload: {
50
- collections: {
51
- media: {
52
- config: {
53
- upload: allowList ? {
54
- pasteURL: {
55
- allowList
56
- }
57
- } : {}
58
- }
59
- }
60
- },
61
- config: {
62
- upload: {
63
- limits: {
64
- fileSize: maxFileSize
65
- }
66
- }
67
- }
68
- }
69
- };
70
- }
71
-
72
- //# sourceMappingURL=fileInput.spec.js.map
@@ -1 +0,0 @@
1
- {"version":3,"sources":["../../../../src/mcp/builtin/collections/fileInput.spec.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\n\nimport { describe, expect, it } from 'vitest'\n\nimport { fileInputSchema, resolveFileInput } from './fileInput.js'\n\ndescribe('MCP file input', () => {\n it('should reject malformed MIME types', () => {\n const result = fileInputSchema.safeParse({\n data: 'aGVsbG8=',\n mimeType: 'text/plain\\r\\nx-test: value',\n name: 'hello.txt',\n source: 'base64',\n })\n\n expect(result.success).toBe(false)\n })\n\n it('should reject oversized base64 files', async () => {\n const req = createRequest({ maxFileSize: 4 })\n\n await expect(\n resolveFileInput({\n collectionSlug: 'media',\n input: {\n data: Buffer.from('hello').toString('base64'),\n mimeType: 'text/plain',\n name: 'hello.txt',\n source: 'base64',\n },\n req,\n }),\n ).rejects.toThrow('File exceeds the 4 byte upload limit.')\n })\n\n it('should reject URLs outside the collection allowlist', async () => {\n const req = createRequest({\n allowList: [{ hostname: 'assets.example.com', protocol: 'https' }],\n })\n\n await expect(\n resolveFileInput({\n collectionSlug: 'media',\n input: {\n source: 'url',\n url: 'https://example.com/image.png',\n },\n req,\n }),\n ).rejects.toThrow('The provided file URL is not allowed.')\n })\n})\n\nfunction createRequest({\n allowList,\n maxFileSize,\n}: {\n allowList?: Array<{ hostname: string; protocol: 'http' | 'https' }>\n maxFileSize?: number\n}): PayloadRequest {\n return {\n payload: {\n collections: {\n media: {\n config: {\n upload: allowList ? { pasteURL: { allowList } } : {},\n },\n },\n },\n config: {\n upload: {\n limits: {\n fileSize: maxFileSize,\n },\n },\n },\n },\n } as unknown as PayloadRequest\n}\n"],"names":["describe","expect","it","fileInputSchema","resolveFileInput","result","safeParse","data","mimeType","name","source","success","toBe","req","createRequest","maxFileSize","collectionSlug","input","Buffer","from","toString","rejects","toThrow","allowList","hostname","protocol","url","payload","collections","media","config","upload","pasteURL","limits","fileSize"],"mappings":"AAEA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAE7C,SAASC,eAAe,EAAEC,gBAAgB,QAAQ,iBAAgB;AAElEJ,SAAS,kBAAkB;IACzBE,GAAG,sCAAsC;QACvC,MAAMG,SAASF,gBAAgBG,SAAS,CAAC;YACvCC,MAAM;YACNC,UAAU;YACVC,MAAM;YACNC,QAAQ;QACV;QAEAT,OAAOI,OAAOM,OAAO,EAAEC,IAAI,CAAC;IAC9B;IAEAV,GAAG,wCAAwC;QACzC,MAAMW,MAAMC,cAAc;YAAEC,aAAa;QAAE;QAE3C,MAAMd,OACJG,iBAAiB;YACfY,gBAAgB;YAChBC,OAAO;gBACLV,MAAMW,OAAOC,IAAI,CAAC,SAASC,QAAQ,CAAC;gBACpCZ,UAAU;gBACVC,MAAM;gBACNC,QAAQ;YACV;YACAG;QACF,IACAQ,OAAO,CAACC,OAAO,CAAC;IACpB;IAEApB,GAAG,uDAAuD;QACxD,MAAMW,MAAMC,cAAc;YACxBS,WAAW;gBAAC;oBAAEC,UAAU;oBAAsBC,UAAU;gBAAQ;aAAE;QACpE;QAEA,MAAMxB,OACJG,iBAAiB;YACfY,gBAAgB;YAChBC,OAAO;gBACLP,QAAQ;gBACRgB,KAAK;YACP;YACAb;QACF,IACAQ,OAAO,CAACC,OAAO,CAAC;IACpB;AACF;AAEA,SAASR,cAAc,EACrBS,SAAS,EACTR,WAAW,EAIZ;IACC,OAAO;QACLY,SAAS;YACPC,aAAa;gBACXC,OAAO;oBACLC,QAAQ;wBACNC,QAAQR,YAAY;4BAAES,UAAU;gCAAET;4BAAU;wBAAE,IAAI,CAAC;oBACrD;gBACF;YACF;YACAO,QAAQ;gBACNC,QAAQ;oBACNE,QAAQ;wBACNC,UAAUnB;oBACZ;gBACF;YACF;QACF;IACF;AACF"}
@@ -1,9 +0,0 @@
1
- import type { CollectionSlug, PayloadRequest } from 'payload';
2
- import type { MCPToolResponse } from '../../../types.js';
3
- export declare const formatCollectionError: ({ action, collectionSlug, error, req, }: {
4
- action: 'creating' | 'duplicating' | 'updating';
5
- collectionSlug: CollectionSlug;
6
- error: unknown;
7
- req: PayloadRequest;
8
- }) => MCPToolResponse;
9
- //# sourceMappingURL=formatCollectionError.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"formatCollectionError.d.ts","sourceRoot":"","sources":["../../../../src/mcp/builtin/collections/formatCollectionError.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAE7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAgCxD,eAAO,MAAM,qBAAqB,4CAK/B;IACD,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,UAAU,CAAA;IAC/C,cAAc,EAAE,cAAc,CAAA;IAC9B,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,EAAE,cAAc,CAAA;CACpB,KAAG,eAuCH,CAAA"}