MCP Tools

🚀 MCP Tools

MCP Tools 是一套为与 Drupal 站点协作的 AI 助手提供的实用工具集，它提供了一系列经过精心策划的高价值工具，能够解决实际问题，而非通用的 CRUD 操作。

🚀 快速开始

环境要求

• Drupal 10.3+ 或 Drupal 11
• Tool API 模块

MCP 传输方式（选择其一）

• 推荐（本地开发）：mcp_tools_stdio — 通过 Drush 在 STDIO 上运行 MCP 服务器。
• 实验性（远程 HTTP）：mcp_tools_remote — 提供带有 API 密钥认证的 HTTP 端点。
• 可选（MCP 服务器桥接）：mcp_tools_mcp_server — 为 MCP Tools 生成 MCP 服务器工具配置（仅在安装 drupal/mcp_server 时相关）。
• 替代方案：MCP Server（可选）。注意：drupal/mcp_server 目前存在上游 Composer 元数据问题，请参考 https://www.drupal.org/project/mcp_server/issues/3560993 获取解决方法。

安装步骤

composer require drupal/mcp_tools
drush en mcp_tools

本地 MCP（STDIO）设置（推荐）

drush en mcp_tools_stdio
drush mcp-tools:serve --uid=1

提示：Drush 通常以 uid 0（匿名）启动。对于本地开发，使用 --uid=1。对于共享环境，使用仅具有所需 MCP Tools 权限的专用用户。

网关模式（可选）：仅公开发现/信息/执行工具以减少工具列表大小。

drush mcp-tools:serve --uid=1 --gateway

网关工具：

• mcp_tools/discover-tools
• mcp_tools/get-tool-info
• mcp_tools/execute-tool

远程 MCP（HTTP）设置（实验性）

drush en mcp_tools_remote
drush mcp-tools:remote-key-create --label="My Key" --scopes=read --ttl=86400

在 MCP 客户端中配置 /_mcp_tools 端点，并将密钥作为 Authorization: Bearer … 或 X-MCP-Api-Key: … 发送。

仅在受信任的内部网络上使用此方式。在 /admin/config/services/mcp-tools/remote 配置执行用户（开发时使用 “uid 1” 复选框，生产环境创建专用的 mcp_executor 账户）。考虑设置 IP 和 Origin/Host 允许列表，除非绝对必要，否则保持密钥为只读。

为减少远程客户端的工具列表大小，在远程设置 UI 中启用 网关模式。这仅公开发现/信息/执行工具，同时仍允许按名称执行任何允许的工具。

✨ 主要特性

• 丰富的工具集：总共提供 223 个工具，涵盖 25 个只读操作和 198 个写/分析操作，分布在 35 个子模块中。
• 资源暴露：暴露只读资源（如 drupal://site/status、drupal://site/snapshot），用于轻量级站点上下文，包括蓝图和配置漂移摘要。
• 提示暴露：暴露提示（如 mcp_tools/site-brief），用于可重用的分析指令。
• 可观测性钩子：在工具执行期间分发工具执行事件，用于自定义日志记录、指标或 Webhook。
• 全 AI 驱动的站点构建：通过自然对话创建内容类型、字段、角色、分类法、视图、块、媒体、Web 表单、主题、布局，并应用配方。
• 管理界面：在 /admin/config/services/mcp-tools 配置设置，包括访问控制、速率限制和 Webhook 通知。

📦 安装指南

安装依赖

composer require drupal/mcp_tools
drush en mcp_tools

本地 MCP（STDIO）设置

drush en mcp_tools_stdio
drush mcp-tools:serve --uid=1

远程 MCP（HTTP）设置

drush en mcp_tools_remote
drush mcp-tools:remote-key-create --label="My Key" --scopes=read --ttl=86400

💻 使用示例

本地（通过 Drush 的 STDIO） — 推荐

# 启用传输方式。
drush en mcp_tools_stdio -y

# 在 STDIO 上运行 MCP 服务器（Claude Desktop、Claude Code 等）。
drush mcp-tools:serve --uid=1

# 使用特定范围（仅本地）
MCP_SCOPE=read,write drush mcp-tools:serve --uid=1
# 或者：drush mcp-tools:serve --uid=1 --scope=read,write

远程（HTTP） — 实验性

# 启用传输方式。
drush en mcp_tools_remote -y

# 创建只读 API 密钥（仅显示一次）。
drush mcp-tools:remote-key-create --label="My Key" --scopes=read --ttl=86400

CLI 辅助命令

# 列出服务器配置文件。
drush mcp:servers

# 应用推荐的开发预设并启用捆绑包。
drush mcp:dev-profile

# 检查服务器配置文件并列出组件。
drush mcp:server-info --server=default --tools --resources --prompts

