@payloadcms/plugin-mcp 4.0.0-internal.38b7f1d → 4.0.0-internal.40de3ec

package/src/components/AccessField/index.client.tsx

@@ -0,0 +1,344 @@
+'use client'
+
+import type { JSONFieldClientProps } from 'payload'
+
+import { CheckboxInput, Collapsible, useField } from '@payloadcms/ui'
+import React from 'react'
+
+import type { ClientMCPPluginConfig, MCPAPIKeysDocAccessTree } from '../../types.js'
+
+import './index.css'
+
+const baseClass = 'mcp-access-field'
+
+type ClientItem = ClientMCPPluginConfig['items'][number]
+type ScopeKey = 'collections' | 'globals'
+type FlatKey = 'prompts' | 'resources' | 'tools'
+
+type Props = {
+  pluginConfig: ClientMCPPluginConfig
+} & JSONFieldClientProps
+
+/** Drop a key from an object and return a new object — or `undefined` if it'd be empty. */
+const without = <T extends Record<string, unknown>>(
+  obj: T | undefined,
+  key: string,
+): T | undefined => {
+  if (!obj || !(key in obj)) {
+    return obj
+  }
+  const { [key]: _omitted, ...rest } = obj
+  return Object.keys(rest).length === 0 ? undefined : (rest as T)
+}
+
+const setKey = <T extends Record<string, unknown>>(
+  obj: T | undefined,
+  key: string,
+  value: unknown,
+): T => ({ ...(obj ?? {}), [key]: value }) as T
+
+export const AccessField: React.FC<Props> = ({ path, pluginConfig }) => {
+  const { setValue, value } = useField<MCPAPIKeysDocAccessTree>({ path })
+  const access = value ?? {}
+
+  // Bucket items for rendering. (Bucketing is cheap and runs once per render;
+  // memoizing would mean managing inputs/refs for marginal benefit.)
+  const collectionsBySlug: Record<string, ClientItem[]> = {}
+  const globalsBySlug: Record<string, ClientItem[]> = {}
+  const tools: ClientItem[] = []
+  const prompts: ClientItem[] = []
+  const resources: ClientItem[] = []
+  for (const item of pluginConfig.items) {
+    switch (item.type) {
+      case 'collectionTool':
+        ;(collectionsBySlug[item.collectionSlug!] ??= []).push(item)
+        break
+      case 'globalTool':
+        ;(globalsBySlug[item.globalSlug!] ??= []).push(item)
+        break
+      case 'prompt':
+        prompts.push(item)
+        break
+      case 'resource':
+        resources.push(item)
+        break
+      case 'tool':
+        tools.push(item)
+        break
+    }
+  }
+
+  const isScopedAllowed = (scope: ScopeKey, slug: string, key: string): boolean =>
+    access[scope]?.[slug]?.[key] !== false
+
+  const isFlatAllowed = (scope: FlatKey, key: string): boolean => access[scope]?.[key] !== false
+
+  const toggleScoped = (scope: ScopeKey, slug: string, key: string, allow: boolean) => {
+    if (allow) {
+      const slugBucket = without(access[scope]?.[slug], key)
+      const scopeBucket = slugBucket
+        ? setKey(access[scope], slug, slugBucket)
+        : without(access[scope], slug)
+      setValue(scopeBucket ? setKey(access, scope, scopeBucket) : (without(access, scope) ?? {}))
+    } else {
+      setValue(
+        setKey(
+          access,
+          scope,
+          setKey(access[scope], slug, setKey(access[scope]?.[slug], key, false)),
+        ),
+      )
+    }
+  }
+
+  const toggleFlat = (scope: FlatKey, key: string, allow: boolean) => {
+    if (allow) {
+      const bucket = without(access[scope], key)
+      setValue(bucket ? setKey(access, scope, bucket) : (without(access, scope) ?? {}))
+    } else {
+      setValue(setKey(access, scope, setKey(access[scope], key, false)))
+    }
+  }
+
+  const setAllScoped = (scope: ScopeKey, slug: string, leaves: ClientItem[], allow: boolean) => {
+    if (allow) {
+      const scopeBucket = without(access[scope], slug)
+      setValue(scopeBucket ? setKey(access, scope, scopeBucket) : (without(access, scope) ?? {}))
+    } else {
+      const slugBucket = leaves.reduce<Record<string, boolean>>(
+        (acc, leaf) => ({ ...acc, [leaf.key]: false }),
+        {},
+      )
+      setValue(setKey(access, scope, setKey(access[scope], slug, slugBucket)))
+    }
+  }
+
+  const setAllFlat = (scope: FlatKey, leaves: ClientItem[], allow: boolean) => {
+    if (allow) {
+      setValue(without(access, scope) ?? {})
+    } else {
+      const bucket = leaves.reduce<Record<string, boolean>>(
+        (acc, leaf) => ({ ...acc, [leaf.key]: false }),
+        {},
+      )
+      setValue(setKey(access, scope, bucket))
+    }
+  }
+
+  const collectionSlugs = Object.keys(collectionsBySlug)
+  const globalSlugs = Object.keys(globalsBySlug)
+
+  return (
+    <div className={baseClass}>
+      {collectionSlugs.length > 0 && (
+        <section className={`${baseClass}__section`}>
+          <header className={`${baseClass}__section-header`}>
+            {/* TODO: needs i18n once design is finalized */}
+            <h4>Collection-level permissions</h4>
+            {/* TODO: needs i18n once design is finalized */}
+            <p>Allow MCP clients to perform the following actions within these collections:</p>
+          </header>
+          {collectionSlugs.map((slug) => {
+            const leaves = collectionsBySlug[slug]!
+            return (
+              <Collapsible
+                actions={
+                  <GroupActions
+                    onSetAll={(allow) => setAllScoped('collections', slug, leaves, allow)}
+                  />
+                }
+                className={`${baseClass}__group`}
+                header={<span className={`${baseClass}__group-label`}>{titleCase(slug)}</span>}
+                initCollapsed
+                key={`collection-${slug}`}
+              >
+                <ul className={`${baseClass}__list`}>
+                  {leaves.map((leaf) => (
+                    <li key={leaf.key}>
+                      <CheckboxInput
+                        checked={isScopedAllowed('collections', slug, leaf.key)}
+                        id={`${path}.collections.${slug}.${leaf.key}`}
+                        label={leaf.label}
+                        onToggle={(e) =>
+                          toggleScoped('collections', slug, leaf.key, e.target.checked)
+                        }
+                        tooltip={leaf.description}
+                      />
+                    </li>
+                  ))}
+                </ul>
+              </Collapsible>
+            )
+          })}
+        </section>
+      )}
+
+      {globalSlugs.length > 0 && (
+        <section className={`${baseClass}__section`}>
+          <header className={`${baseClass}__section-header`}>
+            {/* TODO: needs i18n once design is finalized */}
+            <h4>Global-level permissions</h4>
+            {/* TODO: needs i18n once design is finalized */}
+            <p>Allow MCP clients to perform the following actions on these globals:</p>
+          </header>
+          {globalSlugs.map((slug) => {
+            const leaves = globalsBySlug[slug]!
+            return (
+              <Collapsible
+                actions={
+                  <GroupActions
+                    onSetAll={(allow) => setAllScoped('globals', slug, leaves, allow)}
+                  />
+                }
+                className={`${baseClass}__group`}
+                header={<span className={`${baseClass}__group-label`}>{titleCase(slug)}</span>}
+                initCollapsed
+                key={`global-${slug}`}
+              >
+                <ul className={`${baseClass}__list`}>
+                  {leaves.map((leaf) => (
+                    <li key={leaf.key}>
+                      <CheckboxInput
+                        checked={isScopedAllowed('globals', slug, leaf.key)}
+                        id={`${path}.globals.${slug}.${leaf.key}`}
+                        label={leaf.label}
+                        onToggle={(e) => toggleScoped('globals', slug, leaf.key, e.target.checked)}
+                        tooltip={leaf.description}
+                      />
+                    </li>
+                  ))}
+                </ul>
+              </Collapsible>
+            )
+          })}
+        </section>
+      )}
+
+      {(tools.length > 0 || prompts.length > 0 || resources.length > 0) && (
+        <section className={`${baseClass}__section`}>
+          <header className={`${baseClass}__section-header`}>
+            {/* TODO: needs i18n once design is finalized */}
+            <h4>Project-level permissions</h4>
+            {/* TODO: needs i18n once design is finalized */}
+            <p>Cross-cutting tools, prompts, and resources not scoped to a single collection.</p>
+          </header>
+          {tools.length > 0 && (
+            <Collapsible
+              actions={<GroupActions onSetAll={(allow) => setAllFlat('tools', tools, allow)} />}
+              className={`${baseClass}__group`}
+              header={
+                /* TODO: needs i18n once design is finalized */
+                <span className={`${baseClass}__group-label`}>Tools</span>
+              }
+              initCollapsed
+            >
+              <ul className={`${baseClass}__list`}>
+                {tools.map((leaf) => (
+                  <li key={leaf.key}>
+                    <CheckboxInput
+                      checked={isFlatAllowed('tools', leaf.key)}
+                      id={`${path}.tools.${leaf.key}`}
+                      label={leaf.label}
+                      onToggle={(e) => toggleFlat('tools', leaf.key, e.target.checked)}
+                      tooltip={leaf.description}
+                    />
+                  </li>
+                ))}
+              </ul>
+            </Collapsible>
+          )}
+          {prompts.length > 0 && (
+            <Collapsible
+              actions={<GroupActions onSetAll={(allow) => setAllFlat('prompts', prompts, allow)} />}
+              className={`${baseClass}__group`}
+              header={
+                /* TODO: needs i18n once design is finalized */
+                <span className={`${baseClass}__group-label`}>Prompts</span>
+              }
+              initCollapsed
+            >
+              <ul className={`${baseClass}__list`}>
+                {prompts.map((leaf) => (
+                  <li key={leaf.key}>
+                    <CheckboxInput
+                      checked={isFlatAllowed('prompts', leaf.key)}
+                      id={`${path}.prompts.${leaf.key}`}
+                      label={leaf.label}
+                      onToggle={(e) => toggleFlat('prompts', leaf.key, e.target.checked)}
+                      tooltip={leaf.description}
+                    />
+                  </li>
+                ))}
+              </ul>
+            </Collapsible>
+          )}
+          {resources.length > 0 && (
+            <Collapsible
+              actions={
+                <GroupActions onSetAll={(allow) => setAllFlat('resources', resources, allow)} />
+              }
+              className={`${baseClass}__group`}
+              header={
+                /* TODO: needs i18n once design is finalized */
+                <span className={`${baseClass}__group-label`}>Resources</span>
+              }
+              initCollapsed
+            >
+              <ul className={`${baseClass}__list`}>
+                {resources.map((leaf) => (
+                  <li key={leaf.key}>
+                    <CheckboxInput
+                      checked={isFlatAllowed('resources', leaf.key)}
+                      id={`${path}.resources.${leaf.key}`}
+                      label={leaf.label}
+                      onToggle={(e) => toggleFlat('resources', leaf.key, e.target.checked)}
+                      tooltip={leaf.description}
+                    />
+                  </li>
+                ))}
+              </ul>
+            </Collapsible>
+          )}
+        </section>
+      )}
+    </div>
+  )
+}
+
+const GroupActions: React.FC<{ onSetAll: (allow: boolean) => void }> = ({ onSetAll }) => (
+  // TODO: button labels + aria-labels need i18n once design is finalized
+  <div className={`${baseClass}__group-actions`}>
+    <button
+      aria-label="Select all"
+      className={`${baseClass}__action`}
+      onClick={(e) => {
+        e.stopPropagation()
+        onSetAll(true)
+      }}
+      title="Select all"
+      type="button"
+    >
+      all
+    </button>
+    <span aria-hidden className={`${baseClass}__action-sep`}>
+      /
+    </span>
+    <button
+      aria-label="Clear all"
+      className={`${baseClass}__action`}
+      onClick={(e) => {
+        e.stopPropagation()
+        onSetAll(false)
+      }}
+      title="Clear all"
+      type="button"
+    >
+      none
+    </button>
+  </div>
+)
+
+const titleCase = (slug: string): string =>
+  slug.replace(/(^|[-_])(.)/g, (_, sep: string, ch: string) =>
+    sep ? ` ${ch.toUpperCase()}` : ch.toUpperCase(),
+  )

