'mcp-adapter/discover-abilities', 'tool_get_ability_info' => 'mcp-adapter/get-ability-info', 'tool_execute_ability' => 'mcp-adapter/execute-ability', ); /** * Canonical metadata for the three protocol tools — used by * `ToolsController::get_tools()` when `include_abilities=1` to guarantee * they appear in the response's ability catalog regardless of whether * `wp_get_abilities()` returned them. * * The vendor mcp-adapter registers these via `wp_register_ability` on * `wp_abilities_api_init`, but its listener attaches inside * `Controller::initialize_adapter()` (rest_api_init) — which fires AFTER * `wp_abilities_api_init` on any REST request whose Abilities-API * bootstrap already ran on `init`. That leaves `wp_get_abilities()` * blind to the three protocol slugs at REST-handler time. Since * `ToolPolicy` is the authoritative canonical source for these slugs, * we ship their metadata inline as a runtime-timing-safe fallback. * * (SEC-025-v2-2 correction, 2026-07-14 runtime evidence.) */ public const PROTOCOL_TOOL_METADATA = array( array( 'name' => 'mcp-adapter/discover-abilities', 'label' => 'Discover Abilities', 'description' => 'Lists all publicly available WordPress abilities registered on this site. AI clients use this to discover what actions the server can perform.', 'type' => 'tool', 'category' => 'mcp-adapter', ), array( 'name' => 'mcp-adapter/get-ability-info', 'label' => 'Get Ability Info', 'description' => 'Returns detailed information about a specific ability, including its input/output schema and description. Used by AI clients before executing an ability.', 'type' => 'tool', 'category' => 'mcp-adapter', ), array( 'name' => 'mcp-adapter/execute-ability', 'label' => 'Execute Ability', 'description' => 'Executes a WordPress ability with the provided input parameters and returns the result. This is the primary tool used by AI clients to interact with WordPress.', 'type' => 'tool', 'category' => 'mcp-adapter', ), ); /** * Compose the effective tool list for a server row. * * Union of (enabled protocol columns → slugs) and curated slugs from * `MCPServerToolQuery::get_added_slugs()`. Deduped and `array_values()`- * normalized. Order stability: protocol slugs first (in COLUMN_MAP key * order, only for columns with value 1), curated after (row-insertion * order returned by `get_added_slugs`). * * B18: uses `! empty()` to check column values — never strict-compare to 1 * because `$wpdb` can return TINYINTs as strings; the Row constructor * casts these to int at load time, but defense-in-depth here matches * F020's `ToolExposureGate` style. * * @since 0.1.0 * @param Row $row The server row. * @return string[] The composed tool list. */ public static function compose_for_row( Row $row ): array { $tools = array(); foreach ( self::COLUMN_MAP as $column => $slug ) { if ( ! empty( $row->{$column} ) ) { $tools[] = $slug; } } $curated = MCPServerToolQuery::instance()->get_added_slugs( (int) $row->id ); foreach ( $curated as $slug ) { $tools[] = (string) $slug; } return array_values( array_unique( array_map( 'strval', $tools ) ) ); } /** * Compose the effective tool list for a server row at MCP server-registration * time. * * Returns: * 1. Enabled protocol columns (F025) — three tool_* boolean columns. * 2. Curated ability slugs (F020) — presence rows in wp_acrossai_mcp_server_tools. * * **NOT included** (F026 scope revert, 2026-07-15): abilities where * `meta.mcp.public = true` (or `is_exposed = 1` per-server override) are * NO LONGER advertised directly in `tools/list`. AI clients access them * through the three built-in meta tools (`mcp-adapter/discover-abilities`, * `.../get-ability-info`, `.../execute-ability`) whose callbacks now honor * per-server visibility via commit 070ffe2's `wp_register_ability_args` * swap. This keeps `tools/list` scoped to the operator's Tools-tab picks * and prevents ability slugs from leaking into the tool advertisement * surface. * * **F090 ended the straight-passthrough relationship with * `compose_for_row()`.** The two still answer different questions: * * - `compose_for_row()` — what the operator CONFIGURED * - `compose_effective_tools_for_row()` — what this server ACTUALLY SERVES * * The requirement swap lives HERE, and nowhere else. Architecture review * rated splitting precedence across `ToolPolicy` and `MCP\Controller` * High: REST reads `compose_for_row()` while MCP registration reads this * method, so a rule implemented in only one place would let the Tools tab * show the operator a list the server is not serving. * * Precedence, highest first: * * 1. Type requirement UNMET -> exactly the diagnostic slug. A server * cannot advertise tools whose abilities are not registered, and the * client must be told why rather than handed an empty list. * 2. The configured set (columns + curated rows), narrowed to abilities * that still exist and minus the diagnostic. * * There is deliberately no coarse `expose` / `hide` rule above curation. * One briefly existed (`tools_default_policy`, dropped in schema 1.1.7) and * `ToolExposureGate` never honoured it, so `expose` advertised tools that * `tools/call` then refused. What the operator curates is what the server * serves — one layer, checkable against the Tools tab by eye. * * The server TYPE's own tool list is deliberately NOT in this chain either. * A type is a template that WRITES into layer 2 when Reset or a switch * runs; it is never a runtime filter. * * Writes nothing. An unmet requirement must leave curated rows untouched so * they return intact when the sibling plugin is reactivated. * * @since 0.1.0 (Feature 026; precedence chain added by Feature 090) * @param Row $row The server row. * @return string[] What this server serves right now, deduped. */ public static function compose_effective_tools_for_row( Row $row ): array { $server_type = (string) $row->server_type; // Layer 1 — requirement unmet. Highest precedence: nothing else can // make unregistered abilities servable. if ( ! ServerTypes::is_available( $server_type ) ) { return array( SetupRequired::SLUG ); } // Layer 2 — the configured set, narrowed to abilities that still exist, // minus the diagnostic. // // `SetupRequired` IS a registered ability, so without the subtraction a // slug written straight into the curated rows would survive the narrowing // and a HEALTHY server would advertise a "the add-on is missing" tool // while nothing is missing. T042 specifies it is admitted only to a server // whose own requirement is unmet — layer 1 above — and this is what makes // that true rather than merely intended. // // Not reachable through the UI: the picker renders `ServerTypes::pool()`, // which excludes it. Reachable by POSTing the slug to the tools route as // an administrator, which is why the rule belongs here in the composer // rather than in the picker. // // Curated rows are presence rows and they OUTLIVE the plugin that // registered the ability: deactivate Advanced Custom Fields and the // `toolset/acf` row remains, so the tab kept listing a tool the site can // no longer serve. Filtering here — not deleting the row — means the // operator's pick returns intact the moment the plugin is reactivated, // which is the same guarantee a deactivate/reactivate cycle already has. return array_values( array_diff( ServerTypes::registered_only( self::compose_for_row( $row ) ), array( SetupRequired::SLUG ) ) ); } /** * Split a REST POST body's `tools` array into the two storage layers. * * Returns: * [ * 'columns' => [ * 'tool_discover_abilities' => 0|1, * 'tool_get_ability_info' => 0|1, * 'tool_execute_ability' => 0|1, * ], * 'curated' => string[] // slugs with protocol slugs stripped * ] * * Missing protocol slugs in `$tools` become `0` (the "removed" state). * Non-protocol slugs are handed unchanged to the curated array — the * caller (ToolsController::post_tools) uses this half as * MCPServerToolQuery::replace_set()'s desired-set argument. * * @since 0.1.0 * @param array $tools The submitted tools array (any mix of types; normalized here). * @return array{columns: array, curated: string[]} */ public static function split_payload( array $tools ): array { $normalized = array_values( array_unique( array_filter( array_map( 'strval', $tools ), 'strlen' ) ) ); $columns = array(); foreach ( self::COLUMN_MAP as $column => $slug ) { $columns[ $column ] = in_array( $slug, $normalized, true ) ? 1 : 0; } $curated = array_values( array_diff( $normalized, self::PROTOCOL_TOOLS ) ); return array( 'columns' => $columns, 'curated' => $curated, ); } /** * Write a server type's tool set onto a freshly created server. * * Without this a new server carries whatever the `tool_*` column defaults * give it — the three protocol tools — no matter which type was chosen. An * AcrossAI server arrived with mcp-adapter's tools, and an mcp-adapter one * arrived without `mcp-adapter/server-guide`, because the type's list was * only ever written when the operator pressed Reset to Type Defaults. * * This does NOT make the type a runtime fallback — see the precedence * docblock above, which is deliberate and unchanged. The type is still a * template that WRITES; creation is simply the other moment it should * write, alongside Reset and a type switch. * * Call AFTER the row exists: curated rows are keyed by server id, so they * cannot be folded into the INSERT the way the columns could. * * Extracted rather than inlined because both create paths need it — the * classic form and the Quick Connect wizard (Constitution VI). * * @since 0.3.5 * @param int $server_id The newly created server. * @param string $server_type Its stored type slug. * @return void */ public static function apply_type_defaults( int $server_id, string $server_type ): void { if ( $server_id <= 0 ) { return; } // DECLARED, not `tools_for()`. The latter narrows to abilities registered // right now, so on a site without the add-on an AcrossAI server created // from the form or the wizard was stamped with mcp-adapter's tools — // the exact bug this feature exists to fix, surviving in the create path // after the seeder had been corrected. $split = self::split_payload( ServerTypes::declared_tools( $server_type ) ); MCPServerQuery::instance()->update_item( $server_id, $split['columns'] ); MCPServerToolQuery::instance()->replace_set( $server_id, $split['curated'] ); } }