Adapt abilities-api annotations format to comply with MCP ToolAnnotations specification

[galatanovidiu]

Summary

The mcp-adapter needs to properly convert abilities-api annotations to the https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations format.

Currently, the conversion in RegisterAbilityAsMcpTool passes through annotations unchanged, which doesn't match the MCP field naming requirements.

Current State

The abilities-api currently defines annotations in WP_Ability::$default_annotations (class-wp-ability.php:38-53):

  array(
      'instructions' => '',      // string: Instructions on how to use the ability
      'readonly'     => false,   // bool: Ability does not modify environment
      'destructive'  => true,    // bool: May perform destructive updates
      'idempotent'   => false,   // bool: Same arguments have no additional effect
  )

MCP ToolAnnotations Specification

According to the MCP specification, ToolAnnotations should be:

  interface ToolAnnotations {
    destructiveHint?: boolean;  // Default: true
    idempotentHint?: boolean;   // Default: false
    readOnlyHint?: boolean;     // Default: false
  }

Questions to Resolve

1. Instructions field: The instructions field has no equivalent in MCP ToolAnnotations. MCP uses the tool description field for instructions. Should we:
   • Prepend the instructions to the MCP tool description?
   • Ignore the instructions field entirely?
   • Pass it as a non-standard annotation field (may cause validation issues)?
2. I presume we want all other annotations to be passed to MCP unchanged?

@JasonTheAdams, @justlevine @swissspidy ...

[gziolo]

'instructions' => '', won't get included in WP 6.9 beta 1 after a few rounds of feedback. All other annotations stay, but they default to null. It's up to the developer to set these annotations to true or false. It's also up to the implementer to pick the default value when null is set, or in practice the value is not set. WP defaults to false in REST API implementation, and there is flexibility in how the MCP Adapter approaches it. 😄