package/src/components/AccessField/index.css

@@ -0,0 +1,93 @@
+@layer payload-default {
+  .mcp-access-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--base);
+  }
+
+  .mcp-access-field__section {
+    display: flex;
+    flex-direction: column;
+    gap: calc(var(--base) / 2);
+    padding-bottom: var(--base);
+    /* Full-bleed separator: extend past the sidebar's horizontal gutter so the
+       border-block-end spans the entire sidebar width. */
+    margin-inline-start: calc(-1 * var(--sidebar-gutter-h-left, var(--gutter-h)));
+    margin-inline-end: calc(-1 * var(--sidebar-gutter-h-right, var(--gutter-h)));
+    padding-inline-start: var(--sidebar-gutter-h-left, var(--gutter-h));
+    padding-inline-end: var(--sidebar-gutter-h-right, var(--gutter-h));
+    border-block-end: 1px solid var(--theme-elevation-100);
+  }
+
+  .mcp-access-field__section:last-child {
+    border-block-end: none;
+  }
+
+  .mcp-access-field__section-header {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .mcp-access-field__section-header h4 {
+    margin: 0;
+    color: var(--color-text);
+    font-family: var(--text-heading-small-font-family);
+    font-size: var(--text-heading-small-font-size);
+    font-weight: var(--text-heading-small-font-weight);
+    line-height: var(--text-heading-small-line-height);
+    letter-spacing: var(--text-heading-small-letter-spacing);
+  }
+
+  .mcp-access-field__section-header p {
+    margin: 0;
+    color: var(--color-text-secondary);
+    font-family: var(--text-body-medium-font-family);
+    font-size: var(--text-body-medium-font-size);
+    font-weight: var(--text-body-medium-font-weight);
+    line-height: var(--text-body-medium-line-height);
+    letter-spacing: var(--text-body-medium-letter-spacing);
+  }
+
+  .mcp-access-field__group {
+    margin-block-end: calc(var(--base) / 2);
+  }
+
+  .mcp-access-field__group-label {
+    font-weight: 600;
+  }
+
+  .mcp-access-field__group-actions {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--base) / 6);
+  }
+
+  .mcp-access-field__action {
+    appearance: none;
+    background: none;
+    border: none;
+    color: var(--theme-elevation-500);
+    cursor: pointer;
+    font-size: 0.75rem;
+    padding: 0;
+  }
+
+  .mcp-access-field__action:hover {
+    color: var(--theme-text);
+    text-decoration: underline;
+  }
+
+  .mcp-access-field__action-sep {
+    color: var(--theme-elevation-300);
+    font-size: 0.75rem;
+  }
+
+  .mcp-access-field__list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: calc(var(--base) / 3);
+  }
+}

