@payloadcms/plugin-mcp 4.0.0-internal.5a4aa81 → 4.0.0-internal.5d2e3d1

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 (120) hide show
  1. package/bin.js +0 -7
  2. package/dist/endpoint/access.d.ts +5 -0
  3. package/dist/endpoint/access.d.ts.map +1 -1
  4. package/dist/endpoint/access.js +42 -5
  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 +23 -0
  14. package/dist/endpoint/oauthLoginToken.d.ts.map +1 -0
  15. package/dist/endpoint/oauthLoginToken.js +80 -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 +423 -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 +1 -1
  34. package/dist/mcp/buildMcpServer.d.ts.map +1 -1
  35. package/dist/mcp/buildMcpServer.js +3 -3
  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 +4 -3
  39. package/dist/mcp/builtin/collections/authTools.js.map +1 -1
  40. package/dist/mcp/builtin/collections/createTool.d.ts.map +1 -1
  41. package/dist/mcp/builtin/collections/createTool.js.map +1 -1
  42. package/dist/mcp/builtin/collections/deleteTool.d.ts.map +1 -1
  43. package/dist/mcp/builtin/collections/deleteTool.js +9 -3
  44. package/dist/mcp/builtin/collections/deleteTool.js.map +1 -1
  45. package/dist/mcp/builtin/collections/duplicateTool.d.ts.map +1 -1
  46. package/dist/mcp/builtin/collections/duplicateTool.js +6 -2
  47. package/dist/mcp/builtin/collections/duplicateTool.js.map +1 -1
  48. package/dist/mcp/builtin/collections/fileInput.d.ts.map +1 -1
  49. package/dist/mcp/builtin/collections/fileInput.js +19 -54
  50. package/dist/mcp/builtin/collections/fileInput.js.map +1 -1
  51. package/dist/mcp/builtin/collections/findTool.js +8 -4
  52. package/dist/mcp/builtin/collections/findTool.js.map +1 -1
  53. package/dist/mcp/builtin/collections/getCollectionSchemaTool.d.ts.map +1 -1
  54. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js +19 -3
  55. package/dist/mcp/builtin/collections/getCollectionSchemaTool.js.map +1 -1
  56. package/dist/mcp/builtin/collections/restoreVersionTool.js.map +1 -1
  57. package/dist/mcp/builtin/collections/updateTool.d.ts.map +1 -1
  58. package/dist/mcp/builtin/collections/updateTool.js +6 -2
  59. package/dist/mcp/builtin/collections/updateTool.js.map +1 -1
  60. package/dist/mcp/builtin/collections/uploadInstructionsTool.js.map +1 -1
  61. package/dist/mcp/builtin/globals/findTool.js.map +1 -1
  62. package/dist/mcp/builtin/globals/getGlobalSchemaTool.d.ts.map +1 -1
  63. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js +19 -3
  64. package/dist/mcp/builtin/globals/getGlobalSchemaTool.js.map +1 -1
  65. package/dist/mcp/builtin/globals/updateTool.js.map +1 -1
  66. package/dist/mcp/sanitizeMCPConfig.d.ts.map +1 -1
  67. package/dist/mcp/sanitizeMCPConfig.js +3 -0
  68. package/dist/mcp/sanitizeMCPConfig.js.map +1 -1
  69. package/dist/stdio.js +4 -3
  70. package/dist/stdio.js.map +1 -1
  71. package/dist/types.d.ts +105 -3
  72. package/dist/types.d.ts.map +1 -1
  73. package/dist/types.js.map +1 -1
  74. package/dist/utils/seal.d.ts +17 -0
  75. package/dist/utils/seal.d.ts.map +1 -0
  76. package/dist/utils/seal.js +24 -0
  77. package/dist/utils/seal.js.map +1 -0
  78. package/dist/utils/toStandardSchema.js.map +1 -1
  79. package/dist/views/Authorize/AllowButtons/index.d.ts +18 -0
  80. package/dist/views/Authorize/AllowButtons/index.d.ts.map +1 -0
  81. package/dist/views/Authorize/AllowButtons/index.js +88 -0
  82. package/dist/views/Authorize/AllowButtons/index.js.map +1 -0
  83. package/dist/views/Authorize/index.css +19 -0
  84. package/dist/views/Authorize/index.d.ts +9 -0
  85. package/dist/views/Authorize/index.d.ts.map +1 -0
  86. package/dist/views/Authorize/index.js +86 -0
  87. package/dist/views/Authorize/index.js.map +1 -0
  88. package/package.json +30 -26
  89. package/src/endpoint/access.ts +45 -3
  90. package/src/endpoint/index.ts +50 -4
  91. package/src/endpoint/oauth.ts +108 -0
  92. package/src/endpoint/oauthLoginToken.ts +94 -0
  93. package/src/endpoint/oauthServer.ts +452 -0
  94. package/src/exports/client.ts +1 -1
  95. package/src/exports/rsc.ts +1 -0
  96. package/src/index.ts +53 -9
  97. package/src/mcp/buildMcpServer.ts +5 -5
  98. package/src/mcp/builtin/collections/authTools.ts +7 -4
  99. package/src/mcp/builtin/collections/createTool.ts +1 -3
  100. package/src/mcp/builtin/collections/deleteTool.ts +6 -4
  101. package/src/mcp/builtin/collections/duplicateTool.ts +3 -2
  102. package/src/mcp/builtin/collections/fileInput.ts +17 -59
  103. package/src/mcp/builtin/collections/findTool.ts +4 -4
  104. package/src/mcp/builtin/collections/getCollectionSchemaTool.ts +12 -1
  105. package/src/mcp/builtin/collections/restoreVersionTool.ts +1 -1
  106. package/src/mcp/builtin/collections/updateTool.ts +3 -2
  107. package/src/mcp/builtin/collections/uploadInstructionsTool.ts +1 -1
  108. package/src/mcp/builtin/globals/findTool.ts +1 -1
  109. package/src/mcp/builtin/globals/getGlobalSchemaTool.ts +11 -1
  110. package/src/mcp/builtin/globals/updateTool.ts +1 -1
  111. package/src/mcp/sanitizeMCPConfig.ts +1 -0
  112. package/src/stdio.ts +2 -2
  113. package/src/types.ts +105 -3
  114. package/src/utils/seal.ts +46 -0
  115. package/src/utils/toStandardSchema.ts +1 -1
  116. package/src/views/Authorize/AllowButtons/index.tsx +97 -0
  117. package/src/views/Authorize/index.css +19 -0
  118. package/src/views/Authorize/index.tsx +93 -0
  119. package/dist/mcp/builtin/collections/fileInput.spec.js +0 -86
  120. package/dist/mcp/builtin/collections/fileInput.spec.js.map +0 -1
