flowchart TB
    WP[WordPress HTML Post]:::wordpress
    PFE[pull-for-editing]:::operation
    H2M[HTML→Markdown Conversion]:::converter
    DS[Document SessionHandle: abc123]:::session
    LES[Local Edit State• Clean Markdown• Line Numbers• No HTML Entities]:::state
    
    EDL[edit-document-line]:::edit
    IAL[insert-at-line]:::edit
    SR[search-replace]:::edit
    
    MLS[Modified Local StateMultiple Edits Applied]:::state
    STW[sync-to-wordpress]:::operation
    M2H[Markdown→HTML Conversion]:::converter
    WPU[WordPress UpdateSingle API Call]:::wordpress
    
    WP -->|1| PFE
    PFE --> H2M
    H2M --> DS
    DS --> LES
    LES --> EDL
    LES --> IAL
    LES --> SR
    EDL --> MLS
    IAL --> MLS
    SR --> MLS
    MLS -->|2| STW
    STW --> M2H
    M2H --> WPU
    
    classDef wordpress fill:#1e40af,stroke:#3730a3,color:#ffffff
    classDef operation fill:#059669,stroke:#047857,color:#ffffff
    classDef converter fill:#7c3aed,stroke:#6d28d9,color:#ffffff
    classDef session fill:#ea580c,stroke:#dc2626,color:#ffffff
    classDef state fill:#0891b2,stroke:#0e7490,color:#ffffff
    classDef edit fill:#64748b,stroke:#475569,color:#ffffff

flowchart LR
    subgraph "Human Intent"
        H1[I want to write about MCP servers]:::human
        H2[Fix that typo in my article]:::human
        H3[What do people think of my post?]:::human
    end
    
    subgraph "AI Intent"
        AI1[Create article]:::intent
        AI2[Edit my post]:::intent
        AI3[Review feedback]:::intent
    end
    
    subgraph "Semantic Operations"
        SO1[draft-article]:::semantic
        SO2[pull-for-editing+ edit-document+ sync-to-wordpress]:::semantic
        SO3[view-editorial-feedback]:::semantic
    end
    
    subgraph "WordPress API"
        API1[POST /wp/v2/posts+ Category lookups+ Tag creation+ Status setting]:::api
        API2[GET /wp/v2/posts/:id+ GET categories+ GET tags+ PUT /wp/v2/posts/:id]:::api
        API3[GET /wp/v2/comments+ Filter by post_author+ Parse editorial notes]:::api
    end
    
    H1 --> AI1
    H2 --> AI2
    H3 --> AI3
    
    AI1 --> SO1
    AI2 --> SO2
    AI3 --> SO3
    
    SO1 --> API1
    SO2 --> API2
    SO3 --> API3
    
    classDef human fill:#ec4899,stroke:#db2777,color:#ffffff
    classDef intent fill:#10b981,stroke:#059669,color:#ffffff
    classDef semantic fill:#f59e0b,stroke:#d97706,color:#000000
    classDef api fill:#6366f1,stroke:#4f46e5,color:#ffffff

flowchart TD
    subgraph "MCP Configuration"
        P1[Contributor Personality]:::personality
        P2[Author Personality]:::personality
        P3[Admin Personality]:::personality
    end
    
    subgraph "Available Tools"
        T1[Limited Toolsdraft, edit, submit]:::tools
        T2[Extended Tools+ publish, media]:::tools
        T3[All Tools+ bulk ops, categories]:::tools
    end
    
    subgraph "WordPress User"
        U1[Contributor Account]:::user
        U2[Author Account]:::user
        U3[Admin Account]:::user
    end
    
    subgraph "Actual Capabilities"
        C1[Can only draft]:::capability
        C2[Can publish own]:::capability
        C3[Full control]:::capability
    end
    
    P1 --> T1
    P2 --> T2
    P3 --> T3
    
    T1 --> |Filtered by| U1
    T1 --> |Filtered by| U2
    T1 --> |Filtered by| U3
    
    T2 --> |Filtered by| U1
    T2 --> |Filtered by| U2
    T2 --> |Filtered by| U3
    
    T3 --> |Filtered by| U1
    T3 --> |Filtered by| U2
    T3 --> |Filtered by| U3
    
    U1 --> C1
    U2 --> C2
    U3 --> C3
    
    WP[WordPress Always HasFinal Authority]:::wordpress
    C1 --> WP
    C2 --> WP
    C3 --> WP
    
    classDef personality fill:#8b5cf6,stroke:#7c3aed,color:#ffffff
    classDef tools fill:#0ea5e9,stroke:#0284c7,color:#ffffff
    classDef user fill:#f97316,stroke:#ea580c,color:#ffffff
    classDef capability fill:#22c55e,stroke:#16a34a,color:#000000
    classDef wordpress fill:#dc2626,stroke:#b91c1c,color:#ffffff