package/src/defineTool.ts

@@ -0,0 +1,44 @@
+import type { CollectionTool, GlobalTool, Prompt, Tool, ToolInputSchema } from './types.js'
+
+/**
+ * Two-stage builder: pass the schema/metadata first, then chain `.handler(fn)`. Splitting the
+ * call lets TypeScript resolve `TSchema` from `input` (call 1) before contextually typing the
+ * handler (call 2). A single-call API hit a TS limitation where property order in the literal
+ * decided whether `TSchema` was inferred or pinned to its default.
+ *
+ *     defineCollectionTool({ description, input })
+ *       .handler(({ input }) => …)   // ← input is fully typed here regardless of order
+ *
+ * Config and handler signatures are derived from `Tool` / `CollectionTool` / `GlobalTool` /
+ * `Prompt` via `Omit` + indexed access so there's no duplication with `types.ts`.
+ */
+
+export const defineTool = <
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+>(
+  args: Omit<Tool<TSchema>, 'handler'>,
+): { handler: (fn: Tool<TSchema>['handler']) => Tool } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as Tool,
+})
+
+export const defineCollectionTool = <
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+>(
+  args: Omit<CollectionTool<TSchema>, 'handler'>,
+): { handler: (fn: CollectionTool<TSchema>['handler']) => CollectionTool } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as CollectionTool,
+})
+
+export const defineGlobalTool = <
+  TSchema extends ToolInputSchema | undefined = ToolInputSchema | undefined,
+>(
+  args: Omit<GlobalTool<TSchema>, 'handler'>,
+): { handler: (fn: GlobalTool<TSchema>['handler']) => GlobalTool } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as GlobalTool,
+})
+
+export const definePrompt = <TSchema extends ToolInputSchema = ToolInputSchema>(
+  args: Omit<Prompt<TSchema>, 'handler'>,
+): { handler: (fn: Prompt<TSchema>['handler']) => Prompt } => ({
+  handler: (fn) => ({ ...args, handler: fn }) as unknown as Prompt,
+})

