默认 MCP 服务器

MCP Adapter 会自动创建一个默认服务器，为 WordPress 能力提供核心 MCP 功能。该服务器充当 AI 代理与 WordPress 之间的桥梁，允许它们通过模型上下文协议发现和执行 WordPress 能力。

服务器配置

基本信息

• 服务器 ID：mcp-adapter-default-server
• 端点：/wp-json/mcp/mcp-adapter-default-server
• 传输：HTTP（符合 MCP 2025-06-18 规范）
• 身份验证：需要具有 read 能力的已登录 WordPress 用户（可通过过滤器自定义）

默认配置

$wordpress_defaults = array(
    'server_id'              => 'mcp-adapter-default-server',
    'server_route_namespace' => 'mcp',
    'server_route'           => 'mcp-adapter-default-server',
    'server_name'            => 'MCP Adapter 默认服务器',
    'server_description'     => '用于 WordPress 能力发现和执行的默认 MCP 服务器',
    'server_version'         => 'v1.0.0',
    'mcp_transports'         => array( HttpTransport::class ),
    'error_handler'          => ErrorLogMcpErrorHandler::class,
    'observability_handler'  => NullMcpObservabilityHandler::class,
    'tools'                  => array(
        'mcp-adapter/discover-abilities',
        'mcp-adapter/get-ability-info', 
        'mcp-adapter/execute-ability',
    ),
    'resources'              => array(),
    'prompts'                => array(),
);

核心能力

默认服务器包含三个提供 MCP 功能的核心能力：

分层工具架构

MCP Adapter 使用分层工具方法，其中一组小型元能力提供对所有 WordPress 能力的访问，解决了影响 MCP 服务器的"工具过多问题"。

问题：在传统的 MCP 实现中，每个功能都会被暴露为单独的工具。当 AI 代理连接时，它会请求 tools/list 并接收每个工具的完整模式（名称、描述、输入参数等）。对于数十个或数百个工具，这会产生几个问题：

1. 上下文窗口膨胀：工具模式在任何实际工作开始之前就消耗了 AI 上下文窗口的重要部分
2. 决策瘫痪：AI 代理难以从大量选项中选择合适的工具
3. 可扩展性限制：随着工具数量的增长，系统变得难以管理

解决方案：默认服务器不是将每个 WordPress 能力暴露为单独的 MCP 工具，而是仅暴露三个战略性元能力作为网关：

1. 发现 (mcp-adapter/discover-abilities) – 列出所有通过 MCP 公开可用的 WordPress 能力
2. 获取信息 (mcp-adapter/get-ability-info) – 检索任何特定能力的详细模式
3. 执行 (mcp-adapter/execute-ability) – 使用提供的参数执行任何能力

这种分层方法提供了几个关键优势：

• 最小上下文消耗：无论存在多少 WordPress 能力，只有 3 个工具模式发送到 AI 代理
• 动态能力发现：WordPress 插件可以注册无限的能力，而无需 MCP 服务器重新配置
• 渐进式信息加载：AI 仅获取它实际需要的能力的详细模式
• 更清晰的决策制定：AI 导航简单的结构化界面，而不是从数百个工具中进行选择
• 未来可扩展性：新能力通过现有网关工具自动可发现

AI 代理结合使用这三个工具来系统地探索和与 WordPress 能力生态系统交互：首先发现可用的能力，然后获取相关能力的详细信息，最后执行选择的操作。

1. 发现能力 (mcp-adapter/discover-abilities)

用途：列出所有通过 MCP 公开可用的 WordPress 能力。

MCP 方法：tools/list

安全性：

• 需要已认证的 WordPress 用户
• 需要 read 能力（可通过 mcpadapterdiscoverabilitiescapability 过滤器自定义）
• 仅返回具有 mcp.public=true 元数据的能力

行为：

• 扫描所有已注册的 WordPress 能力
• 排除以 mcp-adapter/ 开头的能力（防止自引用）
• 筛选仅包含在其元数据中具有 mcp.public=true 的能力
• 为每个公共能力返回能力名称、标签和描述

输出格式：

{
  "abilities": [
    {
      "name": "my-plugin/create-post",
      "label": "创建文章", 
      "description": "创建新的 WordPress 文章"
    }
  ]
}

注解：

• readOnlyHint: true（不修改数据）
• destructiveHint: false（安全操作）
• idempotentHint: true（结果一致）
• openWorldHint: false（仅适用于已知能力）

2. 获取能力信息 (mcp-adapter/get-ability-info)

用途：提供有关特定 WordPress 能力的详细信息。

MCP 方法：tools/call 与工具名称 mcp-adapter-get-ability-info

输入参数：

• ability_name（必填）：要查询的能力的完整名称

安全性：

• 需要已认证的 WordPress 用户
• 需要 read 能力（可通过 mcpadaptergetabilityinfo_capability 过滤器自定义）
• 仅适用于具有 mcp.public=true 元数据的能力
• 对非公共能力返回 abilitynotpublic_mcp 错误

输出格式：

{
  "name": "my-plugin/create-post",
  "label": "创建文章",
  "description": "创建新的 WordPress 文章",
  "input_schema": {
    "type": "object",
    "properties": {...}
  },
  "output_schema": {...},
  "meta": {...}
}

注解：

• readOnlyHint: true（不修改数据）
• destructiveHint: false（安全操作）
• idempotentHint: true（结果一致）
• openWorldHint: false（仅适用于已知能力）

3. 执行能力 (mcp-adapter/execute-ability)

用途：使用提供的参数执行任何 WordPress 能力。

MCP 方法：tools/call 与工具名称 mcp-adapter-execute-ability

输入参数：

• ability_name（必填）：要执行的能力的完整名称
• parameters（必填）：包含要传递给能力的参数的对象

安全性：

