@payloadcms/plugin-mcp 4.0.0-beta.7 → 4.0.0-beta.9

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 (69) hide show
  1. package/dist/endpoint/access.d.ts +5 -0
  2. package/dist/endpoint/access.d.ts.map +1 -1
  3. package/dist/endpoint/access.js +42 -5
  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 +25 -0
  7. package/dist/endpoint/index.js.map +1 -1
  8. package/dist/endpoint/oauth.d.ts +37 -0
  9. package/dist/endpoint/oauth.d.ts.map +1 -0
  10. package/dist/endpoint/oauth.js +105 -0
  11. package/dist/endpoint/oauth.js.map +1 -0
  12. package/dist/endpoint/oauthLoginToken.d.ts +27 -0
  13. package/dist/endpoint/oauthLoginToken.d.ts.map +1 -0
  14. package/dist/endpoint/oauthLoginToken.js +86 -0
  15. package/dist/endpoint/oauthLoginToken.js.map +1 -0
  16. package/dist/endpoint/oauthServer.d.ts +28 -0
  17. package/dist/endpoint/oauthServer.d.ts.map +1 -0
  18. package/dist/endpoint/oauthServer.js +432 -0
  19. package/dist/endpoint/oauthServer.js.map +1 -0
  20. package/dist/exports/client.d.ts +1 -1
  21. package/dist/exports/client.d.ts.map +1 -1
  22. package/dist/exports/client.js +1 -1
  23. package/dist/exports/client.js.map +1 -1
  24. package/dist/exports/rsc.d.ts +2 -0
  25. package/dist/exports/rsc.d.ts.map +1 -0
  26. package/dist/exports/rsc.js +3 -0
  27. package/dist/exports/rsc.js.map +1 -0
  28. package/dist/index.d.ts +10 -2
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +34 -10
  31. package/dist/index.js.map +1 -1
  32. package/dist/mcp/builtin/collections/deleteTool.d.ts.map +1 -1
  33. package/dist/mcp/builtin/collections/deleteTool.js +3 -1
  34. package/dist/mcp/builtin/collections/deleteTool.js.map +1 -1
  35. package/dist/mcp/sanitizeMCPConfig.d.ts.map +1 -1
  36. package/dist/mcp/sanitizeMCPConfig.js +3 -0
  37. package/dist/mcp/sanitizeMCPConfig.js.map +1 -1
  38. package/dist/types.d.ts +100 -0
  39. package/dist/types.d.ts.map +1 -1
  40. package/dist/types.js.map +1 -1
  41. package/dist/utils/seal.d.ts +17 -0
  42. package/dist/utils/seal.d.ts.map +1 -0
  43. package/dist/utils/seal.js +24 -0
  44. package/dist/utils/seal.js.map +1 -0
  45. package/dist/views/Authorize/AllowButtons/index.d.ts +18 -0
  46. package/dist/views/Authorize/AllowButtons/index.d.ts.map +1 -0
  47. package/dist/views/Authorize/AllowButtons/index.js +88 -0
  48. package/dist/views/Authorize/AllowButtons/index.js.map +1 -0
  49. package/dist/views/Authorize/index.css +19 -0
  50. package/dist/views/Authorize/index.d.ts +9 -0
  51. package/dist/views/Authorize/index.d.ts.map +1 -0
  52. package/dist/views/Authorize/index.js +86 -0
  53. package/dist/views/Authorize/index.js.map +1 -0
  54. package/package.json +10 -3
  55. package/src/endpoint/access.ts +45 -3
  56. package/src/endpoint/index.ts +17 -1
  57. package/src/endpoint/oauth.ts +108 -0
  58. package/src/endpoint/oauthLoginToken.ts +100 -0
  59. package/src/endpoint/oauthServer.ts +461 -0
  60. package/src/exports/client.ts +1 -1
  61. package/src/exports/rsc.ts +1 -0
  62. package/src/index.ts +52 -8
  63. package/src/mcp/builtin/collections/deleteTool.ts +3 -1
  64. package/src/mcp/sanitizeMCPConfig.ts +1 -0
  65. package/src/types.ts +98 -0
  66. package/src/utils/seal.ts +46 -0
  67. package/src/views/Authorize/AllowButtons/index.tsx +97 -0
  68. package/src/views/Authorize/index.css +19 -0
  69. package/src/views/Authorize/index.tsx +93 -0