package/src/endpoint/access.ts

@@ -0,0 +1,132 @@
+import type { DefaultDocumentIDType, PayloadRequest, TypedUser } from 'payload'
+
+import crypto from 'crypto'
+import { UnauthorizedError } from 'payload'
+
+import type { AuthorizedMCP, MCPAPIKeysDoc } from '../types.js'
+
+import { getLogger } from '../utils/getLogger.js'
+import { getPluginConfig } from '../utils/getPluginConfig.js'
+
+/**
+ * Resolves the API key (or dev-mode session) and returns the items the caller
+ * may use. Denied items are dropped from the array.
+ */
+export const getAuthorizedMCP: (args: { req: PayloadRequest }) => Promise<AuthorizedMCP> = async ({
+  req,
+}) => {
+  const logger = getLogger({ payload: req.payload })
+  const pluginConfig = getPluginConfig({ config: req.payload.config })
+
+  const authHeader = req.headers.get('Authorization')
+  const hasBearerToken = authHeader?.startsWith('Bearer ')
+
+  const buildAuthorized = (apiKeyDoc: MCPAPIKeysDoc): AuthorizedMCP => ({
+    items: pluginConfig.items.filter((item) => {
+      switch (item.type) {
+        case 'collectionTool':
+          return apiKeyDoc.access.collections?.[item.collectionSlug]?.[item.key] !== false
+        case 'globalTool':
+          return apiKeyDoc.access.globals?.[item.globalSlug]?.[item.key] !== false
+        case 'prompt':
+          return apiKeyDoc.access.prompts?.[item.key] !== false
+        case 'resource':
+          return apiKeyDoc.access.resources?.[item.key] !== false
+        case 'tool':
+          return apiKeyDoc.access.tools?.[item.key] !== false
+      }
+    }),
+    overrideAccess:
+      typeof apiKeyDoc.overrideAccess === 'boolean' ? apiKeyDoc.overrideAccess : false,
+    user: apiKeyDoc.user,
+  })
+
+  if (pluginConfig.overrideAuth) {
+    return await pluginConfig.overrideAuth({
+      getAPIKeyDoc: (overrideApiKey) => getAPIKeyDoc({ logger, overrideApiKey, pluginConfig, req }),
+      getAuthorizedMCP: ({ apiKeyDoc }) => buildAuthorized(apiKeyDoc),
+      pluginConfig,
+      req,
+    })
+  }
+
+  if (process.env.NODE_ENV === 'development' && !hasBearerToken) {
+    logger.info('Dev mode: skipping API key check, using session user')
+    return buildAuthorized({
+      id: -1,
+      access: {},
+      overrideAccess: true,
+      user: req.user ?? null,
+    })
+  }
+
+  return buildAuthorized(await getAPIKeyDoc({ logger, pluginConfig, req }))
+}
+
+const getAPIKeyDoc = async ({
+  logger,
+  overrideApiKey,
+  pluginConfig,
+  req,
+}: {
+  logger: ReturnType<typeof getLogger>
+  overrideApiKey?: string
+  pluginConfig: ReturnType<typeof getPluginConfig>
+  req: PayloadRequest
+}): Promise<MCPAPIKeysDoc> => {
+  const authHeader = req.headers.get('Authorization')
+  const hasBearerToken = authHeader?.startsWith('Bearer ')
+
+  const apiKey =
+    overrideApiKey ?? (hasBearerToken ? authHeader?.replace('Bearer ', '').trim() || null : null)
+
+  if (!apiKey) {
+    throw new UnauthorizedError()
+  }
+
+  const sha256APIKeyIndex = crypto
+    .createHmac('sha256', req.payload.secret)
+    .update(apiKey)
+    .digest('hex')
+
+  const doc = await req.payload.db.findOne<MCPAPIKeysDoc>({
+    collection: 'payload-mcp-api-keys',
+    req,
+    where: {
+      apiKeyIndex: { equals: sha256APIKeyIndex },
+    },
+  })
+
+  if (!doc || !doc.user) {
+    throw new UnauthorizedError()
+  }
+
+  logger.info('API Key is valid')
+
+  const userRef = doc.user
+  const userID =
+    typeof userRef === 'object' && userRef !== null && 'id' in userRef
+      ? userRef.id
+      : (userRef as unknown as DefaultDocumentIDType)
+
+  const user = (await req.payload.findByID({
+    id: userID,
+    collection: pluginConfig.userCollection,
+    depth: 0,
+    disableErrors: true,
+    req,
+  })) as null | TypedUser
+
+  if (!user) {
+    throw new UnauthorizedError()
+  }
+
+  return {
+    ...doc,
+    user: {
+      ...user,
+      _strategy: 'mcp-api-key' as const,
+      collection: pluginConfig.userCollection,
+    },
+  }
+}

