@payloadcms/plugin-mcp 4.0.0-internal.9496957 → 4.0.0-internal.970009e

package/src/types.ts

@@ -1,8 +1,9 @@
 import type {
   CallToolResult,
   ContentBlock,
+  Implementation,
   JsonSchemaType,
-  McpServer,
+  McpServerOptions,
   ResourceTemplate,
   ServerContext,
   StandardSchemaWithJSON,
@@ -279,9 +280,24 @@ export type MCPPluginConfig = {
     afterToolCall?: MCPAfterToolCallHook[]
   }
   mcp?: {
+    /**
+     * Largest HTTP request body, in bytes, that the MCP endpoint accepts. Larger requests
+     * are answered with `413`. Base64 file uploads count toward this limit.
+     *
+     * @default 4194304 (4 MiB, the MCP SDK default)
+     */
+    maxRequestBodySize?: number
     serverOptions?: MCPServerOptions
     verboseLogs?: boolean
   }
+  /**
+   * How MCP clients sign in. MCP requests without an authenticated user get a `401` that points
+   * to the protected resource metadata (RFC 9728). Set to `false` to only accept API keys and
+   * anonymous requests.
+   *
+   * @default { type: 'builtin' }
+   */
+  oauth?: false | MCPOAuthConfig
   /**
    * Replace the default MCP authorization resolver.
    *
@@ -299,13 +315,87 @@ export type MCPPluginConfig = {
   tools?: MCPTopLevelToolsMap
 }
 
+export type MCPOAuthConfig = MCPBuiltinOAuthConfig | MCPExternalOAuthConfig
+
+/**
+ * This Payload app is the authorization server. Users sign in to the admin panel and allow the
+ * MCP client, which then gets an access token for them.
+ */
+export type MCPBuiltinOAuthConfig = {
+  /**
+   * Creates the tokens the MCP client gets when the user clicks Allow. `req` is the user's own
+   * browser request, so `req.user` is the user who allowed it. Pass `authenticate` too if
+   * Payload's auth strategies don't accept the access token.
+   *
+   * @default a Payload login token for that user, with a refresh token when the collection uses sessions
+   */
+  issueToken?: (args: { req: PayloadRequest }) => MaybePromise<MCPOAuthTokens>
+  /**
+   * Trades a refresh token from `issueToken`, or from an earlier refresh, for new tokens. Return
+   * `null` when it's no longer valid, and the client sends the user through sign-in again. `req`
+   * is the MCP client's request, without a user. Only used together with `issueToken`.
+   *
+   * OAuth requires noticing copied refresh tokens: return a new refresh token every time, and
+   * revoke the tokens when an already used refresh token comes back.
+   */
+  refreshToken?: (args: {
+    refreshToken: string
+    req: PayloadRequest
+  }) => MaybePromise<MCPOAuthTokens | null>
+  type: 'builtin'
+} & MCPOAuthSharedConfig
+
+export type MCPOAuthTokens = {
+  accessToken: string
+  /** Seconds until the access token expires. */
+  expiresIn?: number
+  /** Lets the client get new tokens without the user, through `refreshToken`. */
+  refreshToken?: string
+}
+
+/** Another service, e.g. your identity provider, is the authorization server. */
+export type MCPExternalOAuthConfig = {
+  /**
+   * The authorization servers that issue access tokens for MCP clients. Clients require each one
+   * to exactly match the `issuer` in that server's metadata, so pass a function when the exact
+   * value is only known at runtime, e.g. from the server's OpenID configuration or per host.
+   */
+  authorizationServers: ((args: { req: PayloadRequest }) => MaybePromise<string[]>) | string[]
+  /**
+   * Scopes MCP clients should request, e.g. `['openid', 'email', 'profile']`. Without them,
+   * clients request none, which some authorization servers reject or answer with a token that
+   * doesn't identify the user.
+   */
+  scopes?: string[]
+  type: 'external'
+} & MCPOAuthSharedConfig
+
+type MCPOAuthSharedConfig = {
+  /**
+   * Called on MCP requests with a bearer token that Payload's auth strategies didn't accept.
+   * Return the Payload user, including its `collection`, or `null` to answer with the OAuth challenge.
+   */
+  authenticate?: (args: {
+    req: PayloadRequest
+    token: string
+  }) => MaybePromise<PayloadRequest['user']>
+  /**
+   * The URL clients call to reach the MCP endpoint.
+   *
+   * @default the absolute URL of `/api/mcp`, based on `serverURL` or the request URL
+   */
+  resource?: string
+}
+
 export type SanitizedMCPPluginConfig = {
   items: MCPItem[]
+  /** `undefined` when OAuth is turned off. */
+  oauth?: MCPOAuthConfig
 } & Pick<MCPPluginConfig, 'disabled' | 'hooks' | 'mcp' | 'overrideGetAuthorizedMCP'>
 
 export type MCPServerOptions = {
-  options?: ConstructorParameters<typeof McpServer>[1]
-  serverInfo?: Partial<ConstructorParameters<typeof McpServer>[0]>
+  options?: McpServerOptions
+  serverInfo?: Partial<Implementation>
 }
 
 /**

package/src/utils/toStandardSchema.ts

@@ -5,5 +5,5 @@ import type { ToolInputSchema } from '../types.js'
 /** Normalize a tool/prompt input to a Standard Schema. Raw JSON Schema gets wrapped; Standard Schema instances pass through. */
 export const toStandardSchema = (schema: ToolInputSchema): StandardSchemaWithJSON =>
   typeof schema === 'object' && schema !== null && '~standard' in schema
-    ? (schema as StandardSchemaWithJSON)
+    ? schema
     : fromJsonSchema(schema)

package/dist/mcp/builtin/collections/fileInput.spec.js

@@ -1,86 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { fileInputSchema, resolveFile } from './fileInput.js';
-describe('MCP file input', ()=>{
-    it('should reject malformed MIME types', ()=>{
-        const result = fileInputSchema.safeParse({
-            data: 'aGVsbG8=',
-            mimeType: 'text/plain\r\nx-test: value',
-            name: 'hello.txt',
-            source: 'base64'
-        });
-        expect(result.success).toBe(false);
-    });
-    it('should accept a prepared upload', ()=>{
-        const result = fileInputSchema.safeParse({
-            file: {
-                filename: 'image.png',
-                mimeType: 'image/png',
-                size: 123,
-                uploadReference: {
-                    uploadId: 'upload-id'
-                }
-            },
-            source: 'uploadReference'
-        });
-        expect(result.success).toBe(true);
-    });
-    it('should reject oversized base64 files', async ()=>{
-        const req = createRequest({
-            maxFileSize: 4
-        });
-        await expect(resolveFile({
-            slug: 'media',
-            input: {
-                data: Buffer.from('hello').toString('base64'),
-                mimeType: 'text/plain',
-                name: 'hello.txt',
-                source: 'base64'
-            },
-            req
-        })).rejects.toThrow('File exceeds the 4 byte upload limit.');
-    });
-    it('should reject URLs outside the collection allowlist', async ()=>{
-        const req = createRequest({
-            allowList: [
-                {
-                    hostname: 'assets.example.com',
-                    protocol: 'https'
-                }
-            ]
-        });
-        await expect(resolveFile({
-            slug: 'media',
-            input: {
-                source: 'externalURL',
-                url: 'https://example.com/image.png'
-            },
-            req
-        })).rejects.toThrow('The provided file URL is not allowed.');
-    });
-});
-function createRequest({ allowList, maxFileSize }) {
-    return {
-        payload: {
-            collections: {
-                media: {
-                    config: {
-                        upload: allowList ? {
-                            pasteURL: {
-                                allowList
-                            }
-                        } : {}
-                    }
-                }
-            },
-            config: {
-                upload: {
-                    limits: {
-                        fileSize: maxFileSize
-                    }
-                }
-            }
-        }
-    };
-}
-
-//# sourceMappingURL=fileInput.spec.js.map

package/dist/mcp/builtin/collections/fileInput.spec.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../../../src/mcp/builtin/collections/fileInput.spec.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\n\nimport { describe, expect, it } from 'vitest'\n\nimport { fileInputSchema, resolveFile } from './fileInput.js'\n\ndescribe('MCP file input', () => {\n  it('should reject malformed MIME types', () => {\n    const result = fileInputSchema.safeParse({\n      data: 'aGVsbG8=',\n      mimeType: 'text/plain\\r\\nx-test: value',\n      name: 'hello.txt',\n      source: 'base64',\n    })\n\n    expect(result.success).toBe(false)\n  })\n\n  it('should accept a prepared upload', () => {\n    const result = fileInputSchema.safeParse({\n      file: {\n        filename: 'image.png',\n        mimeType: 'image/png',\n        size: 123,\n        uploadReference: { uploadId: 'upload-id' },\n      },\n      source: 'uploadReference',\n    })\n\n    expect(result.success).toBe(true)\n  })\n\n  it('should reject oversized base64 files', async () => {\n    const req = createRequest({ maxFileSize: 4 })\n\n    await expect(\n      resolveFile({\n        slug: 'media',\n        input: {\n          data: Buffer.from('hello').toString('base64'),\n          mimeType: 'text/plain',\n          name: 'hello.txt',\n          source: 'base64',\n        },\n        req,\n      }),\n    ).rejects.toThrow('File exceeds the 4 byte upload limit.')\n  })\n\n  it('should reject URLs outside the collection allowlist', async () => {\n    const req = createRequest({\n      allowList: [{ hostname: 'assets.example.com', protocol: 'https' }],\n    })\n\n    await expect(\n      resolveFile({\n        slug: 'media',\n        input: {\n          source: 'externalURL',\n          url: 'https://example.com/image.png',\n        },\n        req,\n      }),\n    ).rejects.toThrow('The provided file URL is not allowed.')\n  })\n})\n\nfunction createRequest({\n  allowList,\n  maxFileSize,\n}: {\n  allowList?: Array<{ hostname: string; protocol: 'http' | 'https' }>\n  maxFileSize?: number\n}): PayloadRequest {\n  return {\n    payload: {\n      collections: {\n        media: {\n          config: {\n            upload: allowList ? { pasteURL: { allowList } } : {},\n          },\n        },\n      },\n      config: {\n        upload: {\n          limits: {\n            fileSize: maxFileSize,\n          },\n        },\n      },\n    },\n  } as unknown as PayloadRequest\n}\n"],"names":["describe","expect","it","fileInputSchema","resolveFile","result","safeParse","data","mimeType","name","source","success","toBe","file","filename","size","uploadReference","uploadId","req","createRequest","maxFileSize","slug","input","Buffer","from","toString","rejects","toThrow","allowList","hostname","protocol","url","payload","collections","media","config","upload","pasteURL","limits","fileSize"],"mappings":"AAEA,SAASA,QAAQ,EAAEC,MAAM,EAAEC,EAAE,QAAQ,SAAQ;AAE7C,SAASC,eAAe,EAAEC,WAAW,QAAQ,iBAAgB;AAE7DJ,SAAS,kBAAkB;IACzBE,GAAG,sCAAsC;QACvC,MAAMG,SAASF,gBAAgBG,SAAS,CAAC;YACvCC,MAAM;YACNC,UAAU;YACVC,MAAM;YACNC,QAAQ;QACV;QAEAT,OAAOI,OAAOM,OAAO,EAAEC,IAAI,CAAC;IAC9B;IAEAV,GAAG,mCAAmC;QACpC,MAAMG,SAASF,gBAAgBG,SAAS,CAAC;YACvCO,MAAM;gBACJC,UAAU;gBACVN,UAAU;gBACVO,MAAM;gBACNC,iBAAiB;oBAAEC,UAAU;gBAAY;YAC3C;YACAP,QAAQ;QACV;QAEAT,OAAOI,OAAOM,OAAO,EAAEC,IAAI,CAAC;IAC9B;IAEAV,GAAG,wCAAwC;QACzC,MAAMgB,MAAMC,cAAc;YAAEC,aAAa;QAAE;QAE3C,MAAMnB,OACJG,YAAY;YACViB,MAAM;YACNC,OAAO;gBACLf,MAAMgB,OAAOC,IAAI,CAAC,SAASC,QAAQ,CAAC;gBACpCjB,UAAU;gBACVC,MAAM;gBACNC,QAAQ;YACV;YACAQ;QACF,IACAQ,OAAO,CAACC,OAAO,CAAC;IACpB;IAEAzB,GAAG,uDAAuD;QACxD,MAAMgB,MAAMC,cAAc;YACxBS,WAAW;gBAAC;oBAAEC,UAAU;oBAAsBC,UAAU;gBAAQ;aAAE;QACpE;QAEA,MAAM7B,OACJG,YAAY;YACViB,MAAM;YACNC,OAAO;gBACLZ,QAAQ;gBACRqB,KAAK;YACP;YACAb;QACF,IACAQ,OAAO,CAACC,OAAO,CAAC;IACpB;AACF;AAEA,SAASR,cAAc,EACrBS,SAAS,EACTR,WAAW,EAIZ;IACC,OAAO;QACLY,SAAS;YACPC,aAAa;gBACXC,OAAO;oBACLC,QAAQ;wBACNC,QAAQR,YAAY;4BAAES,UAAU;gCAAET;4BAAU;wBAAE,IAAI,CAAC;oBACrD;gBACF;YACF;YACAO,QAAQ;gBACNC,QAAQ;oBACNE,QAAQ;wBACNC,UAAUnB;oBACZ;gBACF;YACF;QACF;IACF;AACF"}