@payloadcms/plugin-mcp 4.0.0-canary.20 → 4.0.0-canary.20261117

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 (219) hide show
  1. package/bin.js +0 -7
  2. package/dist/endpoint/access.d.ts +20 -4
  3. package/dist/endpoint/access.d.ts.map +1 -1
  4. package/dist/endpoint/access.js +73 -11
  5. package/dist/endpoint/access.js.map +1 -1
  6. package/dist/endpoint/index.d.ts.map +1 -1
  7. package/dist/endpoint/index.js +58 -4
  8. package/dist/endpoint/index.js.map +1 -1
  9. package/dist/endpoint/oauth.d.ts +37 -0
  10. package/dist/endpoint/oauth.d.ts.map +1 -0
  11. package/dist/endpoint/oauth.js +105 -0
  12. package/dist/endpoint/oauth.js.map +1 -0
  13. package/dist/endpoint/oauthLoginToken.d.ts +27 -0
  14. package/dist/endpoint/oauthLoginToken.d.ts.map +1 -0
  15. package/dist/endpoint/oauthLoginToken.js +86 -0
  16. package/dist/endpoint/oauthLoginToken.js.map +1 -0
  17. package/dist/endpoint/oauthServer.d.ts +28 -0
  18. package/dist/endpoint/oauthServer.d.ts.map +1 -0
  19. package/dist/endpoint/oauthServer.js +455 -0
  20. package/dist/endpoint/oauthServer.js.map +1 -0
  21. package/dist/exports/client.d.ts +1 -1
  22. package/dist/exports/client.d.ts.map +1 -1
  23. package/dist/exports/client.js +1 -1
  24. package/dist/exports/client.js.map +1 -1
  25. package/dist/exports/rsc.d.ts +2 -0
  26. package/dist/exports/rsc.d.ts.map +1 -0
  27. package/dist/exports/rsc.js +3 -0
  28. package/dist/exports/rsc.js.map +1 -0
  29. package/dist/index.d.ts +10 -2
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +34 -10
  32. package/dist/index.js.map +1 -1
  33. package/dist/mcp/buildMcpServer.d.ts +2 -2
  34. package/dist/mcp/buildMcpServer.d.ts.map +1 -1
  35. package/dist/mcp/buildMcpServer.js +36 -24
  36. package/dist/mcp/buildMcpServer.js.map +1 -1
  37. package/dist/mcp/builtin/collections/authTools.d.ts.map +1 -1
  38. package/dist/mcp/builtin/collections/authTools.js +80 -56
  39. package/dist/mcp/builtin/collections/authTools.js.map +1 -1
  40. package/dist/mcp/builtin/collections/countTool.d.ts.map +1 -1
  41. package/dist/mcp/builtin/collections/countTool.js +9 -14
  42. package/dist/mcp/builtin/collections/countTool.js.map +1 -1
  43. package/dist/mcp/builtin/collections/countVersionsTool.d.ts.map +1 -1
  44. package/dist/mcp/builtin/collections/countVersionsTool.js +9 -13
  45. package/dist/mcp/builtin/collections/countVersionsTool.js.map +1 -1
  46. package/dist/mcp/builtin/collections/createTool.d.ts.map +1 -1
  47. package/dist/mcp/builtin/collections/createTool.js +48 -49
  48. package/dist/mcp/builtin/collections/createTool.js.map +1 -1
  49. package/dist/mcp/builtin/collections/deleteTool.d.ts.map +1 -1
  50. package/dist/mcp/builtin/collections/deleteTool.js +47 -44
  51. package/dist/mcp/builtin/collections/deleteTool.js.map +1 -1
  52. package/dist/mcp/builtin/collections/duplicateTool.d.ts.map +1 -1
  53. package/dist/mcp/builtin/collections/duplicateTool.js +31 -37
  54. package/dist/mcp/builtin/collections/duplicateTool.js.map +1 -1
  55. package/dist/mcp/builtin/collections/fileInput.d.ts +21 -21
  56. package/dist/mcp/builtin/collections/fileInput.d.ts.map +1 -1
  57. package/dist/mcp/builtin/collections/fileInput.js +34 -70
  58. package/dist/mcp/builtin/collections/fileInput.js.map +1 -1
  59. package/dist/mcp/builtin/collections/findDistinctTool.d.ts.map +1 -1
  60. package/dist/mcp/builtin/collections/findDistinctTool.js +11 -26
  61. package/dist/mcp/builtin/collections/findDistinctTool.js.map +1 -1
  62. package/dist/mcp/builtin/collections/findTool.d.ts.map +1 -1
  63. package/dist/mcp/builtin/collections/findTool.js +28 -46
  64. package/dist/mcp/builtin/collections/findTool.js.map +1 -1
  65. package/dist/mcp/builtin/collections/findVersionByIDTool.d.ts.map +1 -1
  66. package/dist/mcp/builtin/collections/findVersionByIDTool.js +17 -26
  67. package/dist/mcp/builtin/collections/findVersionByIDTool.js.map +1 -1
  68. package/dist/mcp/builtin/collections/findVersionsTool.d.ts.map +1 -1
  69. package/dist/mcp/builtin/collections/findVersionsTool.js +16 -30
  70. package/dist/mcp/builtin/collections/findVersionsTool.js.map +1 -1
  71. package/dist/mcp/builtin/collections/getCollectionSchemaTool.d.ts.map +1 -1
  72. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js +30 -14
  73. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js.map +1 -1
  74. package/dist/mcp/builtin/collections/restoreVersionTool.d.ts.map +1 -1
  75. package/dist/mcp/builtin/collections/restoreVersionTool.js +14 -26
  76. package/dist/mcp/builtin/collections/restoreVersionTool.js.map +1 -1
  77. package/dist/mcp/builtin/collections/updateTool.d.ts.map +1 -1
  78. package/dist/mcp/builtin/collections/updateTool.js +55 -87
  79. package/dist/mcp/builtin/collections/updateTool.js.map +1 -1
  80. package/dist/mcp/builtin/collections/uploadInstructionsTool.js +11 -11
  81. package/dist/mcp/builtin/collections/uploadInstructionsTool.js.map +1 -1
  82. package/dist/mcp/builtin/formatEntityError.d.ts +16 -0
  83. package/dist/mcp/builtin/formatEntityError.d.ts.map +1 -0
  84. package/dist/mcp/builtin/formatEntityError.js +55 -0
  85. package/dist/mcp/builtin/formatEntityError.js.map +1 -0
  86. package/dist/mcp/builtin/getConfigInfoTool.d.ts.map +1 -1
  87. package/dist/mcp/builtin/getConfigInfoTool.js +3 -2
  88. package/dist/mcp/builtin/getConfigInfoTool.js.map +1 -1
  89. package/dist/mcp/builtin/globals/countVersionsTool.d.ts.map +1 -1
  90. package/dist/mcp/builtin/globals/countVersionsTool.js +9 -13
  91. package/dist/mcp/builtin/globals/countVersionsTool.js.map +1 -1
  92. package/dist/mcp/builtin/globals/findTool.d.ts.map +1 -1
  93. package/dist/mcp/builtin/globals/findTool.js +10 -16
  94. package/dist/mcp/builtin/globals/findTool.js.map +1 -1
  95. package/dist/mcp/builtin/globals/findVersionByIDTool.d.ts.map +1 -1
  96. package/dist/mcp/builtin/globals/findVersionByIDTool.js +13 -24
  97. package/dist/mcp/builtin/globals/findVersionByIDTool.js.map +1 -1
  98. package/dist/mcp/builtin/globals/findVersionsTool.d.ts.map +1 -1
  99. package/dist/mcp/builtin/globals/findVersionsTool.js +13 -29
  100. package/dist/mcp/builtin/globals/findVersionsTool.js.map +1 -1
  101. package/dist/mcp/builtin/globals/getGlobalSchemaTool.d.ts.map +1 -1
  102. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js +29 -13
  103. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js.map +1 -1
  104. package/dist/mcp/builtin/globals/restoreVersionTool.d.ts.map +1 -1
  105. package/dist/mcp/builtin/globals/restoreVersionTool.js +15 -22
  106. package/dist/mcp/builtin/globals/restoreVersionTool.js.map +1 -1
  107. package/dist/mcp/builtin/globals/updateTool.d.ts.map +1 -1
  108. package/dist/mcp/builtin/globals/updateTool.js +27 -36
  109. package/dist/mcp/builtin/globals/updateTool.js.map +1 -1
  110. package/dist/mcp/sanitizeMCPConfig.d.ts.map +1 -1
  111. package/dist/mcp/sanitizeMCPConfig.js +4 -0
  112. package/dist/mcp/sanitizeMCPConfig.js.map +1 -1
  113. package/dist/stdio.js +4 -3
  114. package/dist/stdio.js.map +1 -1
  115. package/dist/types.d.ts +131 -10
  116. package/dist/types.d.ts.map +1 -1
  117. package/dist/types.js.map +1 -1
  118. package/dist/utils/seal.d.ts +17 -0
  119. package/dist/utils/seal.d.ts.map +1 -0
  120. package/dist/utils/seal.js +24 -0
  121. package/dist/utils/seal.js.map +1 -0
  122. package/dist/utils/toStandardSchema.js.map +1 -1
  123. package/dist/views/Authorize/AllowButtons/index.d.ts +18 -0
  124. package/dist/views/Authorize/AllowButtons/index.d.ts.map +1 -0
  125. package/dist/views/Authorize/AllowButtons/index.js +88 -0
  126. package/dist/views/Authorize/AllowButtons/index.js.map +1 -0
  127. package/dist/views/Authorize/index.css +19 -0
  128. package/dist/views/Authorize/index.d.ts +9 -0
  129. package/dist/views/Authorize/index.d.ts.map +1 -0
  130. package/dist/views/Authorize/index.js +98 -0
  131. package/dist/views/Authorize/index.js.map +1 -0
  132. package/package.json +30 -28
  133. package/src/endpoint/access.ts +81 -9
  134. package/src/endpoint/index.ts +50 -4
  135. package/src/endpoint/oauth.ts +108 -0
  136. package/src/endpoint/oauthLoginToken.ts +100 -0
  137. package/src/endpoint/oauthServer.ts +472 -0
  138. package/src/exports/client.ts +1 -1
  139. package/src/exports/rsc.ts +1 -0
  140. package/src/index.ts +53 -9
  141. package/src/mcp/buildMcpServer.ts +40 -30
  142. package/src/mcp/builtin/collections/authTools.ts +82 -71
  143. package/src/mcp/builtin/collections/countTool.ts +9 -21
  144. package/src/mcp/builtin/collections/countVersionsTool.ts +9 -18
  145. package/src/mcp/builtin/collections/createTool.ts +71 -96
  146. package/src/mcp/builtin/collections/deleteTool.ts +40 -66
  147. package/src/mcp/builtin/collections/duplicateTool.ts +36 -86
  148. package/src/mcp/builtin/collections/fileInput.spec.ts +2 -2
  149. package/src/mcp/builtin/collections/fileInput.ts +44 -81
  150. package/src/mcp/builtin/collections/findDistinctTool.ts +11 -63
  151. package/src/mcp/builtin/collections/findTool.ts +24 -106
  152. package/src/mcp/builtin/collections/findVersionByIDTool.ts +15 -58
  153. package/src/mcp/builtin/collections/findVersionsTool.ts +14 -85
  154. package/src/mcp/builtin/collections/getCollectionSchemaTool.ts +23 -12
  155. package/src/mcp/builtin/collections/restoreVersionTool.ts +15 -57
  156. package/src/mcp/builtin/collections/updateTool.ts +55 -109
  157. package/src/mcp/builtin/collections/uploadInstructionsTool.ts +12 -12
  158. package/src/mcp/builtin/formatEntityError.ts +77 -0
  159. package/src/mcp/builtin/getConfigInfoTool.ts +2 -1
  160. package/src/mcp/builtin/globals/countVersionsTool.ts +9 -17
  161. package/src/mcp/builtin/globals/findTool.ts +13 -52
  162. package/src/mcp/builtin/globals/findVersionByIDTool.ts +13 -52
  163. package/src/mcp/builtin/globals/findVersionsTool.ts +14 -92
  164. package/src/mcp/builtin/globals/getGlobalSchemaTool.ts +21 -11
  165. package/src/mcp/builtin/globals/restoreVersionTool.ts +14 -45
  166. package/src/mcp/builtin/globals/updateTool.ts +38 -61
  167. package/src/mcp/sanitizeMCPConfig.ts +2 -0
  168. package/src/stdio.ts +2 -2
  169. package/src/types.ts +130 -10
  170. package/src/utils/seal.ts +46 -0
  171. package/src/utils/toStandardSchema.ts +1 -1
  172. package/src/views/Authorize/AllowButtons/index.tsx +97 -0
  173. package/src/views/Authorize/index.css +19 -0
  174. package/src/views/Authorize/index.tsx +100 -0
  175. package/dist/mcp/builtin/collections/fileInput.spec.js +0 -86
  176. package/dist/mcp/builtin/collections/fileInput.spec.js.map +0 -1
  177. package/dist/mcp/builtin/collections/formatCollectionError.d.ts +0 -9
  178. package/dist/mcp/builtin/collections/formatCollectionError.d.ts.map +0 -1
  179. package/dist/mcp/builtin/collections/formatCollectionError.js +0 -60
  180. package/dist/mcp/builtin/collections/formatCollectionError.js.map +0 -1
  181. package/dist/mcp/builtin/validateEntityData.d.ts +0 -14
  182. package/dist/mcp/builtin/validateEntityData.d.ts.map +0 -1
  183. package/dist/mcp/builtin/validateEntityData.js +0 -82
  184. package/dist/mcp/builtin/validateEntityData.js.map +0 -1
  185. package/dist/utils/getVirtualFieldNames.d.ts +0 -14
  186. package/dist/utils/getVirtualFieldNames.d.ts.map +0 -1
  187. package/dist/utils/getVirtualFieldNames.js +0 -35
  188. package/dist/utils/getVirtualFieldNames.js.map +0 -1
  189. package/dist/utils/schemaConversion/filterFieldsByAccess.d.ts +0 -28
  190. package/dist/utils/schemaConversion/filterFieldsByAccess.d.ts.map +0 -1
  191. package/dist/utils/schemaConversion/filterFieldsByAccess.js +0 -71
  192. package/dist/utils/schemaConversion/filterFieldsByAccess.js.map +0 -1
  193. package/dist/utils/schemaConversion/getEntityInputSchema.d.ts +0 -13
  194. package/dist/utils/schemaConversion/getEntityInputSchema.d.ts.map +0 -1
  195. package/dist/utils/schemaConversion/getEntityInputSchema.js +0 -66
  196. package/dist/utils/schemaConversion/getEntityInputSchema.js.map +0 -1
  197. package/dist/utils/schemaConversion/sanitizeEntitySchema.d.ts +0 -10
  198. package/dist/utils/schemaConversion/sanitizeEntitySchema.d.ts.map +0 -1
  199. package/dist/utils/schemaConversion/sanitizeEntitySchema.js +0 -384
  200. package/dist/utils/schemaConversion/sanitizeEntitySchema.js.map +0 -1
  201. package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js +0 -133
  202. package/dist/utils/schemaConversion/sanitizeEntitySchema.spec.js.map +0 -1
  203. package/dist/utils/transformPointDataToPayload.d.ts +0 -7
  204. package/dist/utils/transformPointDataToPayload.d.ts.map +0 -1
  205. package/dist/utils/transformPointDataToPayload.js +0 -28
  206. package/dist/utils/transformPointDataToPayload.js.map +0 -1
  207. package/dist/utils/whereSchema.d.ts +0 -9
  208. package/dist/utils/whereSchema.d.ts.map +0 -1
  209. package/dist/utils/whereSchema.js +0 -13
  210. package/dist/utils/whereSchema.js.map +0 -1
  211. package/src/mcp/builtin/collections/formatCollectionError.ts +0 -84
  212. package/src/mcp/builtin/validateEntityData.ts +0 -132
  213. package/src/utils/getVirtualFieldNames.ts +0 -53
  214. package/src/utils/schemaConversion/filterFieldsByAccess.ts +0 -123
  215. package/src/utils/schemaConversion/getEntityInputSchema.ts +0 -96
  216. package/src/utils/schemaConversion/sanitizeEntitySchema.spec.ts +0 -96
  217. package/src/utils/schemaConversion/sanitizeEntitySchema.ts +0 -432
  218. package/src/utils/transformPointDataToPayload.ts +0 -40
  219. 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