package/src/endpoint/index.ts

@@ -0,0 +1,35 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server'
+import { APIError, type PayloadHandler } from 'payload'
+
+import { buildMcpServer } from '../mcp/buildMcpServer.js'
+import { getPluginConfig } from '../utils/getPluginConfig.js'
+import { getAuthorizedMCP } from './access.js'
+
+export const mcpEndpoint: PayloadHandler = async (req) => {
+  if (!req.url) {
+    throw new APIError('Missing request URL', 400)
+  }
+
+  req.payloadAPI = 'MCP' as const
+
+  const pluginConfig = getPluginConfig({ config: req.payload.config })
+  const authorizedMCP = await getAuthorizedMCP({ req })
+
+  const server = buildMcpServer({ authorizedMCP, pluginConfig, req })
+
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    enableJsonResponse: true,
+    sessionIdGenerator: undefined, // stateless mode
+  })
+
+  await server.connect(transport)
+
+  const mcpRequest = new Request(req.url, {
+    body: req.body,
+    duplex: 'half',
+    headers: req.headers,
+    method: req.method,
+  } as { duplex: 'half' } & RequestInit)
+
+  return await transport.handleRequest(mcpRequest)
+}

package/src/exports/client.ts

@@ -0,0 +1,2 @@
+'use client'
+export { AccessField } from '../components/AccessField/index.client.js'