故障排除指南

MCP Adapter 的常见问题和快速解决方案。

快速修复

MCP Adapter 未找到

# 检查插件是否激活
wp plugin status mcp-adapter

# 如果使用 Composer，验证 Jetpack 自动加载器
ls vendor/autoload_packages.php

REST API 404 错误

# 检查 WordPress REST API 是否工作
curl "https://your-site.com/wp-json/"

# 检查永久链接（不能是 "纯文本"）
wp option get permalink_structure

权限被拒绝

# 使用管理员用户测试
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# 检查用户能力
wp user list --fields=ID,user_login,roles

安装问题

插件未激活

# 激活插件
wp plugin activate mcp-adapter

# 检查状态
wp plugin status mcp-adapter

Composer 依赖缺失

# 安装依赖，包括 Jetpack Autoloader
cd wp-content/plugins/mcp-adapter
composer require automattic/jetpack-autoloader
composer install

# 检查 Jetpack 自动加载器是否存在
ls vendor/autoload_packages.php

为什么使用 Jetpack Autoloader？

问题：使用不同版本 MCP Adapter 的多个插件会导致冲突：

插件 A 使用 MCP Adapter v1.0 → 首先加载
插件 B 使用 MCP Adapter v1.2 → 无法加载，导致错误

解决方案：Jetpack Autoloader 自动加载最新版本：

插件 A 使用 MCP Adapter v1.0 + Jetpack Autoloader
插件 B 使用 MCP Adapter v1.2 + Jetpack Autoloader
→ 两个插件都使用 v1.2（最新版本），无冲突

优势：

• ✅ 防止插件间版本冲突
• ✅ 自动加载最新版本
• ✅ 针对插件环境优化的 WordPress
• ✅ 无需配置

类未找到

// 对于 Composer 项目，检查 Jetpack 自动加载器
if ( ! class_exists( 'WPMCPCoreMcpAdapter' ) ) {
    // 加载 Jetpack 自动加载器
    if ( is_file( __DIR__ . '/vendor/autoload_packages.php' ) ) {
        require_once __DIR__ . '/vendor/autoload_packages.php';
    }
}

// 对于插件使用，检查插件是否激活
if ( ! class_exists( 'WPMCPCoreMcpAdapter' ) ) {
    add_action( 'admin_notices', function() {
        echo '<div class="notice notice-error"><p>MCP Adapter 插件必须激活。</p></div>';
    });
    return;
}

Abilities API 缺失

// 在您的插件中检查
if ( ! function_exists( 'wp_register_ability' ) ) {
    add_action( 'admin_notices', function() {
        echo '<div class="notice notice-error"><p>需要 WordPress Abilities API。</p></div>';
    });
    return;
}

服务器问题

服务器未创建

// 调试服务器创建
add_action( 'mcp_adapter_init', function( $adapter ) {
    error_log( 'MCP Adapter 初始化触发' );
    
    try {
        $adapter->create_server(
            'test-server',
            'test',
            'mcp',
            '测试服务器',
            '测试服务器创建',
            '1.0.0',
            [ WPMCPTransportHttpTransport::class ],
            WPMCPInfrastructureErrorHandlingErrorLogMcpErrorHandler::class,
            []
        );
        error_log( '服务器创建成功' );
    } catch ( Exception $e ) {
        error_log( '服务器创建失败: ' . $e->getMessage() );
    }
});

检查已注册的服务器

// 列出所有服务器
add_action( 'init', function() {
    if ( class_exists( 'WPMCPCoreMcpAdapter' ) ) {
        $adapter = WPMCPCoreMcpAdapter::instance();
        $servers = $adapter->get_servers();
        error_log( 'MCP 服务器: ' . implode( ', ', array_keys( $servers ) ) );
    }
}, 999 );

REST API 不工作

# 检查永久链接（不能是 "纯文本"）
wp option get permalink_structure

# 测试基本 REST API
curl "https://your-site.com/wp-json/"

# 列出 MCP 路由
wp rest list | grep mcp

路由未找到

// 检查已注册的路由
add_action( 'rest_api_init', function() {
    $routes = rest_get_server()->get_routes();
    $mcp_routes = array_filter( array_keys( $routes ), function( $route ) {
        return strpos( $route, '/mcp' ) !== false;
    });
    error_log( 'MCP 路由: ' . implode( ', ', $mcp_routes ) );
}, 999 );

权限问题

401 未授权

# 测试带身份验证的请求
curl -X POST "https://your-site.com/wp-json/mcp/mcp-adapter-default-server" 
  --user "username:application_password" 
  -H "Content-Type: application/json" 
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 检查用户是否登录
wp user get admin --field=ID