# 对服务器配置和依赖项进行冒烟测试。
drush mcp:server-smoke --server=default

# 验证组件注册表定义。
drush mcp:components-validate

# 搭建组件模块。
drush mcp:scaffold --machine-name=my_module --name="My MCP Module"

替代方案：drupal/mcp_server

如果选择使用 MCP Server 而不是内置传输方式，它提供自己的 Drush 命令（例如 drush mcp:server）。

要为 MCP Tools 准备 MCP 服务器工具配置，请启用可选的桥接并同步：

drush en mcp_tools_mcp_server -y
drush mcp-tools:mcp-server-sync --enable-read

📚 详细文档

• mcp_tools/docs/QUICKSTART.md — 5 分钟入门指南
• mcp_tools/docs/TROUBLESHOOTING.md — 常见错误及解决方法
• mcp_tools/docs/CLIENT_INTEGRATIONS.md — MCP 客户端配置（STDIO + HTTP）
• mcp_tools/docs/USE_CASES.md — 实际工作流程

🔧 技术细节

版本兼容性

PHP 支持：8.3、8.4

CI 在每次推送时针对所有支持的 Drupal 版本运行测试。

模块化架构

MCP Tools 使用 模块化架构，每个功能区域都是一个单独的子模块。这允许你仅启用所需的功能。

mcp_tools/                        # 基础模块（25 个只读工具）
├── src/
│   ├── Form/SettingsForm.php     # 管理界面位于 /admin/config/services/mcp-tools
│   └── Service/
│       ├── AccessManager.php     # 三层访问控制
│       ├── RateLimiter.php       # 写操作的速率限制
│       ├── AuditLogger.php       # 带有清理功能的审计日志记录
│       ├── WebhookNotifier.php   # Webhook 通知
│       └── ErrorFormatter.php    # 标准化错误响应
└── modules/
    ├── mcp_tools_content/        # 内容 CRUD（4 个工具）
    ├── mcp_tools_structure/      # 内容类型、字段、分类法、角色（20 个工具）
    ├── mcp_tools_users/          # 用户管理（5 个工具）
    ├── mcp_tools_menus/          # 菜单管理（5 个工具）
    ├── mcp_tools_views/          # 视图管理（6 个工具）
    ├── mcp_tools_blocks/         # 块放置（5 个工具）
    ├── mcp_tools_media/          # 媒体管理（6 个工具）
    ├── mcp_tools_webform/        # Web 表单集成（7 个工具）
    ├── mcp_tools_theme/          # 主题设置（8 个工具）
    ├── mcp_tools_layout_builder/ # 布局构建器（9 个工具）
    ├── mcp_tools_recipes/        # Drupal 配方（6 个工具）
    ├── mcp_tools_config/         # 配置管理（5 个工具）
    ├── mcp_tools_observability/  # 工具执行日志记录订阅器
    ├── mcp_tools_paragraphs/     # 段落集成（6 个工具）
    ├── mcp_tools_moderation/     # 内容审核（6 个工具）
    ├── mcp_tools_scheduler/      # 计划发布（5 个工具）
    ├── mcp_tools_metatag/        # SEO 元标签（5 个工具）
    ├── mcp_tools_image_styles/   # 图像样式（7 个工具）
    ├── mcp_tools_cache/          # 缓存管理（6 个工具）
    ├── mcp_tools_cron/           # Cron 管理（5 个工具）
    ├── mcp_tools_ultimate_cron/  # 终极 Cron（6 个工具）
    ├── mcp_tools_pathauto/       # URL 别名（6 个工具）
    ├── mcp_tools_redirect/       # URL 重定向（7 个工具）
    ├── mcp_tools_sitemap/        # XML 站点地图（7 个工具）
    ├── mcp_tools_search_api/     # 搜索 API（9 个工具）
    ├── mcp_tools_entity_clone/   # 实体克隆（4 个工具）
    ├── mcp_tools_analysis/       # 站点分析（8 个工具）
    ├── mcp_tools_batch/          # 批量操作（6 个工具）
    ├── mcp_tools_templates/      # 站点模板（5 个工具）
    ├── mcp_tools_migration/      # 内容迁移（7 个工具）
    ├── mcp_tools_jsonapi/        # JSON:API 实体 CRUD（6 个工具）
    └── mcp_tools_remote_media/   # 远程文件获取和媒体（1 个工具）

访问控制

MCP Tools 提供三层访问控制：

1. 基于模块的访问：仅启用的子模块暴露其工具。
2. 全局只读模式：在站点范围内切换以禁用所有写操作：

// 在 settings.php 中或通过配置
$config['mcp_tools.settings']['access']['read_only_mode'] = TRUE;

3. 连接范围：每个连接的访问级别（读/写/管理）。

默认设置：新安装默认仅具有 read 范围，通过 access.default_scopes 配置。

