payload-mcp-toolkit 0.8.1 → 0.9.0

package/README.md

@@ -1,10 +1,13 @@
 # payload-mcp-toolkit
 
-> Standalone schema-aware MCP plugin for Payload CMS v3. Owns the `/api/mcp` endpoint, scoped API keys, draft workflow, and AI-friendly authoring tools so non-technical editors can manage content via AI chat.
+A Payload CMS v3 plugin that lets AI apps such as Claude and ChatGPT read and edit your content over MCP.
 
-`payload-mcp-toolkit` is a single, self-contained Payload v3 plugin. It introspects your Payload config at boot, registers schema-aware **prompts**, **resources**, and **tools** for any MCP-compatible client (Claude Desktop, Claude API, Continue, Cline), and exposes them over `POST /api/mcp` with bearer-token authentication on a built-in API-keys collection.
+It reads your Payload config when the server starts and builds tools, prompts and resources from your collections, globals and blocks. It serves them at `/api/mcp`. Clients connect in one of two ways:
 
-It is the standalone successor to the toolkit's earlier wrapper around `@payloadcms/plugin-mcp` — see [Upgrading from 0.3.x](#upgrading-from-03x) below.
+- **API keys** for scripts and local agents. Each key has its own permissions.
+- **Website sign-in (OAuth)** for Claude and ChatGPT connectors. Users sign in with their site account and choose what the AI may do. Optional. See [docs/oauth.md](docs/oauth.md).
+
+Payload access control applies to every call. Tools run as the signed-in user or the key's user, with `overrideAccess: false`.
 
 ## Install
 
@@ -12,174 +15,125 @@ It is the standalone successor to the toolkit's earlier wrapper around `@payload
 pnpm add payload-mcp-toolkit
 ```
 
-Peer dependencies: `payload` ^3, `zod` ^3.25 or ^4. (Zod 4 needs
-`@modelcontextprotocol/sdk` 1.23 or newer, which this package depends on.)
-
-## Configure — zero config
+Peer dependencies: `payload` ^3, `@payloadcms/ui` ^3, `zod` ^3.25 or ^4.
 
 ```ts
 // payload.config.ts
 import { mcpToolkitPlugin } from 'payload-mcp-toolkit'
 
 export default buildConfig({
-  // ...your collections, blocks, globals
-  serverURL: process.env.SITE_URL,        // used for absolute preview URLs + Host check
-  admin: { user: 'users' },               // your auth collection
+  serverURL: process.env.SITE_URL, // used for preview links and the Host check
+  admin: { user: 'users' },
   plugins: [mcpToolkitPlugin()],
 })
 ```
 
-That is the entire integration. The toolkit:
+This adds:
 
-- Adds the `payload-mcp-api-keys` collection (admin UI: **MCP → API Keys**).
-- Registers a bearer authentication strategy on your user collection.
-- Mounts `POST /api/mcp` and `GET /api/mcp` (the latter returns 405 with a JSON-RPC error so probing clients see something useful).
-- Builds tools / prompts / resources from your introspected schema.
+- The `payload-mcp-api-keys` collection (admin: **MCP → API Keys**) and a bearer strategy on your user collection.
+- `POST /api/mcp`. `GET /api/mcp` returns 405.
+- Tools, prompts and resources built from your schema.
 
-Everything else is inferred:
+The plugin works out the rest from your config:
 
-- **Draft behavior** — collections with `versions.drafts` get `always-draft` semantics (clients flow through `publishDraft` / `patchLayout` / `updateDocument`); others publish immediately.
-- **Preview URLs** — pulled from each collection's `admin.livePreview.url` (or `admin.preview` as a fallback). Falls back to a generic admin-panel hint when neither is set.
-- **Block nesting** — recorded for every blocks-typed field anywhere in the schema; the AI composes layouts at any depth from that map.
-- **User collection** — `admin.user`.
+- **Drafts:** collections and globals with `versions.drafts` save changes as drafts. Others publish on save.
+- **Preview links:** taken from `admin.livePreview.url`, or `admin.preview`.
+- **Blocks:** every blocks field, at any depth, so the AI can build valid layouts.
 
-## API keys
+Schema changes add database tables or columns. On Postgres or SQLite with `push: false`, generate and commit a Payload migration after installing or upgrading.
 
-Create one in admin (**MCP → API Keys → Create**). The plaintext key is shown once on creation; from then on only its `keyPrefix` (first 8 chars) is visible.
+## API keys
 
-Authenticate every MCP request with:
+Create a key in **MCP → API Keys**. The admin shows the full key once. After that you see only its first 8 characters.
 
 ```http