@@ -1,6 +1,7 @@
1
1
  import {
2
2
  duplicateDocumentInputSchema,
3
3
  getCollectionVirtualFieldNames,
4
+ parseDocumentID,
4
5
  stripVirtualFields,
5
6
  transformPointDataToPayload,
6
7
  validateCollectionData,
@@ -50,7 +51,7 @@ export const duplicateDocumentTool = defineCollectionTool({
50
51
  const parsedData = inputData ? transformPointDataToPayload(inputData) : undefined
51
52
 
52
53
  const result = await payload.duplicate({
53
- id,
54
+ id: parseDocumentID({ id, collectionSlug: slug, payload }),
54
55
  collection: slug,
55
56
  depth,
56
57
  draft,
@@ -73,7 +74,7 @@ export const duplicateDocumentTool = defineCollectionTool({
73
74
  text: `Document duplicated successfully in collection "${slug}"!\nDuplicated document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
74
75
  },
75
76
  ],
76
- doc: result as Record<string, unknown>,
77
+ doc: result,
77
78
  }
78
79
  } catch (error) {
79
80
  const errorMessage = error instanceof Error ? error.message : 'Unknown error'
@@ -1,7 +1,11 @@
1
- import type { CollectionSlug, File, FileData, PayloadRequest } from 'payload'
1
+ import type { CollectionSlug, File, PayloadRequest } from 'payload'
2
2
 
3
3
  import { APIError, z } from 'payload'
4
- import { getExternalFile, getFileFromUploadInstructions, isURLAllowed } from 'payload/internal'
4
+ import {
5
+ externalURLInputSchema,
6
+ getFileFromUploadInstructions,
7
+ resolveURLUploadInput,
8
+ } from 'payload/internal'
5
9
  import { sanitizeFilename } from 'payload/shared'
6
10
 
7
11
  const mimeTypeSchema = z
@@ -30,11 +34,7 @@ export const fileInputSchema = z
30
34
  mimeType: mimeTypeSchema.check(z.describe('The file MIME type, for example image/png.')),
31
35
  source: z.literal('base64'),
32
36
  }),
33
- z.strictObject({
34
- name: z.optional(z.string().check(z.minLength(1))).check(z.describe('File name override.')),
35
- source: z.literal('externalURL'),
36
- url: z.url().check(z.describe('The http or https URL to download.')),
37
- }),
37
+ externalURLInputSchema,
38
38
  z.strictObject({
39
39
  file: uploadFileSchema.check(z.describe('getUploadInstructions file field post-upload.')),
40
40
  source: z.literal('uploadReference'),
@@ -75,6 +75,10 @@ export async function resolveFile({
75
75
  }
76
76
  }
77
77
 
78
+ if (input.source === 'externalURL') {
79
+ return resolveURLUploadInput({ slug, input, req })
80
+ }
81
+
78
82
  const uploadConfig = req.payload.collections[slug]?.config.upload
79
83
 
80
84
  if (!uploadConfig) {
@@ -82,48 +86,12 @@ export async function resolveFile({
82
86
  }
83
87
 
84
88
  const maxFileSize = req.payload.config.upload.limits?.fileSize
85
- let file: File
86
-
87
- if (input.source === 'base64') {
88
- const data = decodeBase64({ maxFileSize, value: input.data })
89
-
90
- file = {
91
- name: sanitizeFilename(input.name),
92
- data,
93
- mimetype: input.mimeType,
94
- size: data.length,
95
- }
96
- } else {
97
- if (uploadConfig.pasteURL === false) {
98
- throw new APIError(`Uploading files from URLs is disabled for collection "${slug}".`, 400)
99
- }
100
-
101
- const url = new URL(input.url)
102
-
103
- if (!['http:', 'https:'].includes(url.protocol)) {
104
- throw new APIError('File URLs must use http or https.', 400)
105
- }
106
-
107
- if (
108
- typeof uploadConfig.pasteURL === 'object' &&
109
- !isURLAllowed(input.url, uploadConfig.pasteURL.allowList)
110
- ) {
111
- throw new APIError('The provided file URL is not allowed.', 400)
112
- }
113
-
114
- file = await getExternalFile({
115
- data: {
116
- filename: sanitizeFilename(input.name || getURLFilename(url)),
117
- url: input.url,
118
- } as FileData,
119
- req,
120
- uploadConfig: {
121
- ...uploadConfig,
122
- externalFileHeaderFilter: uploadConfig.externalFileHeaderFilter ?? (() => ({})),
123
- },
124
- })
125
- file.mimetype = file.mimetype?.split(';')[0] || 'application/octet-stream'
126
- file.size = file.data.length
89
+ const data = decodeBase64({ maxFileSize, value: input.data })
90
+ const file: File = {
91
+ name: sanitizeFilename(input.name),
92
+ data,
93
+ mimetype: input.mimeType,
94
+ size: data.length,
127
95
  }
128
96
 
129
97
  if (maxFileSize !== undefined && Number.isFinite(maxFileSize) && file.size > maxFileSize) {
@@ -157,13 +125,3 @@ function decodeBase64({ maxFileSize, value }: { maxFileSize?: number; value: str
157
125
 
158
126
  return data
159
127
  }
160
-
161
- function getURLFilename(url: URL): string {
162
- const pathSegment = url.pathname.split('/').pop() || 'upload'
163
-
164
- try {
165
- return decodeURIComponent(pathSegment)
166
- } catch {
167
- return pathSegment
168
- }
169
- }
@@ -1,4 +1,4 @@
1
- import { findDocumentsInputSchema } from 'payload'
1
+ import { findDocumentsInputSchema, parseDocumentID } from 'payload'
2
2
 
3
3
  import { defaultAccess } from '../../../defaultAccess.js'
4
4
  import { defineCollectionTool } from '../../../defineTool.js'
@@ -45,10 +45,10 @@ export const findDocumentsTool = defineCollectionTool({
45
45
  )
46
46
 
47
47
  try {
48
- if (id) {
48
+ if (id !== undefined) {
49
49
  try {
50
50
  const doc = await payload.findByID({
51
- id,
51
+ id: parseDocumentID({ id, collectionSlug: slug, payload }),
52
52
  collection: slug,
53
53
  depth,
54
54
  overrideAccess: authorizedMCP.overrideAccess,
@@ -69,7 +69,7 @@ export const findDocumentsTool = defineCollectionTool({
69
69
  text: `Document from collection "${slug}":\n${JSON.stringify(doc)}`,
70
70
  },
71
71
  ],
72
- doc: doc as Record<string, unknown>,
72
+ doc,
73
73
  }
74
74
  } catch {
75
75
  logger.warn(`Document not found with ID: ${id} in collection: ${slug}`)
@@ -1,4 +1,5 @@
1
1
  import { getAccessResults, getCollectionInputSchema, getCollectionSchemaInputSchema } from 'payload'
2
+ import { getLLMInstructions } from 'payload/internal'
2
3
 
3
4
  import { defaultAccess } from '../../../defaultAccess.js'
4
5
  import { defineCollectionTool } from '../../../defineTool.js'
@@ -16,7 +17,8 @@ export const getCollectionSchemaTool = defineCollectionTool({
16
17
  readOnlyHint: true,
17
18
  title: 'Get Collection Schema',
18
19
  },
19
- description: 'Get the input schema for creating or updating documents in a collection.',
20
+ description:
21
+ 'Get the input schema and LLM instructions before creating or updating documents in a collection.',
20
22
  input: getCollectionSchemaInputSchema,
21
23
  }).handler(async ({ slug, authorizedMCP, req }) => {
22
24
  const permissions = authorizedMCP.overrideAccess
@@ -64,17 +66,26 @@ export const getCollectionSchemaTool = defineCollectionTool({
64
66
  }
65
67
  : { enabled: false }
66
68
 
69
+ const instructions = await getLLMInstructions({
70
+ slug,
71
+ type: 'collection',
72
+ overrideAccess: authorizedMCP.overrideAccess,
73
+ req,
74
+ })
75
+
67
76
  return {
68
77
  content: [
69
78
  {
70
79
  type: 'text',
71
80
  text: `Schema for collection "${slug}":\n\`\`\`json\n${JSON.stringify(inputSchema)}\n\`\`\`\nUpload configuration:\n\`\`\`json\n${JSON.stringify(upload)}\n\`\`\``,
72
81
  },
82
+ ...(instructions ? [{ type: 'text' as const, text: instructions }] : []),
73
83
  ],
74
84
  structuredContent: {
75
85
  slug,
76
86
  schema: inputSchema,
77
87
  upload,
88
+ ...(instructions ? { instructions } : {}),
78
89
  },
79
90
  }
80
91
  })
@@ -47,7 +47,7 @@ export const restoreVersionTool = defineCollectionTool({
47
47
  text: `Version "${id}" restored successfully in collection "${slug}"!\nRestored document:\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
48
48
  },
49
49
  ],
50
- doc: result as Record<string, unknown>,
50
+ doc: result,
51
51
  }
52
52
  } catch (error) {
53
53
  const errorMessage = error instanceof Error ? error.message : 'Unknown error'
@@ -3,6 +3,7 @@ import type { Where } from 'payload'
3
3
  import {
4
4
  getCollectionInputSchema,
5
5
  getCollectionVirtualFieldNames,
6
+ parseDocumentID,
6
7
  stripVirtualFields,
7
8
  transformPointDataToPayload,
8
9
  updateDocumentInputSchema,
@@ -75,7 +76,7 @@ export const updateDocumentTool = defineCollectionTool({
75
76
 
76
77
  if (id !== undefined) {
77
78
  const result = await payload.update({
78
- id,
79
+ id: parseDocumentID({ id, collectionSlug: slug, payload }),
79
80
  collection: slug,
80
81
  data: parsedData,
81
82
  depth,
@@ -102,7 +103,7 @@ export const updateDocumentTool = defineCollectionTool({
102
103
  text: `Document updated successfully in collection "${slug}"!\nResult:\n\`\`\`json\n${JSON.stringify(responseResult)}\n\`\`\``,
103
104
  },
104
105
  ],
105
- doc: responseResult as Record<string, unknown>,
106
+ doc: responseResult,
106
107
  }
107
108
  }
