@wickedevolutions/abilities-mcp 1.3.1

package/lib/config.js

@@ -0,0 +1,210 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Load configuration from wp-sites.json or build from CLI args.
+ *
+ * Search order for wp-sites.json:
+ *   1. --config=<path> explicit path
+ *   2. Same directory as abilities-mcp.js
+ *   3. ~/.abilities-mcp/wp-sites.json
+ *
+ * If no config file and --host/--path provided, builds a single-site legacy config.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+function loadConfig(args) {
+  // Explicit config path
+  if (args.config) {
+    return loadConfigFile(args.config);
+  }
+
+  // Check alongside script (lib/ → package root)
+  const scriptDir = path.resolve(__dirname, '..');
+  const scriptConfig = path.join(scriptDir, 'wp-sites.json');
+  if (fs.existsSync(scriptConfig)) {
+    return loadConfigFile(scriptConfig);
+  }
+
+  // Check home directory
+  const homeConfig = path.join(os.homedir(), '.abilities-mcp', 'wp-sites.json');
+  if (fs.existsSync(homeConfig)) {
+    return loadConfigFile(homeConfig);
+  }
+
+  // Legacy CLI mode — single site from --host/--path
+  if (args.host && args.path) {
+    return buildLegacyConfig(args);
+  }
+
+  throw new Error(
+    'No wp-sites.json found and no --host/--path provided.\n' +
+    'Create wp-sites.json or use: --host=<ssh-host> --path=<wp-path>'
+  );
+}
+
+function loadConfigFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+
+  // Warn if config file is readable by group or world
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.mode & 0o077) {
+      process.stderr.write(
+        `WARNING: ${filePath} is readable by group/world (mode ${(stat.mode & 0o777).toString(8)}). ` +
+        `Consider running: chmod 600 ${filePath}\n`
+      );
+    }
+  } catch (e) { /* stat failed — skip check */ }
+
+  const config = JSON.parse(raw);
+
+  if (!config.sites || typeof config.sites !== 'object') {
+    throw new Error(`Invalid wp-sites.json: missing "sites" object`);
+  }
+
+  if (!config.defaultSite) {
+    config.defaultSite = Object.keys(config.sites)[0];
+  }
+
+  if (!config.sites[config.defaultSite]) {
+    throw new Error(`Default site "${config.defaultSite}" not found in sites`);
+  }
+
+  // Validate each site
+  for (const [key, site] of Object.entries(config.sites)) {
+    validateSiteConfig(key, site);
+  }
+
+  config._isMultiSite = Object.keys(config.sites).length > 1 ||
+    Object.values(config.sites).some(s => s.multisite);
+  config._configPath = filePath;
+
+  return config;
+}
+
+function validateSiteConfig(key, site) {
+  if (!site.transport) {
+    throw new Error(`Site "${key}": missing "transport" (ssh or http)`);
+  }
+
+  if (site.transport === 'ssh') {
+    if (!site.ssh || !site.ssh.host || !site.ssh.path) {
+      throw new Error(`Site "${key}" (ssh): requires ssh.host and ssh.path`);
+    }
+  } else if (site.transport === 'http') {
+    if (!site.http || !site.http.endpoint || !site.http.username) {
+      throw new Error(`Site "${key}" (http): requires http.endpoint and http.username`);
+    }
+    if (!site.http.password && !site.http.passwordEnv && !site.http.passwordCommand) {
+      throw new Error(`Site "${key}" (http): requires one of http.password, http.passwordEnv, or http.passwordCommand`);
+    }
+    if (!site.http.endpoint.startsWith('https://') && !site.allowInsecure) {
+      throw new Error(`Site "${key}" (http): endpoint is not HTTPS. Set "allowInsecure": true on the site to allow HTTP`);
+    }
+  } else {
+    throw new Error(`Site "${key}": unknown transport "${site.transport}" (use ssh or http)`);
+  }
+}
+
+/**
+ * Build single-site config from legacy CLI args (backward compat with mcp-ssh-bridge).
+ */
+function buildLegacyConfig(args) {
+  return {
+    defaultSite: 'default',
+    _isMultiSite: false,
+    sites: {
+      default: {
+        label: args.host,
+        url: `ssh://${args.host}`,
+        transport: 'ssh',
+        ssh: {
+          host: args.host,
+          path: args.path,
+          user: args.user || '',
+        },
+        mcpServer: args.server || 'mcp-adapter-default-server',
+      }
+    }
+  };
+}
+
+/**
+ * Resolve a composite site key like "wicked.community" into config + subsite URL.
+ */
+function resolveSiteKey(config, compositeKey) {
+  // Direct match — "helena" or "wicked"
+  if (config.sites[compositeKey]) {
+    return { siteConfig: config.sites[compositeKey], subsiteUrl: null, resolvedEndpoint: null };
+  }
+
+  // Dot notation — "wicked.community"
+  const dotIdx = compositeKey.indexOf('.');
+  if (dotIdx > 0) {
+    const siteKey = compositeKey.substring(0, dotIdx);
+    const subsiteKey = compositeKey.substring(dotIdx + 1);
+    const site = config.sites[siteKey];
+    if (site && site.multisite && site.multisite[subsiteKey]) {
+      const subsiteUrl = site.multisite[subsiteKey];
+      let resolvedEndpoint = null;
+
+      // For HTTP transport: build subsite endpoint from subsite URL + parent endpoint path.
+      // This makes WordPress boot natively into the correct blog context —
+      // community.wickedevolutions.com/wp-json/mcp/... boots into blog 2,
+      // not wickedevolutions.com/wp-json/mcp/... which boots into blog 1.
+      if (site.transport === 'http' && site.http && site.http.endpoint) {
+        const parentUrl = new URL(site.http.endpoint);
+        const subsiteOrigin = new URL(subsiteUrl).origin;
+        resolvedEndpoint = subsiteOrigin + parentUrl.pathname;
+      }
+
+      return { siteConfig: site, subsiteUrl, resolvedEndpoint };
+    }
+  }
+
+  throw new Error(`Unknown site: "${compositeKey}". Available: ${Object.keys(config.sites).join(', ')}`);
+}
+
+/**
+ * Build full list of site keys including multisite composites.
+ * e.g. ["helena", "wicked", "wicked.main", "wicked.community"]
+ */
+function buildSiteKeyEnum(config) {
+  const keys = [];
+  for (const [key, site] of Object.entries(config.sites)) {
+    keys.push(key);
+    if (site.multisite) {
+      for (const subKey of Object.keys(site.multisite)) {
+        keys.push(`${key}.${subKey}`);
+      }
+    }
+  }
+  return keys;
+}
+
+/**
+ * Resolve the password for an HTTP transport config, supporting
+ * plaintext password, environment variable, or shell command.
+ */
+function resolvePassword(httpConfig) {
+  if (httpConfig.passwordEnv) {
+    const val = process.env[httpConfig.passwordEnv];
+    if (!val) throw new Error(`Environment variable ${httpConfig.passwordEnv} is not set`);
+    return val;
+  }
+  if (httpConfig.passwordCommand) {
+    return execSync(httpConfig.passwordCommand, { encoding: 'utf8' }).trim();
+  }
+  if (httpConfig.password) {
+    return httpConfig.password;
+  }
+  throw new Error('No password, passwordEnv, or passwordCommand configured');
+}
+
+module.exports = { loadConfig, resolvePassword, resolveSiteKey, buildSiteKeyEnum };