package/src/types.ts CHANGED
@@ -290,6 +290,14 @@ export type MCPPluginConfig = {
290
290
  serverOptions?: MCPServerOptions
291
291
  verboseLogs?: boolean
292
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
293
301
  /**
294
302
  * Replace the default MCP authorization resolver.
295
303
  *
@@ -307,8 +315,98 @@ export type MCPPluginConfig = {
307
315
  tools?: MCPTopLevelToolsMap
308
316
  }
309
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. Its session is labelled with the client's name.
332
+ */
333
+ issueToken?: (args: {
334
+ /** The MCP client the user allowed, with the address it returns to. */
335
+ client: { name: string; redirectURI: string }
336
+ req: PayloadRequest
337
+ }) => MaybePromise<MCPOAuthTokens>
338
+ /**
339
+ * Trades a refresh token from `issueToken`, or from an earlier refresh, for new tokens. Return
340
+ * `null` when it's no longer valid, and the client sends the user through sign-in again. `req`
341
+ * is the MCP client's request, without a user. Only used together with `issueToken`.
342
+ *
343
+ * OAuth requires noticing copied refresh tokens: return a new refresh token every time, and
344
+ * revoke the tokens when an already used refresh token comes back.
345
+ *
346
+ * It also runs when the client trades its authorization code, on the refresh token from
347
+ * `issueToken`, with `reuseInterval: 0`. OAuth requires a code to work only once, so refuse that
348
+ * refresh token if it was used before, even moments ago.
349
+ */
350
+ refreshToken?: (args: {
351
+ refreshToken: string
352
+ req: PayloadRequest
353
+ /**
354
+ * How long a refresh token that was just used may still be accepted, in milliseconds, e.g. for
355
+ * clients that refresh twice at once. `0` means not at all. When it's missing, use your usual
356
+ * leeway.
357
+ */
358
+ reuseInterval?: number
359
+ }) => MaybePromise<MCPOAuthTokens | null>
360
+ type: 'builtin'
361
+ } & MCPOAuthSharedConfig
362
+
363
+ export type MCPOAuthTokens = {
364
+ accessToken: string
365
+ /** Seconds until the access token expires. */
366
+ expiresIn?: number
367
+ /** Lets the client get new tokens without the user, through `refreshToken`. */
368
+ refreshToken?: string
369
+ }
370
+
371
+ /** Another service, e.g. your identity provider, is the authorization server. */
372
+ export type MCPExternalOAuthConfig = {
373
+ /**
374
+ * The authorization servers that issue access tokens for MCP clients. Clients require each one
375
+ * to exactly match the `issuer` in that server's metadata, so pass a function when the exact
376
+ * value is only known at runtime, e.g. from the server's OpenID configuration or per host.
377
+ */
378
+ authorizationServers: ((args: { req: PayloadRequest }) => MaybePromise<string[]>) | string[]
379
+ /**
380
+ * Scopes MCP clients should request, e.g. `['openid', 'email', 'profile']`. Without them,
381
+ * clients request none, which some authorization servers reject or answer with a token that
382
+ * doesn't identify the user.
383
+ */
384
+ scopes?: string[]
385
+ type: 'external'
386
+ } & MCPOAuthSharedConfig
387
+
388
+ type MCPOAuthSharedConfig = {
389
+ /**
390
+ * Called on MCP requests with a bearer token that Payload's auth strategies didn't accept.
391
+ * Return the Payload user, including its `collection`, or `null` to answer with the OAuth challenge.
392
+ */
393
+ authenticate?: (args: {
394
+ req: PayloadRequest
395
+ token: string
396
+ }) => MaybePromise<PayloadRequest['user']>
397
+ /**
398
+ * The URL clients call to reach the MCP endpoint. The metadata link and the built-in
399
+ * authorization server's issuer are based on it.
400
+ *
401
+ * @default the absolute URL of `/api/mcp`, based on `serverURL` or the request URL
402
+ */
403
+ resource?: ((args: { req: PayloadRequest }) => string) | string
404
+ }
405
+
310
406
  export type SanitizedMCPPluginConfig = {
311
407
  items: MCPItem[]
408
+ /** `undefined` when OAuth is turned off. */
409
+ oauth?: MCPOAuthConfig
312
410
  } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
