Payload CMS Expert - Kiro Power

A comprehensive expert system for Payload CMS development, providing complete guidance on collections, fields, hooks, access control, queries, plugins, and advanced patterns.

🚀 What This Power Does

This Kiro Power is your complete companion for Payload CMS development, offering:

Core Capabilities

• Complete Payload CMS guidance - Collections, fields, hooks, access control, queries
• Security best practices - Critical pitfalls and how to avoid them
• Advanced patterns - Multi-tenant, RBAC, plugin development, custom endpoints
• Type-safe development - TypeScript patterns and generated types
• Performance optimization - Query optimization, transaction handling, caching

Key Areas of Expertise

1. Collections & Fields - All field types, validation, conditional fields, relationships
2. Access Control - Row-level security, role-based access, multi-tenant patterns
3. Hooks & Lifecycle - Data transformation, validation, side effects
4. Queries & APIs - Local API, REST, GraphQL with complex filtering
5. Plugin Development - Creating reusable Payload plugins
6. Database Adapters - MongoDB, PostgreSQL, SQLite with transactions
7. Advanced Features - Jobs, custom endpoints, localization, storage

📦 Installation

Option 1: Install via Kiro Powers Panel (Recommended)

1. Open Kiro IDE
2. Open the Powers panel (Ctrl/Cmd + Shift + P → "Open Kiro Powers")
3. Search for "Payload CMS Expert"
4. Click "Install"

Option 2: Manual MCP Configuration

Add this to your .kiro/settings/mcp.json:

{
  "mcpServers": {
    "payload-cms-expert": {
      "command": "uvx",
      "args": ["payload-cms-expert-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

🎯 Quick Start

Once installed, activate the power in Kiro:

@payload-cms-expert activate

Then ask questions like:

• "How do I create a collection with access control?"
• "Show me how to implement role-based permissions"
• "How do I create custom field components?"
• "What's the best way to handle file uploads?"
• "How do I optimize queries for performance?"

📚 Knowledge Base

This power includes comprehensive steering files covering:

Essential Patterns

• Collections - Basic collections, auth, uploads, drafts, live preview
• Fields - All field types, validation, conditional fields, relationships
• Hooks - Collection hooks, field hooks, lifecycle management
• Access Control - Row-level security, RBAC, multi-tenant patterns

Advanced Topics

• Queries - Local API, REST, GraphQL with complex filtering
• Endpoints - Custom API routes, authentication, webhooks
• Adapters - Database, storage, email adapters with transactions
• Plugin Development - Creating and publishing Payload plugins

Security & Performance

• Critical Security Patterns - Access control pitfalls and solutions
• Transaction Safety - Proper req threading in hooks
• Query Optimization - Performance best practices

🛡️ Critical Security Patterns

The power emphasizes these essential security patterns:

1. Local API Access Control (CRITICAL!)

// ❌ SECURITY BUG: Bypasses access control even with user
await payload.find({
  collection: 'posts',
  user: someUser, // Access control is IGNORED!
})

// ✅ SECURE: Actually enforces user permissions  
await payload.find({
  collection: 'posts',
  user: someUser,
  overrideAccess: false, // REQUIRED for security
})

2. Transaction Safety in Hooks

// ✅ CORRECT: Thread req through nested operations
const afterChange: CollectionAfterChangeHook = async ({ doc, req }) => {
  await req.payload.create({
    collection: 'audit-log',
    data: { docId: doc.id },
    req, // Maintains transaction atomicity
  })
}

🏗️ Example: Complete Blog Setup

Here's what the power can help you build:

// Enhanced Posts collection with access control
export const Posts: CollectionConfig = {
  slug: 'posts',
  access: {
    read: ({ req: { user } }) => {
      if (user) return true
      return { status: { equals: 'published' } }
    },
    create: ({ req: { user } }) => Boolean(user),
    update: ({ req: { user } }) => {
      if (!user) return false
      if (user.roles?.includes('admin')) return true
      return { author: { equals: user.id } }
    },
  },
  hooks: {
    beforeChange: [
      async ({ data, req, operation }) => {
        if (operation === 'create' && req.user) {
          data.author = req.user.id
        }
        return data
      },
    ],
  },
  fields: [
    { name: 'title', type: 'text', required: true },
    slugField({ name: 'slug', useAsSlug: 'title' }),
    { name: 'content', type: 'richText', required: true },
    { name: 'author', type: 'relationship', relationTo: 'users' },
    {
      name: 'readingTime',
      type: 'number',
      virtual: true,
      hooks: {
        afterRead: [
          ({ siblingData }) => {
            const wordCount = siblingData.content?.toString().split(' ').length || 0
            return Math.ceil(wordCount / 200)
          },
        ],
      },
    },
  ],
}

🔧 MCP Plugin Integration

This power also includes comprehensive guidance for Payload's MCP (Model Context Protocol) plugin, enabling AI integration with your CMS.

MCP Plugin Installation

pnpm add @payloadcms/plugin-mcp

Basic MCP Configuration

import { buildConfig } from 'payload'
import { mcpPlugin } from '@payloadcms/plugin-mcp'

const config = buildConfig({
  collections: [{
    slug: 'posts',
    fields: [],
  }],
  plugins: [
    mcpPlugin({
      collections: {
        posts: {
          enabled: true,
          description: 'Blog posts with content about technology and development',
        },
      },
    }),
  ],
})

MCP Client Configuration

VSCode

{
  "mcp.servers": {
    "Payload": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote", 
        "http://127.0.0.1:3000/api/mcp",
        "--header",
        "Authorization: Bearer YOUR-API-KEY"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "Payload": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:3000/api/mcp", 
        "--header",
        "Authorization: Bearer YOUR-API-KEY"
      ]
    }
  }
}

Custom MCP Tools

mcpPlugin({
  mcp: {
    tools: [{
      name: 'getPostStats',
      description: 'Get statistics about posts',
      handler: async (args, req) => {
        const stats = await req.payload.find({
          collection: 'posts',
          where: {
            createdAt: { greater_than: args.since },
          },
        })
        
        return {
          content: [{
            type: 'text',
            text: `Found ${stats.totalDocs} posts since ${args.since}`,
          }],
        }
      },
      parameters: z.object({
        since: z.string().describe('ISO date string'),
      }).shape,
    }],
  },
})

MCP API Key Management

1. Start your Payload server
2. Navigate to /admin
3. Go to MCP → API Keys
4. Create new API key with appropriate permissions
5. Use the key in your MCP client configuration

🎓 Learning Path

Beginner

1. Start with basic collections and fields
2. Learn about access control fundamentals
3. Understand hooks and lifecycle events
4. Practice with simple queries

Intermediate

5. Implement role-based access control
6. Create custom field components
7. Build custom API endpoints
8. Work with file uploads and storage

Advanced

9. Develop custom plugins
10. Implement multi-tenant architecture
11. Optimize for performance
12. Integrate with external services

🤝 Contributing

This power is designed to be comprehensive and up-to-date. If you find areas for improvement:

1. Fork this repository
2. Add or update steering files in the appropriate sections
3. Test your changes with real Payload projects
4. Submit a pull request with detailed descriptions

📖 Documentation Structure

steering/
├── collections.md          # Collection configurations
├── fields.md              # All field types and patterns
├── hooks.md               # Lifecycle hooks and patterns
├── access-control.md      # Security and permissions
├── queries.md             # Database queries and APIs
├── endpoints.md           # Custom API endpoints
├── adapters.md            # Database and storage adapters
├── advanced.md            # Jobs, auth, localization
└── plugin-development.md  # Creating Payload plugins

🔗 Resources

• Payload CMS Documentation
• Payload GitHub Repository
• Payload Examples
• Payload Templates
• Model Context Protocol

📄 License

This Kiro Power is open source and available under the MIT License.

---

Made with ❤️ for the Payload CMS community

Get started by asking: "How do I create a secure blog with Payload CMS?"