@wickedevolutions/abilities-mcp 1.3.1

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+All notable changes to Abilities MCP are documented here.
+
+## [1.3.1] - 2026-03-19
+
+### Fixed
+- Convert execute-ability error payloads to `isError` format — fold `input_schema` into error text for AI self-correction (#2)
+- Convert JSON-RPC error objects to `isError` format for client visibility (#4)
+
+### Changed
+- Remove protocol version rewriting from both transports — Adapter now handles MCP version negotiation natively
+
+## [1.3.0] - 2026-03-11
+
+### Added
+- Schema validation warnings in sanitizer — logs when WordPress responses contain non-standard fields
+- Architecture documentation (`docs/architecture.md`)
+
+### Changed
+- Renamed from WP Abilities MCP to **Abilities MCP**
+- Package name: `@wicked-evolutions/abilities-mcp`
+- Entry point: `abilities-mcp.js`
+- GPL-2.0 compliance headers on all source files
+- Repo cleanup: removed ROADMAP (GitHub project board is the authority), fixed stale references
+
+## [1.2.0] - 2026-03-09
+
+### Added
+- JSON-RPC batch coalescing in `HttpTransport._drainQueue()` — 10ms window accumulates concurrent messages and dispatches as a single JSON-RPC batch POST. Reduces N round-trips to 1 for concurrent multi-agent workloads. Sequential single-agent sessions are unaffected.
+
+### Fixed
+- Fix integer overflow in synthetic handshake IDs — replace `Date.now()` with incrementing counter; 13-digit ms timestamps exceed 32-bit int max, causing `TypeError` in PHP `strict_types=1` environments
+- Fix missing cookie support in HTTP transport — add per-host cookie jar; parse `Set-Cookie` response headers and send `Cookie` on subsequent requests so PHP native sessions aren't dropped between requests
+- Fix incomplete session recovery — extend re-handshake trigger to include HTTP 401/403 when an active session exists; some WordPress configs return these for stale session tokens rather than 404/410
+
+## [1.1.0] - 2026-03-08
+
+### Added
+- Permission metadata passthrough — sanitizer preserves `permission` and `enabled` annotation fields from MCP Adapter
+- `[DISABLED]` label injection — tools with `enabled: false` get description suffix showing required permission level
+- Annotation whitelisting — keeps MCP-compliant fields (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`, `permission`, `enabled`), strips non-standard fields
+- Automated test suite using `node:test` (18 sanitizer tests)
+
+### Fixed
+- Fix multisite blog_id not switching for subsite queries — build per-subsite endpoint URLs so WordPress boots into the correct blog context natively (#3)
+- Fix tool registration failure in Claude Code — strip non-standard annotation fields while preserving MCP-compliant ones (#5)
+- Fix HTTP multisite session loss — reuse existing transport for same-endpoint subsites instead of creating competing connections (#1, PR #2)
+
+## [1.0.0] - 2026-02-26
+
+### Added
+- Unified multi-site MCP bridge
+- HTTP transport with session management (Mcp-Session-Id/Token headers)
+- SSH transport with auto-reconnect, exponential backoff, and healthcheck pings
+- Multi-site routing with `site` parameter injection on all tools
+- Lazy connections — non-default sites connect on first tool call
+- MCP handshake replay for mid-session connections
+- WordPress multisite support via dot notation
+- `wp-sites.json` configuration with config file search order
+- `passwordCommand` and `passwordEnv` for secure credential storage
+- Claude Desktop registration (`--register` flag)
+- Debug logging (`--debug` flag)
+- Zero dependencies — Node.js built-in modules only
+- `wp_bridge_health` — check connectivity status of all configured sites
+- `wp_browse_tools` / `wp_load_tools` — category-based lazy tool loading
+- GitHub infrastructure: issue templates, PR template, Actions workflow
+
+### Security
+- Security audit — 9 findings, all fixed
+- Session token forwarding (Mcp-Session-Token header)
+- Schema sanitization (strips non-standard fields from tool definitions)
+
+### Known Issues
+- Session lock contention with concurrent bridge instances (#4) — server-side MySQL GET_LOCK fix deployed, bridge-side auto-recovery adds ~200ms latency
+
+---
+
+## License
+
+GPL-2.0-or-later

package/LICENSE

@@ -0,0 +1,12 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+For the full license text, see: https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html
+
+This software is distributed under the terms of the GNU General Public License
+version 2 or later (GPL-2.0-or-later).

package/README.md

@@ -0,0 +1,321 @@
+# Abilities MCP
+
+> One MCP to Rule Your WordPress World.
+
+Open-source MCP bridge that connects any AI client to your WordPress sites through the [WordPress Abilities API](https://developer.wordpress.org/reference/functions/wp_register_ability/). Single STDIO server, multi-site routing, zero dependencies.
+
+## Features
+
+- **Multi-site routing** — Single MCP server serves all your WordPress sites
+- **Site parameter injection** — LLM sees a `site` enum on every tool, defaults to your primary site
+- **Lazy connections** — Sites connect on first use, not at startup
+- **HTTP transport** — Application Passwords with MCP session management
+- **WordPress multisite** — Subdomain/subdirectory multisites via dot notation (`site.blog`)
+- **Auto-reconnect** — Exponential backoff, healthcheck pings, session recovery
+- **Zero dependencies** — Node.js built-in modules only
+
+## What You Can Do
+
+The abilities available to your AI agent depend on which ability plugins you install. With [Abilities for AI](https://wickedevolutions.com/abilities-for-ai) installed, your agent gets access to:
+
+**Content & Publishing** — content, blocks, patterns, media, menus, taxonomies, comments, revisions
+**Site Management** — plugins, themes, settings, users, site health, cache, cron, rewrite rules
+**Infrastructure** — filesystem, meta, REST discovery, knowledge layer
+**Third-party integrations** — auto-detected modules for supported plugins (Astra, Spectra, SureCart, Presto Player, and more)
+
+Additional ability plugins extend coverage further. For example, [Abilities for Fluent Plugins](https://github.com/Wicked-Evolutions/abilities-for-fluent-plugins) adds modules for FluentCRM, Fluent Community, Fluent Forms, FluentBooking, Fluent Support, Fluent Boards, FluentSMTP, FluentAuth, Fluent Snippets, Fluent Messaging, FluentCart, and FluentAffiliate.
+
+Every ability enforces `current_user_can()` at execution time — your WordPress role is the security boundary.
+
+> **Sign up for the Abilities for AI alpha release:** https://wickedevolutions.com/abilities-for-ai
+
+## Quick Start
+
+### 1. Set up WordPress
+
+Create a dedicated WordPress user for AI access and generate an Application Password.
+
+**In WordPress Admin → Users → Add New:**
+
+| Field | Value |
+|-------|-------|
+| Username | `mcp-agent` (or any name you prefer) |
+| Role | **Administrator** for full access, or **Editor** for content-only access |
+
+**Then generate an Application Password:**
+
+Go to **Users → Edit (your mcp-agent user) → Application Passwords**, enter a name (e.g. "MCP Bridge"), and click **Add New Application Password**. Copy the generated password — it's shown only once.
+
+#### Choosing a role
+
+| Role | Access | Use case |
+|------|--------|----------|
+| **Administrator** | All modules — content, plugins, themes, settings, users, cache, cron, filesystem, and more | Full site management |
+| **Editor** | Content, Blocks, Taxonomies, Patterns, Meta, Media | Content publishing workflows — safe for teams where AI should write but not configure |
+
+> **Tip:** Start with Editor. Upgrade to Administrator when you need infrastructure abilities like plugin management, theme switching, or settings changes.
+
+#### Required plugins
+
+Install both on your WordPress site:
+
+1. **[Abilities for AI](https://wickedevolutions.com/abilities-for-ai)** — registers WordPress abilities across content, site management, infrastructure, and third-party integration modules
+2. **[Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter)** — exposes abilities as MCP tools via REST API
+
+### 2. Configure your sites
+
+Copy the example config and edit:
+
+```bash
+cp wp-sites.example.json wp-sites.json
+```
+
+Edit `wp-sites.json` with your site details.
+
+### 3. Add to your MCP client
+
+Works with any MCP-compatible client — Claude Code, Claude Desktop, Gemini CLI, Cursor, Windsurf, VS Code, and any other IDE or AI tool that supports the Model Context Protocol.
+
+Add the server to your client's MCP config (usually `.mcp.json`, `settings.json`, or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "node",
+      "args": ["/path/to/abilities-mcp/abilities-mcp.js"]
+    }
+  }
+}
+```
+
+| Client | Config location |
+|--------|----------------|
+| Claude Code | `.mcp.json` in project root or `~/.claude/.mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (or use `--register`) |
+| Gemini CLI | `~/.gemini/settings.json` |
+| Cursor | `.cursor/mcp.json` in project root |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
+| VS Code (Copilot) | `.vscode/mcp.json` in project root |
+
+For Claude Desktop, you can also auto-register:
+
+```bash
+node abilities-mcp.js --register
+```
+
+## Configuration
+
+### `wp-sites.json`
+
+```json
+{
+  "defaultSite": "mysite",
+  "sites": {
+    "mysite": {
+      "label": "My WordPress Site",
+      "url": "https://example.com",
+      "transport": "http",
+      "http": {
+        "endpoint": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
+        "username": "mcp-agent",
+        "passwordCommand": "security find-generic-password -a mcp-agent -s example.com -w"
+      }
+    }
+  }
+}
+```
+
+### Config file search order
+
+1. `--config=/path/to/wp-sites.json` (explicit)
+2. Same directory as `abilities-mcp.js`
+3. `~/.abilities-mcp/wp-sites.json`
+
+### WordPress Multisite
+
+For WordPress multisites, add a `multisite` object mapping subsite keys to their URLs:
+
+```json
+{
+  "network": {
+    "label": "My Network",
+    "transport": "http",
+    "http": {
+      "endpoint": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
+      "username": "mcp-agent",
+      "passwordCommand": "security find-generic-password -a mcp-agent -s example.com -w"
+    },
+    "multisite": {
+      "main": "https://example.com/",
+      "blog": "https://blog.example.com/",
+      "shop": "https://shop.example.com/"
+    }
+  }
+}
+```
+
+Use dot notation to target subsites: `"site": "network.blog"`
+
+### Secure password storage
+
+Three options for providing Application Passwords, from most to least secure:
+
+#### `passwordCommand` (recommended)
+
+Runs a shell command at startup and uses stdout as the password. Works with any OS keychain or secrets manager:
+
+```json
+{
+  "http": {
+    "endpoint": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
+    "username": "mcp-agent",
+    "passwordCommand": "security find-generic-password -a mcp-agent -s example.com -w"
+  }
+}
+```
+
+**macOS Keychain** — store the password first, then reference it:
+
+```bash
+# Store (one-time)
+security add-generic-password -a mcp-agent -s example.com -w 'YOUR_APP_PASSWORD'
+
+# The passwordCommand retrieves it at runtime
+"passwordCommand": "security find-generic-password -a mcp-agent -s example.com -w"
+```
+
+**Linux (secret-tool / GNOME Keyring):**
+
+```bash
+# Store
+secret-tool store --label="WP MCP" service example.com user mcp-agent <<< 'YOUR_APP_PASSWORD'
+
+# Config
+"passwordCommand": "secret-tool lookup service example.com user mcp-agent"
+```
+
+**1Password CLI:**
+
+```bash
+"passwordCommand": "op read 'op://Vault/WordPress MCP/password'"
+```
+
+#### `passwordEnv`
+
+Reads the password from an environment variable. Useful in CI/CD, Docker, or when you set secrets via `.env` files:
+
+```json
+{
+  "http": {
+    "endpoint": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
+    "username": "mcp-agent",
+    "passwordEnv": "WP_MCP_PASSWORD"
+  }
+}
+```
+
+Set the variable before starting the bridge:
+
+```bash
+# Shell export
+export WP_MCP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx"
+
+# Or in a .env file loaded by your shell/Docker
+WP_MCP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
+```
+
+The bridge reads `process.env.WP_MCP_PASSWORD` at connection time. If the variable is not set, it throws an error immediately.
+
+#### `password` (not recommended)
+
+Plaintext password directly in the config. Avoid this — config files end up in repos, backups, and logs:
+
+```json
+{
+  "http": {
+    "password": "xxxx xxxx xxxx xxxx xxxx xxxx"
+  }
+}
+```
+
+#### Priority order
+
+If multiple are set: `passwordEnv` → `passwordCommand` → `password`.
+
+## Bridge Tools
+
+The bridge provides three built-in tools (not forwarded to WordPress):
+
+| Tool | Description |
+|------|-------------|
+| `wp_bridge_health` | Check connectivity status of all configured WordPress sites |
+| `wp_browse_tools` | List WordPress tool categories with counts (requires `toolFilter.enabled: true`) |
+| `wp_load_tools` | Activate/deactivate tool categories for lazy loading |
+
+## Usage
+
+### Multi-site mode
+
+When multiple sites are configured, every tool gets an optional `site` parameter:
+
+```json
+{
+  "name": "content-list",
+  "arguments": {
+    "site": "staging",
+    "post_type": "post"
+  }
+}
+```
+
+Omit `site` to use the default site.
+
+## CLI Options
+
+| Flag | Description |
+|------|-------------|
+| `--config=<path>` | Path to wp-sites.json |
+| `--server=<name>` | MCP adapter server name |
+| `--debug` | Enable debug logging to `/tmp/abilities-mcp.log` |
+| `--register` | Register in Claude Desktop config |
+| `--name=<name>` | Server name for `--register` (default: `wordpress`) |
+
+## Architecture
+
+```mermaid
+graph TD
+    Client[AI Client<br/>Claude Code · Gemini CLI · Cursor · any MCP client] -->|STDIO| Bridge[Abilities MCP]
+    Bridge -->|HTTP POST| SiteA[Site A]
+    Bridge -->|HTTP POST| SiteB[Site B]
+    Bridge -->|SSH + WP-CLI| SiteC[Site C]
+
+    subgraph "Each WordPress Site"
+        Adapter[Abilities MCP Adapter] --> AbilitiesAPI[WordPress Abilities API]
+        AbilitiesAPI --> Plugins[Ability Plugins]
+    end
+```
+
+- One STDIO process handles all sites through a unified connection pool
+- **HTTP transport** — Application Passwords with MCP session management, batch coalescing, auto-reconnect
+- **SSH transport** — WP-CLI over SSH tunnel, healthcheck pings, handshake replay
+- Lazy connections — non-default sites connect on first tool call
+- Tool list comes from the default site with `site` enum injected
+- Permission metadata (`permission`, `enabled`) flows through annotations to the LLM
+- Error responses include `input_schema` for AI self-correction
+
+See [docs/architecture.md](docs/architecture.md) for the full technical deep dive — transport comparison tables, session management, multi-site routing internals, and security model.
+
+## Known Limitations
+
+- **Session lock contention** ([#4](https://github.com/Wicked-Evolutions/abilities-mcp/issues/4)) — Concurrent bridge instances targeting the same site can cause session loss. Use a single bridge process per site.
+
+## Requirements
+
+- Node.js >= 18
+- WordPress 6.9+ with [Abilities for AI](https://wickedevolutions.com/abilities-for-ai) and [Abilities MCP Adapter](https://github.com/Wicked-Evolutions/abilities-mcp-adapter) installed
+- Application Passwords enabled (default in WordPress 5.6+)
+
+## License
+
+GPL-2.0-or-later

package/abilities-mcp.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * abilities-mcp v1.0.0
+ *
+ * One MCP to Rule Your WordPress World.
+ *
+ * Unified multi-site MCP bridge for WordPress Abilities API. Replaces
+ * mcp-ssh-bridge and mcp-http-bridge with a single STDIO server that
+ * routes tool calls to any configured WordPress site via SSH or HTTP.
+ *
+ * Usage:
+ *   node abilities-mcp.js                                    (uses wp-sites.json)
+ *   node abilities-mcp.js --config=/path/to/wp-sites.json    (explicit config)
+ *   node abilities-mcp.js --host=<ssh-host> --path=<wp-path> (legacy single-site)
+ *   node abilities-mcp.js --register [--name=<name>]         (Claude Desktop setup)
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @package Wicked-Evolutions/abilities-mcp
+ * @version 1.0.0
+ * @license GPL-2.0-or-later
+ */
+
+'use strict';
+
+const { createLogger } = require('./lib/logger');
+const { loadConfig, buildSiteKeyEnum } = require('./lib/config');
+const { ConnectionPool } = require('./lib/connection-pool');
+const { ToolCatalog } = require('./lib/tool-catalog');
+const { McpRouter } = require('./lib/router');
+const { SshTransport } = require('./lib/transports/ssh-transport');
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const args = {};
+process.argv.slice(2).forEach(arg => {
+  if (arg.startsWith('--')) {
+    const [key, ...rest] = arg.slice(2).split('=');
+    args[key] = rest.length ? rest.join('=') : true;
+  }
+});
+
+const debug    = !!args.debug;
+const register = !!args.register;
+
+// ---------------------------------------------------------------------------
+// Registration mode (--register)
+// ---------------------------------------------------------------------------
+
+if (register) {
+  const { registerClaudeDesktop } = require('./lib/register');
+  registerClaudeDesktop({ name: args.name || 'wordpress', configPath: args.config });
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Initialize
+// ---------------------------------------------------------------------------
+
+const log = createLogger(debug);
+log('abilities-mcp v1.0.0 starting');
+
+// Ensure SSH agent is available (macOS launchd discovery)
+SshTransport.ensureSshAuthSock();
+
+let config;
+try {
+  config = loadConfig(args);
+} catch (err) {
+  process.stderr.write(`abilities-mcp: ${err.message}\n`);
+  process.exit(1);
+}
+
+const isMultiSite = config._isMultiSite;
+const siteKeys = buildSiteKeyEnum(config);
+log(`Config loaded: ${siteKeys.length} site(s): ${siteKeys.join(', ')} (default: ${config.defaultSite})`);
+log(`Multi-site mode: ${isMultiSite}`);
+
+const pool = new ConnectionPool(config, log);
+const catalog = new ToolCatalog(config, log);
+
+if (catalog.isEnabled()) {
+  log('Tool filtering enabled');
+} else {
+  log('Tool filtering disabled (no toolFilter in config or enabled: false)');
+}
+
+function sendToClient(data) {
+  process.stdout.write(data + '\n');
+}
+
+const router = new McpRouter({
+  config,
+  siteKeys,
+  isMultiSite,
+  pool,
+  catalog,
+  sendToClient,
+  log,
+});
+
+// ---------------------------------------------------------------------------
+// Client STDIO processing
+// ---------------------------------------------------------------------------
+
+let inputBuffer = '';
+
+process.stdin.on('data', (chunk) => {
+  inputBuffer += chunk.toString();
+
+  let newlineIdx;
+  while ((newlineIdx = inputBuffer.indexOf('\n')) !== -1) {
+    const line = inputBuffer.slice(0, newlineIdx);
+    inputBuffer = inputBuffer.slice(newlineIdx + 1);
+    if (line.trim()) {
+      let msg;
+      try {
+        msg = JSON.parse(line.trim());
+      } catch (e) {
+        log(`Non-JSON from client (dropped): ${line.substring(0, 200)}`);
+        continue;
+      }
+      router.handleClientMessage(msg, line.trim());
+    }
+  }
+});
+
+process.stdin.on('end', () => {
+  log('Client stdin closed — shutting down');
+  shutdown();
+});
+
+// ---------------------------------------------------------------------------
+// Startup — connect to default site
+// ---------------------------------------------------------------------------
+
+(async function main() {
+  try {
+    const transport = await pool.connectDefault((parsedMsg, rawLine) => {
+      router.handleTransportMessage(parsedMsg, rawLine);
+    });
+    router.setDefaultTransport(transport);
+    log(`Default transport connected: ${config.defaultSite}`);
+    router.drainEarlyQueue();
+  } catch (err) {
+    process.stderr.write(`abilities-mcp: Failed to connect to default site: ${err.message}\n`);
+    process.exit(1);
+  }
+})();
+
+// ---------------------------------------------------------------------------
+// Signal handling
+// ---------------------------------------------------------------------------
+
+function shutdown() {
+  log('Shutting down');
+  pool.shutdownAll().then(() => {
+    process.exit(0);
+  }).catch(() => {
+    process.exit(1);
+  });
+}
+
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+process.on('unhandledRejection', (reason) => {
+  log(`Unhandled rejection: ${reason}`);
+});

package/lib/bridge-tools.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * Bridge tools — synthetic tools handled locally, never forwarded to WordPress.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+
+const BRIDGE_TOOLS = [
+  {
+    name: 'wp_bridge_health',
+    description: 'Check connectivity status of all configured WordPress sites. Returns status (connected/reachable/unreachable) and latency for each site.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        site: {
+          type: 'string',
+          description: 'Optional: check only this site. Omit to check all configured sites.',
+        },
+      },
+    },
+  },
+  {
+    name: 'wp_browse_tools',
+    description: 'List available WordPress tool categories with tool counts. Shows which categories are currently loaded. Use wp_load_tools to activate categories.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'wp_load_tools',
+    description: 'Activate WordPress tool categories to make their tools available. After loading, the tools list is automatically refreshed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        categories: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Category names to activate (e.g. ["fluent-crm", "content", "media"]). Use wp_browse_tools to see available categories.',
+        },
+        deactivate: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Optional: category names to deactivate (unload from the tools list).',
+        },
+      },
+      required: ['categories'],
+    },
+  },
+];
+
+const BRIDGE_TOOL_NAMES = new Set(BRIDGE_TOOLS.map(t => t.name));
+
+function isBridgeTool(name) {
+  return BRIDGE_TOOL_NAMES.has(name);
+}
+
+function injectBridgeTools(msg) {
+  if (!msg.result || !Array.isArray(msg.result.tools)) return;
+  for (const tool of BRIDGE_TOOLS) {
+    msg.result.tools.push(tool);
+  }
+}
+
+module.exports = { BRIDGE_TOOLS, isBridgeTool, injectBridgeTools };