# Clone and install
git clone https://github.com/aaronsb/wordpress-mcp
cd wordpress-mcp
npm install

# Run interactive setup
npm run setup

git clone https://github.com/aaronsb/wordpress-mcp
cd wordpress-mcp
npm install

npm run setup

mkdir -p ~/.wordpress-mcp
cat > ~/.wordpress-mcp/.env  Your Profile > Application Passwords` in your WordPress admin.

### 2. Claude Desktop Setup

First, ensure your credentials are configured (run `npm run setup` if needed).

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

The server will read credentials from its `.env` file.

### 3. Claude Code Setup

#### Option A: Using the CLI (Recommended)

First, ensure your `.env` file is configured (run `npm run setup` if needed).

Then, in your project directory, run:

The server will read credentials from the `.env` file in the wordpress-mcp directory.

#### Option B: Manual Configuration

Alternatively, add to your project's `.claude/settings.json`:

Note: The server reads credentials from its `.env` file, not from the Claude configuration.

**Note**: Adjust the personality parameter (`--personality=`) to one of:
- `contributor` - Limited tools for content creation
- `author` - Full authoring capabilities (recommended)
- `administrator` - Complete site management

## Usage

Once configured, the WordPress tools will be available in Claude. You can:

- Create and edit draft posts and pages
- Publish articles and pages with scheduling options
- **Create hierarchical page structures with parent-child relationships**
- **Search posts using natural language**
- **Pull posts/pages for editing with document sessions**
- **Edit content using line-based operations**
- **Sync changes back in single API call**
- Manage media files
- Perform bulk operations (admin only)

### Content Discovery & Editing Workflows

**Semantic Search Examples:**
- "Find my article about potatoes published yesterday"
- "Search for drafts mentioning MCP servers"
- "Show me posts about AI that need editing"
- "Find published articles with comments to review"

**Natural Language Workflows:**
- "Find my article about potatoes and update the cooking section" 
  → AI uses `find-posts` → suggests `pull-for-editing` → guides you through edits
- "Review feedback on my WordPress tutorial"
  → AI searches published posts → uses `view-editorial-feedback`
- "Edit my latest draft about semantic APIs"
  → AI finds recent drafts → pulls for editing → helps with changes

**Page-Specific Workflows:**
- "Create an About Us page"
  → AI uses `draft-page` or `create-page` with clear semantic context
- "Make a Services page under the main Services section"
  → AI creates hierarchical page with parent relationship
- "Edit the Contact page to add new office hours"
  → AI uses `pull-for-editing` with `type: "page"`

**Direct ID-Based Operations (when you know the ID):**
- "Pull post 42 for editing"
- "Pull page 15 for editing"
- "Publish draft with ID 30"
- "Schedule post 55 for next Monday at 9 AM"

### Intelligent Search with Intent

The `find-posts` operation understands what you want to do:

**Intent-based filtering:**
- `intent: "edit"` → Prioritizes drafts you can modify
- `intent: "review"` → Shows pending posts awaiting approval  
- `intent: "publish"` → Finds drafts ready to go live
- `intent: "comment"` → Shows published posts with feedback

**Workflow guidance:**
Each search result includes:
- Suggested next actions based on post status
- Clear instructions for the next step
- Role-appropriate tool recommendations

Example:

### Document Editing Features

**🔄 Transparent Format Conversion:**
- WordPress HTML → Clean Markdown for AI editing
- AI edits in Markdown → WordPress receives formatted HTML
- Preserves **bold**, *italic*, headers, lists, and more
- No HTML entities or encoding issues

**✏️ Flexible Editing Tools:**
- `read-document` - View content with line numbers
- `edit-document-line` - Replace specific lines by number
- `insert-at-line` - Insert content at precise positions
- `replace-lines` - Replace multi-line blocks
- `search-replace` - Context-aware search with line proximity
- `edit-document` - Traditional string replacement (fallback)

### Example Document Session Workflow

**Key Benefits:**
- AI never sees filesystem paths (security + abstraction)
- Edit in clean Markdown without HTML encoding issues
- WordPress receives properly formatted HTML automatically
- Line-based editing avoids string matching failures
- One pull → multiple edits → one push (API efficiency)

## Personality Mappings

The tool mappings are defined in `config/personalities.json`:

### Contributor

**Content Creation:**
- `draft-article` - Create draft posts
- `draft-page` - Create draft pages for static content
- `edit-draft` - Edit existing drafts
- `submit-for-review` - Submit drafts for editorial review
- `view-editorial-feedback` - See editor comments

**Document Session Workflow:**
- `pull-for-editing` - Fetch posts/pages into editing sessions
- `read-document` - Read documents with line numbers
- `edit-document-line` - Replace specific lines by number
- `insert-at-line` - Insert content at line positions
- `replace-lines` - Replace line ranges
- `search-replace` - Context-aware search and replace
- `edit-document` - String replacement (fallback)
- `sync-to-wordpress` - Push all changes back
- `list-editing-sessions` - View active sessions
- `close-editing-session` - Manual session cleanup

### Author

- All contributor tools, plus:

**Publishing:**
- `create-article` - Create and publish posts immediately
- `create-page` - Create and publish pages with hierarchy
- `publish-workflow` - Publish or schedule posts
- `manage-media` - Upload and manage media files

**Content Management:**
- `trash-own-content` - Move your own posts or pages to trash

### Administrator

- All author tools, plus:

**Site Management:**
- `bulk-content-operations` - Bulk actions on posts/pages (trash, restore, delete, change status)
- `manage-all-content` - View and manage all posts
- `review-content` - Review pending posts and comments
- `moderate-comments` - Approve, reject, or manage comments
- `manage-categories` - Create, update, and organize categories

### Editor

- All author tools, plus:

**Editorial Management:**
- `bulk-content-operations` - Bulk actions on posts/pages (trash, restore, delete, change status)
- `review-content` - Review pending posts and comments
- `moderate-comments` - Approve, reject, or manage comments
- `manage-categories` - Create, update, and organize categories

## Adding Custom Personalities

Edit `config/personalities.json` to create custom role mappings:

Then launch with:

## Customization

See [CUSTOMIZATION.md](CUSTOMIZATION.md) for detailed instructions on:
- Creating custom personalities
- Adding new features
- Configuring role-based tool mappings
- Real-world examples (Editor, Reviewer, Social Media Manager)

## Architecture Benefits

1. **No hardcoded roles** - All personality logic lives in configuration
2. **Easy customization** - Modify JSON to change tool availability
3. **WordPress authority** - The API enforces actual permissions
4. **Clean separation** - Features don't know about personalities
5. **Extensible** - Add features and map them without touching core code

## WordPress Permission Handling

The MCP server presents tools based on personality, but **WordPress always has final authority**:

- If a contributor tries to publish (via API manipulation), WordPress returns 403
- If an author tries to edit others' posts, WordPress denies it
- The MCP server gracefully handles these errors with helpful messages

## Development

## License

MIT