-POST /api/mcp HTTP/1.1
-Authorization: Bearer <plaintext-key>
+POST /api/mcp
+Authorization: Bearer <key>
 Content-Type: application/json
 ```
 
-### Scopes
-
-Configure each key's permissions through typed admin fields — no JSON to hand-edit.
-
-| Field | Effect |
-|---|---|
-| `preset` | Role preset: **Read-only**, **Editor** (read + create + update on collections; read-only on globals — see below), **Admin** (all actions on both), or **Custom** (use the override fields below). Required. Defaults to **Custom** so new keys deny everything until explicitly scoped. Switching away from Custom **clears every override field on save** (collectionScopes, globalScopes, toolAllow, toolDeny); switching back to Custom starts from a fresh deny-all baseline — reconfigure the matrices before saving. |
-| `collectionScopes` | Array of `{ slug, actions[] }`. Only honoured when preset is **Custom**. Each row whitelists a collection and the actions (`read` / `create` / `update` / `delete`) allowed on it. An empty `actions[]` denies all actions on that collection. Listed collections are a *whitelist* — collections not in the list are denied. (Pre-v0.6 rows using `{ collection, actions[] }` are tolerated via a one-release legacy fallback; resave them to migrate.) |
-| `globalScopes` | Array of `{ slug, actions[] }`. Only honoured when preset is **Custom** *and* the host config has at least one global. Globals only support `read` and `update` (no `create` / `delete` — they're singletons). Same whitelist semantics as `collectionScopes`. (Pre-v0.6 rows using `{ global, actions[] }` are tolerated via the same legacy fallback.) |
-| `toolAllow` | Multi-select. Only honoured when preset is **Custom**. If set, only these tools are callable with this key. An empty list under Custom is treated as deny-all on the tools axis **only when no collection or global scopes are set** (the fresh-Custom-key sentinel); when collection or global scopes are populated, an empty list collapses to "no tool restriction" so the resource scopes alone gate access. To deny every tool while keeping resource scopes, enumerate them in `toolDeny` instead. |
-| `toolDeny` | Multi-select. Always applied on top of any preset. Tools listed here are blocked regardless of preset / collection / global scopes. |
-
-The collection and tool dropdowns are populated at plugin-init time from your live Payload config + the toolkit's registered tools. Adding a collection or custom tool requires a dev-server / app restart for it to surface in the dropdowns.
-
-The same shape is editable programmatically via Payload's REST and GraphQL APIs against the `payload-mcp-api-keys` collection — useful for seeding keys from CI or scripted provisioning.
-
-### Lifecycle fields
-
-| Field | Effect |
-|---|---|
-| `name`, `description` | Human-readable identifier in the admin list. |
-| `expiresAt` | Authentication rejects keys past this date. |
-| `revokedAt` | Authentication rejects keys when set. |
-| `lastUsedAt` | Updated fire-and-forget on each successful auth. |
-| `keyPrefix` | First 8 chars of the plaintext, for audit-log identification. |
-
-## What the plugin adds
-
-**Auto-generated prompts:**
+Each key has a **preset**:
 
-- `contentModelOverview` — every collection, fields, and relationships.
-- `blockCompositionGuide` — section/leaf hierarchy and nesting rules.
-- `draftWorkflowGuide` — which collections need `publishDraft` to go live.
+| Preset | Collections | Globals |
+|---|---|---|
+| Read-only | read | read |
+| Editor | read, create, update | read |
+| Admin | read, create, update, delete | read, update |
+| Custom | only what you tick | only what you tick |
 
-**Auto-generated resources:** `blocks://catalog`, `blocks://nesting`, `collections://schema`, `collections://relationships`. Plus `globals://schema` when the host config has at least one global.
+New keys start as **Custom** with nothing ticked, so they can do nothing until you choose. Custom gives you a collection matrix, a global matrix, a tool allow list and a tool deny list. The deny list applies to every preset.
 
-**Tools (19 total — 10 collection-routed, 6 global-routed, 3 account-routed; globals tools register only when the host config has at least one global, and version / publish tools register only on draft-enabled resources):**
+Editor keys cannot change globals. One bad write to a global (site name, footer, navigation) shows on every page. To let a key edit a specific global, use Custom.
 
-*Authoring*
-- `createDocument` — local-API based creation for any collection. JSON-string `data`. Defaults to `draft: true` on draft-enabled collections.
-- `updateDocument` — local-API based update. Replaces the upstream plugin's `update<Resource>` tools, which crash on collections containing richText/upload/blocks fields.
-- `patchLayout` — surgical append/prepend/insertAt/replaceAt against any blocks-typed field. Validates each block recursively against the introspected nesting map.
-- `uploadMedia` — fetch a public HTTPS image, validate (SSRF-safe with a streaming size cap), create a Media doc.
+A key limited to some collections or globals also has these rules:
 
