ساخت ابزار ایجنت وردپرس با Abilities API و MCP Adapter

با Abilities API می‌توان یک قابلیت محدود وردپرس را به ابزار قابل استفاده برای ایجنت تبدیل کرد. MCP Adapter این قابلیت را به Client معرفی می‌کند، اما تصمیم مدل جای کنترل مجوز در وردپرس را نمی‌گیرد. در این آموزش ابزار فقط‌خواندنی «دریافت عنوان و نشانی یک نوشته منتشرشده» می‌سازیم؛ نه ابزار اجرای PHP دلخواه و نه دسترسی کامل مدیر سایت.

اگر تازه با اتصال آشنا شده‌اید، ابتدا راهنمای WordPress MCP و اتصال Client را مطالعه کنید. این مقاله ادامه عملی آن است و بر طراحی قرارداد، Permission و آزمایش حالت‌های ردشده تمرکز دارد. استفاده از هاست وردپرس پاستا محل اجرای سایت را مشخص می‌کند؛ نصب افزونه و تعیین مجوز ابزار همچنان مسئولیت مستقل و مهمی است.

Ability، MCP و مدل چه مسئولیتی دارند؟

Ability نام عملیات، ورودی، خروجی و تابع اجرا را تعریف می‌کند. Adapter آن را در قرارداد MCP ارائه می‌دهد. Client فهرست ابزارها را دریافت می‌کند و مدل می‌تواند پیشنهاد اجرای ابزار را بدهد. در لحظه اجرا، وردپرس باید هویت و مجوز همان درخواست را بررسی کند. متن مقاله یا خروجی ابزار دیگر، منبع معتبر صدور مجوز نیست.

این جداسازی کمک می‌کند مدل را عوض کنید بدون آنکه منطق دسترسی سایت تغییر کند. همچنین خطا قابل تفکیک می‌شود: ابزار در discovery دیده نمی‌شود، ورودی معتبر نیست، مجوز رد شده یا اجرای کسب‌وکار خطا دارد. اصلاح Prompt فقط برای مشکل در فهم وظیفه مناسب است، نه برای دورزدن خطای 403.

نسخه‌ها و محیط آزمایشی را آماده کنید

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

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

قرارداد ابزار را قبل از کد بنویسید

نام ابزار paasta-demo/read-public-post است. ورودی فقط شناسه مثبت نوشته است. خروجی فقط شناسه، عنوان و نشانی عمومی را برمی‌گرداند. پیش‌نویس، نوشته خصوصی و نوشته رمزدار رد می‌شوند. این محدودیت‌ها عمداً ابزار را برای ساخت یک فهرست منابع عمومی مناسب می‌کنند و سطح افشای اطلاعات را پایین نگه می‌دارند.

برای آغاز، ابزار جست‌وجوی نامحدود در همه نوع محتوا نسازید. قرارداد کوچک، آزمون ساده‌تر و رفتار قابل پیش‌بینی‌تری دارد. متن توضیح ابزار نیز باید محدودیت را صریح بیان کند تا Client آن را برای خواندن سفارش یا اطلاعات کاربر انتخاب نکند. Schema، راهنمای مدل است و هم‌زمان بخشی از اعتبارسنجی سمت سرور؛ هیچ‌کدام به‌تنهایی کافی نیست.

افزونه نمونه فقط‌خواندنی

در محیط آزمایشی، فایل wp-content/plugins/paasta-ability-demo/paasta-ability-demo.php را بسازید. کد زیر از API عمومی وردپرس استفاده می‌کند و هیچ تماس با مدل یا ذخیره کلید انجام نمی‌دهد. پیش از نصب روی سایت اصلی، نسخه PHP و وردپرس را با آن تطبیق دهید.

<?php
/**
 * Plugin Name: Paasta Public Post Ability Demo
 * Description: A restricted read-only ability for a public post.
 * Version: 1.0.0
 */
if (!defined('ABSPATH')) { exit; }

add_action('wp_abilities_api_categories_init', static function () {
    wp_register_ability_category('paasta-demo', [
        'label' => 'Paasta demo',
        'description' => 'Restricted demonstration abilities.',
    ]);
});

function paasta_demo_public_post_allowed($input): bool {
    if (!current_user_can('edit_posts') || !is_array($input)) { return false; }
    $id = $input['post_id'] ?? null;
    if (!is_int($id) || $id < 1) { return false; }
    $post = get_post($id);
    return $post instanceof WP_Post
        && $post->post_type === 'post'
        && $post->post_status === 'publish'
        && $post->post_password === ''
        && current_user_can('read_post', $id);
}

add_action('wp_abilities_api_init', static function () {
    wp_register_ability('paasta-demo/read-public-post', [
        'label' => 'Read one public post',
        'description' => 'Return title and URL of one published, unprotected post.',
        'category' => 'paasta-demo',
        'input_schema' => [
            'type' => 'object',
            'properties' => ['post_id' => ['type' => 'integer', 'minimum' => 1]],
            'required' => ['post_id'],
            'additionalProperties' => false,
        ],
        'output_schema' => [
            'type' => 'object',
            'properties' => [
                'id' => ['type' => 'integer'],
                'title' => ['type' => 'string'],
                'url' => ['type' => 'string'],
            ],
            'required' => ['id', 'title', 'url'],
            'additionalProperties' => false,
        ],
        'permission_callback' => 'paasta_demo_public_post_allowed',
        'execute_callback' => static function ($input) {
            if (!paasta_demo_public_post_allowed($input)) {
                return new WP_Error('not_allowed', 'Post is not available.');
            }
            $post = get_post($input['post_id']);
            return [
                'id' => $post->ID,
                'title' => wp_strip_all_tags(get_the_title($post)),
                'url' => get_permalink($post),
            ];
        },
        'meta' => [
            'public' => true,
            'annotations' => ['readonly' => true, 'destructive' => false],
            'mcp' => ['type' => 'tool'],
        ],
    ]);
});

پرچم public ابزار را برای کانال‌های Client قابل ارائه می‌کند؛ به معنی حذف احراز هویت یا Permission نیست. برچسب readonly نیز فقط توضیح رفتار است، نه سازوکار امنیتی. محدودیت واقعی در تابع مجوز و عملیات اجرا اعمال می‌شود. این دو نکته را هنگام کپی‌کردن نمونه‌های اینترنتی جدی بگیرید.