- doc: result as Record<string, unknown>,
85
+ doc: result,
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
  })
@@ -99,10 +99,12 @@ export const sanitizeMCPConfig = ({
99
99
  }
100
100
 
101
101
  return {
102
+ access: pluginConfig.access,
102
103
  disabled: pluginConfig.disabled,
103
104
  hooks: pluginConfig.hooks,
104
105
  items,
105
106
  mcp: pluginConfig.mcp,
107
+ oauth: pluginConfig.oauth === false ? undefined : (pluginConfig.oauth ?? { type: 'builtin' }),
106
108
  overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
107
109
  }
108
110
  }
package/src/stdio.ts CHANGED
@@ -3,7 +3,7 @@ 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'
6
+ import { createPayloadRequest, getPayload } from 'payload'
7
7
  import { findConfig, loadEnv } from 'payload/node'
8
8
 
9
9
  import type { SanitizedMCPPluginConfig } from './types.js'
@@ -91,7 +91,7 @@ export const runMcpStdio = async (): Promise<void> => {
91
91
  headers.set('Authorization', process.env.PAYLOAD_MCP_AUTHORIZATION)
92
92
  }
93
93
 
94
- const req = await createLocalReq({ req: { headers } }, payload)
94
+ const req = await createPayloadRequest({ payload, req: { headers } })
95
95
  req.payloadAPI = 'MCP' as const