-*Discovery*
-- `findDocument` — read documents by `documentId` or `where` filter, polymorphic across collections. Decorates draft responses with preview URLs when configured.
-- `resolveReference` — search collections by name/title/slug for relationship IDs.
-- `searchContent` — natural-language editor triage (status, recency, missing fields, free text).
+- It gets linked entries as IDs only.
+- `findDocument` refuses filters with a dotted path.
+- Search, reference and upload tools are off, because they reach across every collection.
 
-*Lifecycle / safety*
-- `publishDraft` — flip `_status` from draft to published. Recovers from Payload's post-write field-validator quirk (validator throws *after* the new version row commits in some draft+versions setups): on a caught error, the tool re-reads the doc with `draft: false` and only downgrades to a "published-with-warning" response when the live row reflects the current attempt (strictly newer `updatedAt`), so a stale prior publish cannot mask a real failure.
-- `schedulePublish` — auto-registered for collections with drafts AND a `publishedAt` date field. Stamps a future `publishedAt`; you wire up the actual flip via Payload Jobs Queue / cron / `beforeRead`.
-- `listVersions` — recent saved versions of a draft document.
-- `restoreVersion` — roll a document back to a saved version (creates a new version, so reversible).
-- `safeDelete` — relationship-aware delete. Walks the relationship graph; refuses with a structured impact summary if the doc has inbound references. Override with `confirm: true`.
-- `deleteDocument` — fast unsafe delete (no relationship walk). Use only when you know the doc has no inbound references; prefer `safeDelete` for general use.
+Keys also have `expiresAt`, `revokedAt` and `lastUsedAt`.
 
-*Globals* (registered when the host config has at least one global)
-- `findGlobal` — read any global by slug. Stamps a preview URL on draft documents when `admin.livePreview` / `admin.preview` is configured.
-- `updateGlobal` — partial-merge update; same prose JSON contract as `updateDocument`. Draft-enabled globals default to `'always-draft'`.
-- `patchGlobalLayout` — surgical block-array edits on any blocks-typed field inside a global, at any nesting depth (e.g. `footer.sections`). Registered only when at least one global has a blocks field.
-- `publishGlobalDraft`, `listGlobalVersions`, `restoreGlobalVersion` — registered only for globals with `versions: { drafts: true }`. `publishGlobalDraft` uses the same post-write validation recovery as `publishDraft`, with `fallbackLocale: false` on the verify read so localized globals report the literal `_status` of the requested locale.
+## Website sign-in (OAuth)
 
-## Globals
+```ts
+mcpToolkitPlugin({
+  oauth: {
+    canAuthorize: ({ user }) => user?.role === 'admin', // who may connect; checked on every request
+    access: 'editor', // most the site allows; default 'read-only'
+  },
+})
+```
 
-Globals (site-wide singletons such as site settings, navigation, footer) are exposed alongside collections through the tools listed above and a `globals://schema` resource. The admin UI gains a second "Global scopes" matrix beneath "Collection scopes" under the Custom preset; rows are global slugs, columns are `Read` / `Update`.
+Users add `https://YOUR-SITE/api/mcp` as a custom connector in Claude, or in ChatGPT with Developer mode on. Then they sign in and approve access. The approve screen offers the same choices as a Custom key, capped at `access`. Delete and global writes are never allowed this way.
 
-### Why `editor` is read-only on globals
+The plugin also adds:
 
-The `editor` preset grants read-only access to globals — only `admin` (or a Custom key with explicit `globalScopes`) can write them. Collections under `editor` continue to get `read + create + update`.
+- `/admin/mcp-connections`, where users copy the connector URL and agent instructions, and disconnect.
+- A compact "Connect your AI agent" prompt in the admin sidebar.
 
-The asymmetry exists because globals broadcast site-wide on a single write: site name, footer links, social handles, banner text. A typo in a global is visible on every page that consumes it, with no per-document containment to roll back. Editor-tier keys are typically given to AI agents acting on imperfect natural-language instructions, and `"fix the site title"` going wrong is a one-shot vandalism path against the whole site. If you need editor-tier keys to update specific globals, use the Custom preset with a `globalScopes` entry naming the global slug.
+Setup needs a migration, discovery rewrites and two security headers. See [docs/oauth.md](docs/oauth.md).
 
-## Optional configuration
+## Tools
 
-Every option is an escape hatch — pass only what you need:
+Tools for versions and publishing appear only for collections and globals with drafts. Global tools appear only when the config has globals.
 
