@karixi/payload-ai 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,8 @@
 # @karixi/payload-ai
 
-AI-powered data population and admin features for Payload CMS 3.
+AI-powered data population and admin features for [Payload CMS 3](https://payloadcms.com).
+
+Generate realistic content for any collection using Anthropic Claude or OpenAI — via MCP tools, the admin panel, or automatic hooks.
 
 ## Installation
 
@@ -8,120 +10,219 @@ AI-powered data population and admin features for Payload CMS 3.
 bun add @karixi/payload-ai
 ```
 
-## Quick Start
+Peer dependencies:
+
+```bash
+bun add payload @payloadcms/plugin-mcp
+```
+
+## Setup
+
+This plugin has two parts:
 
-```typescript
+1. **`aiPlugin`** — injects hooks into your Payload config (smart defaults, auto alt text)
+2. **`getAITools` / `getAIPrompts` / `getAIResources`** — registers MCP tools inside `@payloadcms/plugin-mcp`
+
+### Anthropic (Claude)
+
+```ts
 // payload.config.ts
 import { buildConfig } from 'payload'
-import { mongooseAdapter } from '@payloadcms/db-mongodb'
 import { mcpPlugin } from '@payloadcms/plugin-mcp'
 import { aiPlugin, getAITools, getAIPrompts, getAIResources } from '@karixi/payload-ai'
 
 export default buildConfig({
   plugins: [
+    // 1. AI plugin — hooks and admin features
     aiPlugin({
       provider: 'anthropic',
-      apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+      apiKeyEnvVar: 'ANTHROPIC_API_KEY', // reads process.env.ANTHROPIC_API_KEY
       features: {
         adminUI: true,
         devTools: false,
       },
       rollbackOnError: true,
     }),
+
+    // 2. MCP plugin — exposes AI tools to Claude Code / Claude Desktop
     mcpPlugin({
-      tools: (incomingTools) => [...incomingTools, ...getAITools()],
-      prompts: (incomingPrompts) => [...incomingPrompts, ...getAIPrompts()],
-      resources: (incomingResources) => [...incomingResources, ...getAIResources()],
+      collections: {
+        posts: { enabled: true },
+        categories: { enabled: true },
+        media: { enabled: { find: true, create: false, update: false, delete: false } },
+      },
+      mcp: {
+        tools: getAITools({
+          provider: 'anthropic',
+          apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+        }),
+        prompts: getAIPrompts(),
+        resources: getAIResources(),
+      },
     }),
   ],
-  db: mongooseAdapter({ url: process.env.DATABASE_URI! }),
-  collections: [/* your collections */],
+  // ...
 })
 ```
 
-## MCP Tools
+### OpenAI
 
-| Tool | Description |
-|------|-------------|
-| `populateCollection` | Generate N documents for any collection using AI |
-| `bulkPopulate` | Populate the entire site in dependency order |
-| `getCollectionSchema` | View the analyzed schema for a collection |
-| `listCollections` | List all collections with their populatable status |
+```ts
+aiPlugin({
+  provider: 'openai',
+  apiKeyEnvVar: 'OPENAI_API_KEY',
+  features: { adminUI: true },
+}),
+
+mcpPlugin({
+  collections: { posts: { enabled: true } },
+  mcp: {
+    tools: getAITools({
+      provider: 'openai',
+      apiKeyEnvVar: 'OPENAI_API_KEY',
+    }),
+    prompts: getAIPrompts(),
+    resources: getAIResources(),
+  },
+}),
+```
 
-## Claude Code Integration
+> **Note:** `getAITools` requires the same `provider` and `apiKeyEnvVar` as `aiPlugin` so it can create the AI provider when tools are invoked. `getAIPrompts()` and `getAIResources()` take no arguments.
+
+## Connecting Claude Code
+
+After starting your Payload dev server:
 
 ```bash
+# 1. Create an API key in the Payload admin panel (MCP > API Keys)
+#    Enable the AI tools under the key's permissions
+
+# 2. Register the MCP server with Claude Code
 claude mcp add --transport http Payload http://localhost:3000/api/mcp \
-  --header "Authorization: Bearer YOUR_API_KEY"
+  --header "Authorization: Bearer YOUR_MCP_API_KEY"
 ```
 
-Then use natural language in Claude Code:
+Then use natural language:
 
 ```
-Generate 10 blog posts for the posts collection
-Populate all collections with realistic sample data
+> Generate 10 blog posts about sustainable fashion
+> Populate all collections with realistic sample data for an ecommerce demo
+> Show me the schema for the products collection
 ```
 
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "Payload": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "http://localhost:3000/api/mcp",
+        "--header",
+        "Authorization: Bearer YOUR_MCP_API_KEY"
+      ]
+    }
+  }
+}
+```
+
+## MCP Tools
+
+These tools are registered inside the MCP plugin and callable by any MCP client:
+
+| Tool | Parameters | Description |
+|------|------------|-------------|
+| `populateCollection` | `collection`, `count`, `theme?` | Generate and insert N documents into a single collection |
+| `bulkPopulate` | `theme`, `counts` | Populate multiple collections at once in dependency order |
+| `getCollectionSchema` | `collection` | Return the analyzed field schema as JSON |
+| `listCollections` | — | List all collections with field counts and populatable status |
+
+### MCP Prompts
+
+| Prompt | Args | Description |
+|--------|------|-------------|
+| `generateContentBrief` | `collection`, `theme`, `count` | Structured brief to guide content generation |
+| `reviewGeneratedContent` | `collection`, `documentId` | Quality review of a generated document |
+
+### MCP Resources
+
+| Resource | URI | Description |
+|----------|-----|-------------|
+| `schemaOverview` | `schema://collections` | High-level overview of all collections |
+
 ## Features
 
 ### Admin UI (`features.adminUI: true`)
 
