传输权限回调

传输权限回调为您的 MCP 服务器提供自定义身份验证。默认情况下，服务器使用 isuserlogged_in()，但您可以实现自定义身份验证逻辑。

基本使用

默认行为（已登录用户）

$adapter->create_server(
    'my-server',
    'my-plugin',
    'mcp',
    '我的 MCP 服务器',
    '服务器描述',
    '1.0.0',
    [WPMCPTransportHttpTransport::class],
    WPMCPInfrastructureErrorHandlingErrorLogMcpErrorHandler::class,
    WPMCPInfrastructureObservabilityNullMcpObservabilityHandler::class,
    ['my-plugin/tool'], // 工具
    [], // 资源
    [], // 提示词
    // 无权限回调 = 使用 is_user_logged_in()
);

自定义权限回调

将权限回调添加为最后一个参数：

// 仅管理员访问
$adapter->create_server(
    'admin-server',
    'my-plugin',
    'mcp-admin',
    '管理员 MCP 服务器',
    '仅管理员服务器',
    '1.0.0',
    [WPMCPTransportHttpTransport::class],
    WPMCPInfrastructureErrorHandlingErrorLogMcpErrorHandler::class,
    WPMCPInfrastructureObservabilityNullMcpObservabilityHandler::class,
    ['my-plugin/admin-tool'], // 工具
    [], // 资源
    [], // 提示词
    function(): bool {  // 权限回调
        return current_user_can('manage_options');
    }
);

权限回调类型

简单布尔返回

function(): bool {
    return current_user_can('edit_posts');
}

详细错误信息

function(): WP_Error|bool {
    if (!is_user_logged_in()) {
        return new WP_Error('not_logged_in', '请登录', ['status' => 401]);
    }
    
    if (!current_user_can('manage_options')) {
        return new WP_Error('insufficient_permissions', '需要管理员访问', ['status' => 403]);
    }
    
    return true;
}

错误处理

• 自动回退：异常会回退到 isuserlogged_in()
• 错误日志记录：回调失败会被记录
• 安全默认值：始终需要身份验证

常见模式

基于角色的访问

// 允许编辑者和管理员
function(): bool {
    return current_user_can('edit_posts');
}

// 多个角色
function(): bool {
    return current_user_can('edit_posts') || current_user_can('manage_options');
}

API 密钥身份验证

function(WP_REST_Request $request): WP_Error|bool {
    $api_key = $request->get_header('X-API-Key');
    
    if (empty($api_key)) {
        return new WP_Error('missing_api_key', '需要 API 密钥', ['status' => 401]);
    }
    
    $valid_keys = get_option('my_plugin_api_keys', []);
    if (!in_array($api_key, $valid_keys, true)) {
        return new WP_Error('invalid_api_key', '无效的 API 密钥', ['status' => 403]);
    }
    
    return true;
}

基于时间的访问

function(): WP_Error|bool {
    if (!is_user_logged_in()) {
        return new WP_Error('not_logged_in', '需要身份验证', ['status' => 401]);
    }
    
    // 营业时间（上午 9 点 - 下午 5 点）
    $current_hour = (int) wp_date('H');
    
    if ($current_hour < 9 || $current_hour > 17) {
        if (!current_user_can('manage_options')) {
            return new WP_Error(
                'outside_business_hours', 
                '仅在营业时间（上午 9 点 - 下午 5 点）可用', 
                ['status' => 403]
            );
        }
    }
    
    return current_user_can('edit_posts');
}

两层安全

MCP Adapter 使用两层安全机制：

1. 传输权限（服务器范围的看门狗）
2. 能力权限（单个工具访问）

传输权限充当看门狗 – 如果在此处被阻止，用户无法访问该服务器上的任何能力。

示例

// 传输：允许编辑者和管理员
$adapter->create_server(
    'content-server',
    'my-plugin',
    'mcp-content',
    '内容服务器',
    '内容管理服务器',
    '1.0.0',
    [WPMCPTransportHttpTransport::class],
    WPMCPInfrastructureErrorHandlingErrorLogMcpErrorHandler::class,
    WPMCPInfrastructureObservabilityNullMcpObservabilityHandler::class,
    ['my-plugin/edit-post', 'my-plugin/delete-post'],
    [], // 资源
    [], // 提示词
    function(): bool {
        // 传输：允许编辑者和管理员
        return current_user_can('edit_posts');
    }
);

// 各个能力检查特定权限：
wp_register_ability('my-plugin/edit-post', [
    'permission_callback' => function($args) {
        // 能力：检查用户是否可以编辑这篇特定的文章
        return current_user_can('edit_post', $args['post_id']);
    },
    // ...
]);

最佳实践

保持回调快速

// ✅ 良好：简单直接
function(): bool {
    return current_user_can('edit_posts');
}

// ❌ 避免：复杂操作会减慢请求速度
function(): bool {
    return $this->check_remote_api() && $this->complex_calculation();
}

使用最广泛的能力

将传输权限设置为服务器上任何能力所需的最广泛能力：

// ✅ 良好：传输允许编辑者，能力决定具体权限
function(): bool {
    return current_user_can('edit_posts'); // 所需的最广泛能力
}

测试

使用不同的用户角色测试权限回调：

# 以管理员身份测试
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | wp mcp-adapter serve --user=admin --server=admin-server

# 以编辑者身份测试（对于仅管理员服务器应该失败）
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | wp mcp-adapter serve --user=editor --server=admin-server

实现说明

回调参数

• HttpTransport：接收 WPRESTRequest $request 参数
• 旧版传输：可能有不同的签名
• 返回类型：bool 或 WP_Error

错误处理

• 异常会自动回退到 isuserlogged_in()
• 所有失败都会记录上下文
• 安全的默认行为

下一步

• 自定义传输 – 用于复杂身份验证需求
• 错误处理 – 自定义错误管理
• 创建能力 – 能力级别的权限