-```ts
-mcpToolkitPlugin({
-  auth: {
-    allowedOrigins: ['https://app.example.com'],   // origin allow-list for the /api/mcp Origin/Host check; browser preflight not yet handled — see Known limitations
-  },
-  apiKeyCollection: {
-    slug: 'mcp-keys',                              // default 'payload-mcp-api-keys'
-    userCollection: 'admins',                      // default admin.user
-  },
-  preview: {
-    siteUrl: 'https://staging.example.com',
-    disabled: false,
-  },
-  draftBehavior: {
-    posts: 'always-publish',                       // publish immediately on update
-  },
-  userCollection: 'admins',
-  exclude: {
-    collections: ['internal-bookkeeping'],
-    globals: ['secret-config'],
-  },
-  mediaUpload: { maxFileSize: 25 * 1024 * 1024, collectionSlug: 'images' },
-  domainPrompts: [
-    { name: 'siteVocabulary', title: 'Site Vocabulary', description: 'Site-specific terms.', content: '...' },
-  ],
-})
-```
+| Tool | What it does |
+|---|---|
+| `findDocument` | Read by ID or `where` filter. Draft results include a preview link. |
+| `searchContent` | Find entries by text, status, recent changes or missing fields. |
+| `resolveReference` | Look up IDs by name, title or slug, for relationship fields. |
+| `createDocument` | Create an entry. Draft collections save a draft. |
+| `updateDocument` | Update an entry, including rich text, upload and blocks fields. |
+| `patchLayout` | Append, insert or replace blocks in a blocks field. Checks each block against your schema. |
+| `uploadMedia` | Fetch a public HTTPS image and create a media entry. Size-capped while downloading. |
+| `publishDraft`, `schedulePublish` | Publish a draft now, or set a future `publishedAt`. You run the scheduled publish yourself (Jobs Queue or cron). |
+| `listVersions`, `restoreVersion` | List saved versions and roll back. |
+| `safeDelete` | Delete only if nothing links to the entry, unless `confirm: true`. |
+| `deleteDocument` | Delete without checking links. |
+| `findGlobal`, `updateGlobal`, `patchGlobalLayout` | The same for globals. |
+| `publishGlobalDraft`, `listGlobalVersions`, `restoreGlobalVersion` | Draft tools for globals. |
+
+**Prompts:** `contentModelOverview`, `blockCompositionGuide`, `draftWorkflowGuide`.
+
+**Resources:** `collections://schema`, `collections://relationships`, `blocks://catalog`, `blocks://nesting`, `globals://schema`.
+
+## Options
 
 | Option | Description |
 |---|---|
