آموزش WordPress Abilities API؛ ساخت قابلیت‌های هوشمند برای اتصال افزونه‌ها به AI Agentها و MCP

WordPress Abilities API یکی از مهم‌ترین APIهای جدید وردپرس برای ساخت قابلیت‌های استاندارد، قابل کشف و قابل اجرا است. این API به توسعه‌دهنده اجازه می‌دهد یک عملکرد مشخص از افزونه یا قالب را با نام، توضیح، ورودی، خروجی، Schema و کنترل دسترسی تعریف کند تا بخش‌های مختلف وردپرس و ابزارهای بیرونی بتوانند آن را به‌شکل یکسان پیدا و اجرا کنند. این API از WordPress 6.9 در هسته وردپرس قرار گرفته است و در نسخه‌های بعدی نیز توسعه پیدا کرده است. مستندات رسمی WordPress Abilities API

پیشنهادات

عضویت ویژه در ووکامرس – YITH WooCommerce Membership

افزونه عضویت ویژه در ووکامرس  WooCommerce Membership...

آموزش رفع خطای اتصال به پایگاه داده در وردپرس

یکی از خطاهای رایجی که ممکن است...

جلوگیری از سئوی بیش از حد در وردپرس با کنترل کلمات کلیدی

جلوگیری از سئوی بیش از حد -...

افزونه فروش اقساطی ووکامرس YITH Deposits and Down Payments

افزونه فروش اقساطی ووکامرس YITH Deposits and...

افزایش سرعت وردپرس با پاکسازی و بهینه سازی دیتابیس WP Optimize

افزایش سرعت وردپرس واقعی را تجربه کنید! ...

اهمیت Abilities API زمانی بیشتر می‌شود که بخواهید افزونه خود را به AI Agentها و Model Context Protocol یا MCP متصل کنید. در این معماری، یک قابلیت وردپرس می‌تواند با استفاده از MCP Adapter به یک Tool تبدیل شود تا Agent بتواند آن را کشف کرده و در صورت داشتن مجوز، اجرا کند.

بنابراین به‌جای ساخت اتصال اختصاصی برای هر Agent، یک لایه استاندارد برای Capabilityهای افزونه ایجاد می‌کنید. مقاله رسمی WordPress درباره MCP Adapter

در این آموزش از پایه شروع می‌کنیم، ساختار یک Ability را می‌شناسیم، یک Ability واقعی با PHP می‌سازیم، Schema و Permission را پیاده‌سازی می‌کنیم، آن را از PHP و REST تست می‌کنیم و سپس مسیر اتصال آن به MCP و AI Agent را بررسی خواهیم کرد.

WordPress Abilities API چیست؟

Abilities API یک رجیستری استاندارد در WordPress است که به توسعه‌دهندگان اجازه می‌دهد قابلیت‌های مشخص سایت را تعریف و ثبت کنند. هر قابلیت که با نام namespace/ability-name ثبت می‌شود، یک واحد مستقل از عملکرد است که می‌تواند ورودی مشخص دریافت کند و خروجی مشخصی تحویل دهد.

برای مثال، یک افزونه را در نظر بگیرید که امکان دریافت اطلاعات یک نوشته را دارد. در معماری سنتی ممکن است این عملکرد فقط به‌صورت یک Function داخلی وجود داشته باشد:

my_plugin_get_post_data( $post_id );

اما همین عملکرد را می‌توان به یک Ability تبدیل کرد:

my-plugin/get-post-data

در این حالت، علاوه بر خود Function، اطلاعات قابل فهمی درباره Capability در اختیار WordPress و مصرف‌کننده‌های خارجی قرار می‌گیرد؛ برای نمونه اینکه Ability چه کاری انجام می‌دهد، چه ورودی‌ای لازم دارد، چه خروجی‌ای تولید می‌کند و چه کسی اجازه اجرای آن را دارد.

پیشنهادات

افزونه اشتراک ویژه وردپرس و ووکامرس سلطان

افزونه اشتراک ویژه وردپرس و ووکامرس سلطان...

افزونه ثبت سفارش از طریق واتساپ Woocommerce WhatsApp Order

ثبت سفارش از طریق واتساپ Woocommerce WhatsApp...

افزونه دسترسی کاربران بر اساس نقش به صفحات سایت Pages by User Roles

با استفاده از Pages by User Role...

افزونه Exclusive Addons برای المنتور

افزونه Exclusive Addons برای المنتور یک مجموعه...

چرا و چگونه آدرس URL سایتمان را بهینه کنیم؟

بهینه سازی URL سایت یک از مهمترین...

طبق مستندات رسمی WordPress، Abilities API برای ثبت و کشف قابلیت‌های متمایز در سایت طراحی شده و هر Ability شامل اجزایی مانند نام یکتا، Label، Description، Category، Schema، Callback و Permission است. مرجع رسمی Abilities API

نکته مهم این است که Abilities API خودش هوش مصنوعی نیست. این API نقش یک لایه Capability را ایفا می‌کند؛ یعنی عملکرد واقعی افزونه را به شکلی استاندارد در اختیار مصرف‌کننده قرار می‌دهد.

چرا Abilities API برای توسعه افزونه‌های مدرن اهمیت دارد؟

قبل از Abilities API، افزونه‌ها برای در اختیار قرار دادن قابلیت‌های خود به بخش‌های دیگر وردپرس معمولاً از ترکیبی از Functionها، Hookها، کلاس‌ها و Endpointهای REST اختصاصی استفاده می‌کردند. این روش‌ها همچنان معتبر هستند، اما یک قرارداد استاندارد و واحد برای تعریف قابلیت وجود نداشت.

Abilities API این لایه را استاندارد می‌کند.

در نتیجه، قابلیت‌های افزونه را می‌توان به شکلی تعریف کرد که برای چند نوع مصرف‌کننده قابل استفاده باشند:

• کد PHP: یک افزونه یا بخش دیگری از وردپرس می‌تواند Ability را پیدا و اجرا کند.
• JavaScript: قابلیت‌ها می‌توانند از طریق لایه Client-Side مورد استفاده قرار گیرند.
• REST API: Abilityهای قابل انتشار می‌توانند از طریق Endpointهای استاندارد در دسترس باشند.
• MCP: MCP Adapter می‌تواند Ability را به Tool، Resource یا Prompt تبدیل کند.
• AI Agent: Agent می‌تواند قابلیت‌های در معرض دسترس را کشف، انتخاب و اجرا کند.