• 需要已认证的 WordPress 用户
• 需要 read 能力（可通过 mcpadapterexecuteabilitycapability 过滤器自定义）
• 仅执行具有 mcp.public=true 元数据的能力
• 对目标能力本身执行额外的权限检查
• 执行前双重检查权限作为额外的安全层

执行流程：

1. 验证用户身份和能力
2. 检查目标能力是否有 mcp.public=true 元数据
3. 验证目标能力存在
4. 调用目标能力的权限回调
5. 使用提供的参数执行目标能力
6. 返回包含成功/错误状态的结构化响应

输出格式：

{
  "success": true,
  "data": {
    // 执行的能力的结果
  }
}

错误格式：

{
  "success": false,
  "error": "错误消息，描述出现了什么问题"
}

注解：

• readOnlyHint: false（可能会根据执行的能力修改数据）
• openWorldHint: true（可以执行任何已注册的能力）

安全模型

公共 MCP 元数据

默认服务器实现了一个基于元数据的安全模型：

• 默认安全：默认情况下，能力不可通过 MCP 访问
• 显式选择加入：能力必须在其元数据中包含 mcp.public=true 才能访问
• 精细控制：每个能力单独决定是否应该通过 MCP 访问

公共 MCP 能力示例：

wp_register_ability('my-plugin/safe-tool', [
    'label' => '安全工具',
    'description' => '用于 MCP 访问的安全工具',
    'execute_callback' => 'my_safe_callback',
    'permission_callback' => function() {
        return current_user_can('read');
    },
    'meta' => [
        'mcp' => [
            'public' => true, // 这使得它可以通过 MCP 访问
        ]
    ]
]);

身份验证要求

所有核心能力都需要：

1. WordPress 身份验证：用户必须登录 (isuserlogged_in())
2. 能力检查：用户必须具有所需的能力（默认：read）
3. MCP 暴露检查：目标能力必须具有 mcp.public=true 元数据

能力过滤器

您可以使用 WordPress 过滤器自定义所需的能力：

// 要求 'edit_posts' 能力才能发现能力
add_filter('mcp_adapter_discover_abilities_capability', function() {
    return 'edit_posts';
});

// 要求 'manage_options' 能力才能获取能力信息
add_filter('mcp_adapter_get_ability_info_capability', function() {
    return 'manage_options';
});

// 要求 'publish_posts' 能力才能执行能力
add_filter('mcp_adapter_execute_ability_capability', function() {
    return 'publish_posts';
});

自定义

服务器配置过滤器

您可以使用 mcpadapterdefaultserverconfig 过滤器自定义整个服务器配置：

add_filter('mcp_adapter_default_server_config', function($config) {
    // 更改服务器名称
    $config['server_name'] = '我的自定义 MCP 服务器';
    
    // 添加自定义错误处理程序
    $config['error_handler'] = MyCustomErrorHandler::class;
    
    // 添加其他工具
    $config['tools'][] = 'my-plugin/custom-tool';
    
    return $config;
});

添加资源和提示词

默认服务器可以使用资源和提示词进行扩展：

add_filter('mcp_adapter_default_server_config', function($config) {
    // 添加资源
    $config['resources'] = [
        'my-plugin/site-config',
        'my-plugin/user-data'
    ];
    
    // 添加提示词  
    $config['prompts'] = [
        'my-plugin/code-review',
        'my-plugin/content-analysis'
    ];
    
    return $config;
});

使用示例

使用 WP-CLI 测试

# 列出所有可用工具
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | 
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# 获取特定能力的信息
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp-adapter-get-ability-info","arguments":{"ability_name":"my-plugin/create-post"}}}' | 
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# 执行能力
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp-adapter-execute-ability","arguments":{"ability_name":"my-plugin/create-post","parameters":{"title":"测试文章","content":"Hello World"}}}}' | 
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

HTTP REST API

# 使用 curl 测试（需要身份验证）
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","params":{}}'

错误处理

默认服务器使用结构化错误处理：

常见错误代码

• authentication_required: 用户未登录
• insufficient_capability: 用户缺乏所需的 WordPress 能力
• abilitynotfound: 请求的能力不存在
• abilitynotpublic_mcp: 能力未通过 MCP 暴露（缺少 mcp.public=true）
• missingabilityname: 缺少所需的能力名称参数

错误响应格式

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32008,
    "message": "权限被拒绝：用户缺乏所需的能力：read"
  }
}

最佳实践

对于插件开发者

1. 默认安全：仅向应通过 MCP 访问的能力添加 mcp.public=true
2. 适当的权限：为您的能力实现适当的权限回调
3. 清晰的文档：为您的能力提供良好的标签和描述
4. 输入验证：使用适当的输入模式验证参数

对于网站管理员

1. 用户管理：仅向可信用户授予 MCP 访问权限
2. 能力审核：定期审核哪些用户具有所需的能力
3. 监控使用情况：使用错误日志监控 MCP 使用情况和潜在的安全问题
4. 自定义过滤器：如果需要，使用能力过滤器加强安全性

故障排除

未返回任何能力

• 检查能力在其元数据中是否有 mcp.public=true
• 验证用户已认证并具有所需的能力
• 确保能力在 wpabilitiesapi_init 期间正确注册

权限被拒绝错误

• 验证用户身份验证（已登录）
• 检查用户是否具有所需的能力（默认：read）
• 确认能力具有 mcp.public=true 元数据

找不到能力

• 确保能力在 MCP 服务器初始化之前已注册
• 检查能力名称拼写和格式
• 验证能力注册是否在 wpabilitiesapi_init 动作期间发生

下一步

• 创建能力 – 学习如何创建 MCP 兼容的能力
• 传输权限 – 自定义服务器范围的身份验证
• 错误处理 – 实现自定义错误管理