313
411
 
314
412
  export type MCPServerOptions = {
@@ -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
+ }
@@ -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
+ }
@@ -0,0 +1,93 @@
1
+ import type { AdminViewServerProps } from 'payload'
2
+
3
+ import { FormHeader, Logo, MinimalTemplate } from '@payloadcms/ui/rsc'
4
+ import { formatAdminURL } from 'payload/shared'
5
+ import React from 'react'
6
+
7
+ import type { AuthorizeViewError, Client, Consent } from '../../endpoint/oauthServer.js'
8
+
9
+ // eslint-disable-next-line payload/no-imports-from-exports-dir -- Server component must reference exports dir for proper client boundary
10
+ import { AllowButtons } from '../../exports/client.js'
11
+ import { unseal } from '../../utils/seal.js'
12
+ import './index.css'
13
+
14
+ const baseClass = 'mcp-authorize'
15
+
16
+ const errorTitles: Record<AuthorizeViewError, string> = {
17
+ expired: 'This sign-in request expired',
18
+ 'invalid-link': 'This sign-in link is invalid',
19
+ }
20
+
21
+ /**
22
+ * The admin page where users allow an MCP client to use their account, for the built-in OAuth
23
+ * server. Its authorize endpoint sends users here with the consent to show, or with an error.
24
+ */
25
+ export function MCPAuthorizeView({
26
+ initPageResult,
27
+ params,
28
+ searchParams,
29
+ server,
30
+ user,
31
+ }: AdminViewServerProps) {
32
+ const { locale, permissions, req } = initPageResult
33
+ const { i18n, payload } = req
34
+ const sealedConsent = getSearchParam(searchParams?.consent)
35
+ const consent = unseal<Consent>({ type: 'consent', req, value: sealedConsent })
36
+ const client = consent && unseal<Client>({ type: 'client', req, value: consent.clientID })
37
+ // The consent is only valid for the user it was made for
38
+ const isConsentValid =
39
+ client &&
40
+ consent &&
41
+ req.user?.id === consent.userID &&
42
+ req.user.collection === consent.collection
43
+ const error: AuthorizeViewError =
44
+ getSearchParam(searchParams?.error) === 'invalid-link' ? 'invalid-link' : 'expired'
45
+ const account = String(user?.email ?? consent?.userID)
46
+ const returnHost = consent && (new URL(consent.redirectURI).host || consent.redirectURI)
47
+
48
+ return (
49
+ <MinimalTemplate className={baseClass}>
50
+ <div className={`${baseClass}__brand`}>
51
+ <Logo
52
+ i18n={i18n}
53
+ locale={locale}
54
+ params={params}
55
+ payload={payload}
56
+ permissions={permissions}
57
+ searchParams={searchParams}
58
+ server={server}
59
+ user={user}
60
+ />
61
+ </div>
62
+ {/* Not translated yet, so screen readers in other admin languages read it as English */}
63
+ <div lang="en">
64
+ {isConsentValid ? (
65
+ <>
66
+ <FormHeader
67
+ description={`It will be able to use this app's MCP tools as ${account}, and you will return to ${returnHost}.`}
68
+ heading={`Allow ${client.name} to use your account?`}
69
+ />
70
+ <form
71
+ action={formatAdminURL({
72
+ apiRoute: payload.config.routes.api,
73
+ path: '/mcp/oauth/authorize',
74
+ })}
75
+ method="post"
76
+ >
77
+ <input name="consent" type="hidden" value={sealedConsent!} />
78
+ <AllowButtons />
79
+ </form>
80
+ </>
81
+ ) : (
82
+ <FormHeader
83
+ description="Start the sign-in again from your MCP client."
84
+ heading={errorTitles[error]}
85
+ />
86
+ )}
87
+ </div>
88
+ </MinimalTemplate>
89
+ )
90
+ }
91
+
92
+ const getSearchParam = (value: string | string[] | undefined): null | string =>
93
+ typeof value === 'string' ? value : null