این معماری در مستندات رسمی WordPress نیز به‌عنوان راهی برای ایجاد قابلیت‌های استاندارد، ماشین‌خوان و قابل استفاده در Automation و AI معرفی شده است. معرفی رسمی WordPress Abilities API

اجزای اصلی یک Ability در وردپرس

برای درک Abilities API، ابتدا باید اجزای آن را بشناسید. هر Ability در ساده‌ترین حالت، یک قرارداد مشخص بین افزونه و مصرف‌کننده آن است.

طبق Reference رسمی تابع wp_register_ability()، نام Ability باید حتماً Namespaced باشد، Category باید معتبر باشد و Callback اجرایی و Permission Callback در ثبت Capability تعریف شوند. Schemaها نیز برای اعتبارسنجی و مستندسازی داده استفاده می‌شوند. مرجع رسمی wp_register_ability()

Abilities API از کدام نسخه وردپرس در دسترس است؟

Abilities API در WordPress 6.9 به هسته وردپرس اضافه شد. بنابراین اگر افزونه شما باید با نسخه‌های قبل از 6.9 نیز سازگار باشد، نباید فرض کنید کلاس‌ها و توابع Abilities API همیشه وجود دارند.

روش ساده برای سازگاری بهتر این است که قبل از استفاده از API، وجود کلاس WP_Ability را بررسی کنید:

if ( ! class_exists( 'WP_Ability' ) ) {
    return;
}

مستندات رسمی WordPress برای سازگاری با نسخه‌های قدیمی‌تر دقیقاً امکان بررسی وجود WP_Ability را پیشنهاد می‌کند. راهنمای Getting Started

در WordPress 7.0، لایه Client-Side برای Abilities API نیز توسعه پیدا کرد و بسته‌های JavaScript مرتبط با مدیریت Abilityها معرفی شدند. در WordPress 7.1 نیز امکاناتی مانند Exposure عمومی یکپارچه، Schemaهای سازگارتر با Clientها و Hookهای جدید چرخه اجرای Ability اضافه شد. WordPress 7.1 Field Guide

مرحله اول؛ ثبت Category برای Ability

هر Ability باید به یک Category معتبر تعلق داشته باشد. Category کمک می‌کند Capabilityها ساختار منظم‌تری داشته باشند و کشف و مدیریت آن‌ها ساده‌تر شود.

برای یک افزونه واقعی، می‌توانید Category اختصاصی خود را ثبت کنید:

<?php

add_action(
    'wp_abilities_api_categories_init',
    function () {
        wp_register_ability_category(
            'my-plugin',
            array(
                'label'       => __( 'My Plugin', 'my-plugin' ),
                'description' => __( 'Abilities provided by My Plugin.', 'my-plugin' ),
            )
        );
    }
);

در این نمونه Category با Slug برابر my-plugin ساخته شده است. سپس همین مقدار را در تنظیمات Ability استفاده می‌کنیم.

نکته مهم: Category باید قبل از Ability ثبت شده باشد. مرجع رسمی WordPress نیز صراحتاً ثبت Category از طریق wp_abilities_api_categories_init و سپس استفاده از آن در ثبت Ability را توضیح می‌دهد. مستندات ثبت Ability و Category

مرحله دوم؛ ساخت اولین Ability وردپرس

حالا یک Ability واقعی می‌سازیم که اطلاعات یک نوشته را بر اساس شناسه آن برمی‌گرداند.

نام این قابلیت را در نظر بگیرید:

my-plugin/get-post-data

این نام از دو بخش تشکیل شده است:

namespace/ability-name

در این مثال:

namespace = my-plugin
ability-name = get-post-data

نام Ability باید کوتاه، قابل فهم و بیانگر یک عمل مشخص باشد. استفاده از نام‌هایی مانند run یا action1 در پروژه‌های Agent محور انتخاب مناسبی نیست، چون برای انسان و ماشین اطلاعات کافی درباره هدف Capability فراهم نمی‌کند.

کد ثبت Ability:

<?php

add_action(
    'wp_abilities_api_init',
    function () {
        wp_register_ability(
            'my-plugin/get-post-data',
            array(
                'label'       => __( 'Get Post Data', 'my-plugin' ),
                'description' => __( 'Returns the title, status, and URL of a WordPress post.', 'my-plugin' ),
                'category'    => 'my-plugin',

                'input_schema' => array(
                    'type'       => 'object',
                    'properties' => array(
                        'post_id' => array(
                            'type'        => 'integer',
                            'description' => __( 'The WordPress post ID.', 'my-plugin' ),
                            'minimum'     => 1,
                        ),
                    ),
                    'required' => array( 'post_id' ),
                ),

                'output_schema' => array(
                    'type'       => 'object',
                    'properties' => array(
                        'id' => array(
                            'type' => 'integer',
                        ),
                        'title' => array(
                            'type' => 'string',
                        ),
                        'status' => array(
                            'type' => 'string',
                        ),
                        'url' => array(
                            'type'   => 'string',
                            'format' => 'uri',
                        ),
                    ),
                    'required' => array(
                        'id',
                        'title',
                        'status',
                        'url',
                    ),
                ),

                'execute_callback' => function ( $input ) {
                    $post_id = absint( $input['post_id'] );
                    $post    = get_post( $post_id );

                    if ( ! $post ) {
                        return new WP_Error(
                            'post_not_found',
                            __( 'The requested post was not found.', 'my-plugin' )
                        );
                    }

                    return array(
                        'id'     => $post->ID,
                        'title'  => get_the_title( $post->ID ),
                        'status' => $post->post_status,
                        'url'    => get_permalink( $post->ID ),
                    );
                },

                'permission_callback' => function ( $input ) {
                    $post_id = isset( $input['post_id'] )
                        ? absint( $input['post_id'] )
                        : 0;

                    return $post_id > 0 && current_user_can( 'read_post', $post_id );
                },

                'meta' => array(
                    'public' => false,
                    'annotations' => array(
                        'readonly'    => true,
                        'destructive' => false,
                        'idempotent'  => true,
                    ),
                ),
            )
        );
    }
);

