SDK custom abilities

Kodavio puede descubrir abilities registradas por otros plugins y, si estan marcadas de forma explicita, exponerlas por su servidor MCP. Usa esto para dar al agente una operacion concreta y segura, no acceso generico a funciones internas.

Regla de seguridad

Una custom ability debe tener:

• schema de entrada cerrado con additionalProperties: false;
• permiso WordPress claro;
• dry_run para escrituras;
• confirmacion para acciones destructivas;
• salida redactada sin secretos;
• meta MCP publica solo si realmente quieres exponerla.

Ejemplo minimo

add_action('wp_abilities_api_init', static function (): void {
    wp_register_ability('mi-plugin/crear-resumen', [
        'label' => 'Crear resumen',
        'description' => 'Genera un resumen seguro de un contenido interno.',
        'category' => 'content',
        'input_schema' => [
            'type' => 'object',
            'properties' => [
                'post_id' => ['type' => 'integer'],
            ],
            'required' => ['post_id'],
            'additionalProperties' => false,
        ],
        'output_schema' => ['type' => 'object'],
        'execute_callback' => 'mi_plugin_crear_resumen',
        'permission_callback' => static function (): bool {
            return current_user_can('edit_posts');
        },
        'meta' => [
            'mcp' => ['public' => true],
            'kodavio' => [
                'custom_ability' => true,
                'expose_via_mcp' => true,
            ],
            'annotations' => [
                'readonly' => true,
                'destructive' => false,
                'idempotent' => true,
            ],
        ],
    ]);
});

La marca kodavio.expose_via_mcp evita que Kodavio publique abilities de terceros por accidente. Sin esa marca, Kodavio puede descubrir la ability en integraciones, pero no la expone como tool MCP propia.

En modo compacto, las custom abilities pueden ejecutarse mediante mcp-adapter-execute-ability usando su nombre completo. Si cambias el modo de exposicion directa a all, tambien apareceran como tools directas.

Escrituras

Para una escritura, anade dry_run y una confirmacion explicita:

'input_schema' => [
    'type' => 'object',
    'properties' => [
        'post_id' => ['type' => 'integer'],
        'title' => ['type' => 'string'],
        'dry_run' => ['type' => 'boolean', 'default' => true],
        'confirm_write' => ['type' => 'boolean', 'default' => false],
    ],
    'required' => ['post_id', 'title'],
    'additionalProperties' => false,
],

La callback debe devolver un plan cuando dry_run=true y escribir solo cuando el usuario haya confirmado.

Como pedirle a Codex que la use

Primero descubre integraciones y custom abilities.
Si aparece mi-plugin/crear-resumen, lee su schema y ejecutala solo con permisos de lectura.
No uses ninguna custom ability de escritura sin dry_run y confirmacion.

Cuando crear un adapter Kodavio

Crea un adapter nativo de Kodavio cuando:

• la ability toca builders, formularios, checkout, usuarios o ajustes sensibles;
• necesitas normalizar salidas de varios plugins;
• quieres backups, audit log o rollback propios;
• la operacion debe formar parte de un workflow publico de beta.