package/lib/connection-pool.js

@@ -0,0 +1,272 @@
+'use strict';
+
+const { SshTransport } = require('./transports/ssh-transport');
+const { resolveSiteKey, resolvePassword } = require('./config');
+
+// Incrementing counter for synthetic handshake IDs.
+// Avoids integer overflow from Date.now() (13-digit ms timestamps exceed
+// 32-bit int max, causing TypeError in PHP strict_types=1 environments).
+// Starting at 1000 to avoid collision with real request IDs (typically 1+).
+let _synthIdCounter = 1000;
+
+/**
+ * Connection Pool — manages one transport per site, lazily instantiated.
+ *
+ * Each site gets its own independent SSH (or HTTP) connection with its own
+ * reconnection state. The pool caches the MCP handshake messages so it can
+ * replay them when connecting to a new site mid-session.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+class ConnectionPool {
+
+  constructor(config, logger) {
+    this.config = config;
+    this.log = logger;
+    this.transports = new Map();      // compositeKey -> Transport
+    this.connecting = new Map();      // compositeKey -> Promise<Transport>
+
+    // Handshake cache — set after the default site completes init
+    this.cachedInitRequest = null;
+    this.cachedInitNotification = null;
+    this.clientProtocolVersion = null;
+  }
+
+  /**
+   * Cache the client's handshake messages for replay to other sites.
+   */
+  setHandshakeCache(initRequest, initNotification, protocolVersion) {
+    this.cachedInitRequest = initRequest;
+    this.cachedInitNotification = initNotification;
+    this.clientProtocolVersion = protocolVersion;
+  }
+
+  /**
+   * Get or lazily create a transport for a composite site key.
+   * Handles "helena", "wicked", "wicked.community" etc.
+   *
+   * For HTTP transport, multisite subsites (e.g. "wicked.community") share the
+   * same endpoint as their parent site ("wicked"). Creating a second transport
+   * to the same endpoint causes session contention. Instead, we reuse the
+   * existing transport — the WordPress MCP adapter handles subsite routing
+   * internally.
+   */
+  async getTransport(compositeKey) {
+    // Return existing
+    if (this.transports.has(compositeKey)) {
+      return this.transports.get(compositeKey);
+    }
+
+    // For HTTP multisite subsites, reuse the parent site's transport if it
+    // connects to the same endpoint. This avoids two transports competing
+    // for sessions on the same WordPress install.
+    const existing = this._findExistingHttpTransport(compositeKey);
+    if (existing) {
+      this.log(`Reusing transport for ${compositeKey} (same endpoint as ${existing.key})`);
+      this.transports.set(compositeKey, existing.transport);
+      return existing.transport;
+    }
+
+    // Prevent concurrent creation
+    if (this.connecting.has(compositeKey)) {
+      return this.connecting.get(compositeKey);
+    }
+
+    const promise = this._create(compositeKey);
+    this.connecting.set(compositeKey, promise);
+    try {
+      const transport = await promise;
+      this.connecting.delete(compositeKey);
+      return transport;
+    } catch (err) {
+      this.connecting.delete(compositeKey);
+      throw err;
+    }
+  }
+
+  /**
+   * Get the default site's transport (must already exist).
+   */
+  getDefaultTransport() {
+    return this.transports.get(this.config.defaultSite) || null;
+  }
+
+  /**
+   * Create and connect transport for the default site (no handshake replay).
+   * Called once at startup — the client handles the handshake directly.
+   */
+  async connectDefault(onMessage) {
+    const key = this.config.defaultSite;
+    const transport = this._createTransport(key, null);
+    transport.onMessage = onMessage;
+    await transport.connect();
+    this.transports.set(key, transport);
+    return transport;
+  }
+
+  /**
+   * Get list of currently connected composite keys.
+   */
+  getConnectedKeys() {
+    return Array.from(this.transports.keys());
+  }
+
+  /**
+   * Check if a composite key has an active, ready transport.
+   */
+  isConnected(compositeKey) {
+    const transport = this.transports.get(compositeKey);
+    return !!(transport && transport.isReady());
+  }
+
+  /**
+   * Probe connectivity to a site. If already connected, checks transport state.
+   * If not connected, does a lightweight SSH or HTTP reachability test.
+   * Returns { status, latencyMs, error? }
+   */
+  async healthCheck(compositeKey) {
+    const start = Date.now();
+
+    // Already connected — check transport state
+    const transport = this.transports.get(compositeKey);
+    if (transport) {
+      if (transport.isReady()) {
+        return { status: 'connected', latencyMs: Date.now() - start };
+      }
+      if (transport.reconnecting) {
+        return { status: 'reconnecting', latencyMs: Date.now() - start };
+      }
+      return { status: 'stale', latencyMs: Date.now() - start };
+    }
+
+    // Not connected — lightweight probe
+    const { resolveSiteKey } = require('./config');
+    try {
+      const { siteConfig } = resolveSiteKey(this.config, compositeKey);
+
+      if (siteConfig.transport === 'ssh') {
+        const { execFileSync } = require('child_process');
+        execFileSync('ssh', [
+          '-o', 'BatchMode=yes',
+          '-o', 'ConnectTimeout=5',
+          siteConfig.ssh.host,
+          'echo ok',
+        ], { timeout: 10000, encoding: 'utf8' });
+        return { status: 'reachable', latencyMs: Date.now() - start };
+      }
+
+      if (siteConfig.transport === 'http') {
+        const mod = siteConfig.http.endpoint.startsWith('https://') ? require('https') : require('http');
+        const url = new URL(siteConfig.http.endpoint);
+        await new Promise((resolve, reject) => {
+          const req = mod.request({
+            hostname: url.hostname, port: url.port,
+            path: url.pathname, method: 'HEAD', timeout: 10000,
+          }, (res) => resolve(res.statusCode));
+          req.on('error', reject);
+          req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+          req.end();
+        });
+        return { status: 'reachable', latencyMs: Date.now() - start };
+      }
+
+      return { status: 'unknown_transport', latencyMs: Date.now() - start };
+    } catch (err) {
+      return { status: 'unreachable', latencyMs: Date.now() - start, error: err.message };
+    }
+  }
+
+  /**
+   * Shut down all transports.
+   */
+  async shutdownAll() {
+    const promises = [];
+    for (const [key, transport] of this.transports) {
+      this.log(`Shutting down transport: ${key}`);
+      promises.push(transport.shutdown());
+    }
+    await Promise.allSettled(promises);
+    this.transports.clear();
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+
+  async _create(compositeKey) {
+    const { subsiteUrl } = resolveSiteKey(this.config, compositeKey);
+
+    this.log(`Lazy-connecting to site: ${compositeKey}`);
+
+    const transport = this._createTransport(compositeKey, subsiteUrl);
+
+    // Set up message callback — route responses back to main
+    // The main entry will set this after getting the transport
+    transport.onMessage = null; // Caller must set this
+
+    await transport.connect();
+
+    // Replay handshake if we have cached init messages
+    if (this.cachedInitRequest) {
+      // Use a numeric ID — WordPress MCP adapter's InitializeHandler declares
+      // strict_types=1 and expects int $request_id. String IDs cause TypeError → 500.
+      const synthInit = { ...this.cachedInitRequest, id: _synthIdCounter++ };
+      await transport.performHandshake(synthInit, this.cachedInitNotification);
+      this.log(`Handshake replayed for ${compositeKey}`);
+    }
+
+    this.transports.set(compositeKey, transport);
+    return transport;
+  }
+
+  _createTransport(compositeKey, subsiteUrl) {
+    const { siteConfig, subsiteUrl: resolvedSubsiteUrl, resolvedEndpoint } = resolveSiteKey(this.config, compositeKey);
+    const finalSubsiteUrl = subsiteUrl || resolvedSubsiteUrl;
+
+    if (siteConfig.transport === 'ssh') {
+      return new SshTransport({
+        host: siteConfig.ssh.host,
+        path: siteConfig.ssh.path,
+        user: siteConfig.ssh.user,
+        mcpServer: siteConfig.mcpServer || 'mcp-adapter-default-server',
+        subsiteUrl: finalSubsiteUrl,
+        logger: this.log,
+      });
+    }
+
+    if (siteConfig.transport === 'http') {
+      // HTTP transport — loaded lazily to avoid requiring it when only SSH is used
+      const { HttpTransport } = require('./transports/http-transport');
+      const password = resolvePassword(siteConfig.http);
+      return new HttpTransport({
+        endpoint: resolvedEndpoint || siteConfig.http.endpoint,
+        username: siteConfig.http.username,
+        password: password,
+        logger: this.log,
+      });
+    }
+
+    throw new Error(`Unknown transport: ${siteConfig.transport}`);
+  }
+
+  /**
+   * Check if a composite key resolves to the same HTTP endpoint as an
+   * already-connected transport. Returns { key, transport } or null.
+   */
+  _findExistingHttpTransport(compositeKey) {
+    const { siteConfig, resolvedEndpoint } = resolveSiteKey(this.config, compositeKey);
+    if (siteConfig.transport !== 'http') return null;
+
+    const targetEndpoint = resolvedEndpoint || siteConfig.http.endpoint;
+
+    for (const [key, transport] of this.transports) {
+      if (transport.endpoint === targetEndpoint) {
+        return { key, transport };
+      }
+    }
+    return null;
+  }
+}
+
+module.exports = { ConnectionPool };

