@wickedevolutions/abilities-mcp 1.6.2 → 1.6.3

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to Abilities MCP are documented here.
 
+## [1.6.3] - 2026-05-12
+
+### Fixed
+
+- **Sanitizer normalizes array-shaped `inputSchema.properties` (Issue [#83](https://github.com/Wicked-Evolutions/abilities-mcp/issues/83), Sprint C 2026-05-11).** Extends `validateToolSchema` in `lib/sanitizer.js` so that when a tool's `inputSchema.properties` is an array (PHP `'properties' => array()` JSON-encodes to `[]`), `null`, a string, or any other non-plain-object value, it is normalized to `{}` before client emission. The previous v1.6.2 fix (#78/#79) normalized broken top-level `inputSchema` but left malformed nested `properties` untouched — the value passed `typeof === 'object'` (arrays are objects in JS) and reached the `Object.entries()` loop unchanged. Anthropic's draft 2020-12 validator rejects the entire `tools/list` payload on the first invalid schema (`/properties must be object`), so a single vendor-registered `properties: []` shape breaks the whole catalog. Defends against the entire class of vendor-registered ability schema slips that share the `properties: []` shape; SureCart's `surecart/get-store-info` was the trigger case (live capture from helenawillow.com 2026-05-11, 1 of 789 tools failing) but the fix is name-agnostic. Boundary discipline binding: `inputSchema: { type: "object" }` shapes that omit the `properties` key entirely remain byte-unchanged (early-return on `schema.properties === undefined` before the malformed-shape normalize). Already-valid object-shaped `properties` pass through byte-identical (regression-guarded with reference-equality assertion in `test/sanitizer.test.js`).
+
+- **Bridge orientation: `mcp-adapter-*` reliably visible as the cross-site discovery path when filtering is enabled; `wp_browse_tools` / `wp_load_tools` describe themselves honestly (Issue [#85](https://github.com/Wicked-Evolutions/abilities-mcp/issues/85), Sprint C-follow-up 2026-05-12).** Surfaced during v1.6.3 release validation: AI clients were orienting around the bridge-local meta-tools first, treating their default-site catalog as the full ability surface and missing abilities registered only on non-default sites (e.g., `surecart/get-store-info` on helenawillow when `defaultSite=wickedevolutions`). The cross-site execution path via `mcp-adapter-discover-abilities` / `mcp-adapter-get-ability-info` / `mcp-adapter-execute-ability` already worked correctly — it just wasn't the path clients reached for. Three minimal changes restore orientation without changing architecture: (1) `lib/tool-catalog.js` — when `toolFilter.enabled === true` and the operator has not set their own `alwaysIncludeCategories`, default to `['mcp-adapter']` so the five `mcp-adapter-*` tools are always callable without a prior `wp_load_tools` step. Explicit operator override (including `[]`) is honored — guarded against the `[] || ['mcp-adapter']` truthy-array pitfall with an explicit `undefined`/`null` check. (2) `lib/bridge-tools.js` — `wp_browse_tools` and `wp_load_tools` descriptions now explicitly state they operate on the direct-tool catalog scoped to the default site, not full cross-site ability discovery. (3) `lib/router.js` — `wp_browse_tools` response leads with a `Scope:` line; `wp_load_tools` computes which requested categories are missing from the catalog and returns a structured pointer ("Not in the direct-tool catalog (scoped to defaultSite `<site>`): `<category>`. To call abilities in this category on another site, use `mcp-adapter-discover-abilities` with `{site, category}` then `mcp-adapter-execute-ability` with `{site, ability_name, parameters}`") instead of the prior silent "No changes — categories may already be active" zero-activation. No union-catalog architecture introduced; no `defaultSite`-switching workaround required; adapter unchanged. Acceptance pin: with `defaultSite = wickedevolutions` and `toolFilter.enabled = true`, a fresh session can discover and execute `surecart/get-store-info` on `helenawillow` through the adapter meta-tool path without changing `defaultSite` (empirically verified, MD5-pinned behavior-reversal cycle, 415/415 tests passing).
+
+### Compatibility & operator notes
+
+- **No protocol semantics change** for valid schemas. Healthy operators see no behavioral difference. The fix activates only on the malformed-`properties` shape it closes.
+- **No operator action required** — passive defensive normalization on next bridge restart.
+- **Coordinated release wave** — held for joint release with abilities-mcp-adapter v1.4.8 per the cross-sprint coupling decision.
+
 ## [1.6.2] - 2026-05-10
 
 Schema validity polish + boot fragility MVP + multisite topology gate. Four Bridge fixes ship together as a bundled release closing the operator-side schema-400 + the silent-bridge-death-on-expired-refresh-token (both connect-time and request-time refresh boundaries) + the misplaced-multisite-block-cross-product issues.

package/lib/bridge-tools.js

@@ -23,7 +23,8 @@ const BRIDGE_TOOLS = [
   },
   {
     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.',
+    description:
+      'List categories in the bridge\'s direct-tool catalog (scoped to defaultSite) with tool counts and load-state. This is the local-catalog control surface — not full cross-site ability discovery. For abilities on another site, or in a category not listed here, use mcp-adapter-discover-abilities / mcp-adapter-execute-ability with { site }.',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -31,14 +32,16 @@ const BRIDGE_TOOLS = [
   },
   {
     name: 'wp_load_tools',
-    description: 'Activate WordPress tool categories to make their tools available. After loading, the tools list is automatically refreshed.',
+    description:
+      'Activate categories in the bridge\'s direct-tool catalog (scoped to defaultSite) to expose their tools in tools/list. This is the local-catalog control surface — not full cross-site ability discovery. If a requested category is not in the local catalog, the response points to mcp-adapter-discover-abilities + mcp-adapter-execute-ability for the cross-site path.',
     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.',
+          description:
+            'Category names to activate from the direct-tool catalog (e.g. ["fluent-crm", "content", "media"]). Use wp_browse_tools to see available categories. Categories not in the local catalog return a pointer to mcp-adapter-discover-abilities instead of silently activating nothing.',
         },
         deactivate: {
           type: 'array',

package/lib/router.js

@@ -463,14 +463,26 @@ class McpRouter {
       }
 
       const summary = this.catalog.getCategorySummary();
-      const lines = summary.map(c =>
-        `${c.active ? '[LOADED]' : '       '} ${c.name} (${c.toolCount} tools)`
+      const lines = [];
+      lines.push(
+        `Scope: direct-tool catalog scoped to defaultSite (${this.config.defaultSite}). ` +
+          `Not full cross-site ability discovery.`
       );
       lines.push('');
+      for (const c of summary) {
+        lines.push(`${c.active ? '[LOADED]' : '       '} ${c.name} (${c.toolCount} tools)`);
+      }
+      lines.push('');
       lines.push(`Total: ${this.catalog.fullTools.length} tools in ${summary.length} categories`);
       lines.push(`Loaded: ${summary.filter(c => c.active).reduce((n, c) => n + c.toolCount, 0)} tools`);
       lines.push('');
       lines.push('Use wp_load_tools with categories array to activate.');
+      lines.push('');
+      lines.push(
+        'For abilities on another site, or in a category not listed here, use ' +
+          'mcp-adapter-discover-abilities { site, category } and ' +
+          'mcp-adapter-execute-ability { site, ability_name, parameters }.'
+      );
 
       this.sendToClient(JSON.stringify({
         jsonrpc: '2.0', id: msg.id,
@@ -496,6 +508,7 @@ class McpRouter {
       }
 
       const activated = this.catalog.activateCategories(toActivate);
+      const missing = toActivate.filter((c) => !this.catalog.categories[c]);
       const lines = [];
 
       if (activated.length > 0) {
@@ -504,8 +517,25 @@ class McpRouter {
       if (toDeactivate.length > 0) {
         lines.push(`Deactivated: ${toDeactivate.join(', ')}`);
       }
-      if (activated.length === 0 && toDeactivate.length === 0) {
-        lines.push('No changes — categories may already be active or not found.');
+      if (missing.length > 0) {
+        lines.push(
+          `Not in the direct-tool catalog (scoped to defaultSite "${this.config.defaultSite}"): ` +
+            missing.join(', ') +
+            '.'
+        );
+        lines.push(
+          'For abilities on another site, or in a category not in this catalog, use the ' +
+            'adapter meta-tools instead:'
+        );
+        for (const cat of missing) {
+          lines.push(`  mcp-adapter-discover-abilities { site: "<site>", category: "${cat}" }`);
+        }
+        lines.push(
+          '  mcp-adapter-execute-ability { site: "<site>", ability_name: "<ability>", parameters: { ... } }'
+        );
+      }
+      if (activated.length === 0 && toDeactivate.length === 0 && missing.length === 0) {
+        lines.push('No changes — categories may already be active.');
       }
 
       const filtered = this.catalog.getFilteredTools();

package/lib/sanitizer.js

@@ -29,7 +29,19 @@ function validateToolSchema(toolName, schema, log) {
     log(`SCHEMA WARN [${toolName}]: invalid top-level type "${schema.type}"`);
   }
 
-  if (!schema.properties || typeof schema.properties !== 'object') return;
+  // Boundary: properties key absent — leave inputSchema byte-unchanged.
+  if (schema.properties === undefined) return;
+
+  // Normalize malformed `properties` shapes (PHP `array()` JSON-encodes to `[]`,
+  // strings, null, primitives) to `{}` before downstream validation. Anthropic's
+  // draft 2020-12 validator rejects the entire tools/list payload on the first
+  // invalid schema, so a single vendor-registered `properties: []` breaks the
+  // whole catalog. Mirror of the top-level inputSchema normalize one frame up.
+  if (schema.properties === null || typeof schema.properties !== 'object' || Array.isArray(schema.properties)) {
+    log(`SCHEMA NORMALIZE [${toolName}]: inputSchema.properties not a plain object — normalized to {}`);
+    schema.properties = {};
+    return;
+  }
 
   for (const [prop, def] of Object.entries(schema.properties)) {
     if (!def || typeof def !== 'object') {

package/lib/tool-catalog.js

@@ -32,11 +32,22 @@ class ToolCatalog {
     // Active (loaded) categories
     this.activeCategories = new Set();
 
-    // Initialize always-included categories from config
-    if (this.filterConfig && this.filterConfig.alwaysIncludeCategories) {
-      for (const cat of this.filterConfig.alwaysIncludeCategories) {
-        this.activeCategories.add(cat);
-      }
+    // Resolve "always-include" categories once. Explicit operator config wins
+    // (including an explicit empty list, which preserves the operator's choice).
+    // When filtering is enabled and the operator hasn't set their own list,
+    // default to ['mcp-adapter'] so the cross-site adapter meta-tools
+    // (mcp-adapter-discover-abilities / -get-ability-info / -execute-ability)
+    // are always visible without requiring a prior wp_load_tools call.
+    const explicit = this.filterConfig && this.filterConfig.alwaysIncludeCategories;
+    const resolved =
+      explicit !== undefined && explicit !== null
+        ? explicit
+        : this.isEnabled()
+        ? ['mcp-adapter']
+        : [];
+    this.effectiveAlwaysInclude = new Set(resolved);
+    for (const cat of this.effectiveAlwaysInclude) {
+      this.activeCategories.add(cat);
     }
   }
 
@@ -104,12 +115,11 @@ class ToolCatalog {
    * Deactivate categories (return to compact mode).
    */
   deactivateCategories(categoryNames) {
-    // Don't deactivate always-included categories
-    const alwaysIncluded = new Set(
-      (this.filterConfig && this.filterConfig.alwaysIncludeCategories) || []
-    );
+    // Don't deactivate always-included categories (single source of truth:
+    // the set resolved at construction, so the default mcp-adapter inclusion
+    // is treated the same as an explicit operator-configured entry).
     for (const name of categoryNames) {
-      if (!alwaysIncluded.has(name)) {
+      if (!this.effectiveAlwaysInclude.has(name)) {
         this.activeCategories.delete(name);
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wickedevolutions/abilities-mcp",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Open-source MCP bridge connecting AI clients to WordPress through the Abilities API — multi-site routing, zero dependencies",
   "main": "abilities-mcp.js",
   "bin": {