@payloadcms/plugin-mcp 4.0.0-internal.5b1e7cd → 4.0.0-internal.688c4d0

package/src/components/APIKeyField/index.css

@@ -0,0 +1,105 @@
+@layer payload-default {
+  /* Section wrapper: description + panel, closed off by a full-bleed divider
+     that spans the fields column past its horizontal gutter. */
+  .mcp-api-key-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--base);
+    margin-inline: calc(-1 * var(--gutter-h));
+    padding-inline: var(--gutter-h);
+    padding-block-end: var(--spacer-4);
+    border-block-end: var(--stroke-width-small) solid var(--color-border);
+  }
+
+  .mcp-api-key-field__description {
+    margin: 0;
+    color: var(--color-text);
+    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-api-key-field__panel {
+    overflow: hidden;
+    background: var(--color-bg);
+    border: var(--stroke-width-small) solid var(--color-border);
+    border-radius: var(--button-radius);
+  }
+
+  .mcp-api-key-field__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--spacer-2);
+    min-height: var(--spacer-5);
+    padding: var(--spacer-2) var(--spacer-3);
+    background: var(--color-bg-secondary);
+  }
+
+  /* Holds the warning + key row; its top border is the full-width divider
+     under the header. Only rendered once a key exists. */
+  .mcp-api-key-field__body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacer-2);
+    padding: var(--spacer-3);
+    border-block-start: var(--stroke-width-small) solid var(--color-border);
+  }
+
+  .mcp-api-key-field__title {
+    color: var(--color-text);
+    font-family: var(--text-body-medium-strong-font-family);
+    font-size: var(--text-body-medium-strong-font-size);
+    font-weight: var(--text-body-medium-strong-font-weight);
+    line-height: var(--text-body-medium-strong-line-height);
+  }
+
+  .mcp-api-key-field__generate {
+    margin: 0;
+  }
+
+  /* Matches the core Banner's warning treatment: theme-adaptive warning-tertiary
+     bg with regular --color-text (NOT --color-text-onwarning, which is only
+     defined for light mode and reads as muddy dark-on-dark in dark mode). */
+  .mcp-api-key-field__warning {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--base) / 2);
+    padding: calc(var(--spacer-2) + (var(--spacer-1) / 2)) calc(var(--base) / 2);
+    background: var(--color-bg-warning-tertiary);
+    border: none;
+    border-radius: var(--radius-medium);
+    color: var(--color-text);
+  }
+
+  .mcp-api-key-field__warning-icon {
+    flex-shrink: 0;
+    width: 15px;
+    height: 13px;
+  }
+
+  .mcp-api-key-field__warning-text {
+    flex-grow: 1;
+    margin: 0;
+    font-family: var(--text-body-medium-font-family);
+    font-size: var(--text-body-medium-font-size);
+    line-height: var(--text-body-medium-line-height);
+  }
+
+  .mcp-api-key-field__warning-text strong {
+    font-weight: var(--text-body-medium-strong-font-weight);
+  }
+
+  .mcp-api-key-field__warning-dismiss {
+    appearance: none;
+    background: none;
+    border: none;
+    cursor: pointer;
+    color: inherit;
+    font-size: 1rem;
+    line-height: 1;
+    padding: 0;
+  }
+}

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

@@ -0,0 +1,36 @@
+'use client'
+
+import type { NoResultsClientProps } from 'payload'
+
+import { Button, NoListResults, useTranslation } from '@payloadcms/ui'
+import React from 'react'
+
+import type {
+  PluginMCPTranslationKeys,
+  PluginMCPTranslations,
+} from '../../translations/index.js'
+
+export const APIKeysEmptyState: React.FC<NoResultsClientProps> = ({
+  hasCreatePermission,
+  newDocumentURL,
+  viewType,
+}) => {
+  const { t } = useTranslation<PluginMCPTranslations, PluginMCPTranslationKeys>()
+
+  return (
+    <NoListResults
+      Actions={
+        hasCreatePermission && newDocumentURL && viewType !== 'trash'
+          ? [
+              <Button el="link" key="create" to={newDocumentURL}>
+                {t('authentication:generateNewAPIKey')}
+              </Button>,
+            ]
+          : []
+      }
+      description={t('plugin-mcp:apiKeyDescription')}
+      title={t('plugin-mcp:noAPIKeys')}
+      withMargin
+    />
+  )
+}

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

