@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.
- package/dist/endpoint/access.d.ts +5 -0
- package/dist/endpoint/access.d.ts.map +1 -1
- package/dist/endpoint/access.js +42 -5
- package/dist/endpoint/access.js.map +1 -1
- package/dist/endpoint/index.d.ts.map +1 -1
- package/dist/endpoint/index.js +25 -0
- package/dist/endpoint/index.js.map +1 -1
- package/dist/endpoint/oauth.d.ts +37 -0
- package/dist/endpoint/oauth.d.ts.map +1 -0
- package/dist/endpoint/oauth.js +105 -0
- package/dist/endpoint/oauth.js.map +1 -0
- package/dist/endpoint/oauthLoginToken.d.ts +27 -0
- package/dist/endpoint/oauthLoginToken.d.ts.map +1 -0
- package/dist/endpoint/oauthLoginToken.js +86 -0
- package/dist/endpoint/oauthLoginToken.js.map +1 -0
- package/dist/endpoint/oauthServer.d.ts +28 -0
- package/dist/endpoint/oauthServer.d.ts.map +1 -0
- package/dist/endpoint/oauthServer.js +432 -0
- package/dist/endpoint/oauthServer.js.map +1 -0
- package/dist/exports/client.d.ts +1 -1
- package/dist/exports/client.d.ts.map +1 -1
- package/dist/exports/client.js +1 -1
- package/dist/exports/client.js.map +1 -1
- package/dist/exports/rsc.d.ts +2 -0
- package/dist/exports/rsc.d.ts.map +1 -0
- package/dist/exports/rsc.js +3 -0
- package/dist/exports/rsc.js.map +1 -0
- package/dist/index.d.ts +10 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +34 -10
- package/dist/index.js.map +1 -1
- package/dist/mcp/builtin/collections/deleteTool.d.ts.map +1 -1
- package/dist/mcp/builtin/collections/deleteTool.js +3 -1
- package/dist/mcp/builtin/collections/deleteTool.js.map +1 -1
- package/dist/mcp/sanitizeMCPConfig.d.ts.map +1 -1
- package/dist/mcp/sanitizeMCPConfig.js +3 -0
- package/dist/mcp/sanitizeMCPConfig.js.map +1 -1
- package/dist/types.d.ts +100 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/dist/utils/seal.d.ts +17 -0
- package/dist/utils/seal.d.ts.map +1 -0
- package/dist/utils/seal.js +24 -0
- package/dist/utils/seal.js.map +1 -0
- package/dist/views/Authorize/AllowButtons/index.d.ts +18 -0
- package/dist/views/Authorize/AllowButtons/index.d.ts.map +1 -0
- package/dist/views/Authorize/AllowButtons/index.js +88 -0
- package/dist/views/Authorize/AllowButtons/index.js.map +1 -0
- package/dist/views/Authorize/index.css +19 -0
- package/dist/views/Authorize/index.d.ts +9 -0
- package/dist/views/Authorize/index.d.ts.map +1 -0
- package/dist/views/Authorize/index.js +86 -0
- package/dist/views/Authorize/index.js.map +1 -0
- package/package.json +10 -3
- package/src/endpoint/access.ts +45 -3
- package/src/endpoint/index.ts +17 -1
- package/src/endpoint/oauth.ts +108 -0
- package/src/endpoint/oauthLoginToken.ts +100 -0
- package/src/endpoint/oauthServer.ts +461 -0
- package/src/exports/client.ts +1 -1
- package/src/exports/rsc.ts +1 -0
- package/src/index.ts +52 -8
- package/src/mcp/builtin/collections/deleteTool.ts +3 -1
- package/src/mcp/sanitizeMCPConfig.ts +1 -0
- package/src/types.ts +98 -0
- package/src/utils/seal.ts +46 -0
- package/src/views/Authorize/AllowButtons/index.tsx +97 -0
- package/src/views/Authorize/index.css +19 -0
- 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
|