安全默认设置：默认禁用 HTTP 范围覆盖。仅在有受信任的反向代理剥离/覆盖客户端提供的范围头/参数时启用。

# 通过 HTTP 头
X-MCP-Scope: read,write

# 通过查询参数
?mcp_scope=read,write

# 通过环境变量（用于 STDIO 传输）
MCP_SCOPE=read,write drush mcp-tools:serve --uid=1

服务器配置文件（仅 YAML）

在 mcp_tools_servers.settings.yml 中定义多个 MCP 服务器配置文件，并通过 STDIO 的 --server 选项或远程的 server_id 设置选择它们。

新安装包括 development、staging 和 production 预设；更新 default_server 以指向所需的配置文件。

default_server: default
servers:
  default:
    name: 'Drupal MCP Tools'
    version: '1.0.0'
    pagination_limit: 50
    include_all_tools: false
    gateway_mode: false
    enable_resources: true
    enable_prompts: true
    component_public_only: false
    transports: ['http', 'stdio']
    scopes: ['read', 'write']
    # permission_callback: 'my_module.server_access:check'

范围始终受 access.allowed_scopes 限制。当没有受信任的覆盖时，使用 access.default_scopes。

设置 transports 以限制哪些入口点（HTTP/STDIO）可以运行配置文件；留空或省略以允许所有传输方式。 设置 component_public_only 以仅暴露明确标记为公共的组件。

可用范围：

• read - 只读操作
• write - 写操作
• admin - 管理操作

只读工具（25 个）

站点健康

内容

配置

用户

结构

发现

写子模块（31 个子模块中的 198 个工具）

启用所需功能的子模块。每个子模块的工具在其自己的 README.md 中列出。

可观测性钩子

MCP Tools 在工具执行期间分发 PSR-14 事件。订阅 code-wheel/mcp-events 中的这些类：

• CodeWheel\McpEvents\ToolExecutionStartedEvent
• CodeWheel\McpEvents\ToolExecutionSucceededEvent
• CodeWheel\McpEvents\ToolExecutionFailedEvent

事件包括工具名称、插件 ID、清理后的参数、请求 ID 和执行持续时间。失败事件包括原因常量（例如 REASON_VALIDATION、REASON_ACCESS_DENIED）。

启用可选的 mcp_tools_observability 子模块以将执行事件记录到看门狗日志。

📄 许可证

GPL-2.0-or-later

贡献

问题和合并请求：https://www.drupal.org/project/issues/mcp_tools

安全说明

内置保护

• 默认模块化：仅启用所需的子模块。
• 三层访问控制：模块、全局切换、连接范围。
• 基于权限：每个类别都有自己的 Drupal 权限。
• 审计日志记录：所有写操作都记录用户信息。
• 读操作节流：昂贵的读操作进行速率限制（断链、内容搜索）。
• 敏感数据清理：密码和机密信息从不记录。
• 受保护实体：uid 1、管理员角色、核心视图/菜单受保护。
• 危险权限阻止：无法通过 MCP 授予站点管理员权限。

受保护实体

阻止的权限

以下权限永远不能通过 MCP 授予：

• administer permissions
• administer users
• administer site configuration
• administer modules
• administer software updates
• administer themes
• bypass node access
• synchronize configuration
• import configuration
• export configuration

安全考虑

生产环境加固

如果必须在生产环境中使用 MCP Tools：

// settings.php - 启用只读模式
$config['mcp_tools.settings']['access']['read_only_mode'] = TRUE;

// 或者默认只允许读范围
$config['mcp_tools.settings']['access']['default_scopes'] = ['read'];

// 启用速率限制
$config['mcp_tools.settings']['rate_limiting']['enabled'] = TRUE;
$config['mcp_tools.settings']['rate_limiting']['max_writes_per_minute'] = 10;
$config['mcp_tools.settings']['rate_limiting']['max_writes_per_hour'] = 100;

额外建议：

1. 在 Web 服务器级别使用 IP 允许列表。
2. 要求 MCP 端点进行身份验证。
3. 监控审计日志以发现异常活动。
4. 在生产环境中禁用写子模块。
5. 使用单独的环境进行 AI 辅助开发。

配置管理警告

MCP Tools 直接在数据库中创建配置。这可能导致 配置漂移：

开发者将配置提交到 Git
  ↓
部署到生产环境
  ↓
AI 通过 MCP 创建新的内容类型（仅在数据库中！）
  ↓
下次部署：配置冲突或覆盖！

最佳实践：使用写工具后始终导出配置：

# 使用 MCP 创建结构后
drush config:export
git add config/
git commit -m "Export MCP-created configuration"

测试

PHPUnit 测试包含所有服务：

cd mcp_tools
../vendor/bin/phpunit