این ساختار بر اساس API واقعی WordPress طراحی شده است: Ability در Hook مربوط به Abilities API ثبت می‌شود، نام آن Namespaced است و برای ورودی، خروجی، اجرای عملیات و مجوز، قرارداد جداگانه دارد. مستندات رسمی wp_register_ability()

Input Schema چیست و چرا برای AI Agent اهمیت دارد؟

اگر یک Function معمولی PHP داشته باشید، ممکن است فقط بدانید که باید یک شناسه عددی به آن بدهید. اما یک AI Agent یا یک ابزار خارجی باید بتواند از روی Metadata بفهمد:

«این قابلیت چه چیزی می‌گیرد؟»

«نوع داده چیست؟»

«کدام فیلد اجباری است؟»

«چه محدودیتی دارد؟»

Input Schema دقیقاً برای همین هدف استفاده می‌شود.

در مثال بالا:

'input_schema' => array(
    'type'       => 'object',
    'properties' => array(
        'post_id' => array(
            'type'    => 'integer',
            'minimum' => 1,
        ),
    ),
    'required' => array( 'post_id' ),
),

یعنی Ability یک Object دریافت می‌کند و این Object باید شامل post_id باشد. نوع این مقدار باید Integer و حداقل آن 1 باشد.

WordPress از ساختار JSON Schema برای Schemaهای ورودی و خروجی استفاده می‌کند و این Schemaها هم برای اعتبارسنجی و هم برای مستندسازی قابلیت کاربرد دارند. مرجع PHP برای Abilities API

در معماری AI، این موضوع اهمیت بیشتری پیدا می‌کند؛ زیرا Agent به قرارداد ساختاریافته‌ای نیاز دارد تا بتواند Tool مناسب را انتخاب و پارامترهای معتبر برای آن تولید کند.

Output Schema چیست؟

Input Schema مشخص می‌کند Ability چه چیزی دریافت می‌کند؛ Output Schema مشخص می‌کند چه چیزی تحویل می‌دهد.

در مثال ما:

'output_schema' => array(
    'type' => 'object',
    'properties' => array(
        'id' => array(
            'type' => 'integer',
        ),
        'title' => array(
            'type' => 'string',
        ),
        'status' => array(
            'type' => 'string',
        ),
        'url' => array(
            'type'   => 'string',
            'format' => 'uri',
        ),
    ),
),

Agent می‌داند که نتیجه یک Object است و در آن چهار فیلد اصلی وجود دارد.

این موضوع برای Integrationهای پایدار بسیار مهم است. اگر خروجی Ability هر بار ساختار متفاوتی داشته باشد، مصرف‌کننده باید منطق پیچیده‌ای برای تفسیر نتیجه بنویسد. اما وقتی Output Schema ثابت است، می‌توان روی آن قرارداد مشخص ساخت.

طبق مستندات WordPress، Output Schema برای توصیف و اعتبارسنجی خروجی موفق execute_callback استفاده می‌شود. مرجع رسمی wp_register_ability()

execute_callback چه کاری انجام می‌دهد؟

تمام منطق واقعی Ability در execute_callback اجرا می‌شود.

در مثال ما این Callback:

function ( $input ) {
    $post_id = absint( $input['post_id'] );
    $post    = get_post( $post_id );

    if ( ! $post ) {
        return new WP_Error(
            'post_not_found',
            'The requested post was not found.'
        );
    }

    return array(
        'id'     => $post->ID,
        'title'  => get_the_title( $post->ID ),
        'status' => $post->post_status,
        'url'    => get_permalink( $post->ID ),
    );
}

را اجرا می‌کند.

Callback می‌تواند تقریباً هر عملکرد مشروع افزونه را انجام دهد؛ از دریافت داده گرفته تا اجرای یک فرآیند، بروزرسانی محتوا یا فراخوانی یک سرویس خارجی.

بااین‌حال، بهتر است هر Ability یک مسئولیت روشن داشته باشد. یک Ability که ده‌ها عملیات نامرتبط را انجام می‌دهد، هم تست دشوارتری دارد و هم برای Agent مبهم‌تر است.

permission_callback؛ مهم‌ترین بخش امنیتی Ability

وقتی Ability به REST یا MCP متصل می‌شود، مسئله Authorization بسیار مهم می‌شود.

وجود یک Capability در رجیستری به این معنی نیست که همه کاربران باید بتوانند آن را اجرا کنند.

برای همین WordPress از permission_callback استفاده می‌کند:

'permission_callback' => function ( $input ) {
    $post_id = isset( $input['post_id'] )
        ? absint( $input['post_id'] )
        : 0;

    return $post_id > 0 && current_user_can( 'read_post', $post_id );
},

در این نمونه، قبل از اجرای Ability بررسی می‌شود که کاربر برای همان نوشته مجوز لازم را دارد یا خیر.

این تفکیک بسیار مهم است:

در WordPress 7.1 فلگ عمومی meta.public معرفی شد، اما خود مستندات Core تأکید می‌کنند که Exposure با Authorization یکی نیست و public کردن Ability به معنی حذف کنترل دسترسی نیست. مستندات رسمی WordPress 7.1 درباره public

پس این تصور کاملاً اشتباه است که:

'public' => true

یعنی:

«هر کسی اجازه اجرای Ability را دارد.»

این دو مسئله باید همیشه جداگانه مدیریت شوند.

meta.public در WordPress 7.1 چیست؟

در WordPress 7.1 یک فلگ با نام meta.public به Abilities API اضافه شد تا نیت توسعه‌دهنده برای Exposure به Clientهای خارجی را به‌صورت یکپارچه مشخص کند.

نمونه:

'meta' => array(
    'public' => true,
),

این مقدار می‌تواند پیش‌فرض Exposure برای کانال‌های مختلف را تعیین کند. برای REST API، مقدار public => true می‌تواند show_in_rest را به‌صورت پیش‌فرض فعال کند.

در عین حال می‌توانید Exposure خاص یک کانال را Override کنید:

'meta' => array(
    'public'       => true,
    'show_in_rest' => false,
),

در این حالت Ability از نظر عمومی برای Clientها قابل Exposure در نظر گرفته شده، اما به‌صورت اختصاصی از REST خارج شده است.

این مدل در WordPress 7.1 برای کاهش نیاز به تنظیم جداگانه Exposure در هر Integration معرفی شد. A unified public exposure flag for Abilities

