MCP Drupal文档服务器
一个模型上下文协议（MCP）服务器，提供用于搜索和访问Drupal和PHP文档的工具和资源。
概述
该项目实现了一个MCP服务器，允许AI助手从Drupal和PHP文档中搜索和检索信息。它遵循严格的测试驱动开发（TDD）方法，以确保高代码质量和全面的测试覆盖率。
特性
- 遵循模型上下文协议规范的MCP服务器实现
- 用于搜索Drupal和PHP文档的工具
- 用于访问文档内容的资源
- 基于自定义文件的矢量数据库集成用于语义搜索
- 全面的测试套件，覆盖率高
项目结构
mcp-drupal-ts/
├── src/ # Source code
│ ├── mcp/ # MCP server implementation
│ │ ├── tools/ # MCP tools
│ │ └── resources/ # MCP resources
│ ├── types/ # TypeScript type definitions
│ └── index.ts # Entry point
├── tests/ # Test files
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── docs/ # Documentation
│ └── README.md # Documentation index
└── README.md # This file测试驱动开发
该项目遵循严格的测试驱动开发（TDD）方法。所有功能和错误修复必须按照TDD流程实施：
- 先写测试
- 运行测试以验证它们是否失败
- 实现最少的代码以使测试通过
- 在保持通过测试的同时进行重构
有关此项目中TDD过程的详细信息，请参阅 TDD文档.
入门指南
先决条件
- Node.js 18或更高版本
- npm 8或更高版本
安装
- 克隆存储库：
git clone https://github.com/yourusername/mcp-drupal-ts.git
cd mcp-drupal-ts- 安装依赖项：
npm install- 构建项目：
npm run build运行测试
运行所有测试：
npm test仅运行单元测试：
npm run test:unit仅运行集成测试：
npm run test:integration生成覆盖率报告：
npm run test:coverage运行服务器
启动MCP服务器：
npm start对于自动重建的开发：
npm run dev用法
MCP服务器可供支持模型上下文协议的AI助手使用。它提供了搜索和访问Drupal和PHP文档的工具和资源。
用于RooCode的MCP服务器
该项目可以用作RooCode的MCP服务器，为PHP和Drupal文档提供语义搜索功能。有关详细说明，请参阅 RooCode MCP服务器指南.
文档管道
该项目包括一个文档管道，用于收集、处理和导入Drupal和PHP文档：
- 从来源收集文件
npm run collect-php-docs
npm run collect-drupal-docs- 将文档转换为markdown格式
npm run markdown-php-docs
npm run markdown-drupal-docs- 将文档导入数据库
npm run import-docs- 运行整个管道
npm run docs-pipeline矢量搜索
该项目使用基于自定义文件的矢量数据库进行语义搜索：
- 使用语义搜索搜索文档
npm run search-docs -- "your search query"矢量数据库是一个简单的基于JSON的存储系统，不需要单独的服务器进程。
有关矢量数据库集成的更多详细信息，请参阅 矢量数据库文档.
矢量数据库发布管理
该项目为矢量数据库文件实现了一种基于发布的分发方法。它们不是在Git存储库中存储大型矢量数据库文件，而是通过GitHub版本进行管理，并在需要时自动下载。
架构概述
矢量数据库发布系统由几个组件组成：
- 版本管理A.
vector-db-version.jsonfile跟踪矢量文件的元数据，包括版本、校验和和和兼容性信息 - 开发设置：用于设置具有必要矢量文件的开发环境的工具
- 释放大楼：用于构建和发布新矢量数据库版本的脚本
- 部署：确保矢量文件在部署过程中存在的脚本
- CI/CD集成：GitHub Actions工作流用于自动化发布过程
这种方法有几个好处：
- 保持Git存储库的小型化和可管理性
- 确保所有开发人员使用相同的矢量数据库文件
- 提供版本控制和兼容性检查
- 通过完整性验证实现轻松更新
矢量数据库版本系统
该系统对矢量数据库版本使用语义版本控制，独立于主应用程序版本。矢量文件元数据存储在 vector-db-version.json:
{
"version": "0.1.0", // Semantic version of the vector database
"releaseDate": "2025-05-12", // Last update date
"compatibility": { // App version compatibility range
"minAppVersion": "0.1.0",
"maxAppVersion": null
},
"files": { // Vector files included in this version
"drupal-vectors.json": {
"size": 0,
"checksum": "",
"lastUpdated": "2025-05-12",
"description": "Drupal documentation vector embeddings"
},
"php-vectors.json": {
"size": 0,
"checksum": "",
"lastUpdated": "2025-05-12",
"description": "PHP documentation vector embeddings"
}
},
"repositoryInfo": { // Repository information for downloads
"owner": "your-github-username",
"repo": "mcp-drupal-ts",
"releasesUrl": "https://github.com/your-github-username/mcp-drupal-ts/releases"
}
}当应用程序运行时，它会检查这些矢量文件，如果它们丢失或损坏，则会下载它们。
开发工作流程
建立发展环境
当您首次克隆存储库或需要刷新矢量文件时：
# Install dependencies and auto-setup vector files (runs after npm install)
npm install
# Or manually set up the development environment
npm run setup:dev
# Force redownload of all vector files
npm run setup:dev:force安装脚本：
- 检查矢量数据库文件是否存在
- 从GitHub版本下载缺失的文件
- 使用校验和验证文件完整性
- 报告所有文件的状态
创建新的矢量数据库版本
当您需要创建新的矢量版本时（例如，在更新嵌入后）：
# Build a release with patch version increment (0.1.0 → 0.1.1)
npm run vector:build-release:patch
# Build a release with minor version increment (0.1.0 → 0.2.0)
npm run vector:build-release:minor
# Build a release with major version increment (0.1.0 → 1.0.0)
npm run vector:build-release:major
# Or specify the increment type as an argument
npm run vector:build-release -- minor发布生成器：
- 根据指定类型递增版本
- 更新文件元数据（大小、校验和、日期）
- 在中创建发布包
dist/vector-release目录 - 提供在GitHub上发布版本的说明
建成后：
- 提交更新
vector-db-version.json文件 - 用标记提交
vector-db-v{version}（例如。，vector-db-v0.2.0) - 使用以下文件创建GitHub版本
dist/vector-release
使用矢量文件部署
部署应用程序时：
# Deploy with automatic vector file management
npm run deploy
# Or directly
bash scripts/deploy-with-vectors.sh部署脚本：
- 读取矢量数据库版本信息
- 检查每个所需的矢量文件
- 从GitHub版本下载缺失的文件
- 继续部署过程
这确保了在应用程序启动之前，所有必要的矢量文件都可用。
带有GitHub操作的CI/CD
该项目包括一个用于自动矢量数据库发布的GitHub Actions工作流：
手动触发
您可以从GitHub Actions选项卡手动触发发布：
- 选择“矢量数据库发布”工作流程
- 点击“运行工作流”
- 选择版本增量类型（主要、次要、补丁）
- 可选择启用自动GitHub发布创建
自动触发
按格式推送标签 vector-db-v* （例如。， vector-db-v0.2.0)也将触发工作流：
git tag vector-db-v0.2.0
git push origin vector-db-v0.2.0工作流程：
- 构建应用程序
- 生成矢量数据库文件（如果手动触发）
- 更新版本信息
- 使用矢量文件创建GitHub版本
- 可选地提交对版本文件的更改
NPM脚本参考
矢量数据库管理：
setup:dev：使用矢量文件设置开发环境setup:dev:force：强制重新下载所有矢量文件vector:build-release：构建向量版本（默认：补丁）vector:build-release:patch：使用补丁增量构建矢量发布vector:build-release:minor：以较小的增量构建矢量版本vector:build-release:major：以大幅增量构建矢量版本deploy：使用自动矢量文件管理进行部署
相关文档脚本：
docs-pipeline：运行完整的文档处理管道import-docs：将文档导入矢量数据库search-docs：使用语义搜索搜索文档
常见问题排查
缺少矢量文件
- 问题：应用程序报告缺少矢量文件
- 解决方案：运行
npm run setup:dev下载矢量文件
校验和验证失败
- 问题：矢量文件校验和验证失败
- 解决方案：运行
npm run setup:dev:force强制重新下载所有文件
未找到GitHub版本
- 问题：无法从GitHub版本下载矢量文件
- 解决方案：检查中的存储库信息
vector-db-version.json正确且GitHub版本存在
拒绝使用sectors.sh进行部署的权限
- 问题：无法执行部署脚本
- 解决方案：使脚本可执行
chmod +x scripts/deploy-with-vectors.sh
部署脚本中找不到jq错误
- 问题：部署脚本报告找不到jq
- 解决方案：这只是一个警告；脚本将回退到Node.js进行JSON解析
通过MCP进行语义搜索
矢量数据库为通过MCP服务器公开的语义搜索工具提供动力。这允许像RooCode这样的AI助手对文档进行语义搜索：
{
"id": "789",
"jsonrpc": "2.0",
"method": "call_tool",
"params": {
"name": "semantic-docs-search",
"arguments": {
"query": "How to apply a function to each element of an array?"
}
}
}MCP服务器可供支持模型上下文协议的AI助手使用。它提供了搜索和访问Drupal和PHP文档的工具和资源。
工具使用示例
{
"id": "123",
"jsonrpc": "2.0",
"method": "call_tool",
"params": {
"name": "drupal-docs-search",
"arguments": {
"query": "hook_form_alter"
}
}
}资源访问示例
{
"id": "456",
"jsonrpc": "2.0",
"method": "read_resource",
"params": {
"uri": "drupal-docs://api/hook_form_alter"
}
}贡献
欢迎投稿！请按照以下步骤操作：
- 分叉存储库
- 创建要素分支
- 遵循TDD流程（先写测试！）
- 提交拉取请求
有关更多详细信息，请参阅 贡献指南.
开发指南
- 遵循TDD流程进行所有更改
- 保持高测试覆盖率（最低80%）
- 遵循TypeScript的最佳实践
- 使用ESLint提高代码质量
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
致谢
- MCP规范的模型上下文协议团队
- Drupal社区的优秀文档