payload-mcp-oauth: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

@brainwebuk/payload-plugin-mcp-oauth is a Payload CMS plugin that adds OAuth 2.1 + PKCE + Dynamic Client Registration to @payloadcms/plugin-mcp MCP servers. This enables Payload-backed MCP servers to be used as Custom Connectors in Claude.ai alongside the existing API-key flow.

The plugin is purely additive — it wraps the existing MCP endpoint handler and adds OAuth endpoints/collections as a sibling plugin. See PROJECT_PLAN.md for the full architecture and phased task breakdown.

Repository Structure

.
├── packages/plugin/          # @brainwebuk/payload-plugin-mcp-oauth (the published package)
│   └── src/                  # Source lives here (to be created per PROJECT_PLAN.md §3)
├── examples/payload-app/     # Reference Payload 3 app (SQLite) for integration testing
├── tsconfig.base.json        # Shared TS config (strict, ESNext, Bundler resolution)
└── PROJECT_PLAN.md           # Authoritative task list and architecture decisions

Commands

All commands use pnpm. The workspace root scripts delegate to packages with -r.

# Install (run once at root)
pnpm install

# Build the plugin package only
pnpm --filter ./packages/plugin build

# Run all tests across workspace
pnpm test

# Run tests in a single package
pnpm --filter ./packages/plugin test
pnpm --filter ./examples/payload-app test:integration

# Typecheck
pnpm typecheck
pnpm --filter @brainwebuk/payload-plugin-mcp-oauth typecheck

# Lint
pnpm lint
pnpm --filter ./packages/plugin lint

# Run example app dev server
pnpm dev:example

Build

The plugin uses tsup for dual ESM + CJS output with .d.ts declarations. packages/plugin/tsconfig.json extends the root tsconfig.base.json (strict mode, noUncheckedIndexedAccess, verbatimModuleSyntax). Both packages source from src/ and output to dist/.

Key Architecture Decisions