اجرای Ability از داخل PHP

Abilities API فقط برای REST یا هوش مصنوعی ساخته نشده است. یک بخش دیگر از افزونه شما نیز می‌تواند Ability را از رجیستری دریافت و اجرا کند.

برای گرفتن Ability:

$ability = wp_get_ability( 'my-plugin/get-post-data' );

سپس:

if ( ! $ability ) {
    return;
}

$result = $ability->execute(
    array(
        'post_id' => 123,
    )
);

if ( is_wp_error( $result ) ) {
    // Handle the error.
    return;
}

$data = $result;

این معماری به شما اجازه می‌دهد Capability را یک بار تعریف کنید و همان قرارداد را در بخش‌های مختلف پروژه استفاده کنید.

برای مثال:

Admin UI
   ↓
Ability

Plugin B
   ↓
Ability

REST Client
   ↓
Ability

MCP Adapter
   ↓
Ability

در همه این مسیرها، منطق اصلی Capability همان Ability ثبت‌شده است.

مستندات رسمی Getting Started نیز استفاده از wp_get_ability() و سپس execute() را برای بازیابی و اجرای Ability نشان می‌دهد. Getting Started with Abilities API

اتصال Abilities API به REST API

WordPress برای Abilities API یک Namespace اختصاصی REST دارد:

/wp-json/wp-abilities/v1/

یکی از Endpointهای مهم:

GET /wp-json/wp-abilities/v1/abilities

این Endpoint برای فهرست Abilityهای قابل مشاهده در REST استفاده می‌شود.

برای دریافت یک Ability مشخص:

GET /wp-json/wp-abilities/v1/my-plugin/get-post-data

و برای اجرا:

GET|POST|DELETE /wp-json/wp-abilities/v1/my-plugin/get-post-data/run

روش HTTP براساس ماهیت و Annotationهای Ability مشخص می‌شود. Abilityهای Read-Only می‌توانند با GET اجرا شوند، عملیات دارای ورودی که تغییر ایجاد می‌کنند معمولاً با POST اجرا می‌شوند و قابلیت‌های Destructive باید از DELETE استفاده کنند. همچنین همه Endpointهای Abilities REST API نیازمند کاربر احراز هویت‌شده هستند و اجرای Ability به Permission Callback آن وابسته است. مستندات رسمی REST API برای Abilities

برای مثال، اجرای یک Ability با POST می‌تواند به این شکل باشد:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"input":{"post_id":123}}' \
  https://example.com/wp-json/wp-abilities/v1/my-plugin/get-post-data/run

البته در محیط واقعی باید احراز هویت مناسب WordPress نیز وجود داشته باشد. مستندات رسمی Abilities REST API، Cookie Authentication، Application Passwords و روش‌های احراز هویت سفارشی را پشتیبانی‌شده اعلام می‌کنند. Authentication در Abilities REST API

Abilities API چه تفاوتی با REST API دارد؟

REST و Abilities API دو چیز متفاوت هستند اما می‌توانند مکمل یکدیگر باشند.

REST API بیشتر یک مکانیزم دسترسی و انتقال داده از طریق HTTP است.

Abilities API چارچوبی برای تعریف و ثبت یک Capability استاندارد است.

بنابراین REST می‌تواند یکی از کانال‌های Exposure برای Ability باشد.

به همین دلیل، استفاده از Abilities API به‌معنای کنار گذاشتن REST نیست؛ بلکه می‌توانید Capability را به‌صورت استاندارد تعریف کنید و در صورت نیاز همان Capability را از طریق REST، MCP یا سایر Integrationها در اختیار مصرف‌کننده قرار دهید. WordPress Abilities API

MCP چیست و چه ارتباطی با Abilities API دارد؟

Model Context Protocol یا MCP پروتکلی برای استانداردسازی تعامل سیستم‌های هوش مصنوعی با ابزارها و منابع خارجی است.

در معماری WordPress، MCP Adapter بین Abilities API و MCP قرار می‌گیرد. یعنی به‌جای اینکه برای هر AI Agent یک Integration اختصاصی در افزونه بسازید، Ability را به‌صورت استاندارد ثبت می‌کنید و Adapter آن را به Primitiveهای MCP تبدیل می‌کند.

معماری کلی:

WordPress Plugin
       ↓
Abilities API
       ↓
MCP Adapter
       ↓
MCP Tool / Resource / Prompt
       ↓
AI Agent

مستندات رسمی MCP Adapter توضیح می‌دهند که Abilityهای WordPress می‌توانند به‌صورت Tool، Resource یا Prompt در MCP ارائه شوند. به‌طور معمول Abilityهای اجرایی بیشتر به Tool تبدیل می‌شوند، زیرا Agent می‌تواند آن‌ها را فراخوانی کند. راهنمای رسمی Creating Abilities for MCP

WordPress MCP Adapter چیست؟

MCP Adapter یک پروژه از اکوسیستم AI Building Blocks وردپرس است که Abilities API را به Model Context Protocol متصل می‌کند.

این Adapter به Agentها اجازه می‌دهد Capabilityهای WordPress را کشف کرده و آن‌ها را از طریق MCP فراخوانی کنند. پروژه رسمی WordPress توضیح می‌دهد که MCP Adapter می‌تواند Abilities ثبت‌شده توسط Core، Plugin و Theme را به Primitiveهای MCP تبدیل کند. مخزن رسمی WordPress MCP Adapter در GitHub

در مسیر ساده، کافی است Ability را طوری طراحی کنید که Adapter بتواند آن را بشناسد و برای Exposure موردنظر تنظیم کنید.

برای نمونه:

'meta' => array(
    'public' => true,
    'mcp'    => array(
        'type' => 'tool',
    ),
),

در مستندات فعلی MCP Adapter، Abilityها به‌صورت پیش‌فرض خصوصی هستند و می‌توان با meta.public یا meta.mcp.public آن‌ها را برای Clientها یا MCP قابل مشاهده کرد. MCP Exposure در مستندات رسمی Adapter

چگونه یک Ability را برای MCP قابل استفاده کنیم؟

برای یک Ability که باید از طریق MCP قابل استفاده باشد، می‌توانید Exposure اختصاصی MCP تعریف کنید:

'meta' => array(
    'public' => false,
    'mcp'    => array(
        'public' => true,
        'type'   => 'tool',
    ),
),