-- **AI Fill** button on individual documents — generates field values with one click
-- **Bulk Generate** panel — populate any collection with N documents from the admin panel
-- **Smart defaults** — AI infers sensible values from field names and collection context
-- **Image alt text** — automatically generates alt text for uploaded media
+- **AI Fill** button on individual fields — generates a value with one click
+- **Bulk Generate** panel — populate any collection with N documents
+- **Smart defaults** — auto-fills empty fields on document creation via `beforeChange` hook
+- **Image alt text** — generates alt text for uploaded media via `afterChange` hook
 
 ### Dev Tools (`features.devTools: true`)
 
-Requires `@anthropic-ai/stagehand` (optional peer dependency).
+Requires `@anthropic-ai/stagehand` (optional peer dependency):
+
+```bash
+bun add -d @anthropic-ai/stagehand
+```
 
-- `screenshot` — capture screenshots of your frontend
-- `visual_diff` — compare before/after screenshots to catch regressions
-- `test_form` — fill and submit forms programmatically
-- `edit_test_fix` — AI-driven edit → test → fix loop for frontend issues
+Adds four additional MCP tools:
+
+| Tool | Description |
+|------|-------------|
+| `screenshot` | Capture page screenshots with viewport presets |
+| `visual_diff` | Compare before/after screenshots for regressions |
+| `test_form` | Fill and submit Payload admin forms programmatically |
+| `edit_test_fix` | AI-driven screenshot → analyze → suggest fix loop |
 
 ## Plugin Configuration
 
-```typescript
+```ts
 aiPlugin({
-  provider: 'anthropic' | 'openai',    // AI provider
-  apiKeyEnvVar: string,                 // env var name for the API key
+  // Required
+  provider: 'anthropic' | 'openai',
+  apiKeyEnvVar: string,           // env var name (not the key itself)
+
+  // Optional
   features: {
-    adminUI: boolean,                   // default: false
-    devTools: boolean,                  // default: false
+    adminUI: boolean,             // default: false
+    devTools: boolean,            // default: false
   },
   collections: {
     posts: {
       fields: {
         title: { enabled: true, prompt: 'A compelling blog post title' },
-        status: { enabled: false },
+        status: { enabled: false }, // skip this field
       },
     },
   },
   rateLimit: {
     maxTokensPerBatch: 100000,
-    delayBetweenRequests: 200,          // ms
+    delayBetweenRequests: 200,    // ms
     maxConcurrentRequests: 3,
   },
-  rollbackOnError: true,                // delete created docs if bulk run fails
-  maxConcurrentBrowserInstances: 2,    // for dev tools
+  rollbackOnError: true,          // delete created docs if bulk generation fails
+  maxConcurrentBrowserInstances: 2,
 })
 ```
 
-## API
-
-### Plugin entry points
+## How It Works
 
-```typescript
-import { aiPlugin } from '@karixi/payload-ai'
-import { getAITools } from '@karixi/payload-ai'
-import { getAIPrompts } from '@karixi/payload-ai'
-import { getAIResources } from '@karixi/payload-ai'
-```
+1. **Schema analysis** — reads your Payload collection configs and normalizes fields into a structured schema
+2. **Dependency resolution** — topologically sorts collections so referenced collections are populated first
+3. **Prompt building** — generates per-field AI instructions (respects select options, relationship IDs, richText handling)
+4. **AI generation** — calls the configured provider, validates responses, retries with error context (up to 3 attempts)
+5. **Post-processing** — converts plain text to Lexical JSON for richText fields, links relationships, adds content variation
+6. **Rollback** — if `rollbackOnError` is enabled, deletes all created documents on failure
 
-### Types
+## Types
 
-```typescript
+```ts
 import type {
   AIPluginConfig,
   AIProvider,
@@ -134,30 +235,13 @@ import type {
 } from '@karixi/payload-ai'
 ```
 
-### Core utilities (advanced)
-
-```typescript
-// Analyze collection fields into a structured schema
-import { analyzeFields } from '@karixi/payload-ai/core/field-analyzer'
-
-// Resolve creation order for collections with relationships
-import { resolveCreationOrder, getDependencies } from '@karixi/payload-ai/core/dependency-resolver'
-
-// Convert plain text or structured content to Lexical rich text format
-import { textToLexical, contentToLexical } from '@karixi/payload-ai/generate/richtext-generator'
-```
-
 ## Requirements
 
-- `payload` ^3.79.0
-- `@payloadcms/plugin-mcp` ^3.79.0
+- Payload CMS ^3.81.0
+- `@payloadcms/plugin-mcp` ^3.81.0
 - Node.js 20+ or Bun 1.1+
-- Optional: `@anthropic-ai/stagehand` (for dev tools feature)
+- An Anthropic or OpenAI API key
 
-## Development
+## License
 
-```bash
-bun run build        # compile TypeScript
-bun run typecheck    # type-check without emitting
-bun run test         # run unit tests
-```
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karixi/payload-ai",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "main": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -15,6 +15,14 @@
   "files": [
     "dist"
   ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leecois/karixi-payload-ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/leecois/karixi-payload-ai/issues"
+  },
+  "homepage": "https://github.com/leecois/karixi-payload-ai#readme",
   "peerDependencies": {
     "payload": "^3.81.0",
     "@payloadcms/plugin-mcp": "^3.81.0"