108
109
 
@@ -9,7 +9,7 @@ export const getUploadInstructionsTool = defineCollectionTool({
9
9
  defaultAccess(args) &&
10
10
  Boolean(
11
11
  args.permissions?.collections?.[args.slug]?.create ||
12
- args.permissions?.collections?.[args.slug]?.update,
12
+ args.permissions?.collections?.[args.slug]?.update,
13
13
  ),
14
14
  annotations: {
15
15
  destructiveHint: false,
@@ -54,7 +54,7 @@ export const findGlobalTool = defineGlobalTool({
54
54
  text: `Global "${slug}":\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
55
55
  },
56
56
  ],
57
- doc: result as Record<string, unknown>,
57
+ doc: result,
58
58
  }
59
59
  } catch (error) {
60
60
  const errorMessage = error instanceof Error ? error.message : 'Unknown error'
@@ -1,4 +1,5 @@
1
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'
@@ -16,7 +17,7 @@ export const getGlobalSchemaTool = defineGlobalTool({
16
17
  readOnlyHint: true,
17
18
  title: 'Get Global Schema',
18
19
  },
19
- description: 'Get the input schema for updating a global.',
20
+ description: 'Get the input schema and LLM instructions before updating a global.',
20
21
  input: getGlobalSchemaInputSchema,
21
22
  }).handler(async ({ slug, authorizedMCP, req }) => {
22
23
  const permissions = authorizedMCP.overrideAccess
@@ -48,16 +49,25 @@ export const getGlobalSchemaTool = defineGlobalTool({
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
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
68
  slug,
60
69
  schema: inputSchema,
70
+ ...(instructions ? { instructions } : {}),
61
71
  },
62
72
  }
63
73
  })
@@ -82,7 +82,7 @@ export const updateGlobalTool = defineGlobalTool({
82
82
  text: `Global "${slug}" updated successfully!\n\`\`\`json\n${JSON.stringify(result)}\n\`\`\``,
83
83
  },
84
84
  ],
85
- doc: result as Record<string, unknown>,
85
+ doc: result,
86
86
  }
87
87
  } catch (error) {
88
88
  const message = error instanceof Error ? error.message : 'Unknown error'
@@ -103,6 +103,7 @@ export const sanitizeMCPConfig = ({
103
103
  hooks: pluginConfig.hooks,
104
104
  items,
105
105
  mcp: pluginConfig.mcp,
106
+ oauth: pluginConfig.oauth === false ? undefined : (pluginConfig.oauth ?? { type: 'builtin' }),
106
107
  overrideGetAuthorizedMCP: pluginConfig.overrideGetAuthorizedMCP,
107
108
  }
108
109
  }
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,
@@ -279,9 +280,24 @@ 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
+ * How MCP clients sign in. MCP requests without an authenticated user get a `401` that points
295
+ * to the protected resource metadata (RFC 9728). Set to `false` to only accept API keys and
296
+ * anonymous requests.
297
+ *
298
+ * @default { type: 'builtin' }
299
+ */
300
+ oauth?: false | MCPOAuthConfig
285
301
  /**
286
302
  * Replace the default MCP authorization resolver.
287
303
  *
@@ -299,13 +315,99 @@ export type MCPPluginConfig = {
299
315
  tools?: MCPTopLevelToolsMap
300
316
  }
301
317
 
318
+ export type MCPOAuthConfig = MCPBuiltinOAuthConfig | MCPExternalOAuthConfig
319
+
320
+ /**
321
+ * This Payload app is the authorization server. Users sign in to the admin panel and allow the
322
+ * MCP client, which then gets an access token for them.
323
+ */
324
+ export type MCPBuiltinOAuthConfig = {
325
+ /**
326
+ * Creates the tokens the MCP client gets when the user clicks Allow. `req` is the user's own
327
+ * browser request, so `req.user` is the user who allowed it. Pass `authenticate` too if
328
+ * Payload's auth strategies don't accept the access token.
329
+ *
330
+ * @default a Payload login token for that user that only works for MCP, with a refresh token when
331
+ * the collection uses sessions
332
+ */
333
+ issueToken?: (args: { req: PayloadRequest }) => MaybePromise<MCPOAuthTokens>
334
+ /**
335
+ * Trades a refresh token from `issueToken`, or from an earlier refresh, for new tokens. Return
336
+ * `null` when it's no longer valid, and the client sends the user through sign-in again. `req`
337
+ * is the MCP client's request, without a user. Only used together with `issueToken`.
338
+ *
339
+ * OAuth requires noticing copied refresh tokens: return a new refresh token every time, and
340
+ * revoke the tokens when an already used refresh token comes back.
341
+ *
342
+ * It also runs when the client trades its authorization code, on the refresh token from
343
+ * `issueToken`, with `reuseInterval: 0`. OAuth requires a code to work only once, so refuse that
344
+ * refresh token if it was used before, even moments ago.
345
+ */
346
+ refreshToken?: (args: {
347
+ refreshToken: string
348
+ req: PayloadRequest
349
+ /**
350
+ * How long a refresh token that was just used may still be accepted, in milliseconds, e.g. for
351
+ * clients that refresh twice at once. `0` means not at all. When it's missing, use your usual
352
+ * leeway.
353
+ */
354
+ reuseInterval?: number
355
+ }) => MaybePromise<MCPOAuthTokens | null>
356
+ type: 'builtin'
357
+ } & MCPOAuthSharedConfig
358
+
359
+ export type MCPOAuthTokens = {
360
+ accessToken: string
361
+ /** Seconds until the access token expires. */
362
+ expiresIn?: number
363
+ /** Lets the client get new tokens without the user, through `refreshToken`. */
364
+ refreshToken?: string
365
+ }
366
+
367
+ /** Another service, e.g. your identity provider, is the authorization server. */
368
+ export type MCPExternalOAuthConfig = {
369
+ /**
370
+ * The authorization servers that issue access tokens for MCP clients. Clients require each one
371
+ * to exactly match the `issuer` in that server's metadata, so pass a function when the exact
372
+ * value is only known at runtime, e.g. from the server's OpenID configuration or per host.
373
+ */
374
+ authorizationServers: ((args: { req: PayloadRequest }) => MaybePromise<string[]>) | string[]
375
+ /**
376
+ * Scopes MCP clients should request, e.g. `['openid', 'email', 'profile']`. Without them,
377
+ * clients request none, which some authorization servers reject or answer with a token that
378
+ * doesn't identify the user.
379
+ */
380
+ scopes?: string[]
381
+ type: 'external'
382
+ } & MCPOAuthSharedConfig
383
+
384
+ type MCPOAuthSharedConfig = {
385
+ /**
386
+ * Called on MCP requests with a bearer token that Payload's auth strategies didn't accept.
387
+ * Return the Payload user, including its `collection`, or `null` to answer with the OAuth challenge.
388
+ */
389
+ authenticate?: (args: {
390
+ req: PayloadRequest
391
+ token: string
392
+ }) => MaybePromise<PayloadRequest['user']>
393
+ /**
394
+ * The URL clients call to reach the MCP endpoint. The metadata link and the built-in
395
+ * authorization server's issuer are based on it.
396
+ *
397
+ * @default the absolute URL of `/api/mcp`, based on `serverURL` or the request URL
398
+ */
399
+ resource?: ((args: { req: PayloadRequest }) => string) | string
400
+ }
401
+
302
402
  export type SanitizedMCPPluginConfig = {
303
403
  items: MCPItem[]
404
+ /** `undefined` when OAuth is turned off. */
405
+ oauth?: MCPOAuthConfig
304
406
  } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
305
407
 
306
408
  export type MCPServerOptions = {
307
- options?: ConstructorParameters<typeof McpServer>[1]
308
- serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
409
+ options?: McpServerOptions
410
+ serverInfo?: Partial<Implementation>
309
411
  }
310
412
 
311
413
  /**
@@ -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)
@@ -0,0 +1,97 @@
1
+ 'use client'
2
+
3
+ import { Button } from '@payloadcms/ui'
4
+ import React, { useEffect, useState, useSyncExternalStore } from 'react'
5
+
6
+ const baseClass = 'mcp-authorize'
7
+
8
+ /** How long the page must have been in front of the user before the buttons work, in ms. */
9
+ const enableDelay = 1000
10
+
11
+ // Whether the page is inside a frame never changes, so there's nothing to subscribe to
12
+ const subscribe = () => () => {}
13
+
14
+ /**
15
+ * The Allow and Deny buttons, protected against clicks the user didn't mean for this page:
16
+ *
17
+ * - Inside a frame they aren't shown, so other sites can't frame the page and trick users into
18
+ * clicking them. The server can't tell, so they're missing until the browser has checked.
19
+ * - They're disabled until the page has been visible and focused for a moment. Otherwise another
20
+ * site could open the page under the user's cursor while they double-click something else, so
21
+ * the second click lands on Allow. Leaving the page disables them again. Waiting works for every
22
+ * way of clicking, unlike requiring a mouse movement or key press first.
23
+ *
24
+ * @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-17#section-7.11 for why the
25
+ * OAuth server must prevent clickjacking
26
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Clickjacking_Defense_Cheat_Sheet.html#defending-against-doubleclickjacking
27
+ * for the double-click attack and its mitigation
28
+ */
29
+ export function AllowButtons() {
30
+ const isTopLevel = useSyncExternalStore(
31
+ subscribe,
32
+ () => window.top === window.self,
33
+ () => false,
34
+ )
35
+ const [isEnabled, setIsEnabled] = useState(false)
36
+
37
+ useEffect(() => {
38
+ let timeout: ReturnType<typeof setTimeout> | undefined
39
+
40
+ const enableAfterDelay = () => {
41
+ clearTimeout(timeout)
42
+ if (document.visibilityState === 'visible' && document.hasFocus()) {
43
+ timeout = setTimeout(() => setIsEnabled(true), enableDelay)
44
+ }
45
+ }
46
+ const disable = () => {
47
+ clearTimeout(timeout)
48
+ setIsEnabled(false)
49
+ }
50
+ const onVisibilityChange = () => {
51
+ if (document.visibilityState === 'visible') {
52
+ enableAfterDelay()
53
+ } else {
54
+ disable()
55
+ }
56
+ }
57
+
58
+ enableAfterDelay()
59
+ window.addEventListener('focus', enableAfterDelay)
60
+ window.addEventListener('blur', disable)
61
+ document.addEventListener('visibilitychange', onVisibilityChange)
62
+
63
+ return () => {
64
+ clearTimeout(timeout)
65
+ window.removeEventListener('focus', enableAfterDelay)
66
+ window.removeEventListener('blur', disable)
67
+ document.removeEventListener('visibilitychange', onVisibilityChange)
68
+ }
69
+ }, [])
70
+
71
+ if (!isTopLevel) {
72
+ return null
73
+ }
74
+
75
+ return (
76
+ <div className={`${baseClass}__actions`}>
77
+ <Button
78
+ buttonStyle="primary"
79
+ disabled={!isEnabled}
80
+ extraButtonProps={{ name: 'decision', value: 'allow' }}
81
+ margin={false}
82
+ type="submit"
83
+ >
84
+ Allow
85
+ </Button>
86
+ <Button
87
+ buttonStyle="secondary"
88
+ disabled={!isEnabled}
89
+ extraButtonProps={{ name: 'decision', value: 'deny' }}
90
+ margin={false}
91
+ type="submit"
92
+ >
93
+ Deny
94
+ </Button>
95
+ </div>
96
+ )
97
+ }
@@ -0,0 +1,19 @@
1
+ @layer payload-default {
2
+ .mcp-authorize {
3
+ overflow-wrap: anywhere;
4
+ }
5
+
6
+ .mcp-authorize__brand {
7
+ display: flex;
8
+ justify-content: center;
9
+ width: 100%;
10
+ margin-block-end: var(--spacer-5);
11
+ }
12
+
13
+ .mcp-authorize__actions {
14
+ display: flex;
15
+ flex-wrap: wrap;
16
+ justify-content: center;
17
+ gap: var(--spacer-2);
18
+ }
19
+ }