یا اگر می‌خواهید Capability شما به‌صورت عمومی برای Clientهای مختلف قابل Exposure باشد:

'meta' => array(
    'public' => true,
),

در این حالت، کانال MCP نیز می‌تواند از این نیت عمومی استفاده کند؛ مگر اینکه برای MCP به‌صورت اختصاصی Override تعریف شده باشد.

مثلاً:

'meta' => array(
    'public' => true,
    'mcp'    => array(
        'public' => false,
    ),
),

این ساختار در پروژه‌های بزرگ مفید است، زیرا ممکن است نخواهید یک Ability در تمام کانال‌ها منتشر شود.

مستندات رسمی MCP Adapter صراحتاً توضیح می‌دهند که meta.mcp.public می‌تواند رفتار Exposure عمومی را برای کانال MCP Override کند. MCP Exposure و Metadata

Tool، Resource و Prompt در MCP چه تفاوتی دارند؟

MCP فقط برای Functionهای قابل اجرا طراحی نشده و چند Primitive اصلی دارد.

برای Abilityهایی که وظیفه انجام یک عمل مشخص را بر عهده دارند، Tool معمولاً مدل طبیعی‌تری است. برای اطلاعات Read-Only که بیشتر نقش Context دارند، Resource می‌تواند مناسب‌تر باشد.

MCP Adapter امکان تعیین این نوع را در Metadata مربوط به MCP فراهم می‌کند. مستندات Creating Abilities for MCP

Annotationها؛ چگونه رفتار Ability را به Agent توضیح دهیم؟

در معماری Agent محور، فقط نام Tool کافی نیست. مصرف‌کننده باید بداند این Capability چه نوع عملیاتی انجام می‌دهد.

برای همین Abilities API از Annotationهایی مانند این موارد پشتیبانی می‌کند:

'annotations' => array(
    'readonly'    => true,
    'destructive' => false,
    'idempotent'  => true,
),

معنای آن‌ها:

• readonly: Ability محیط یا داده را تغییر نمی‌دهد.
• destructive: Ability می‌تواند عملیات مخرب یا حذف‌کننده انجام دهد.
• idempotent: اجرای دوباره با همان ورودی اثر اضافی روی وضعیت سیستم ایجاد نمی‌کند.

این اطلاعات در زمان تبدیل Ability به MCP می‌توانند به Annotationهای قابل فهم برای MCP Clientها نگاشت شوند. مستندات رسمی MCP Adapter نیز این پشتیبانی را توضیح داده‌اند. MCP Annotations

بنابراین اگر Ability شما اطلاعات می‌خواند، آن را Read-Only معرفی کنید. اگر داده‌ای را حذف می‌کند، نباید آن را با readonly => true علامت‌گذاری کنید.

AI Agent چگونه از Ability وردپرس استفاده می‌کند؟

برای درک بهتر، یک Agent را تصور کنید که کاربر از آن می‌خواهد:

«اطلاعات نوشته شماره 123 را بررسی کن.»

Agent ابتدا باید بداند چه ابزارهایی در اختیار دارد. در معماری MCP، این Capabilityها قابل کشف هستند. سپس Agent توضیحات و Schemaهای آن‌ها را بررسی می‌کند.

فرآیند مفهومی می‌تواند چنین باشد:

1. Discover
      ↓
2. Read tool description
      ↓
3. Read input schema
      ↓
4. Select the appropriate Ability
      ↓
5. Send input
      ↓
6. Permission check
      ↓
7. Execute callback
      ↓
8. Return structured result
      ↓
9. Agent interprets the result

نکته کلیدی این است که Agent Function داخلی افزونه شما را نمی‌بیند؛ بلکه با Capability استانداردی که شما منتشر کرده‌اید کار می‌کند.

در نتیجه، کیفیت نام، Description، Input Schema، Output Schema و Permission مستقیماً روی قابلیت استفاده از Tool تأثیر می‌گذارد.

WordPress نیز در راهنمای رسمی ساخت افزونه AI-powered همین ایده را با ترکیب Abilities API، AI Client و MCP Adapter نشان می‌دهد. Build your first AI-Powered WordPress plugin

Ability Composition چیست؟

یکی از الگوهای قدرتمند Abilities API این است که یک Ability بتواند چند Ability دیگر را با هم ترکیب کند.

فرض کنید افزونه شما این Capabilityها را دارد:

seo-plugin/get-post-data
seo-plugin/analyze-content
seo-plugin/generate-seo-suggestion
seo-plugin/update-post-meta

به‌جای اینکه یک Ability بزرگ داشته باشید که همه کارها را از ابتدا تا انتها انجام دهد، می‌توانید Capabilityهای کوچک‌تر بسازید و سپس یک Ability سطح بالاتر ایجاد کنید.

مثلاً:

seo-plugin/optimize-post

می‌تواند:

1. اطلاعات نوشته را دریافت کند.
2. محتوا را تحلیل کند.
3. پیشنهاد سئو تولید کند.
4. در صورت وجود مجوز لازم، نتیجه را ذخیره کند.

این معماری باعث می‌شود Capabilityها قابل تست، قابل استفاده مجدد و قابل ترکیب باشند.

WordPress در نمونه رسمی «Photo to Post» نیز از ترکیب چند Ability برای ساخت یک Workflow کامل‌تر استفاده کرده است؛ در آن معماری، Abilityهای کوچک‌تر در یک Capability سطح بالاتر Orchestrate می‌شوند. نمونه رسمی Ability Composition در WordPress

تفاوت Abilities API با WordPress AI Client چیست؟

این دو فناوری مکمل یکدیگر هستند اما کار متفاوتی دارند.

Abilities API مشخص می‌کند WordPress چه Capabilityهایی دارد.

WordPress AI Client برای ارتباط برنامه‌نویسی با مدل‌های هوش مصنوعی استفاده می‌شود.

به همین دلیل، یک افزونه می‌تواند Capabilityهایی داشته باشد که در Callback خودشان از AI Client استفاده می‌کنند.

مثلاً:

my-plugin/generate-product-description

این Ability می‌تواند:

• شناسه محصول را دریافت کند.
• اطلاعات محصول را از WooCommerce بخواند.
• داده را به سرویس AI ارسال کند.
• پاسخ ساختاریافته دریافت کند.
• نتیجه را به مصرف‌کننده برگرداند.

