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