403 禁止访问

// 调试用户能力
add_action( 'wp_loaded', function() {
    $user = wp_get_current_user();
    if ( $user->ID ) {
        error_log( sprintf( '用户 %d 能力: %s', 
            $user->ID, 
            implode( ', ', array_keys( $user->allcaps ) ) 
        ));
    }
});

测试权限回调

// 临时允许所有用户进行测试
function(): bool {
    error_log( '用户权限检查: ' . get_current_user_id() );
    return is_user_logged_in(); // 非常宽松的权限
}

能力问题

能力未找到

# 检查能力是否已注册
wp eval "var_dump(wp_get_ability('my-plugin/my-ability'));"

# 列出所有能力
wp eval "var_dump(array_keys(wp_get_abilities()));"

执行错误

// 调试能力执行
'execute_callback' => function( $input ) {
    error_log( '能力输入: ' . wp_json_encode( $input ) );
    
    try {
        $result = your_operation( $input );
        error_log( '能力输出: ' . wp_json_encode( $result ) );
        return $result;
    } catch ( Exception $e ) {
        error_log( '能力错误: ' . $e->getMessage() );
        throw $e;
    }
}

模式验证错误

// 测试您的输入模式
$test_input = ['title' => 'Test'];
$ability = wp_get_ability('my-plugin/my-ability');
if ( $ability ) {
    $schema = $ability->get_input_schema();
    error_log( '输入模式: ' . wp_json_encode( $schema ) );
}

调试

启用调试日志

// 添加到 wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

检查系统状态

// 快速系统检查
add_action( 'wp_loaded', function() {
    if ( current_user_can( 'manage_options' ) ) {
        $adapter = WPMCPCoreMcpAdapter::instance();
        error_log( sprintf(
            'MCP 状态 - 适配器: %s, Abilities API: %s, 服务器: %d',
            class_exists( 'WPMCPCoreMcpAdapter' ) ? 'OK' : '缺失',
            function_exists( 'wp_register_ability' ) ? 'OK' : '缺失',
            count( $adapter->get_servers() )
        ));
    }
});

日志分析

# 监视 MCP 问题的调试日志
tail -f wp-content/debug.log | grep MCP

# 搜索最近的错误
grep "MCP.*Error" wp-content/debug.log | tail -10

# 统计错误类型
grep "MCP.*Error" wp-content/debug.log | cut -d']' -f2 | sort | uniq -c

性能监控

// 简单的能力计时
'execute_callback' => function( $input ) {
    $start = microtime( true );
    
    try {
        $result = your_operation( $input );
        $duration = microtime( true ) - $start;
        
        if ( $duration > 1.0 ) {
            error_log( sprintf( '慢速能力: %.2fs', $duration ) );
        }
        
        return $result;
    } catch ( Exception $e ) {
        error_log( '能力失败: ' . $e->getMessage() );
        throw $e;
    }
}

错误处理程序问题

处理程序不工作

// 验证错误处理程序接口
class MyErrorHandler implements WPMCPInfrastructureErrorHandlingContractsMcpErrorHandlerInterface {
    public function log(string $message, array $context = [], string $type = 'error'): void {
        error_log( "[MCP {$type}] {$message}" );
    }
}

// 检查实现
if ( ! in_array( 
    WPMCPInfrastructureErrorHandlingContractsMcpErrorHandlerInterface::class, 
    class_implements( MyErrorHandler::class ) 
)) {
    error_log( '错误处理程序缺少接口' );
}

使用错误工厂

// 创建适当的错误响应
use WPMCPInfrastructureErrorHandlingMcpErrorFactory;

if ( empty( $params['name'] ) ) {
    return [
        'error' => McpErrorFactory::missing_parameter( $request_id, 'name' )['error']
    ];
}

常见修复

永久链接问题

# 检查永久链接结构
wp option get permalink_structure

# 如果为空，设置为文章名称
wp option update permalink_structure "/%postname%/"

内存限制

// 增加 MCP 操作的内存
add_action( 'mcp_adapter_init', function() {
    if ( defined( 'REST_REQUEST' ) ) {
        ini_set( 'memory_limit', '512M' );
        ini_set( 'max_execution_time', 300 );
    }
});

缓存问题

// 如果使用持久缓存，清除对象缓存
wp_cache_flush();

// 或者通过 WP-CLI
wp cache flush

下一步

• 安装指南 – 设置验证
• 创建能力 – 工作示例
• 错误处理 – 自定义错误管理