Labsco
aaronsb logo

WordPress Author MCP Server

★ 3

from aaronsb

A personality-based MCP server for WordPress, providing role-appropriate tools for content management.

🔥🔥🔥✓ VerifiedFreeNeeds API keys
#automation#social-media#calendar#git#security

WordPress Author MCP Server

A personality-based Model Context Protocol (MCP) server for WordPress that provides role-appropriate tools for content management. This server enables AI assistants like Claude to create, edit, and manage WordPress content through natural language interactions.

Purpose & Features

  • 🎭 Personality-Based Tool Mapping: Three modes (Contributor/Author/Administrator) with role-appropriate tools
  • 🔧 Semantic Operations: High-level WordPress actions without API complexity
  • 📁 Document Session Workflow: Abstracted temp file editing with opaque handles (no filesystem exposure)
  • 🔄 Transparent Format Conversion: AI edits clean Markdown → WordPress receives formatted HTML
  • ✏️ Flexible Line-Based Editing: Precise line operations + contextual search/replace
  • 🛡️ WordPress-Native Permissions: Let WordPress handle all permission enforcement
  • 📝 Content Management: Create drafts, publish posts/pages, schedule content, manage media
  • ⚡ Map-Based Architecture: JSON configuration for tool assignments, no hardcoded roles

Semantic Architecture

This MCP server is not just an API wrapper. It provides intelligent semantic operations that map human workflows to WordPress actions, with sophisticated state management and format conversion.

Document Session State Flow

flowchart TB
    WP[WordPress HTML Post]:::wordpress
    PFE[pull-for-editing]:::operation
    H2M[HTML→Markdown Conversion]:::converter
    DS[Document Session<br/>Handle: abc123]:::session
    LES[Local Edit State<br/>• Clean Markdown<br/>• Line Numbers<br/>• No HTML Entities]:::state
    
    EDL[edit-document-line]:::edit
    IAL[insert-at-line]:::edit
    SR[search-replace]:::edit
    
    MLS[Modified Local State<br/>Multiple Edits Applied]:::state
    STW[sync-to-wordpress]:::operation
    M2H[Markdown→HTML Conversion]:::converter
    WPU[WordPress Update<br/>Single 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

Semantic Operation Mapping

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<br/>+ edit-document<br/>+ sync-to-wordpress]:::semantic
        SO3[view-editorial-feedback]:::semantic
    end
    
    subgraph "WordPress API"
        API1[POST /wp/v2/posts<br/>+ Category lookups<br/>+ Tag creation<br/>+ Status setting]:::api
        API2[GET /wp/v2/posts/:id<br/>+ GET categories<br/>+ GET tags<br/>+ PUT /wp/v2/posts/:id]:::api
        API3[GET /wp/v2/comments<br/>+ Filter by post_author<br/>+ 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

Key Architectural Components

  1. Document Session Manager

    • Maintains editing sessions with opaque handles
    • No filesystem paths exposed to AI
    • Automatic cleanup on sync

  2. Format Conversion Layer

    • Turndown: HTML → Markdown (with fallbacks)
    • Marked: Markdown → HTML (with fallbacks)
    • Handles WordPress HTML entities transparently

  3. Semantic Operation Engine

    • Maps high-level intents to WordPress workflows
    • Batches related API calls
    • Provides transaction-like operations

  4. Line-Based Edit System

    • Precise line number operations
    • Context-aware search within line ranges
    • Avoids brittle string matching

Permission Flow

flowchart TD
    subgraph "MCP Configuration"
        P1[Contributor Personality]:::personality
        P2[Author Personality]:::personality
        P3[Admin Personality]:::personality
    end
    
    subgraph "Available Tools"
        T1[Limited Tools<br/>draft, edit, submit]:::tools
        T2[Extended Tools<br/>+ publish, media]:::tools
        T3[All Tools<br/>+ 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 Has<br/>Final 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

Documentation

How It Works

  1. Features are defined as standalone modules in src/features/
  2. Personalities map to specific sets of features in config/personalities.json
  3. At launch, specify a personality to expose only its mapped tools
  4. WordPress handles all actual permission enforcement

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:

{
  "custom-editor": {
    "name": "Custom Editor",
    "description": "Custom editorial team member",
    "features": ["manage-all-content", "edit-draft", "publish-workflow", "bulk-content-operations"],
    "context": {
      "can_publish": true,
      "can_edit_others": true
    }
  }
}

Then launch with:

npx wordpress-author-mcp --personality=editor

Customization

See 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

# Run in development mode with auto-reload
npm run dev