内容
# 矩阵需求 MCP 服务器
一个连接 Claude 到您的 [矩阵需求](https://matrixreq.com/) ALM 实例的 MCP（模型上下文协议）服务器。提供对项目、项目项、文件夹、链接、标签、待办事项和文档生成的完全 CRUD 访问。
## 先决条件
- Node.js 18+
- 一个具有 API 访问权限的 Matrix Requirements 实例
- 一个 API令牌（在 Matrix 的用户菜单 → 访问令牌下创建）
## 设置
### 1. 安装依赖并构建
```bash
npm install
npm run build
```
### 2. 配置环境变量
服务器需要两个环境变量：
| 变量 | 描述 | 示例 |
|---|---|---|
| `MATRIX_URL` | 您的 Matrix 实例 URL | `https://clouds5.matrixreq.com` |
| `MATRIX_TOKEN` | 您的 API 令牌（不带 "Token " 前缀） | `abc123def456...` |
### 3. 添加到 Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"matrix-requirements": {
"command": "node",
"args": ["/absolute/path/to/matrix-req-mcp/dist/index.js"],
"env": {
"MATRIX_URL": "https://your-instance.matrixreq.com",
"MATRIX_TOKEN": "your-api-token-here"
}
}
}
}
```
### 4. 添加到 Claude Code
```bash
claude mcp add matrix-requirements \
-e MATRIX_URL=https://your-instance.matrixreq.com \
-e MATRIX_TOKEN=your-api-token-here \
-- node /absolute/path/to/matrix-req-mcp/dist/index.js
```
## 可用工具
### 项目与导航
| 工具 | 描述 |
|---|---|
| `list_projects` | 列出实例上的所有项目 |
| `get_project_info` | 获取项目的类别和字段定义 |
| `get_folder_tree` | 获取项目的根文件夹树 |
| `get_folder_children` | 获取特定文件夹的子文件夹 |
### 项目项（CRUD）
| 工具 | 描述 |
|---|---|
| `get_item` | 获取具有所有字段、链接和标签的单个项目项 |
| `search_items` | 按 MRQL 或自由文本搜索项目项（返回 ID） |
| `search_items_with_details` | 搜索具有完整详细信息的项目项 |
| `create_item` | 在文件夹中创建新的项目项 |
| `update_item_title` | 更新项目项的标题 |
| `set_field` | 设置单个字段值 |
| `set_fields` | 同时设置多个字段值 |
| `delete_item` | 删除项目项或文件夹 |
| `move_items` | 将项目项移动到不同文件夹 |
### 文件夹
| 工具 | 描述 |
|---|---|
| `create_folder` | 在项目中创建新文件夹 |
### 链接（可追溯性）
| 工具 | 描述 |
|---|---|
| `get_links` | 获取项目项的所有上行和下行链接 |
| `add_downlink` | 在项目项之间添加跟踪链接 |
| `remove_downlink` | 删除项目项之间的跟踪链接 |
### 标签
| 工具 | 描述 |
|---|---|
| `set_labels` | 在项目项上设置标签 |
### 待办事项与审计
| 工具 | 描述 |
|---|---|
| `get_todos` | 获取项目的待办事项 |
| `get_audit` | 获取变更/审计日志 |
### 文档生成
| 工具 | 描述 |
|---|---|
| `generate_document` | 将 DOC 导出为 PDF、HTML、DOCX 或 ODT |
## MRQL 搜索语法
Matrix 使用 MRQL 进行结构化查询。示例：
- `mrql:category=REQ` — 所有需求
- `mrql:category=REQ AND title~"safety"` — 标题中包含"safety"的需求
- `mrql:category=TC AND label=approved` — 已批准的测试用例
- 自由文本搜索也有效（只需传递搜索字符串）
## 开发
```bash
npm run dev # 监视模式 - 更改时重新编译
npm run build # 一次性构建
npm start # 运行服务器
```
