内容
# 红矿MCP服务器插件
一款红矿插件，暴露一个模型上下文协议（MCP）服务器，使AI助手能够与您的红矿安装程序交互。该插件允许AI工具通过标准化的协议读取和管理问题、项目、wiki页面、时间条目等。
## 概述
红矿MCP服务器插件将您的红矿实例转换为MCP兼容的服务器，允许AI助手：
- 浏览和搜索问题、项目和wiki页面
- 创建和更新问题，支持完整的字段
- 记录问题和项目的时间条目
- 访问用户配置文件和项目元数据
- 使用实时红矿数据生成结构化报告
- 利用预建的常见工作流提示模板
所有操作都尊重红矿的权限系统，确保AI助手只能访问经过身份验证的用户可以查看的数据。
## 功能
- **49种综合工具** 用于问题管理、项目导航、时间跟踪、wiki编辑、附件、元数据查询和管理员配置
- **5种智能提示** 带有嵌入式实时数据，用于错误报告、状态报告、冲刺总结和发布说明
- **6种资源模板** 通过URI模式高效访问数据
- **HTTP + SSE传输** 实现完整的MCP协议合规性
- **API密钥身份验证** 使用标准的红矿API密钥
- **基于权限的访问** - 尊重所有红矿权限和可见性规则
- **速率限制** 防止AI循环失控
- **写入保护** - 可选限制AI仅进行只读操作
- **无外部依赖** - 仅使用Ruby标准库
## 要求
- **红矿：** 5.0或更高
- **Ruby：** 2.7或更高
- **MCP客户端：** 任何MCP兼容的客户端
## 安装
1. **下载插件：**
```bash
cd /path/to/redmine/plugins
git clone https://github.com/Toblias/redmine_mcp.git
```
2. **重启红矿：**
```bash
# For Passenger
touch /path/to/redmine/tmp/restart.txt
# For Puma/Unicorn
systemctl restart redmine
```
3. **配置插件：**
- 导航到 **管理 > 插件 > 红矿MCP服务器 > 配置**
- 启用MCP服务器
- 根据需要配置速率限制和超时
- 可选启用写入操作（默认为安全禁用）
## 配置
### 管理员设置
在 **管理 > 插件 > 红矿MCP服务器 > 配置** 访问插件设置：
| 设置 | 默认值 | 描述 |
|---------|---------|-------------|
| **启用MCP服务器** | 已启用 | MCP端点的主开关 |
| **启用写入操作** | 禁用 | 允许AI创建/更新问题，记录时间，编辑wiki |
| **速率限制** | 60/分钟 | 每用户请求限制，防止AI循环失控 |
| **请求超时** | 30秒 | 最大工具执行时间 |
| **SSE连接超时** | 3600秒（1小时） | 最大SSE连接持续时间 |
| **心跳间隔** | 30秒 | SSE连接保持活跃的ping频率 |
| **默认列表限制** | 25 | 列表操作的默认分页大小 |
| **最大列表限制** | 100 | 允许的最大分页大小 |
### 安全考虑
1. **写入操作：** 默认禁用。启用后，AI助手可以创建/修改数据。仅为受信任的用户启用。
2. **API密钥：** 为MCP客户端使用专用的API密钥。定期轮换密钥。
3. **速率限制：** 防止AI进行过多请求。根据服务器容量调整。
4. **权限：** 所有操作都尊重红矿权限。用户只能访问他们有权查看的数据。
## 初始设置检查清单
在使用MCP插件创建问题之前，请确保您的红矿实例已配置以下内容：
### 必需配置
这些项目是创建问题所需的：
- [ ] **问题状态** - 至少一个状态（例如：新建、进行中、已关闭）
- [ ] **问题跟踪器** - 至少一个跟踪器（例如：错误、功能、任务）
- [ ] **问题优先级** - 至少一个优先级（例如：低、正常、高）
- [ ] **时间条目活动** - 至少一个活动用于时间跟踪（例如：开发、设计）
### 可选配置
- [ ] **问题类别** - 按项目的分类
- [ ] **版本/里程碑** - 按项目的发布跟踪
### 通过MCP快速设置（仅限管理员）
如果您的红矿是全新安装的，您可以使用管理员工具设置基础：
```
1. create_status - 创建“新建”、“进行中”、“已关闭”状态
2. create_tracker - 创建“错误”、“功能”、“任务”跟踪器（需要先创建状态）
3. create_priority - 创建“低”、“正常”、“高”、“紧急”优先级
4. create_activity - 创建“开发”、“设计”、“测试”活动
```
**示例工作流：**
```
# 首先，创建状态（跟踪器需要）
create_status(name: "New", is_closed: false)
create_status(name: "In Progress", is_closed: false)
create_status(name: "Closed", is_closed: true)
# 然后创建跟踪器（需要默认状态）
create_tracker(name: "Bug", default_status_id: 1)
create_tracker(name: "Feature", default_status_id: 1)
# 创建优先级
create_priority(name: "Low")
create_priority(name: "Normal", is_default: true)
create_priority(name: "High")
# 创建时间跟踪活动
create_activity(name: "Development", is_default: true)
create_activity(name: "Design")
```
## MCP端点
插件在您的红矿基准URL上暴露一个MCP端点：
### 端点
| 方法 | 路径 | 目的 |
|--------|------|---------|
| **GET** | `/mcp` | 服务器发起事件的SSE流 |
| **POST** | `/mcp` | JSON-RPC消息处理（工具执行） |
| **GET** | `/mcp/health` | 负载均衡器的健康检查（不需要身份验证） |
### 身份验证
所有请求（`/mcp/health`除外）都需要通过`X-Redmine-API-Key`头进行身份验证：
```bash
# 健康检查（不需要身份验证）
curl https://redmine.example.com/mcp/health
# MCP请求需要API密钥
curl -X POST \
-H "X-Redmine-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"ping","id":1}' \
https://redmine.example.com/mcp
```
**生成API密钥：**
1. 登录红矿
2. 进入 **我的账户** （右上角）
3. 点击 **显示** 在“API访问密钥”下（或如果不存在则生成）
4. 复制密钥用于MCP客户端配置
## 工具
插件提供49种工具，分为类别：
### 问题工具（8）
| 工具 | 描述 |
|------|-------------|
| `list_issues` | 列出问题并过滤（项目、状态、指派人、跟踪器、优先级、排序） |
| `get_issue` | 获取详细的问题信息，可选日志、附件、关系 |
| `create_issue` | 创建一个新问题，支持完整的字段 |
| `update_issue` | 更新现有的问题字段，添加备注，变更状态 |
| `search_issues` | 问题主体和描述的全文搜索 |
| `delete_issue` | 删除一个问题（需要delete_issues权限） |
| `bulk_update_issues` | 一次更新多个问题 |
| `bulk_delete_issues` | 一次删除多个问题（需要delete_issues权限） |
### 项目工具（5）
| 工具 | 描述 |
|------|-------------|
| `list_projects` | 列出所有可见的项目，支持按状态过滤 |
| `get_project` | 获取项目详情，包括成员、版本、启用的模块 |
| `create_project` | 创建一个新项目，包含模块、跟踪器和父设置 |
| `update_project` | 更新项目设置、模块、父项目和可见性 |
| `delete_project` | 删除一个项目和所有数据（仅限管理员，不可逆） |
### 时间条目工具（4）
| 工具 | 描述 |
|------|-------------|
| `list_time_entries` | 列出时间条目并过滤（项目、问题、用户、日期范围） |
| `get_time_entry` | 获取详细的时间条目信息 |
| `log_time` | 记录时间到问题或项目 |
| `delete_time_entry` | 删除时间条目（需要delete_time_entries权限） |
### Wiki工具（3）
| 工具 | 描述 |
|------|-------------|
| `list_wiki_pages` | 列出项目中的所有wiki页面 |
| `get_wiki_page` | 获取wiki页面内容（当前或历史版本） |
| `update_wiki_page` | 创建或更新wiki页面内容 |
### 用户工具（3）
| 工具 | 描述 |
|------|-------------|
| `list_users` | 列出用户（管理员看到所有用户，其他用户看到共享项目的用户） |
| `get_current_user` | 获取当前认证用户的配置文件 |
| `get_user` | 获取用户配置文件（基于权限的分级响应） |
### 附件工具（2）
| 工具 | 描述 |
|------|-------------|
| `list_attachments` | 列出问题或项目的附件 |
| `get_attachment` | 获取附件元数据和下载信息 |
### 实用工具（6）
| 工具 | 描述 |
|------|-------------|
| `list_trackers` | 列出所有问题跟踪器 |
| `list_statuses` | 列出所有问题状态 |
| `list_priorities` | 列出所有问题优先级 |
| `list_activities` | 列出时间条目活动（全局或特定于项目） |
| `list_versions` | 列出项目版本/里程碑 |
| `list_categories` | 列出项目的问题类别 |
### 管理员工具 - 跟踪器（3）
| 工具 | 描述 |
|------|-------------|
| `create_tracker` | 创建一个新的问题跟踪器（仅限管理员） |
| `update_tracker` | 更新现有的跟踪器（仅限管理员） |
| `delete_tracker` | 删除跟踪器（仅限管理员，如果存在问题则失败） |
### 管理员工具 - 状态（3）
| 工具 | 描述 |
|------|-------------|
| `create_status` | 创建新的问题状态（仅限管理员） |
| `update_status` | 更新现有的状态（仅限管理员） |
| `delete_status` | 删除状态（仅限管理员，如果正在使用则失败） |
### 管理员工具 - 优先级（3）
| 工具 | 描述 |
|------|-------------|
| `create_priority` | 创建新的问题优先级（仅限管理员） |
| `update_priority` | 更新现有的优先级（仅限管理员） |
| `delete_priority` | 删除优先级（仅限管理员，如果问题使用它则失败） |
### 管理员工具 - 活动（3）
| 工具 | 描述 |
|------|-------------|
| `create_activity` | 创建新的时间条目活动（仅限管理员） |
| `update_activity` | 更新现有的活动（仅限管理员） |
| `delete_activity` | 删除活动（仅限管理员，如果时间条目使用它则失败） |
### 类别工具（3）
| 工具 | 描述 |
|------|-------------|
| `create_category` | 在项目中创建一个新的问题类别 |
| `update_category` | 更新现有的类别 |
| `delete_category` | 删除类别（可以重新分配问题） |
### 版本工具（3）
| 工具 | 描述 |
|------|-------------|
| `create_version` | 在项目中创建一个新的版本/里程碑 |
| `update_version` | 更新现有的版本 |
| `delete_version` | 删除版本（如果分配问题则失败） |
有关详细的文档和示例，请参阅 [docs/TOOLS.md](docs/TOOLS.md)。
## 提示
插件包括5种智能提示模板，嵌入实时红矿数据：
| 提示 | 参数 | 描述 |
|--------|-----------|-------------|
| `bug_report` | `project_id`, `summary` | 结构化的错误报告模板，包含重现步骤 |
| `feature_request` | `project_id`, `title` | 功能请求模板，包含验收标准 |
| `status_report` | `project_id` （必填），`period` | 项目状态报告，来自实际问题统计 |
| `sprint_summary` | `version_id` （必填） | 冲刺进度总结，完成度指标 |
| `release_notes` | `version_id` （必填），`format` | 从已关闭的问题生成发布说明 |
**示例：** `status_report`提示查询实际问题数据并生成类似的消息：
> 为项目“My Project”生成状态报告，涵盖过去2周。
>
> 数据摘要：
> - 已关闭的问题：12
> - 已开启的问题：8
> - 活动问题：45
然后AI会将此格式化为专业的更新状态。
## 资源模板
插件使用URI模板，AI助手可以按需构造：
| URI模板 | 描述 | MIME类型 |
|--------------|-------------|-----------|
| `redmine://issues/{id}` | 完整的问题详情，包含日志和附件 | application/json |
| `redmine://projects/{id}` | 项目信息，包含成员和版本 | application/json |
| `redmine://projects/{project_id}/wiki/{title}` | Wiki页面内容，Textile/Markdown格式 | text/markdown |
| `redmine://users/{id}` | 用户配置文件（基于权限的字段） | application/json |
| `redmine://users/current` | 当前认证用户的完整配置文件 | application/json |
| `redmine://time_entries/{id}` | 时间条目，包含项目和活动详情 | application/json |
## MCP客户端配置
有关客户端设置说明，包括桌面、Cursor IDE和故障排除，请参阅 [docs/MCP_CLIENT_SETUP.md](docs/MCP_CLIENT_SETUP.md)。
### 快速入门 - 通用MCP客户端
添加到MCP客户端配置：
```json
{
"mcpServers": {
"redmine": {
"transport": "sse",
"url": "https://redmine.example.com/mcp",
"headers": {
"X-Redmine-API-Key": "your_api_key_here"
}
}
}
}
```
### 快速入门 - 桌面
添加到 `~/Library/Application Support/Desktop/config.json`（macOS）或 `%APPDATA%/Desktop/config.json`（Windows）：
```json
{
"mcpServers": {
"redmine": {
"transport": "sse",
"url": "https://your-redmine.example.com/mcp",
"headers": {
"X-Redmine-API-Key": "your_api_key_here"
}
}
}
}
```
配置后，重启应用程序。AI助手现在可以访问您的红矿实例。
有关详细的设置说明、故障排除和其他MCP客户端，请参阅 [docs/MCP_CLIENT_SETUP.md](docs/MCP_CLIENT_SETUP.md)。
## 服务器配置
对于生产部署，您可能需要配置您的Web服务器以正确处理SSE连接。请参阅 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)以获取：
- Nginx配置的SSE代理
- Apache配置
- Puma/Passenger考虑事项
- Web服务器级别的速率限制
## 分页
所有`list_*`工具返回分页元数据以帮助AI助手理解结果集：
```json
{
"content": [{"type": "text", "text": "[... results ...]"},
"_meta": {
"total": 142,
"limit": 25,
"offset": 0,
"has_more": true
}
}
```
_meta`字段使用下划线前缀（非MCP扩展）提供分页上下文。AI助手可以检查`has_more`以确定是否存在额外的页面。
## 故障排除
### MCP端点返回404
- 验证插件是否安装在`plugins/redmine_mcp`
- 安装后重启红矿
- 检查Rails日志中的路由错误
### 身份验证失败
- 验证您的API密钥是否正确（查看我的账户 > API访问密钥）
- 确保密钥在`X-Redmine-API-Key`头中发送
- 检查用户账户是否活跃且未锁定
### SSE连接立即关闭
- 检查您的Web服务器配置（Nginx可能需要`X-Accel-Buffering: no`)
- 验证防火墙/代理允许长期连接
- 查看 `sse_timeout`设置（默认：3600s）
- 检查红矿日志中的连接错误
### 速率限制错误
- 增加插件设置中的速率限制（管理员 > 插件）
- 检查多个MCP客户端是否使用相同的API密钥
- 查看最近的请求模式在Rails日志中
### 写操作失败
- 验证“启用写操作”是否在插件设置中选中问题时失败
### 工具返回空结果
- 验证用户是否具有查看请求数据的权限
- 检查项目可见性设置
- 确保项目模块已启用（wiki、时间跟踪等）
- 查看红矿权限以获取用户的角色
### 性能问题
- 降低设置中的`default_limit`和`max_limit`以减小页面大小
- 使用特定过滤器（项目ID、日期范围）来缩小查询范围
- 如果搜索速度慢，请考虑在数据库中添加索引
- 在AI操作期间监控服务器资源
## 开发
### 运行测试
```bash
cd /path/to/redmine
bundle exec rake redmine:plugins:test NAME=redmine_mcp
```
### 添加自定义工具
1. 在`lib/redmine_mcp/tools/`中创建一个新的工具类
2. 继承自`RedmineMcp::Tools::Base`
3. 实现必需的方法：`tool_name`, `description`, `execute`
4. 使用`RedmineMcp::Registry.register_tool(YourTool)`
5. 重启红矿
### 添加自定义提示
1. 在`lib/redmine_mcp/prompts/`中创建一个新的提示类
2. 继承自`RedmineMcp::Prompts::Base`
3. 实现必需的方法：`prompt_name`, `description`, `execute`
4. 使用`RedmineMcp::Registry.register_prompt(YourPrompt)`
5. 重启红矿
## 版本历史
详见 [CHANGELOG.md](CHANGELOG.md)。
## 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建一个功能分支
3. 为新功能添加测试
4. 提交拉取请求
## 许可
本插件遵循MIT许可证。
```
MIT License
Copyright (c) 2025 Redmine MCP Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```
## 支持
- **文档：** [docs/](docs/)
- **问题：** 通过GitHub Issues报告错误和功能请求
- **讨论：** 通过GitHub Discussions进行社区支持
## 相关资源
- [模型上下文协议规范](https://spec.modelcontextprotocol.io/)
- [红矿插件开发](https://www.redmine.org/projects/redmine/wiki/Plugin_Tutorial)
- [红矿API文档](https://www.redmine.org/projects/redmine/wiki/Rest_api)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器