自定义传输层

本指南介绍了当内置的 HttpTransport 无法满足您的特定需求时，如何为 MCP Adapter 实现自定义传输层。

内置传输

• ✅ HttpTransport – 推荐（实现 MCP 2025-06-18 规范）
• ✅ STDIO Transport – 通过 WP-CLI 命令可用

何时创建自定义传输

> 💡 首先考虑 传输权限：对于身份验证需求，使用传输权限回调而不是自定义传输。

为以下情况创建自定义传输：

• 自定义路由模式或 URL 结构
• 消息队列集成（Redis、RabbitMQ、AWS SQS）
• 请求签名和验证
• 自定义加密或数据屏蔽
• HTTP/STDIO 以外的专门协议

传输接口

自定义传输实现以下两个接口之一：

McpTransportInterface（基础）

interface McpTransportInterface {
    public function __construct( McpTransportContext $context );
    public function register_routes(): void;
}

McpRestTransportInterface（REST 特定）

interface McpRestTransportInterface extends McpTransportInterface {
    public function check_permission( WP_REST_Request $request );
    public function handle_request( WP_REST_Request $request ): WP_REST_Response;
}

助手特质

使用 McpTransportHelperTrait 实现通用功能：

use WPMCPTransportInfrastructureMcpTransportHelperTrait;

class MyTransport implements McpRestTransportInterface {
    use McpTransportHelperTrait;
    
    // 提供 get_transport_name() 方法
}

创建自定义传输

基本示例：API 密钥传输

<?php
use WPMCPTransportContractsMcpRestTransportInterface;
use WPMCPTransportInfrastructureMcpTransportContext;
use WPMCPTransportInfrastructureMcpTransportHelperTrait;

class ApiKeyTransport implements McpRestTransportInterface {
    use McpTransportHelperTrait;
    
    private McpTransportContext $context;
    
    public function __construct( McpTransportContext $context ) {
        $this->context = $context;
        $this->register_routes();
    }
    
    public function register_routes(): void {
        $server = $this->context->mcp_server;
        
        register_rest_route(
            $server->get_server_route_namespace(),
            $server->get_server_route(),
            [
                'methods' => ['POST', 'GET', 'DELETE'],
                'callback' => [$this, 'handle_request'],
                'permission_callback' => [$this, 'check_permission'],
            ]
        );
    }
    
    public function check_permission( WP_REST_Request $request ) {
        $api_key = $request->get_header( 'X-API-Key' );
        
        if ( empty( $api_key ) ) {
            return false;
        }
        
        // 验证存储的密钥
        $valid_keys = get_option( 'mcp_api_keys', [] );
        return in_array( $api_key, $valid_keys, true );
    }
    
    public function handle_request( WP_REST_Request $request ): WP_REST_Response {
        $body = $request->get_json_params();
        
        if ( empty( $body['method'] ) ) {
            return new WP_REST_Response( 
                ['error' => '需要 MCP 方法'], 
                400 
            );
        }
        
        // 通过请求路由器进行路由
        $result = $this->context->request_router->route_request(
            $body['method'],
            $body['params'] ?? [],
            $body['id'] ?? 0,
            $this->get_transport_name()
        );
        
        return rest_ensure_response( $result );
    }
}

使用自定义传输

add_action( 'mcp_adapter_init', function( $adapter ) {
    $adapter->create_server(
        'api-key-server',
        'my-plugin',
        'secure-mcp',
        '安全 MCP 服务器',
        '带有 API 密钥身份验证的 MCP 服务器',
        '1.0.0',
        [ ApiKeyTransport::class ], // 使用自定义传输
        WPMCPInfrastructureErrorHandlingErrorLogMcpErrorHandler::class,
        [ 'my-plugin/secure-tool' ]
    );
});

传输权限与自定义传输

使用传输权限的情况：

• ✅ 身份验证逻辑（角色检查、API 密钥）
• ✅ 基于用户的权限（能力验证）
• ✅ 基于时间的访问（营业时间）
• ✅ 大多数授权需求

有关更简单的身份验证解决方案，请参阅 传输权限。

使用自定义传输的情况：

• ✅ 自定义路由模式
• ✅ 消息队列集成
• ✅ 请求签名/加密
• ✅ 专门协议

实现说明

必需方法

• _construct()：接受 McpTransportContext 并调用 registerroutes()
• register_routes()：注册 WordPress REST API 端点
• check_permission()：验证请求访问（仅 REST 传输）
• handle_request()：处理 MCP 请求（仅 REST 传输）

助手特质的优势

• gettransportname()：用于指标的标准化传输名称
• 一致的命名约定
• 共享的实用方法

请求路由

所有传输使用注入的 request_router 来处理 MCP 方法：

$result = $this->context->request_router->route_request(
    $method,
    $params,
    $request_id,
    $this->get_transport_name()
);

下一步

• 传输权限 – 更简单的身份验证方法
• 错误处理 – 自定义错误管理
• 架构概述 – 系统设计