Drupal API MCP服务器
一个模型上下文协议（MCP）服务器，在Drupal API文档中提供语义搜索。用自然语言提问，获取相关的Drupal函数、钩子、类和API文档。
这是什么？
MCP（模型上下文协议） 是允许AI助手访问外部工具和数据源的标准。该服务器实现MCP，使人工智能助手（如Cursor、Claude Desktop等）能够通过语义搜索访问Drupal的API文档。
服务器通过读取项目的Drupal版本来自动检测您正在使用的Drupal版本 composer.lock 文件，确保您获得与Drupal版本匹配的文档。
您可以提出以下问题，而不是手动搜索文档：
- “如何复制实体？”
- “保存节点时会触发什么钩子？”
- “显示实体API”
获取相关的Drupal API文档，其中包含特定Drupal版本的代码示例。
运作原理
此项目使用 向量嵌入 以启用语义搜索。架构如下：
flowchart TB
subgraph Maintainer["🔧 Maintainer Workflow"]
direction LR
A1[Drupal Core
*.api.php files] -->|Parse| A2[API Documentation]
A2 -->|Generate Embeddings| A3[Ollama
Embedding Model]
A3 -->|Export| A4[JSON Files
in Git]
end
subgraph EndUser["👤 End User Workflow"]
direction TB
B1[JSON Files
from Git] -->|Hydrate| B2[Redis
Vector Store]
B3[IDE
Cursor/Claude] -->|Query| B4[MCP Server]
B4 -->|Generate Query Embedding| B5[Ollama
Embedding Model]
B5 -->|Query Vector| B4
B4 -->|Vector Search| B2
B2 -->|Results| B4
B4 -->|Documentation| B3
end
Maintainer -->|Pre-computed| EndUser
style A1 fill:#16A085,stroke:#138D75,stroke-width:2px,color:#fff
style A2 fill:#5C6BC0,stroke:#3F51B5,stroke-width:2px,color:#fff
style A3 fill:#F39C12,stroke:#D68910,stroke-width:2px,color:#fff
style A4 fill:#FF9800,stroke:#F57C00,stroke-width:2px,color:#fff
style B1 fill:#FF9800,stroke:#F57C00,stroke-width:2px,color:#fff
style B2 fill:#E74C3C,stroke:#C0392B,stroke-width:2px,color:#fff
style B3 fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
style B4 fill:#9B59B6,stroke:#6C3483,stroke-width:2px,color:#fff
style B5 fill:#F39C12,stroke:#D68910,stroke-width:2px,color:#fff过程
- 摄入 （仅限维护人员）：
- 解析Drupal *.api.php 用于提取API文档的文件 - 使用Ollama的嵌入模型生成向量嵌入 - 将嵌入导出为JSON文件并提交到Git
- 水合 （最终用户）：
- 从Git下载预先计算的JSON嵌入 - 将它们加载到Redis矢量存储中以进行快速搜索
- 运行时 （最终用户）：
- 您的IDE向MCP服务器发送自然语言查询 - 服务器会自动检测您的Drupal版本 composer.lock （或使用手动设置的版本） - 服务器使用Ollama为您的查询生成嵌入 - 在Redis矢量存储中搜索与Drupal版本匹配的类似文档 - 返回相关的API文档以及特定版本的代码示例
关键组件
所有组件均 开源和免费:
- MCP-PHP-SDK (
mcp/sdk)：处理IDE和服务器之间的MCP协议通信 - PHP解析器 (
nikic/php-parser)：解析Drupal的*.api.php用于提取函数、钩子、类和文档的文件 - DocBlock提取器：从PHP文档块中提取文档和代码示例
- Docker&Docker编写：容器化Redis和Ollama服务，便于设置和管理
- 瑞迪斯 （使用Redis Stack）：用于嵌入的快速语义搜索的矢量数据库
- 奥拉玛：用于生成向量嵌入的免费本地LLM服务（不需要API密钥）
- 预计算嵌入：包含Drupal API文档嵌入的JSON文件（存储在Git中）
快速开始
先决条件
- PHP 8.2+ （检查
php -v) - 作曲家 （检查
composer --version) - Docker&Docker编写 （适用于Redis和Ollama服务）
安装步骤
- 克隆和安装依赖关系：
git clone https://github.com/your-org/surge-mcp.git
cd surge-mcp
composer install- 设置服务（Redis和Ollama）：
bin/surge setup此命令：
- 使用Docker Compose启动Redis和Ollama - 提取所需的嵌入模型(nomic-embed-text) - 验证服务是否正在运行
- 将预先计算的嵌入加载到Redis中：
bin/surge hydrate或者使用控制台命令：
php bin/console surge:hydrate这从 embeddings/ 目录到Redis。
- 配置您的MCP客户端 （例如，光标）：
将其添加到MCP配置文件中（通常 ~/.cursor/mcp.json 或类似）：
{
"mcpServers": {
"drupal-api": {
"command": "php",
"args": ["/absolute/path/to/surge-mcp/server.php"]
}
}
}替换 /absolute/path/to/surge-mcp 与这个项目的实际路径。
- 重新启动IDE 加载MCP服务器。
就是这样！您的AI助手现在可以搜索Drupal文档。
配置（可选）
如果需要自定义设置，请创建 .env 项目根目录中的文件：
# Redis connection (default: redis://localhost:6379)
REDIS_URL=redis://localhost:6379
# Ollama URL (default: http://localhost:11434)
OLLAMA_URL=http://localhost:11434
# Ollama embedding model (default: nomic-embed-text)
OLLAMA_MODEL=nomic-embed-text服务器将自动读取这些环境变量。如果未设置，则使用上面显示的默认值。
可用工具
MCP服务器为AI助手提供以下工具：
| 工具 | 说明 | 示例 |
|---|---|---|
drupal_search | 用自然语言进行语义搜索 | “触发实体保存的钩子” |
drupal_lookup | 按确切名称直接查找 | hook_entity_presave |
drupal_versions | 列出可用的Drupal版本 | 返回： ["10.x", "11.x"] |
drupal_set_version | 设置会话的默认版本 | "11.x" |
drupal_app_info | 从项目中自动检测版本 | 读取 composer.lock |
搜索工作原理
当您通过IDE提问时，MCP服务器会结合多种策略以获得最佳结果：
flowchart LR
A[Your Question] --> B[MCP Server]
B --> C{Exact Match?}
C -->|Yes| D[Return Result]
C -->|No| E[Generate Query Embedding]
E --> F[Vector Search in Redis]
F --> G[Rank & Combine Results]
G --> D
style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:2px,color:#fff
style B fill:#9B59B6,stroke:#6C3483,stroke-width:2px,color:#fff
style C fill:#95A5A6,stroke:#7F8C8D,stroke-width:2px,color:#fff
style D fill:#27AE60,stroke:#229954,stroke-width:2px,color:#fff
style E fill:#F39C12,stroke:#D68910,stroke-width:2px,color:#fff
style F fill:#E74C3C,stroke:#C0392B,stroke-width:2px,color:#fff
style G fill:#5C6BC0,stroke:#3F51B5,stroke-width:2px,color:#fff搜索策略：
- 完全匹配：如果你搜索
hook_entity_presave，它直接找到它（快速路径） - 语义搜索：将您的问题转换为向量嵌入，并使用向量相似度查找类似的文档
- 关键词提升：与重要关键字匹配的结果排名更高
- 智能排名：组合所有信号（精确匹配、语义相似性、关键字匹配）以返回最相关的结果
查询流示例：
You: "What hook fires when an entity is saved?"
1. Try exact match: "hook_entity_save" → Not found
2. Generate embedding for your question using Ollama
3. Search Redis for similar vectors
4. Find: hook_entity_presave, hook_entity_update, etc.
5. Boost results with "hook" and "save" keywords
6. Return top 5 results with descriptions and examples命令参考
该项目提供两个命令界面：
bin/surge -高级CLI工具
常见任务的简化命令：
bin/surge setup # Set up Docker services (Redis, Ollama)
bin/surge hydrate [version] # Load embeddings into Redis (all or specific version)
bin/surge status # Show status of services and versions
bin/surge add # Add a new Drupal version (maintainers only)
bin/surge update # Update an existing Drupal version (maintainers only)php bin/console -Symfony控制台命令
用于高级使用的低级命令：
php bin/console surge:hydrate [--drupal-version=VERSION] [--force]
php bin/console surge:ingest # Generate embeddings (maintainers only)
php bin/console surge:export # Export embeddings to JSON (maintainers only)
php bin/console surge:test # Test the MCP server connection项目结构
surge-mcp/
├── bin/
│ ├── console # Symfony Console entry point
│ └── surge # High-level CLI tool
├── src/
│ ├── Commands/ # Console commands
│ ├── Embeddings/ # Embedding provider implementations
│ ├── Parser/ # Drupal API file parsers
│ ├── Services/ # Core services (Redis, EmbeddingService, etc.)
│ └── Tools/ # MCP tools (search, lookup, etc.)
├── embeddings/ # Pre-computed JSON embeddings (committed to Git)
├── server.php # MCP server entry point
├── docker-compose.yml # Docker services configuration
└── composer.json # PHP dependencies对于维护人员
摄取工作流用于添加或更新Drupal版本：
添加新的Drupal版本
- 设置服务 （如果尚未运行）：
bin/surge setup- 添加Drupal版本：
bin/surge add 11.x这将：
- 使用Composer下载Drupal核心 - 解析 *.api.php 用于提取API元素的文件 - 使用Olama生成嵌入 - 导出到JSON文件 embeddings/
- 提交嵌入：
git add embeddings/drupal-11.x.json embeddings/manifest.json
git commit -m "Add Drupal 11.x support"更新现有版本
bin/surge update 11.x这将更新Drupal核心，重新生成嵌入，并导出为JSON。
故障排除
服务未启动
检查Docker是否正在运行：
docker ps检查服务状态：
bin/surge status嵌入未加载
确保Redis正在运行且可访问：
docker-compose ps
redis-cli ping # Should return PONGMCP服务器未连接
- 验证MCP配置中的路径是否绝对正确
- 检查PHP是否可以执行：
php server.php（应等待输入） - 检查IDE的MCP控制台中的日志
- 确保安装了所有依赖项：
composer install