در یک سناریوی دیگر، ممکن است Callback اصلاً از AI استفاده نکند و فقط داده WordPress را برگرداند؛ سپس AI Agent بیرون از وردپرس تصمیم بگیرد با آن داده چه کاری انجام دهد.

راهنمای رسمی WordPress برای ساخت افزونه AI-powered دقیقاً روی ترکیب سه Building Block تمرکز می‌کند: Abilities API برای Capability، AI Client برای تعامل با مدل و MCP Adapter برای ارائه Abilityها به Agent. راهنمای رسمی توسعه افزونه AI در WordPress

چگونه یک افزونه را برای AI Agentها آماده کنیم؟

اگر قصد دارید افزونه شما در آینده توسط Agentها استفاده شود، بهتر است از همان ابتدا API داخلی آن را Capability محور طراحی کنید.

برای مثال، فرض کنید یک افزونه مدیریت محتوا دارید. به‌جای ساخت یک Function عمومی با نام مبهم:

process_content()

به Capabilityهای مشخص فکر کنید:

content/get-post
content/get-post-seo-data
content/create-draft
content/update-post
content/publish-post

این نام‌گذاری نه‌تنها برای AI، بلکه برای توسعه‌دهندگان انسانی نیز بهتر است.

سپس برای هر Capability مشخص کنید:

• چه داده‌ای دریافت می‌کند؟
• چه نتیجه‌ای برمی‌گرداند؟
• آیا Read-Only است؟
• آیا داده را تغییر می‌دهد؟
• چه Capability وردپرس برای اجرای آن لازم است؟
• آیا قرار است از REST استفاده شود؟
• آیا قرار است از طریق MCP منتشر شود؟

در نتیجه، AI Integration تبدیل به بخشی از معماری افزونه می‌شود، نه یک لایه موقت و جدا از منطق اصلی.

نکات امنیتی مهم در ساخت Ability برای AI Agent

وقتی یک Capability را به Agent متصل می‌کنید، در واقع یک سطح تعامل جدید برای سایت ایجاد می‌کنید. به همین دلیل طراحی امنیتی Ability باید قبل از Exposure آن انجام شود.

۱. Permission را در خود Ability کنترل کنید.

روی Exposure یا public بودن Ability به‌عنوان مرز امنیتی حساب نکنید. Authorization باید داخل Permission Callback اعمال شود. مستندات رسمی WordPress درباره تفاوت Exposure و Authorization

۲. ورودی‌ها را اعتبارسنجی کنید.

از Input Schema برای مشخص‌کردن نوع، مقدار اجباری و محدودیت داده استفاده کنید.

۳. مجوز را با عملیات هماهنگ کنید.

Ability برای خواندن اطلاعات نباید مجوز بیشتری از نیاز واقعی خود بگیرد. Ability برای تغییر تنظیمات یا حذف اطلاعات نیز نباید با Capability بسیار ضعیف اجرا شود.

۴. عملیات مخرب را دقیق علامت‌گذاری کنید.

برای قابلیت حذف، انتقال، تغییر یا سایر عملیات Destructive از Annotation مناسب استفاده کنید.

۵. Secretها را وارد Metadata نکنید.

API Key، Token، رمز عبور، اطلاعات احراز هویت و سایر Secretها نباید داخل Description، Schema یا Metadata قابل کشف قرار گیرند.

۶. داده حساس را بی‌دلیل برنگردانید.

Output Schema را محدود به داده‌ای کنید که مصرف‌کننده واقعاً نیاز دارد.

۷. Ability را کوچک و محدود نگه دارید.

Capability کوچکی که فقط یک وظیفه مشخص را انجام می‌دهد، ساده‌تر قابل ممیزی و کنترل است.

اشتباهات رایج در استفاده از WordPress Abilities API

یکی از اشتباهات رایج، ثبت Ability خارج از Hook مخصوص API است. روش استاندارد، استفاده از wp_abilities_api_init برای ثبت Abilityها است. Hooks رسمی Abilities API

اشتباه دیگر، استفاده از Categoryی است که ثبت نشده است. Category باید پیش از Ability ثبت شود.

اشتباه بعدی، تعریف Schema مبهم است. این کد:

'input_schema' => array(
    'type' => 'object',
),

برای یک پروژه پیچیده معمولاً اطلاعات کافی در اختیار مصرف‌کننده قرار نمی‌دهد.

بهتر است:

'input_schema' => array(
    'type'       => 'object',
    'properties' => array(
        'post_id' => array(
            'type'        => 'integer',
            'minimum'     => 1,
            'description' => 'ID of the WordPress post.',
        ),
    ),
    'required' => array( 'post_id' ),
),

را استفاده کنید.

اشتباه مهم دیگر، اشتباه‌گرفتن public با Permission است. public کردن Capability به‌تنهایی نباید باعث شود Authorization حذف شود.

همچنین نامگذاری مبهم Capabilityها، خروجی غیرقابل پیش‌بینی و استفاده از Abilityهای بیش از حد بزرگ، کیفیت Integration با Agentها را کاهش می‌دهد.

چگونه Ability را تست و عیب‌یابی کنیم؟

بهتر است تست Ability را مرحله‌به‌مرحله انجام دهید و مستقیماً از MCP شروع نکنید.

ابتدا بررسی کنید Ability در Registry ثبت شده است:

$ability = wp_get_ability( 'my-plugin/get-post-data' );

if ( ! $ability ) {
    // Ability is not registered.
}

سپس آن را مستقیم از PHP اجرا کنید:

$result = $ability->execute(
    array(
        'post_id' => 123,
    )
);

اگر REST را فعال کرده‌اید، Endpoint فهرست Abilityها را بررسی کنید:

https://example.com/wp-json/wp-abilities/v1/abilities

سپس Ability خاص:

https://example.com/wp-json/wp-abilities/v1/my-plugin/get-post-data

و در نهایت Endpoint اجرا:

https://example.com/wp-json/wp-abilities/v1/my-plugin/get-post-data/run

مستندات REST API برای Abilityها خطاهایی مانند ability_invalid_input، ability_invalid_permissions، ability_invalid_output و rest_ability_not_found را نیز تعریف کرده‌اند که برای عیب‌یابی بسیار مفید هستند. خطاهای رسمی Abilities REST API