package/lib/logger.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Create a file-based debug logger (opt-in via --debug flag).
+ * Writes to ~/.abilities-mcp/logs/abilities-mcp.log when enabled, no-op otherwise.
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+function createLogger(enabled, logPath) {
+  if (!enabled) return function noop() {};
+
+  const defaultDir = path.join(os.homedir(), '.abilities-mcp', 'logs');
+  const logFile = logPath || path.join(defaultDir, 'abilities-mcp.log');
+  const logDir = path.dirname(logFile);
+
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true, mode: 0o700 });
+  }
+
+  try {
+    const stat = fs.lstatSync(logFile);
+    if (stat.isSymbolicLink()) {
+      process.stderr.write(`abilities-mcp: refusing to write to symlink: ${logFile}\n`);
+      return function noop() {};
+    }
+  } catch (e) {
+    // File doesn't exist yet — fine
+  }
+
+  let fd = null;
+
+  return function log(msg) {
+    if (!fd) fd = fs.openSync(logFile, 'a', 0o600);
+    fs.writeSync(fd, `[${new Date().toISOString()}] ${msg}\n`);
+  };
+}
+
+module.exports = { createLogger };

package/lib/register.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+/**
+ * Register abilities-mcp as a server in Claude Desktop's config.
+ *
+ * @param {object} opts
+ * @param {string} [opts.name='wordpress'] - Server name in config
+ * @param {string} [opts.configPath]       - Explicit wp-sites.json path
+ *
+ * Copyright (C) 2026 Influencentricity | Wicked Evolutions
+ * @license GPL-2.0-or-later
+ */
+function registerClaudeDesktop(opts = {}) {
+  const name = opts.name || 'wordpress';
+
+  // Determine Claude Desktop config path per platform
+  let configDir;
+  if (process.platform === 'darwin') {
+    configDir = path.join(os.homedir(), 'Library', 'Application Support', 'Claude');
+  } else if (process.platform === 'win32') {
+    configDir = path.join(process.env.APPDATA || '', 'Claude');
+  } else {
+    configDir = path.join(os.homedir(), '.config', 'claude');
+  }
+
+  const configPath = path.join(configDir, 'claude_desktop_config.json');
+  const bridgePath = path.resolve(path.join(__dirname, '..', 'abilities-mcp.js'));
+
+  // Build server entry
+  const entryArgs = [bridgePath];
+  if (opts.configPath) {
+    entryArgs.push(`--config=${opts.configPath}`);
+  }
+
+  const entry = {
+    command: 'node',
+    args: entryArgs,
+  };
+
+  // Read or create config
+  let config = { mcpServers: {} };
+  if (fs.existsSync(configPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      if (!config.mcpServers) config.mcpServers = {};
+    } catch (e) {
+      process.stderr.write(`Warning: could not parse ${configPath}, creating new config\n`);
+      config = { mcpServers: {} };
+    }
+  } else {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  const existed = !!config.mcpServers[name];
+  config.mcpServers[name] = entry;
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  process.stderr.write(`${existed ? 'Updated' : 'Added'} MCP server "${name}" in ${configPath}\n`);
+}
+
+module.exports = { registerClaudeDesktop };