@@ -0,0 +1,299 @@
+'use client'
+
+import type { JSONFieldClientProps } from 'payload'
+
+import { CheckboxInput, Collapsible, Tabs, useField, useTranslation } from '@payloadcms/ui'
+import React, { useState } from 'react'
+
+import type {
+  PluginMCPTranslationKeys,
+  PluginMCPTranslations,
+} from '../../translations/index.js'
+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 TabKey = 'collections' | 'globals' | 'server'
+
+const LEAF_GROUP_KEYS = ['operations', 'auth', 'custom'] as const
+
+type LeafGroupKey = (typeof LEAF_GROUP_KEYS)[number]
+
+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 { t } = useTranslation<PluginMCPTranslations, PluginMCPTranslationKeys>()
+  const [activeTab, setActiveTab] = useState<null | TabKey>(null)
+  const access = value ?? {}
+  const leafGroupLabels: Record<LeafGroupKey, string> = {
+    auth: t('plugin-mcp:authentication'),
+    custom: t('general:custom'),
+    operations: t('plugin-mcp:operations'),
+  }
+
+  const collectionsBySlug: Record<string, ClientItem[]> = {}
+  const globalsBySlug: Record<string, ClientItem[]> = {}
+  const prompts: ClientItem[] = []
+  const resources: ClientItem[] = []
+  const tools: 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, configKey: string): boolean =>
+    access[scope]?.[slug]?.[configKey] !== false
+
+  const isFlatAllowed = (scope: FlatKey, configKey: string): boolean =>
+    access[scope]?.[configKey] !== false
+
+  const toggleScoped = (scope: ScopeKey, slug: string, configKey: string, allow: boolean) => {
+    if (allow) {
+      const slugBucket = without(access[scope]?.[slug], configKey)
+      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], configKey, false)),
+        ),
+      )
+    }
+  }
+
+  const toggleFlat = (scope: FlatKey, configKey: string, allow: boolean) => {
+    if (allow) {
+      const bucket = without(access[scope], configKey)
+      setValue(bucket ? setKey(access, scope, bucket) : (without(access, scope) ?? {}))
+    } else {
+      setValue(setKey(access, scope, setKey(access[scope], configKey, 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.configKey]: 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.configKey]: false }),
+        {},
+      )
+      setValue(setKey(access, scope, bucket))
+    }
+  }
+
+  const renderLeaf = (
+    leaf: ClientItem,
+    id: string,
+    checked: boolean,
+    onToggle: (allow: boolean) => void,
+  ) => (
+    <li className={`${baseClass}__leaf`} key={leaf.configKey}>
+      <CheckboxInput
+        checked={checked}
+        id={id}
+        label={leaf.label}
+        onToggle={(e) => onToggle(e.target.checked)}
+      />
+      {leaf.description && <p className={`${baseClass}__leaf-description`}>{leaf.description}</p>}
+    </li>
+  )
+
+  const renderCard = ({
+    id,
+    isLeafAllowed,
+    label,
+    leaves,
+    onSetAll,
+    onToggleLeaf,
+  }: {
+    id: string
+    isLeafAllowed: (leaf: ClientItem) => boolean
+    label: string
+    leaves: ClientItem[]
+    onSetAll: (allow: boolean) => void
+    onToggleLeaf: (leaf: ClientItem, allow: boolean) => void
+  }) => {
+    const allowedCount = leaves.filter(isLeafAllowed).length
+    const groups = LEAF_GROUP_KEYS.map((key) => ({
+      key,
+      label: leafGroupLabels[key],
+      leaves: leaves.filter((leaf) => (leaf.group ?? 'custom') === key),
+    })).filter((group) => group.leaves.length > 0)
+    const hasGroupLabels = groups.length > 1
+
+    return (
+      <Collapsible
+        className={`${baseClass}__card`}
+        header={
+          // Keep header clicks on the checkbox from also toggling the collapsible.
+          <span
+            className={`${baseClass}__card-checkbox`}
+            onClick={(e) => e.stopPropagation()}
+            role="presentation"
+          >
+            <CheckboxInput
+              checked={allowedCount === leaves.length}
+              id={`${id}._all`}
+              label={label}
+              onToggle={() => onSetAll(allowedCount < leaves.length)}
+              partialChecked={allowedCount > 0 && allowedCount < leaves.length}
+            />
+          </span>
+        }
+        initCollapsed
+        key={id}
+      >
+        <div className={`${baseClass}__card-groups`}>
+          {groups.map((group) => (
+            <div className={`${baseClass}__leaf-group`} key={group.key}>
+              {hasGroupLabels && <p className={`${baseClass}__leaf-group-label`}>{group.label}</p>}
+              <ul className={`${baseClass}__list`}>
+                {group.leaves.map((leaf) =>
+                  renderLeaf(leaf, `${id}.${leaf.configKey}`, isLeafAllowed(leaf), (allow) =>
+                    onToggleLeaf(leaf, allow),
+                  ),
+                )}
+              </ul>
+            </div>
+          ))}
+        </div>
+      </Collapsible>
+    )
+  }
+
+  const renderScope = (scope: ScopeKey, bySlug: Record<string, ClientItem[]>) =>
+    Object.entries(bySlug).map(([slug, leaves]) =>
+      renderCard({
+        id: `${path}.${scope}.${slug}`,
+        isLeafAllowed: (leaf) => isScopedAllowed(scope, slug, leaf.configKey),
+        label: titleCase(slug),
+        leaves,
+        onSetAll: (allow) => setAllScoped(scope, slug, leaves, allow),
+        onToggleLeaf: (leaf, allow) => toggleScoped(scope, slug, leaf.configKey, allow),
+      }),
+    )
+
+  const renderFlat = (scope: FlatKey, label: string, leaves: ClientItem[]) =>
+    leaves.length > 0 &&
+    renderCard({
+      id: `${path}.${scope}`,
+      isLeafAllowed: (leaf) => isFlatAllowed(scope, leaf.configKey),
+      label,
+      leaves,
+      onSetAll: (allow) => setAllFlat(scope, leaves, allow),
+      onToggleLeaf: (leaf, allow) => toggleFlat(scope, leaf.configKey, allow),
+    })
+
+  const tabs: Array<{ key: TabKey; label: string }> = [
+    ...(Object.keys(collectionsBySlug).length > 0
+      ? [{ key: 'collections' as const, label: t('general:collections') }]
+      : []),
+    ...(Object.keys(globalsBySlug).length > 0
+      ? [{ key: 'globals' as const, label: t('general:globals') }]
+      : []),
+    ...(prompts.length > 0 || resources.length > 0 || tools.length > 0
+      ? [{ key: 'server' as const, label: t('plugin-mcp:server') }]
+      : []),
+  ]
+  if (tabs.length === 0) {
+    return null
+  }
+
+  const currentTab = activeTab ?? tabs[0]!.key
+
+  return (
+    <div className={baseClass}>
+      <header className={`${baseClass}__header`}>
+        <h4>{t('plugin-mcp:permissions')}</h4>
+        <p>{t('plugin-mcp:permissionsDescription')}</p>
+      </header>
+      <div className={`${baseClass}__tabbed-content`}>
+        <Tabs
+          className={`${baseClass}__tabs`}
+          onChange={setActiveTab}
+          tabs={tabs.map((tab) => ({
+            label: tab.label,
+            value: tab.key,
+          }))}
+          value={currentTab}
+        />
+        <div className={`${baseClass}__cards`}>
+          {currentTab === 'collections' && renderScope('collections', collectionsBySlug)}
+          {currentTab === 'globals' && renderScope('globals', globalsBySlug)}
+          {currentTab === 'server' && (
+            <>
+              {renderFlat('prompts', t('plugin-mcp:prompts'), prompts)}
+              {renderFlat('resources', t('plugin-mcp:resources'), resources)}
+              {renderFlat('tools', t('plugin-mcp:tools'), tools)}
+            </>
+          )}
+        </div>
+      </div>
+    </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,99 @@
+@layer payload-default {
+  .mcp-access-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--base);
+    /* Breathing room below the API-key section's divider - the fields
+       container itself adds no gap between these two fields. */
+    padding-block-start: var(--spacer-4);
+    /* This custom field renders straight into `render-fields` (no `.field-type`
+       wrapper), so it must carry the standard inter-field margin itself -
+       otherwise the next field (e.g. an overrideApiKeyCollection field) butts
+       against the last card. */
+    margin-block-end: var(--spacer-3);
+  }
+
+  .mcp-access-field__header {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .mcp-access-field__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__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__tabbed-content {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .mcp-access-field__cards {
+    display: flex;
+    flex-direction: column;
+    gap: calc(var(--base) / 2);
+  }
+
+  /* The collapsible header is pointer-events: none so clicks reach the toggle
+     overlay; re-enable events on the checkbox and lift it above the toggle. */
+  .mcp-access-field__card-checkbox {
+    position: relative;
+    z-index: 1;
+    display: inline-flex;
+    pointer-events: auto;
+  }
+
+  .mcp-access-field__leaf-group {
+    padding-block: calc(var(--base) / 2);
+    border-block-end: 1px solid var(--theme-elevation-100);
+  }
+
+  .mcp-access-field__leaf-group:first-child {
+    padding-block-start: 0;
+  }
+
+  .mcp-access-field__leaf-group:last-child {
+    border-block-end: none;
+    padding-block-end: 0;
+  }
+
+  .mcp-access-field__leaf-group-label {
+    margin: 0 0 calc(var(--base) / 2);
+    color: var(--color-text-secondary);
+    font-family: var(--text-body-medium-font-family);
+    font-size: var(--text-body-medium-font-size);
+    line-height: var(--text-body-medium-line-height);
+  }
+
+  .mcp-access-field__list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: calc(var(--base) / 2);
+  }
+
+  .mcp-access-field__leaf-description {
+    margin: calc(var(--base) / 6) 0 0;
+    color: var(--color-text-secondary);
+    font-family: var(--text-body-medium-font-family);
+    font-size: var(--text-body-medium-font-size);
+    line-height: var(--text-body-medium-line-height);
+  }
+}

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

@@ -0,0 +1,34 @@
+'use client'
+
+import { PopupList, useConfig, useTranslation } from '@payloadcms/ui'
+import { formatAdminURL } from 'payload/shared'
+import React from 'react'
+
+import type {
+  PluginMCPTranslationKeys,
+  PluginMCPTranslations,
+} from '../../translations/index.js'
+
+/**
+ * Entry in the user menu's Settings sub-popup linking to the API keys
+ * collection. The collection is excluded from the main nav
+ * (`admin.group: false`) and managed from here instead.
+ */
+export const MCPSettingsMenu: React.FC = () => {
+  const { config } = useConfig()
+  const { t } = useTranslation<PluginMCPTranslations, PluginMCPTranslationKeys>()
+
+  return (
+    <PopupList.MenuItem>
+      <PopupList.GroupLabel label={t('plugin-mcp:mcp')} />
+      <PopupList.Button
+        href={formatAdminURL({
+          adminRoute: config.routes.admin,
+          path: '/collections/payload-mcp-api-keys',
+        })}
+      >
+        {t('plugin-mcp:manageAPIKeys')}
+      </PopupList.Button>
+    </PopupList.MenuItem>
+  )
+}

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,
+})