اگر REST به‌درستی کار می‌کند اما MCP Tool ظاهر نمی‌شود، مرحله بعد باید Metadata و تنظیمات MCP Adapter بررسی شود.

معماری پیشنهادی برای یک افزونه حرفه‌ای متصل به AI

برای یک پروژه واقعی بهتر است ساختار Capabilityها را از ابتدا به‌صورت مشخص طراحی کنید.

برای نمونه یک افزونه مدیریت محصولات می‌تواند چنین Abilitiesی داشته باشد:

product/get-details
product/search
product/generate-description
product/update-description
product/get-stock-status
product/update-stock

در اینجا بهتر است عملیات Read و Write از یکدیگر تفکیک شوند.

برای مثال:

product/get-details
```
readonly = true

product/search
```
readonly = true

product/update-description
```
readonly = false

product/update-stock
```
readonly = false

سپس می‌توانید برای هر Ability Permission متناسب تعریف کنید.

در مرحله بعد، بسته به معماری پروژه، می‌توانید تصمیم بگیرید:

Ability
   ├── PHP
   ├── REST
   ├── MCP
   └── JavaScript

کدام کانال باید فعال باشد.

این طراحی باعث می‌شود Capabilityهای افزونه مستقل از نوع Client باقی بمانند.

اتصال یک افزونه وردپرس به AI Agent از طریق MCP

پس از ساخت و تست Ability، برای اتصال آن به Agent باید MCP Adapter در معماری قرار گیرد.

MCP Adapter رسمی WordPress قابلیت‌های WordPress را به MCP متصل می‌کند و برای Clientهای مختلف مسیرهایی برای استفاده از MCP فراهم می‌کند. پروژه رسمی Adapter نمونه‌هایی برای Clientهایی مانند Claude، Cursor و VS Code نیز ارائه کرده است. مقاله رسمی From Abilities to AI Agents

در مستندات فعلی Adapter، یک Server پیش‌فرض نیز وجود دارد که Abilityهای قابل Exposure را برای Clientهای MCP در دسترس قرار می‌دهد. Repository رسمی پروژه همچنین مسیر HTTP زیر را برای Server پیش‌فرض مستند کرده است:

/wp-json/mcp/mcp-adapter-default-server

مخزن رسمی MCP Adapter

در یک سناریوی عملی، مسیر کلی به این شکل است:

WordPress
   ↓
Plugin Ability
   ↓
MCP Adapter
   ↓
MCP Server
   ↓
AI Client
   ↓
AI Agent
   ↓
Tool Call
   ↓
WordPress Ability
   ↓
Structured Result

نکته مهم این است که Agent مستقیماً Function PHP شما را فراخوانی نمی‌کند؛ بلکه از Capability منتشرشده استفاده می‌کند.

نمونه واقعی‌تر؛ ساخت Ability برای یک Workflow هوشمند

فرض کنید یک افزونه تولید محتوا دارید و می‌خواهید Agent بتواند اطلاعات یک مقاله را دریافت کند و سپس Workflow تولید پیشنهاد محتوایی را اجرا کند.

می‌توانید قابلیت‌ها را به این شکل تقسیم کنید:

content/get-post-context
content/analyze-post
content/generate-content-suggestion
content/create-draft

برای مثال content/get-post-context فقط اطلاعات مقاله را برگرداند:

{
    "id": 123,
    "title": "آموزش وردپرس",
    "status": "publish",
    "excerpt": "..."
}

سپس Agent می‌تواند Tool بعدی را انتخاب کند.

این معماری چند مزیت دارد. هر Ability قابل تست مستقل است، Permission هر مرحله جداگانه قابل کنترل است و تغییر در یک بخش لزوماً به معنی بازنویسی کل Integration نیست.

در پروژه‌های بزرگ حتی می‌توانید یک Ability Orchestrator داشته باشید که چند Ability را براساس یک Workflow مشخص اجرا کند.

چرا بهتر است به‌جای Functionهای پراکنده از Ability استفاده کنیم؟

Functionهای داخلی همچنان بخش اساسی توسعه PHP هستند و Abilities API قرار نیست آن‌ها را حذف کند.

مزیت Ability در سطح قرارداد و Integration است.

Function معمولی:

my_plugin_get_data( $id );

برای توسعه‌دهنده داخلی مفید است، اما اطلاعات محدودی درباره خودش دارد.

Ability:

my-plugin/get-data

می‌تواند هم‌زمان مشخص کند:

• نام آن چیست؟
• چه کاری انجام می‌دهد؟
• چه داده‌ای نیاز دارد؟
• چه داده‌ای برمی‌گرداند؟
• عضو کدام Category است؟
• چه کسی می‌تواند آن را اجرا کند؟
• آیا Read-Only است؟
• آیا برای Clientهای خارجی قابل Exposure است؟

این Metadata همان چیزی است که قابلیت را برای Integrationهای آینده ارزشمند می‌کند.

تغییرات مهم WordPress 7.1 برای Abilities API

WordPress 7.1 توسعه Abilities API را ادامه داده و چند قابلیت مهم را به این سیستم اضافه کرده است.

از جمله موارد مهم:

• فلگ عمومی public برای Exposure یکپارچه.
• امکان فیلترکردن نتیجه wp_get_abilities().
• Hookهای جدید مرتبط با چرخه اجرای Ability.
• بهبود آماده‌سازی JSON Schema برای Clientها.
• اصلاحات مختلف برای Discoverability و Integrationهای خارجی.

این تغییرات نشان می‌دهند Abilities API دیگر صرفاً یک رجیستری ساده نیست و به سمت تبدیل‌شدن به یک لایه عمومی برای تعامل وردپرس با Clientها و Agentها حرکت کرده است. WordPress 7.1 Field Guide

بهترین روش‌های طراحی Ability برای Agentها

برای اینکه Capability شما در یک معماری AI قابل استفاده‌تر باشد، چند اصل بسیار مهم را رعایت کنید.

نام را براساس عمل انتخاب کنید.

product/get-details
product/update-description
product/delete-product

از نام‌های مبهم مانند:

run
task
process-data

دوری کنید.

Description باید کاربرد را توضیح دهد.

این توضیح:

Retrieves product details.

از این عبارت بهتر است:

Retrieves the product title, SKU, price, stock status, and permalink for a WooCommerce product by ID.

Schema را دقیق بنویسید.

هرچه ورودی و خروجی دقیق‌تر تعریف شود، مصرف Capability برای Clientهای انسانی و ماشینی ساده‌تر خواهد بود.

Ability را تک‌وظیفه‌ای نگه دارید.

یک Capability مشخص که فقط یک کار انجام می‌دهد، معمولاً از Capability عظیمی که ده عملیات مختلف را ترکیب کرده، قابل فهم‌تر است.

Write و Read را از هم جدا کنید.

Ability برای دریافت داده بهتر است از Ability برای تغییر آن مستقل باشد.

Permission را براساس عملیات تعیین کنید.

Never use a broad permission صرفاً برای ساده‌ترشدن توسعه.

Exposure را آگاهانه انجام دهید.

هر Ability لازم نیست عمومی یا MCP-enabled باشد. فقط Capabilityهایی را در معرض Clientها قرار دهید که واقعاً باید توسط آن‌ها مصرف شوند.

آینده WordPress Abilities API و AI Agentها

جهت توسعه فعلی WordPress نشان می‌دهد که Abilities API در حال تبدیل‌شدن به یکی از پایه‌های مهم معماری AI در اکوسیستم وردپرس است.

WordPress در کنار Abilities API، روی AI Client، MCP Adapter و Client-Side Abilities نیز کار کرده است. هدف این مجموعه، ایجاد مسیر استانداردتری برای تعامل WordPress با مدل‌ها، Agentها، ابزارهای خارجی و Workflowهای هوشمند است. راهنمای رسمی WordPress برای ساخت افزونه AI-Powered

در سمت Client نیز Abilities API دارای بسته‌های JavaScript برای کار با Capabilityها شده است و WordPress آن را به‌عنوان یکی از زیرساخت‌های مهم برای سناریوهایی مانند Browser Agent و WebMCP بررسی کرده است. What’s new for developers? April 2026

این روند برای توسعه‌دهندگان افزونه یک پیام روشن دارد: اگر افزونه شما قرار است در آینده با Automation، Agent یا AI Workflowها تعامل داشته باشد، طراحی Capabilityها به شکل استاندارد ارزش بیشتری پیدا می‌کند.

جمع‌بندی

WordPress Abilities API یک روش استاندارد برای تعریف و ثبت قابلیت‌های قابل کشف و قابل اجرا در وردپرس است. این API به شما اجازه می‌دهد یک Capability را با نام مشخص، Category، Schema، Callback و Permission تعریف کنید و سپس همان قابلیت را در مسیرهای مختلف مورد استفاده قرار دهید. مستندات رسمی Abilities API

برای یک افزونه مدرن، مهم‌ترین نکته این است که Ability را فقط به‌عنوان یک Function جدید نبینید؛ بلکه آن را یک قرارداد قابل مصرف در نظر بگیرید. Input Schema و Output Schema باید روشن باشند، Permission باید دقیق پیاده‌سازی شود و Annotationهای رفتاری باید واقعیت عملیات را توصیف کنند.

در مرحله بعد، REST می‌تواند یکی از کانال‌های دسترسی به Ability باشد و MCP Adapter می‌تواند همین Capability را به MCP متصل کند تا AI Agent بتواند آن را کشف و اجرا کند. WordPress MCP Adapter

بنابراین معماری پیشنهادی را می‌توان در یک جمله خلاصه کرد:

یک بار Capability را درست طراحی کنید؛ سپس بسته به نیاز، همان Capability را برای PHP، REST، MCP و Agentهای هوشمند قابل استفاده کنید.

سؤالات متداول درباره WordPress Abilities API

WordPress Abilities API از چه نسخه‌ای اضافه شد؟

Abilities API از WordPress 6.9 در هسته وردپرس در دسترس است. مستندات رسمی Getting Started

آیا Abilities API فقط برای هوش مصنوعی ساخته شده است؟

خیر. Abilities API یک لایه عمومی برای تعریف و کشف قابلیت‌های WordPress است و می‌تواند توسط PHP، JavaScript، REST و Integrationهای خارجی استفاده شود. اتصال به AI Agentها یکی از کاربردهای مهم آن است. WordPress Abilities API

آیا public کردن Ability باعث می‌شود همه بتوانند آن را اجرا کنند؟

خیر. public بیشتر برای Exposure و Discoverability استفاده می‌شود و جایگزین permission_callback نیست. Authorization باید در خود Ability enforce شود. مستندات رسمی WordPress 7.1

آیا Abilities API جایگزین REST API است؟

خیر. REST API یکی از کانال‌هایی است که می‌تواند Ability را از طریق HTTP در دسترس قرار دهد. Abilities API مسئول تعریف و ثبت Capability است. REST API برای Abilities

MCP Adapter چه کاری انجام می‌دهد؟

MCP Adapter بین WordPress Abilities API و Model Context Protocol قرار می‌گیرد و امکان ارائه Abilityها به‌عنوان Tool، Resource یا Prompt را برای MCP Clientها فراهم می‌کند. مخزن رسمی MCP Adapter

آیا هر Ability باید به MCP متصل شود؟

خیر. Abilityها به‌صورت پیش‌فرض لازم نیست برای MCP منتشر شوند و باید فقط Capabilityهایی را Exposure کنید که واقعاً برای مصرف‌کننده خارجی موردنیاز هستند. راهنمای رسمی MCP Adapter

Input Schema و Output Schema چه فایده‌ای دارند؟

Input Schema ساختار و محدودیت ورودی را مشخص می‌کند و Output Schema ساختار نتیجه را توصیف می‌کند. این Schemaها هم برای اعتبارسنجی و هم برای درک بهتر Capability توسط ابزارها و Clientها کاربرد دارند. PHP Reference رسمی Abilities API

برای ساخت افزونه AI در وردپرس، آیا فقط Abilities API کافی است؟

نه لزوماً. بسته به معماری، ممکن است در کنار Abilities API به WordPress AI Client برای ارتباط با مدل AI و به MCP Adapter برای اتصال Agentها از طریق MCP نیاز داشته باشید.

این اجزا وظایف متفاوتی دارند و می‌توانند در یک افزونه کنار یکدیگر استفاده شوند. راهنمای رسمی ساخت افزونه AI-Powered