shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

mcp-tools

MCP Tools是一个为Drupal站点提供AI助手工具的模块，包含223个工具，支持读写操作、资源访问和提示功能，主要用于本地开发和原型设计，具有模块化架构和三层访问控制安全机制。

article

README

🚀 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 — 实际工作流程

🔧 技术细节

版本兼容性

| Drupal 版本 | PHP 版本 | 状态 | 说明 | |----------------|-------------|--------|-------| | 10.3.x | 8.3 | ✅ 已测试 | 最低支持版本 | | 11.x | 8.4 | ✅ 已测试 | Drupal 11 需要 PHP 8.4+ |

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;
  1. 连接范围：每个连接的访问级别（读/写/管理）。

默认设置：新安装默认仅具有 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 个）

站点健康

| 工具 | 描述 | |------|-------------| | get_site_status | Drupal/PHP 版本、模块数量、Cron、维护模式 | | get_system_status | 系统要求、PHP 信息、数据库状态 | | check_security_updates | 核心和贡献模块的安全更新 | | check_cron_status | Cron 健康状况和上次运行时间 | | analyze_watchdog | 日志分析 - 错误、警告、摘要 | | get_queue_status | 队列项数量和工作器状态 | | get_file_system_status | 目录权限、磁盘使用情况 |

内容

| 工具 | 描述 | |------|-------------| | list_content_types | 带有字段定义的内容类型 | | get_recent_content | 最近创建/修改的内容 | | search_content | 基于标题的内容搜索 | | get_vocabularies | 带有术语计数的分类法词汇表 | | get_terms | 词汇表中的术语（扁平或层次结构） | | get_files | 带有 MIME 分类的托管文件 | | find_orphaned_files | 未使用文件检测 |

配置

| 工具 | 描述 | |------|-------------| | get_config_status | 配置同步状态（活动与暂存） | | get_config | 查看特定配置对象 | | list_config | 列出配置名称，可选择前缀过滤 | | list_text_formats | 列出所有可用的文本格式 | | get_text_format | 获取特定文本格式的详细信息 |

用户

| 工具 | 描述 | |------|-------------| | get_roles | 带有权限的角色 | | get_users | 用户账户、状态、活动 | | get_permissions | 按提供者列出所有权限 |

结构

| 工具 | 描述 | |------|-------------| | get_menus | 所有菜单及其链接计数 | | get_menu_tree | 层次结构菜单结构 |

发现

| 工具 | 描述 | |------|-------------| | mcp_tools_list_available | 按类别或搜索列出所有可用的 MCP 工具 |

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

启用所需功能的子模块。每个子模块的工具在其自己的 README.md 中列出。 | 子模块 | 工具数量 | 描述 | |-----------|------:|-------------| | mcp_tools_content | 4 | 内容 CRUD（创建、更新、删除、发布） | | 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 | 7 | Web 表单管理和提交（需要 webform） | | mcp_tools_theme | 8 | 主题设置、启用/禁用 | | mcp_tools_layout_builder | 9 | 布局部分、块、插件（需要 layout_builder） | | mcp_tools_recipes | 6 | Drupal 配方 — 应用需要 admin 范围（10.3+） | | mcp_tools_config | 5 | 配置差异、导出、MCP 更改跟踪、预览 | | mcp_tools_paragraphs | 6 | 段落类型和字段（需要 paragraphs） | | mcp_tools_moderation | 6 | 内容审核工作流程（需要 content_moderation） | | mcp_tools_scheduler | 5 | 计划发布/取消发布（需要 scheduler） | | mcp_tools_metatag | 5 | SEO 元标签（需要 metatag） | | mcp_tools_image_styles | 7 | 图像样式和效果 | | mcp_tools_cache | 6 | 缓存清除、失效、重建 | | mcp_tools_cron | 5 | Cron 作业和队列 | | mcp_tools_ultimate_cron | 6 | 终极 Cron 作业管理（需要 ultimate_cron） | | mcp_tools_pathauto | 6 | URL 别名模式（需要 pathauto） | | mcp_tools_redirect | 7 | URL 重定向（需要 redirect） | | mcp_tools_sitemap | 7 | XML 站点地图管理（需要 simple_sitemap） | | mcp_tools_search_api | 9 | 搜索索引和服务器（需要 search_api） | | mcp_tools_entity_clone | 4 | 实体克隆（需要 entity_clone） | | mcp_tools_analysis | 8 | SEO、安全、可访问性、性能审计 | | mcp_tools_batch | 6 | 批量内容操作（每批最大 50 项） | | mcp_tools_templates | 5 | 站点模板（博客、投资组合、商业、文档） | | mcp_tools_migration | 7 | CSV/JSON 导入和导出（最大 100 项） | | mcp_tools_jsonapi | 6 | 通过 JSON:API 进行通用实体 CRUD（需要 jsonapi） | | mcp_tools_remote_media | 1 | 远程文件获取和媒体创建 |

可观测性钩子

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 授予站点管理员权限。

受保护实体

| 实体 | 保护措施 | |--------|------------| | 用户 ID 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

安全考虑

| 风险 | 缓解措施 | 状态 | |------|------------|--------| | 提示注入 | 恶意内容可能指示 AI | ⚠️ 在生产环境中使用只读模式 | | 权限提升 | 阻止危险权限 | ✅ 已实现 | | 内容注入（XSS） | 依赖 Drupal 的文本过滤 | ✅ Drupal 处理 | | 通过大规模创建进行 DoS 攻击 | 速率限制 | ✅ 已实现 | | 数据泄露 | 读工具暴露站点信息 | ⚠️ 使用适当的身份验证 | | 配置漂移 | 更改不在 Git 中 | ⚠️ 更改后导出配置 |

生产环境加固

如果必须在生产环境中使用 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
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端