-| `auth.allowedOrigins` | Origins permitted on the `Origin` header for the DNS-rebinding check. Empty / unset means server-to-server only. `*` is intentionally not honoured. **Note:** browser MCP clients are not yet fully supported — the endpoint does not emit CORS response headers or handle the `OPTIONS` preflight. See [Known limitations](#known-limitations). |
-| `apiKeyCollection.slug` | API-keys collection slug. Defaults to `payload-mcp-api-keys` for zero-touch upgrade compatibility. |
-| `apiKeyCollection.userCollection` | User collection that API keys link to. Defaults to `userCollection` / `admin.user`. |
-| `preview.siteUrl` | Base URL for preview links. Defaults to `serverURL`, then `NEXT_PUBLIC_SERVER_URL`/`SITE_URL` env vars. |
-| `preview.disabled` | Suppress preview URL injection on draft responses. |
-| `draftBehavior` | Per-collection override of inferred behavior. |
-| `userCollection` | Override `admin.user` for API key linkage. |
-| `exclude.collections` / `exclude.globals` | Hide from MCP exposure. |
-| `domainPrompts` | Site-specific vocabulary prompts. |
-| `mediaUpload.maxFileSize` | Default 10MB. Enforced as a streaming cap, not a post-buffer check. |
-| `mediaUpload.collectionSlug` | Default `'media'`. |
-| `customTools` | Extra tools registered alongside the built-ins. See [Custom tools](#custom-tools). |
+| `oauth` | Website sign-in. See above. |
+| `exclude.collections`, `exclude.globals` | Hide collections and globals from MCP. |
+| `customTools` | Your own tools. See below. |
+| `draftBehavior` | Per-collection override, for example `{ posts: 'always-publish' }`. |
+| `preview.siteUrl`, `preview.disabled` | Base URL for preview links (default `serverURL`), or turn them off. |
+| `mediaUpload.maxFileSize`, `mediaUpload.collectionSlug` | Default 10 MB and `'media'`. |
+| `domainPrompts` | Extra prompts with site vocabulary. |
+| `userCollection` | Override `admin.user`. |
+| `apiKeyCollection.slug`, `apiKeyCollection.userCollection` | Rename the keys collection or link keys to another user collection. |
+| `auth.allowedOrigins` | Origins allowed by the `Origin` check. Unset means server-to-server only. |
 
 ## Custom tools
 
-Pass your own tools through `customTools` and they register next to the built-in
-ones:
-
 ```ts
 import { mcpToolkitPlugin, jsonResponse, type ToolFactoryOutput } from 'payload-mcp-toolkit'
 import { z } from 'zod'
@@ -188,137 +142,46 @@ const countActiveMembers: ToolFactoryOutput = {
   name: 'countActiveMembers',
   description: 'Number of members with an active membership.',
   parameters: { since: z.string().optional().describe('ISO date.') },
-  // 'account', not 'collection': the target is hard-coded in the handler, so
-  // there is no argument for the scope check to read. See Scope routing below.
   routing: { kind: 'account', action: 'read' },
   handler: async (args, req) => {
-    const { totalDocs } = await req.payload.count({
-      collection: 'memberships',
-      user: req.user,
-      overrideAccess: false,
-    })
+    const { totalDocs } = await req.payload.count({ collection: 'memberships', user: req.user, overrideAccess: false })
     return jsonResponse({ totalDocs })
   },
 }
 
-plugins: [mcpToolkitPlugin({ customTools: [countActiveMembers] })]
-```
-
-What you get for free:
-
-- **The same wrapper as the built-ins** — the scope check runs before your
-  handler, `req.context.source` is stamped `'mcp'`, and every call (success,
-  failure, scope rejection) lands in the structured audit log.
-- **A slot in the API-key scope dropdowns** — your tool name appears in
-  **Tool allow** / **Tool deny** alongside the built-ins.
-- **A boot-time name check** — reusing a built-in name throws instead of
-  silently shadowing that tool.
-
-The field-by-field contract:
-
-| Field | Notes |
-|---|---|
-| `name` | Must be unique across built-in and custom tools. |
-| `description` | Shown to the model in `tools/list`. Say when to reach for it. |
-| `parameters` | A raw Zod shape (`{ key: z.string() }`) or a `z.object({...})`. Both are accepted. |
-| `routing` | `{kind, action}` — which scope axis gates the tool. `kind` is `'collection'`, `'global'`, or `'account'`. |
-| `handler` | `(args, req, extra) => McpTextResponse`. Read `req.payload` / `req.user` per call; do not close over them at boot. |
-
-### Scope routing
-
-Scope routing reads the target resource from the call's own arguments. A
-`collection`-routed tool **must** take a required `collection` argument (a
-`global`-routed tool, a required `slug`); the registry reads that value to
-decide whether the key's scopes permit the call.
-
-A `collection`- or `global`-routed tool called without that argument is
-**denied**, whatever the key's scopes say. There is no target to check, so the
-check cannot pass. Use `routing.kind: 'account'` for a tool whose target is
-fixed in the handler or spans the whole install — account-routed tools are
-gated by the key's preset instead.
-
-Making the argument optional is the trap: the call then reaches the scope check
-with no target and is refused every time.
-
-Run queries as the authenticated user (`user: req.user, overrideAccess: false`)
-so Payload's own access rules still apply inside the tool. `overrideAccess:
-true` hands an MCP client more reach than the user behind its API key.
-
-## Upgrading from 0.7.0
-
-v0.7.1 is a patch release; no API or breaking config changes. The behavioural changes worth knowing:
-
-- **Preset-switch clears overrides on save.** Switching an API key away from Custom now nulls `collectionScopes`, `globalScopes`, `toolAllow`, and `toolDeny` on save (admin UI conditional-field trap fix — previously, stale Custom-era values silently survived the switch and continued to narrow access). Switching back to Custom starts from a fresh deny-all baseline; reconfigure the matrices before saving.
-- **Empty `toolAllow` under Custom + populated resource scopes no longer denies all tools.** When the key carries collection or global scopes and `toolAllow` is empty, it is treated as "no tool restriction" so the resource scopes alone determine what is callable. The fresh-Custom-key sentinel (no scopes anywhere → deny-all) still applies.
-- **Legacy non-Custom rows with populated overrides emit a one-time warn.** Keys persisted before v0.7.1 that carry populated `collectionScopes` / `globalScopes` / `toolAllow` arrays under a non-Custom preset still narrow access as written (fail-closed safe), but `composeScopes` now logs `mcp.auth.legacy_non_custom_override` once per process to flag them for audit. Re-save affected keys in admin to align persisted state with the v0.7.1 semantics.
-- **Publish tools recover from Payload's post-write validator throw deterministically.** Both `publishDraft` and `publishGlobalDraft` snapshot the document's `updatedAt` before the update and only downgrade a caught error to a `[publishDraft:published_with_warning]` / `[publishGlobalDraft:published_with_warning]` response when the live row reflects the current attempt (strictly newer `updatedAt`). MCP clients can branch on the stable token prefix without regex-matching prose.
-
-## Upgrading from 0.6
-
-v0.7 renames the exported plugin factory so the public symbol matches the package name. Pure rename — no options, runtime behaviour, or scope semantics changed.
-
-```diff
-- import { contentToolkitPlugin } from 'payload-mcp-toolkit'
-+ import { mcpToolkitPlugin } from 'payload-mcp-toolkit'
-
-- plugins: [contentToolkitPlugin()],
-+ plugins: [mcpToolkitPlugin()],
+mcpToolkitPlugin({ customTools: [countActiveMembers] })
 ```
 
-## Upgrading from 0.5
-
-v0.6 adds globals support across the MCP surface. The changes most likely to surprise an upgrade:
-
-- **`editor` preset is read-only on globals.** Editor-tier keys cannot `updateGlobal` or `patchGlobalLayout`. Use the `admin` preset or a Custom key with explicit `globalScopes` for editor-tier writes. See [Why `editor` is read-only on globals](#why-editor-is-read-only-on-globals) for the rationale.
-- **Audit log field rename.** The per-tool audit field `collectionArg` is replaced by `targetSlug` + `targetKind` (`'collection' | 'global' | 'account' | undefined`). Operators with SIEM rules / dashboards filtering on `collectionArg` must update their queries. The old field is gone — there is no compatibility alias, because the original field misreported for global operations.
-- **`tools.allow` without an explicit resource scope is now a deny.** Previously `tools: { allow: ['updateDocument'] }` with no `collections` map and no preset implicitly allowed `updateDocument` on every collection. The fix lands now and applies symmetrically across collections and globals. If your keys rely on the `tools.allow`-only shape (not a documented configuration), add an explicit `collections` / `globals` map or a `preset`.
-- **Production deploys need a migration.** Run `pnpm payload migrate:create` after upgrading to capture the new `globalScopes` JSONB column on `payload-mcp-api-keys`. Local dev with `push: true` syncs on the next `pnpm dev`.
+Custom tools go through the same permission check and audit log as the built-in tools. They also appear in the API-key and sign-in tool lists.
 
-## Upgrading from 0.3.x
+- **`routing`** says which permission gates the tool.
+  - `collection` tools must take a required `collection` argument.
+  - `global` tools must take a required `slug`.
+  - Use `account` when the target is fixed in the handler or spans the whole site. Without the argument, a collection or global tool is always denied.
+- **`handler`** should read `req.payload` and `req.user` on each call. Query with `user: req.user, overrideAccess: false`.
+- **Names** must be unique. Reusing a built-in name throws at startup.
 
-v0.3.x wrapped `@payloadcms/plugin-mcp`. v0.4 owns the small remaining surface (transport, auth, API-key collection, find/delete) directly. The migration is short.
+## Upgrading
 
-1. **Remove the upstream plugin** from `plugins[]`:
-   ```diff
-   - import { mcpPlugin } from '@payloadcms/plugin-mcp'
-   - // ...
-   - plugins: [mcpToolkitPlugin(), mcpPlugin({ ... })],
-   + plugins: [mcpToolkitPlugin()],
-   ```
-2. **Drop the dependency** from `package.json`:
-   ```bash
-   pnpm remove @payloadcms/plugin-mcp
-   ```
-3. **Existing API keys keep authenticating zero-touch.** The `payload-mcp-api-keys` slug, `apiKey` / `apiKeyIndex` columns, and HMAC formula are all preserved.
-4. **Re-scope each key** — see the [API keys](#api-keys) section. Open each existing key in admin, pick a preset (or **Custom** with explicit collection / tool overrides), and save. Until you do, keys carry no scopes and authenticate at full access.
-5. **Browser MCP clients are not yet fully supported.** Server-to-server callers (no `Origin` header — backend scripts, Claude Desktop's local connector) work as before and require no opt-in. Browser-based clients additionally need CORS response headers and `OPTIONS` preflight handling, which haven't landed yet — see [Known limitations](#known-limitations).
-
-If you forget step 1, the plugin throws on boot with the same message — it refuses to register two MCP plugins racing for the `payload-mcp-api-keys` slug.
+- **0.8 → 0.9:** OAuth is new and off by default. Without it, nothing changes for API-key sites, except one rule. Keys limited to some collections or globals now get linked entries as IDs only, and `findDocument` refuses dotted filter paths for them. Regenerate your import map.
+- **Older versions:** see [CHANGELOG.md](CHANGELOG.md).
 
 ## Known limitations
 
-- **Browser MCP clients are not yet fully supported.** The `/api/mcp` endpoint validates the `Origin` / `Host` headers (DNS-rebinding protection) and the `auth.allowedOrigins` option restricts which origins may call it, but the endpoint does not yet emit CORS response headers (`Access-Control-Allow-Origin` etc.) or handle the `OPTIONS` preflight request that browsers send before authenticated cross-origin POSTs. Server-to-server callers (backend scripts, Claude Desktop's local connector — no `Origin` header) are unaffected. Full browser-client support will land in a follow-up release once there is a concrete client to validate against; until then, treat `auth.allowedOrigins` as a server-side allow-list, not a browser opt-in.
+- Browser-based MCP clients are not supported yet. The endpoint does not send CORS headers or answer `OPTIONS` preflight. Server-to-server clients and hosted connectors (Claude, ChatGPT) are not affected.
 
 ## Development
 
-This package follows the [official Payload 3 plugin template](https://github.com/payloadcms/payload/tree/main/templates/plugin) layout: source in `src/`, a fully-working Payload + Next.js app in `dev/`, source-export `package.json` so the dev harness consumes the plugin directly without a build step.
+The `dev/` folder is a working Payload and Next.js app that uses the plugin source directly.
 
 ```bash
 pnpm install
 cp dev/.env.example dev/.env
-pnpm dev          # boot dev/ Next.js + Payload at http://localhost:3000
-pnpm test         # vitest — runs the unit + integration suite
-pnpm build        # produce dist/ for npm publish
+pnpm dev    # http://localhost:3000
+pnpm test
+pnpm build
 ```
 
-The dev harness ships with a realistic CMS schema:
-
-- `Pages` — block-based layout (FullWidth, TwoColumn, CtaBanner, HeadingOnly), drafts enabled.
-- `Posts` — title/slug/excerpt/content/cover/category/authors/tags/SEO, drafts enabled.
-- `Authors`, `Categories`, `Media`, `Users` — taxonomy + auth.
-- `SiteSettings` — global with site name, logo, social, footer.
-- 5 leaf blocks (Heading, RichText, Image, ButtonGroup, Quote) and 4 section blocks.
-
 ## License
 
 MIT

package/dist/auth-strategy.js

@@ -1,10 +1,10 @@
 import { extractBearerToken, hashKey } from './hash';
 export const AUTH_STRATEGY_NAME = 'mcp-toolkit-bearer';
-/**
- * Reads the row's slug, tolerating the pre-0.6 `collection` / `global`
- * keys for one release. Logs a one-line warn when the legacy fallback
- * fires so operators can spot keys that need re-saving. The fallback is
- * scheduled for removal in v0.7.
+/**
+ * Reads the row's slug, tolerating the pre-0.6 `collection` / `global`
+ * keys for one release. Logs a one-line warn when the legacy fallback
+ * fires so operators can spot keys that need re-saving. The fallback is
+ * scheduled for removal in v0.7.
  */ let warnedLegacyShape = false;
 let warnedLegacyNonCustomOverride = false;
 /** @internal test-only: reset the one-time legacy warns. */ export function _resetLegacyWarnsForTests() {
@@ -36,40 +36,40 @@ const VALID_GLOBAL_ACTIONS = new Set([
     'read',
     'update'
 ]);
-/**
- * Builds the runtime `KeyScopes` shape consumed by `registry.assertScopeAllows`
- * from the typed scope fields on the api-key row.
- *
- * Returns null when no typed fields are populated AND no preset is set
- * (= full access — back-compat for pre-0.5 rows that pre-date scoped authz).
- *
- * Two complementary fail-closed rules:
- *
- * 1. **`'custom'` deny-all sentinel.** `'custom'` is a UI sentinel meaning
- *    "use my override fields"; it never becomes `KeyScopes.preset` itself.
- *    Payload persists unset JSON / select fields as `null`, so a fresh
- *    Custom key with no overrides arrives as `{preset:'custom',
- *    collectionScopes:null, globalScopes:null, toolAllow:null,
- *    toolDeny:null}`. That row must deny everything (not fall through to
- *    full access). The sentinel emits `{collections:{}, globals:{},
- *    tools:{allow:[]}}`.
- *
- * 2. **Per-axis explicit-empty, Custom-only.** Under the Custom preset, an
- *    empty array on any axis (even `[]`) is honoured as written — an empty
- *    `toolAllow:[]` means "deny all tools on this axis", not "no opinion".
- *    Under non-Custom presets, empty arrays are IGNORED because Payload's
- *    hasMany / unpopulated-JSON reads return `[]` for fields the user
- *    never touched (the override matrices are hidden in the admin UI under
- *    non-Custom presets via `condition: isCustomPreset`). The on-write
- *    counterpart of this rule lives in `createApiKeysCollection`'s
- *    `beforeValidate` hook, which proactively nulls the override axes on
- *    save when the preset is non-Custom — both layers must stay in sync.
- *    Non-empty arrays still apply as layered narrowing under any preset.
- *    `toolDeny` is a deny-list, so an empty array carries no entries — it
- *    is dropped rather than emitted. NOTE: legacy non-Custom rows persisted
- *    BEFORE v0.7.1 with populated stale override arrays continue to narrow
- *    on read until each row is manually re-saved; the on-write fix only
- *    applies to fresh writes.
+/**
+ * Builds the runtime `KeyScopes` shape consumed by `registry.assertScopeAllows`
+ * from the typed scope fields on the api-key row.
+ *
+ * Returns null when no typed fields are populated AND no preset is set
+ * (= full access — back-compat for pre-0.5 rows that pre-date scoped authz).
+ *
+ * Two complementary fail-closed rules:
+ *
+ * 1. **`'custom'` deny-all sentinel.** `'custom'` is a UI sentinel meaning
+ *    "use my override fields"; it never becomes `KeyScopes.preset` itself.
+ *    Payload persists unset JSON / select fields as `null`, so a fresh
+ *    Custom key with no overrides arrives as `{preset:'custom',
+ *    collectionScopes:null, globalScopes:null, toolAllow:null,
+ *    toolDeny:null}`. That row must deny everything (not fall through to
+ *    full access). The sentinel emits `{collections:{}, globals:{},
+ *    tools:{allow:[]}}`.
+ *
+ * 2. **Per-axis explicit-empty, Custom-only.** Under the Custom preset, an
+ *    empty array on any axis (even `[]`) is honoured as written — an empty
+ *    `toolAllow:[]` means "deny all tools on this axis", not "no opinion".
+ *    Under non-Custom presets, empty arrays are IGNORED because Payload's
+ *    hasMany / unpopulated-JSON reads return `[]` for fields the user
+ *    never touched (the override matrices are hidden in the admin UI under
+ *    non-Custom presets via `condition: isCustomPreset`). The on-write
+ *    counterpart of this rule lives in `createApiKeysCollection`'s
+ *    `beforeValidate` hook, which proactively nulls the override axes on
+ *    save when the preset is non-Custom — both layers must stay in sync.
+ *    Non-empty arrays still apply as layered narrowing under any preset.
+ *    `toolDeny` is a deny-list, so an empty array carries no entries — it
+ *    is dropped rather than emitted. NOTE: legacy non-Custom rows persisted
+ *    BEFORE v0.7.1 with populated stale override arrays continue to narrow
+ *    on read until each row is manually re-saved; the on-write fix only
+ *    applies to fresh writes.
  */ export function composeScopes(row, logger) {
     const presetRaw = row.preset;
     const hasPreset = typeof presetRaw === 'string' && presetRaw.length > 0;
@@ -160,13 +160,13 @@ const VALID_GLOBAL_ACTIONS = new Set([
     }
     return out;
 }
-/**
- * Builds the Payload `auth.strategies` entry that authenticates MCP requests.
- *
- * Authenticates `Authorization: Bearer <plaintext>` by computing the
- * upstream-compatible `apiKeyIndex` HMAC and looking up the row. On match,
- * it fires a non-blocking `lastUsedAt` write and hydrates `req.user` with
- * the linked user record + key context for downstream scope checks.
+/**
+ * Builds the Payload `auth.strategies` entry that authenticates MCP requests.
+ *
+ * Authenticates `Authorization: Bearer <plaintext>` by computing the
+ * upstream-compatible `apiKeyIndex` HMAC and looking up the row. On match,
+ * it fires a non-blocking `lastUsedAt` write and hydrates `req.user` with
+ * the linked user record + key context for downstream scope checks.
  */ export function createBearerStrategy(options) {
     const { collectionSlug, userCollection } = options;
     return {
@@ -250,9 +250,9 @@ const VALID_GLOBAL_ACTIONS = new Set([
         }
     };
 }
-/**
- * Reads the per-request API-key context populated by the bearer strategy.
- * Returns null for non-MCP requests (e.g. cookie-authenticated admin users).
+/**
+ * Reads the per-request API-key context populated by the bearer strategy.
+ * Returns null for non-MCP requests (e.g. cookie-authenticated admin users).
  */ export function getApiKeyContext(req) {
     const user = req.user;
     return user?._mcpKey ?? null;