96
96
  const authorizedMCP = await getAuthorizedMCP({ overrideAccess, req })
97
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> = {
@@ -266,6 +267,19 @@ export type MCPPluginGlobalConfig = {
266
267
  * actually works with.
267
268
  */
268
269
  export type MCPPluginConfig = {
270
+ /**
271
+ * Decides who can use MCP at all. Runs on every MCP request once the user is authenticated,
272
+ * before the `access` callbacks of tools, prompts, and resources, and when a user allows an MCP
273
+ * client on the built-in OAuth server's sign-in page. Return `false` to answer MCP requests with
274
+ * `403` and to refuse to sign the client in. This is skipped when `overrideAccess` is enabled.
275
+ * `overrideGetAuthorizedMCP` replaces it on MCP requests.
276
+ *
277
+ * It only applies to MCP, not to Payload's REST or GraphQL APIs, so it doesn't replace access
278
+ * control on collections and globals.
279
+ *
280
+ * @default no check, so tools, prompts, and resources decide on their own
281
+ */
282
+ access?: (args: MCPAccessArgs) => MaybePromise<boolean>
269
283
  collections?: {
270
284
  [Slug in CollectionSlug]?: MCPPluginCollectionConfig<Slug>
271
285
  }
@@ -279,14 +293,30 @@ export type MCPPluginConfig = {
279
293
  afterToolCall?: MCPAfterToolCallHook[]
280
294
  }
281
295
  mcp?: {
296
+ /**
297
+ * Largest HTTP request body, in bytes, that the MCP endpoint accepts. Larger requests
298
+ * are answered with `413`. Base64 file uploads count toward this limit.
299
+ *
300
+ * @default 4194304 (4 MiB, the MCP SDK default)
301
+ */
302
+ maxRequestBodySize?: number
282
303
  serverOptions?: MCPServerOptions
283
304
  verboseLogs?: boolean
284
305
  }
306
+ /**
307
+ * How MCP clients sign in. MCP requests without an authenticated user get a `401` that points
308
+ * to the protected resource metadata (RFC 9728). Set to `false` to only accept API keys and
309
+ * anonymous requests.
310
+ *
311
+ * @default { type: 'builtin' }
312
+ */
313
+ oauth?: false | MCPOAuthConfig
285
314
  /**
286
315
  * Replace the default MCP authorization resolver.
287
316
  *
288
- * This hook replaces the default authentication flow. It must set `req.user` to the
289
- * authenticated Payload user, or to `null` for an anonymous caller, before returning.
317
+ * This hook replaces the default authentication flow, including the plugin's `access`. It must
318
+ * set `req.user` to the authenticated Payload user, or to `null` for an anonymous caller, before
319
+ * returning.
290
320
  */
291
321
  overrideGetAuthorizedMCP?: (
292
322
  args: {
@@ -299,13 +329,103 @@ export type MCPPluginConfig = {
299
329
  tools?: MCPTopLevelToolsMap
300
330
  }
301
331
 
332
+ export type MCPOAuthConfig = MCPBuiltinOAuthConfig | MCPExternalOAuthConfig
333
+
334
+ /**
335
+ * This Payload app is the authorization server. Users sign in to the admin panel and allow the
336
+ * MCP client, which then gets an access token for them.
337
+ */
338
+ export type MCPBuiltinOAuthConfig = {
339
+ /**
340
+ * Creates the tokens the MCP client gets when the user clicks Allow. `req` is the user's own
341
+ * browser request, so `req.user` is the user who allowed it. Pass `authenticate` too if
342
+ * Payload's auth strategies don't accept the access token.
343
+ *
344
+ * @default a Payload login token for that user that only works for MCP, with a refresh token when
345
+ * the collection uses sessions. Its session is labelled with the client's name.
346
+ */
347
+ issueToken?: (args: {
348
+ /** The MCP client the user allowed, with the address it returns to. */
349
+ client: { name: string; redirectURI: string }
350
+ req: PayloadRequest
351
+ }) => MaybePromise<MCPOAuthTokens>
352
+ /**
353
+ * Trades a refresh token from `issueToken`, or from an earlier refresh, for new tokens. Return
354
+ * `null` when it's no longer valid, and the client sends the user through sign-in again. `req`
355
+ * is the MCP client's request, without a user. Only used together with `issueToken`.
356
+ *
357
+ * OAuth requires noticing copied refresh tokens: return a new refresh token every time, and
358
+ * revoke the tokens when an already used refresh token comes back.
359
+ *
360
+ * It also runs when the client trades its authorization code, on the refresh token from
361
+ * `issueToken`, with `reuseInterval: 0`. OAuth requires a code to work only once, so refuse that
362
+ * refresh token if it was used before, even moments ago.
363
+ */
364
+ refreshToken?: (args: {
365
+ refreshToken: string
366
+ req: PayloadRequest
367
+ /**
368
+ * How long a refresh token that was just used may still be accepted, in milliseconds, e.g. for
369
+ * clients that refresh twice at once. `0` means not at all. When it's missing, use your usual
370
+ * leeway.
371
+ */
372
+ reuseInterval?: number
373
+ }) => MaybePromise<MCPOAuthTokens | null>
374
+ type: 'builtin'
375
+ } & MCPOAuthSharedConfig
376
+
377
+ export type MCPOAuthTokens = {
378
+ accessToken: string
379
+ /** Seconds until the access token expires. */
380
+ expiresIn?: number
381
+ /** Lets the client get new tokens without the user, through `refreshToken`. */
382
+ refreshToken?: string
383
+ }
384
+
385
+ /** Another service, e.g. your identity provider, is the authorization server. */
386
+ export type MCPExternalOAuthConfig = {
387
+ /**
388
+ * The authorization servers that issue access tokens for MCP clients. Clients require each one
389
+ * to exactly match the `issuer` in that server's metadata, so pass a function when the exact
390
+ * value is only known at runtime, e.g. from the server's OpenID configuration or per host.
391
+ */
392
+ authorizationServers: ((args: { req: PayloadRequest }) => MaybePromise<string[]>) | string[]
393
+ /**
394
+ * Scopes MCP clients should request, e.g. `['openid', 'email', 'profile']`. Without them,
395
+ * clients request none, which some authorization servers reject or answer with a token that
396
+ * doesn't identify the user.
397
+ */
398
+ scopes?: string[]
399
+ type: 'external'
400
+ } & MCPOAuthSharedConfig
401
+
402
+ type MCPOAuthSharedConfig = {
403
+ /**
404
+ * Called on MCP requests with a bearer token that Payload's auth strategies didn't accept.
405
+ * Return the Payload user, including its `collection`, or `null` to answer with the OAuth challenge.
406
+ */
407
+ authenticate?: (args: {
408
+ req: PayloadRequest
409
+ token: string
410
+ }) => MaybePromise<PayloadRequest['user']>
411
+ /**
412
+ * The URL clients call to reach the MCP endpoint. The metadata link and the built-in
413
+ * authorization server's issuer are based on it.
414
+ *
415
+ * @default the absolute URL of `/api/mcp`, based on `serverURL` or the request URL
416
+ */
417
+ resource?: ((args: { req: PayloadRequest }) => string) | string
418
+ }
419
+
302
420
  export type SanitizedMCPPluginConfig = {
303
421
  items: MCPItem[]
304
- } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
422
+ /** `undefined` when OAuth is turned off. */
423
+ oauth?: MCPOAuthConfig
424
+ } & Pick<MCPPluginConfig, 'access' | 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
305
425
 
306
426
  export type MCPServerOptions = {
307
- options?: ConstructorParameters<typeof McpServer>[1]
308
- serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
427
+ options?: McpServerOptions
428
+ serverInfo?: Partial<Implementation>
309
429
  }
310
430
 
311
431
  /**
@@ -0,0 +1,46 @@
1
+ import type { PayloadRequest } from 'payload'
2
+
3
+ /**
4
+ * Encrypts data for the client to hold, so it doesn't need to be stored. `type` keeps one kind
5
+ * from being used as another, e.g. a client ID as an authorization code.
6
+ */
7
+ export const seal = ({
8
+ type,
9
+ data,
10
+ expiresInSeconds,
11
+ req,
12
+ }: {
13
+ data: object
14
+ expiresInSeconds?: number
15
+ req: PayloadRequest
16
+ type: string
17
+ }): string =>
18
+ req.payload.encrypt(
19
+ JSON.stringify({
20
+ ...data,
21
+ type,
22
+ exp: expiresInSeconds && Date.now() + expiresInSeconds * 1000,
23
+ }),
24
+ )
25
+
26
+ export const unseal = <T>({
27
+ type,
28
+ req,
29
+ value,
30
+ }: {
31
+ req: PayloadRequest
32
+ type: string
33
+ value: null | string
34
+ }): T | undefined => {
35
+ // Only the v1 format is authenticated. Older formats decrypt anything without an error.
36
+ if (!value?.startsWith('v1:')) {
37
+ return undefined
38
+ }
39
+
40
+ try {
41
+ const data = JSON.parse(req.payload.decrypt(value, { secret: req.payload.config.secret }))
42
+ return data.type === type && (!data.exp || data.exp > Date.now()) ? data : undefined
43
+ } catch {
44
+ return undefined
45
+ }
46
+ }
@@ -5,5 +5,5 @@ import type { ToolInputSchema } from '../types.js'
5
5
  /** Normalize a tool/prompt input to a Standard Schema. Raw JSON Schema gets wrapped; Standard Schema instances pass through. */
6
6
  export const toStandardSchema = (schema: ToolInputSchema): StandardSchemaWithJSON =>
7
7
  typeof schema === 'object' && schema !== null && '~standard' in schema
8
- ? (schema as StandardSchemaWithJSON)
8
+ ? schema
9
9
  : fromJsonSchema(schema)