mcp-core.php
4 months ago
mcp-rest.php
4 months ago
mcp.conf
1 year ago
mcp.js
8 months ago
mcp.md
8 months ago
mcp.php
4 months ago
mcp.md
319 lines
| 1 | # Using MCP with AI Engine |
| 2 | |
| 3 | ## What's this all about? |
| 4 | |
| 5 | **Model‑Context‑Protocol (MCP)** is the open standard Claude uses to talk to external *tool servers.* When Claude detects an MCP server it can: |
| 6 | |
| 7 | 1. **list** the server's tools (`tools/list`), |
| 8 | 2. (optionally) let you pick one, then |
| 9 | 3. **call** a tool (`tools/call`) via JSON‑RPC. |
| 10 | |
| 11 | With **AI Engine** active your WordPress site publishes **30‑plus tools** that let Claude: |
| 12 | |
| 13 | - read & write posts, pages and custom post‑types, |
| 14 | - upload or generate media, |
| 15 | - manage categories, tags & any taxonomy, |
| 16 | - switch, fork and live‑edit themes, |
| 17 | - list plugins… and more. |
| 18 | |
| 19 | `mcp.js` is the Node relay that connects Claude Desktop to your WordPress site seamlessly. |
| 20 | |
| 21 | > **Heads‑up – advanced users only.** Everything here is still beta. Be ready for CLI work, PHP/FPM restarts and some detective work if hosting layers interfere. |
| 22 | |
| 23 | --- |
| 24 | |
| 25 | ## 1 · Quick Start |
| 26 | |
| 27 | ### Requirements |
| 28 | - **WordPress 6.x** with REST API enabled |
| 29 | - **AI Engine plugin** active |
| 30 | - **Claude Desktop ≥ 0.9.2** |
| 31 | - **Node ≥ 20.19.0** |
| 32 | |
| 33 | ### Setup (2 simple steps) |
| 34 | |
| 35 | 1. **Get your No-Auth URL from WordPress** |
| 36 | - Go to **AI Engine › DevTools › MCP Settings** |
| 37 | - Enable **No-Auth URL** |
| 38 | - Copy the full URL (e.g., `https://yoursite.com/wp-json/mcp/v1/abc123token/sse`) |
| 39 | |
| 40 | 2. **Add your site and test** |
| 41 | ```bash |
| 42 | ./mcp.js add https://yoursite.com/wp-json/mcp/v1/YOUR_TOKEN/sse |
| 43 | ./mcp.js start |
| 44 | ``` |
| 45 | |
| 46 | That's it! Claude should now show a **plug icon** and **hammer** with ≈30 tools. |
| 47 | |
| 48 | --- |
| 49 | |
| 50 | ## 2 · Available Commands |
| 51 | |
| 52 | ```bash |
| 53 | # Add a new site with No-Auth URL (automatically sets it as Claude's target) |
| 54 | ./mcp.js add <noauth-url> |
| 55 | # Example: ./mcp.js add https://example.com/wp-json/mcp/v1/abc123/sse |
| 56 | |
| 57 | # List all registered sites (→ shows current Claude target) |
| 58 | ./mcp.js list |
| 59 | |
| 60 | # Interactively select which site Claude should use |
| 61 | ./mcp.js select |
| 62 | |
| 63 | # Test connection with verbose output |
| 64 | ./mcp.js start |
| 65 | |
| 66 | # Remove a site |
| 67 | ./mcp.js remove <site-url> |
| 68 | |
| 69 | # Advanced: Manual testing |
| 70 | ./mcp.js post <domain> <json> <session_id> |
| 71 | ``` |
| 72 | |
| 73 | ### Smart Defaults |
| 74 | - `start` automatically uses the site Claude is configured for |
| 75 | - `add` automatically sets the new site as Claude's target |
| 76 | - `select` shows a numbered menu when you have multiple sites |
| 77 | |
| 78 | --- |
| 79 | |
| 80 | ## 3 · Testing Your Connection |
| 81 | |
| 82 | When you run `./mcp.js start`, you'll see: |
| 83 | |
| 84 | ``` |
| 85 | /\_/\ |
| 86 | ( o.o ) |
| 87 | > ^ < Welcome to MCP by AI Engine |
| 88 | |
| 89 | ▶ Connecting to MCP server |
| 90 | https://yoursite.com/wp-json/mcp/v1/sse/ |
| 91 | |
| 92 | ✓ SSE connection established |
| 93 | ✓ MCP server connected |
| 94 | https://yoursite.com/wp-json/mcp/v1/messages?session_id=abc123... |
| 95 | |
| 96 | Test the connection in another terminal: |
| 97 | ./mcp.js post yoursite.com '{"jsonrpc":"2.0","method":"tools/list","id":1}' abc123... |
| 98 | |
| 99 | Or test with simple ping (requires Tuned Core): |
| 100 | ./mcp.js post yoursite.com '{"jsonrpc":"2.0","method":"mcp_ping","id":2}' abc123... |
| 101 | |
| 102 | Results will appear in this terminal. |
| 103 | ``` |
| 104 | |
| 105 | Just copy-paste one of the test commands to verify everything works! |
| 106 | |
| 107 | --- |
| 108 | |
| 109 | ## 4 · Multiple Sites Made Easy |
| 110 | |
| 111 | If you have multiple WordPress sites: |
| 112 | |
| 113 | ```bash |
| 114 | # Add all your sites (get each No-Auth URL from WordPress) |
| 115 | ./mcp.js add https://site1.com/wp-json/mcp/v1/token1/sse |
| 116 | ./mcp.js add https://site2.com/wp-json/mcp/v1/token2/sse |
| 117 | ./mcp.js add https://site3.com/wp-json/mcp/v1/token3/sse |
| 118 | |
| 119 | # See which one Claude is using |
| 120 | ./mcp.js list |
| 121 | # Output: |
| 122 | # → https://site3.com |
| 123 | # • https://site1.com |
| 124 | # • https://site2.com |
| 125 | |
| 126 | # Switch to a different site |
| 127 | ./mcp.js select |
| 128 | # Shows interactive menu: |
| 129 | # Select a site for Claude: |
| 130 | # 1. https://site1.com |
| 131 | # 2. https://site2.com |
| 132 | # 3. https://site3.com (current) |
| 133 | # |
| 134 | # Enter selection (1-3): 1 |
| 135 | # ✓ Claude → https://site1.com |
| 136 | ``` |
| 137 | |
| 138 | --- |
| 139 | |
| 140 | ## 5 · Prompt Ideas |
| 141 | |
| 142 | | Level | Example | |
| 143 | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | |
| 144 | | *Simple* | "List my latest 5 posts." "Create a post titled *My AI Journey* (one paragraph) and attach a media‑library image." | |
| 145 | | *Intermediate* | "Look at the 10 newest posts, then publish a logical follow‑up. Re‑use existing categories & tags. If no image fits, generate one." | |
| 146 | | *Advanced* | "Fork *Twenty Twenty‑One* into a grid‑layout theme called *Futurism* supporting post types Article & Project." | |
| 147 | |
| 148 | --- |
| 149 | |
| 150 | ## 6 · Troubleshooting |
| 151 | |
| 152 | ### Authentication Issues |
| 153 | - **Claude shows no tools**: Verify your No-Auth URL is correct |
| 154 | - **401/403 errors**: Get a fresh No-Auth URL from WordPress → AI Engine → Dev Tools → MCP Settings |
| 155 | - **Invalid URL format**: Make sure you copied the full URL including `/sse` at the end |
| 156 | |
| 157 | ### Connection Issues |
| 158 | - **Can't connect**: Test the No-Auth URL directly in a browser - you should see SSE connection |
| 159 | - **Stalls on managed hosting**: See hosting caveats below |
| 160 | |
| 161 | ### Quick Reset |
| 162 | ```bash |
| 163 | ./mcp.js remove yoursite.com |
| 164 | # Get fresh No-Auth URL from WordPress, then: |
| 165 | ./mcp.js add https://yoursite.com/wp-json/mcp/v1/NEW_TOKEN/sse |
| 166 | ./mcp.js start # test again |
| 167 | ``` |
| 168 | |
| 169 | --- |
| 170 | |
| 171 | ## 7 · Hosting Caveats |
| 172 | |
| 173 | ### Edge Caching (Cloudflare/Kinsta) |
| 174 | Edge caching must be **bypassed** for `/wp-json/mcp/*` routes: |
| 175 | |
| 176 | *Cloudflare Dashboard › Rules › Bypass Cache* for pattern `/wp-json/mcp/*` |
| 177 | |
| 178 | ### PHP Worker Limits |
| 179 | Each SSE connection uses one PHP worker. On shared hosting (5-8 workers), multiple Claude tabs can exhaust your pool. |
| 180 | |
| 181 | ### If Site Stalls |
| 182 | ```bash |
| 183 | # Reset and restart PHP |
| 184 | sudo systemctl restart php-fpm |
| 185 | ./mcp.js start # try again |
| 186 | ``` |
| 187 | |
| 188 | --- |
| 189 | |
| 190 | ## 8 · Advanced Usage |
| 191 | |
| 192 | ### Manual JSON-RPC Testing |
| 193 | ```bash |
| 194 | # Test tools list |
| 195 | ./mcp.js post yoursite.com '{"jsonrpc":"2.0","method":"tools/list","id":1}' SESSION_ID |
| 196 | |
| 197 | # Test simple ping (requires Tuned Core) |
| 198 | ./mcp.js post yoursite.com '{"jsonrpc":"2.0","method":"mcp_ping","id":2}' SESSION_ID |
| 199 | ``` |
| 200 | |
| 201 | ### Logs Location |
| 202 | All logs are stored in `~/.mcp/`: |
| 203 | - `mcp.log` - Headers and requests |
| 204 | - `mcp-results.log` - Full responses |
| 205 | - `error.log` - Errors and crashes |
| 206 | - `sites.json` - Your registered sites |
| 207 | |
| 208 | ### Verbose PHP Logging |
| 209 | ```php |
| 210 | // wp-content/plugins/ai-engine/classes/modules/mcp.php |
| 211 | private $logging = true; |
| 212 | ``` |
| 213 | |
| 214 | Then tail `wp-content/debug.log`. |
| 215 | |
| 216 | ### Adding Custom MCP Tools |
| 217 | |
| 218 | Developers can extend MCP with custom tools using WordPress filters. Here's an example that adds a search function: |
| 219 | |
| 220 | ```php |
| 221 | // In your theme's functions.php or a custom plugin |
| 222 | |
| 223 | // Register your custom tool |
| 224 | add_filter( 'mwai_mcp_tools', function( $tools ) { |
| 225 | $tools[] = [ |
| 226 | 'name' => 'search_posts', |
| 227 | 'description' => 'Search posts by keyword and return titles with URLs', |
| 228 | 'inputSchema' => [ |
| 229 | 'type' => 'object', |
| 230 | 'properties' => [ |
| 231 | 'keyword' => [ |
| 232 | 'type' => 'string', |
| 233 | 'description' => 'The keyword to search for in post titles and content', |
| 234 | ], |
| 235 | 'limit' => [ |
| 236 | 'type' => 'number', |
| 237 | 'description' => 'Maximum number of results to return (default: 10)', |
| 238 | 'default' => 10, |
| 239 | ], |
| 240 | ], |
| 241 | 'required' => ['keyword'], |
| 242 | ], |
| 243 | ]; |
| 244 | |
| 245 | return $tools; |
| 246 | }); |
| 247 | |
| 248 | // Handle the tool execution - just return the result! |
| 249 | add_filter( 'mwai_mcp_callback', function( $result, $tool, $args, $id ) { |
| 250 | if ( $tool !== 'search_posts' ) { |
| 251 | return $result; |
| 252 | } |
| 253 | |
| 254 | $keyword = $args['keyword'] ?? ''; |
| 255 | $limit = $args['limit'] ?? 10; |
| 256 | |
| 257 | // Perform the search |
| 258 | $query = new WP_Query([ |
| 259 | 's' => $keyword, |
| 260 | 'post_type' => 'post', |
| 261 | 'post_status' => 'publish', |
| 262 | 'posts_per_page' => $limit, |
| 263 | ]); |
| 264 | |
| 265 | $results = []; |
| 266 | if ( $query->have_posts() ) { |
| 267 | while ( $query->have_posts() ) { |
| 268 | $query->the_post(); |
| 269 | $results[] = [ |
| 270 | 'title' => get_the_title(), |
| 271 | 'url' => get_permalink(), |
| 272 | 'excerpt' => get_the_excerpt(), |
| 273 | 'date' => get_the_date(), |
| 274 | ]; |
| 275 | } |
| 276 | wp_reset_postdata(); |
| 277 | } |
| 278 | |
| 279 | // Simply return the results - AI Engine handles the JSON-RPC wrapping! |
| 280 | return $results; |
| 281 | |
| 282 | // You can also return: |
| 283 | // - A string: return 'Found ' . count($results) . ' posts'; |
| 284 | // - An array with 'content' key for custom formatting: |
| 285 | // return [ |
| 286 | // 'content' => [ |
| 287 | // ['type' => 'text', 'text' => 'Search results:'], |
| 288 | // ['type' => 'text', 'text' => json_encode($results)] |
| 289 | // ] |
| 290 | // ]; |
| 291 | }, 10, 4 ); |
| 292 | ``` |
| 293 | |
| 294 | This simplified example shows: |
| 295 | - Using `mwai_mcp_tools` filter to register new tools |
| 296 | - Defining proper `inputSchema` for tool parameters |
| 297 | - Using `mwai_mcp_callback` filter to handle tool execution |
| 298 | - **Just returning your data** - AI Engine automatically handles the JSON-RPC protocol! |
| 299 | |
| 300 | The callback can return: |
| 301 | - **A string**: Simple text response |
| 302 | - **An array**: Will be JSON-encoded and sent to Claude |
| 303 | - **An array with 'content' key**: For custom formatting with multiple text blocks |
| 304 | - **Throw an Exception**: For error handling (AI Engine will format it properly) |
| 305 | |
| 306 | Claude will automatically discover your custom tool and can use it like: |
| 307 | > "Search for posts about 'artificial intelligence' and show me the top 5 results" |
| 308 | |
| 309 | --- |
| 310 | |
| 311 | ## 9 · What Happens Under the Hood |
| 312 | |
| 313 | 1. `mcp.js` opens a long‑lived **SSE** connection to `/wp-json/mcp/v1/sse` |
| 314 | 2. WordPress sends back a session URL: `/wp-json/mcp/v1/messages?session_id=...` |
| 315 | 3. The relay tunnels Claude's JSON‑RPC to that messages endpoint |
| 316 | 4. Responses stream back to Claude via stdout |
| 317 | 5. When Claude quits, the relay sends `{"method":"mwai/kill"}` and cleans up |
| 318 | |
| 319 | Simple and reliable! |