内容
红矿MCP服务器
模型上下文CP）服务器REST API为AI助手提供对红矿项目管理软件的访问。
## 功能
- **完整的红矿API访问**: 与项目、问题、用户、时间条目等交互
- **MCP协议**: AI与工具通信的标准协议
- **独立服务器**: 独立部署，连接到任何红矿实例
- ** 基于API密钥的身份验证与红矿 **灵活**: 通过环境变量可配置
## 先决条件
- Ruby 3.1 或更高版本
- 访问具有启用REST API的红矿实例（5.0+）
- 红矿API密钥（从红矿的/my/account页面获取）
### 可选的红矿插件
一些MCP工具需要 **红矿扩展API插件** 以实现高级功能：
- **自定义字段CRUD**: `create_custom_field`, `update_custom_field`, `delete_custom_field`
- **查询CRUD**: `create_query`, `update_query`, `delete_query`
- **批量时间条目**: `bulk_create_time_entries`
**安装**:
```bash
cd/to/redmine/plugins
https://github.com/zh/redmine_extended_api.git
cd /path/to/redmine
bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production
systemctl restart redmine
```
参见 [redmine_extended_api](https://github.com/zh/redmine_extended_api) 获取详细信息。
**注意**: 所有其他MCP工具都与标准的红矿REST API一起工作（无需插件）。
## 安装
1. 克隆或下载此仓库
2. 安装依赖项：
```bash
bundle install
```
3. 复制示例环境文件并 ```bash
cp .env.example .env ```
4. 编辑 `.env` 并设置您的红矿凭证：
```bash REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your_api_key_here
```
## 配置
所有配置都通过 `.env` 文件中的环境变量完成：
### 必需配置
| 变量 | 描述 | 默认值 | 必需 |
|----------|-------------|---------|----------|
| `REDMINE_URL` | 您的红矿实例的基本URL | - | 是 |
| `REDMINE_API_KEY` | 您的红矿API密钥 | 是 |
###
| 变量 | 描述 | 默认值 | 必|----------|-------------|---------|---------- `MCP_PORT MCP服务器端口 | 3100 | 否 |
| `MCP_HOST` | 绑定的主机 | localhost | 否 |
| `RACK_ENV` | 环境（开发/生产） | development | 否 |
| `LOG_LEVEL` | 日志级别（调试/信息/警告/错误） | info | 否 |
###
| 变量 | 描述 | 默认值 | 必需 |
|----------|-------------|---------|----------|
| `HTTP_TIMEOUT` | HTTP请求超时（秒） | 30 | 否 |
| `HTTP_READ_TIMEOUT` | HTTP读取超时（秒） | 60 | 否 |
| `FALCON_PROCESSES` | 服务器工作进程数 | 1 | 否 |
| `METRICS_SLOW_THRESHOLD` | 慢请求阈值（秒） | 1.0 | 否 |
**注意**: 连接池和压缩（gzip/deflate）由异步HTTP客户端自动处理。
### 获取您的红矿API密钥
1. 登录到您的红矿实例
2. 导航到账户”（/my/account）
3. 在右侧边栏查找“API访问密钥”
4. 点击“显示”以显示您的密钥，或点击“重置”以生成新密钥
5. 将密钥复制到您的 `.env` 文件中
## 用法
### 启动服务器
服务器使用 [Falcon](https://socketry.github.io/falcon/)，一个高性能的异步Web服务器。
**开发模式** （自动重载）：
```bash
bundle exec rerun -- falcon serve --bind http://localhost:3100
```
**生产模式**：
```bash
bundle exec fal --bind http://localhost:3100
将启动多个工作默认为8）以获得最佳性能。您可以通过在` 文件中设置ALCON_PROCESSES` 来控制工作进程数MCP客户端连接
将服务器添加到您的客户端配置中（例如aude Desktop）：
{
"": {
mine": {
"command": "bundle",
["exec",con", "serve", "--bind", "http://localhost:3100"],
": "/path/to_mcp_server"
}
}
}
```
或连接到正在运行的服务器：
```json
{
"mcpServers": {
"redmine": {
"url": "http://localhost:3100/mcp"
}
}
}
```
## 可用工具
### 当前状态
- **53个完全实现的工具** （项目、成员、版本、问题、用户、组、时间条目、自定义字段、查询、批量操作）
- **21个骨架工具** （结构已定义，待实现）
- **74个总工具**，涵盖14个资源类别
### 已实现的工具
#### 项目操作（5个工具）
- `list_projects` - 列出所有可访问的项目，支持分页和筛选
- `get_project` - 获取特定项目的详细信息
- `create_project` - 创建新项目
- `update_project` - 更新现有项目 `delete_project`项目
#### 成员操作（5个工具）
- `list_memberships 列出项目的所有成员
- `get_membership` - 获取特定成员的详细信息
- `create_membership` - 将用户/组添加到项目并分配角色
- `update_membership` - 更新项目成员的角色
- `delete_membership` - 从项目中/组
####里程碑操作（5个工具）
- `` - 列出里程碑get_version`特定版本的详细信息
create_version` -/里程碑
update_version` - 更新现有版本
- `delete_version` - 删除#### 问题操作（13个工具）
- `` - 列，支持筛选、排序和分页（支持query保存的查询）
- `get_issue` - 获取特定问题的详细信息
- `create_issue` - 在项目新问题
-_issue` - 更新- `delete - 删除问题
add_issue_watcher 添加观察者到问题
- `remove_issue_watcher` - 从问题中删除观察者
-_issue_relations` - 获取问题的所有关联（阻塞、）
- `create_issue_relation` - 创建两个问题之间的关联
- `delete_issue_relation` - 删除问题关联
- `get_issue_journals` - 获取问题的变更历史（日志）
- `copy_issue` - 复制问题到另一个项目或同一项目
- `move_issue` - 移动问题到不同项目
#### 用户操作（5个工具）
- `list_users` -用户，支持筛选和分页
- `get_user` - 获取特定用户的详细信息
- `create_user` - 创建新用户账户（需要管理员）
- `update_user` - 更新现有用户账户
- `delete_user` - 删除用户账户
#### 组操作（5个工具）
- `list_groups` - 列出所有组（需要管理员）
-` -详细信息，包括成员create_group`新组，可选
- `update_group` - 更新组详细信息
- `delete - 删除组
#### 时间条目操作（）
- `list_time_entries` - 列出时间条目，支持按用户、项目、问题或日期范围筛选
-_time_entry` - 获取特定时间条目的详细信息 `create_time_entry` - 记录问题或项目的时间
- `update_time_entry` - 更新现有时间
- `delete` - 删除时间
- `bulk_entries` - 创建多个时间条目（需要扩展API插件）
#### 自定义字段操作（4个工具）
- `list_custom_fields` - 列出所有自定义字段及其配置
create_custom_field`自定义字段（需要管理员，扩展API插件）
- `update_custom_field` - 更新现有自定义字段管理员，扩展API- `delete_custom 删除自定义字段管理员，扩展API插件）
**注意：值可以在问题、项目、用户和其他实体中使用 `custom_field_values` 或 `custom_fields` 参数创建/更新工具中设置。
#### 查询4个工具）
- `list_queries`出所有可访问（保存的筛选器），支持分页
-_query` - 创建新包含筛选器、可见性和列（需要扩展API插件）
- `update_query` - 更新现有查询（需要扩展API插件）
- `delete_query` - 删除查询（需要扩展API插件）
**查询功能：**
- **保存的筛选器**：查询是问题、时间条目、项目等的保存筛选器。
- **筛选器运算符**：支持所有红矿运算符（`=`, `!=`, `>=`, `<=`, `~`, `!~`, `o` （打开），`c` （关闭），`t` （今天），`w` （周），`m` （月），`<t+N`, `>t-N`）
- **可见性级别**：私有（0），角色（1），公共（2）
- **查询：问题查询，项目查询，时间条目查询
- **执行**：使用 `query_id` 参数与 `list_issues` 一起执行查询
- **权限**：用户管理自己的；`manage_public_queries` 用于项目查询；管理员用于全局查询
**示例 - 创建和执行**
```json
// 1. 创建查询以获取延迟的问题
{
"name": "create_query",
"params": {
"name": "Late Issues Before May",
type": "Issue "visibility": 0,
"filters": {
"due_date": {"operator": "<=", "values": ["2025-05-01"]},
"status_id": {"operator": "o"}
},
"column_names": ["id", " "status", ""],
"sort_criteria": [["due_date", "asc"]]
}
}
// 返回：{"id10, "name": "Late Issues Before May", ...}
// 2. 执行保存的查询
name": "issues",
"params": {
"": 10
}
}
// 返回基于保存筛选和排序的问题
```
#### 批量个工具）
- `batch_execute` -执行多个MCP工具以提高性能
骨架工具（准备实施）
所有骨都已定义完整的模式，但会引发 `Error`：
- **Wiki页面** （工具）：列出创建、更新、版本
- **附件** （3个工具）：上传、获取、删除
- **新闻** （2个工具出、获取
- **参考数据** （工具）：跟踪器、状态、优先级、活动、角色、搜索
参见OLS.md](.md) 获取完整的工具文档。
## 监控
MCP服务器包含内置的性能优化和监控功能。
### 性能特点
#### HTTP优化（异步架构）
- **自动连接池**: 异步HTTP客户端自动管理连接
- **HTTP Keep-Alive**: 高效的连接重用，自动管理
- **响应压缩**: 自动gzip/deflate压缩（-80%的带宽）
- **基于纤程的并发**:纤程实现轻并发操作
可配置的超时**: 连接操作的独立设置
- **多进程服务器**: Falcon运行多个工作进程（可配置）以实现真正的并行
#### 批量执行
使用 `batch_execute` 运行多个操作：
```json
{
"name": "batch "params": "calls": [
{ "name":_issue", "params": { "id": 123 } },
{ "name": "get_issueparams": { "id": 456 } { "name":_time_entries", "params": { "issue_id": 123 } }
"max_concurrency": 5
}
}
```
**性能提升**: 与顺序执行独立操作最高可倍。
### 指标端点
实时性能：
**Prometheus格式** （适用于Grafana等监控工具```bash
curl http://localhost:310etrics
```
**工具指标** （JSON）：
```bash
curl http://localhost:3100/metrics/tools
```
返回：
```json
{
": [
{
"tool": "list_issues",
"total_calls": 42,
"success_count": 40,
"": 2,
"total_duration_ms": 1250.5,
"avg_duration_ms": 29.77 "errors_by_type "NotFoundError": 2 }
}
]
}
```
**API指标** （JSON```bash
curl http://localhost:3100/metrics/api
```
速请求**）：
```bash
curl http://localhost/metrics/slow
```
列出超过阈值（默认：1.0秒）的请求。
### 性能配置
在 `.env` 中配置性能设置：
```bash
# HTTP超时（秒）
HTTP_TIMEOUT=30 # 请求超时
HTTP_READ_TIMEOUT=60 # 读取超时
# 服务器配置ALCON_PROCESSES=1 #数（生产环境中增加）
#METRICS_SLOW_THRESHOLD=1.0 # 慢速请求阈值（秒）
```
**注意**: 异步HTTP客户端自动处理连接池和压缩。
无需为这些功能进行手动配置。
参见 [docs/PERFORMANCE.md](docs/PERFORMANCE.md) 获取详细的性能调优指南。
## 开发
### 运行测试
所有已实现的工具都具有全面的RSpec测试覆盖（330+测试）。
**运行所有测试：**
```bundle exec rspec
```
**运行特定工具类别：**
```bash
bundle exec rspec spec/tools/time_entries/
bundle exec rspec spec/tools/custom_fields/
bundle exec rspec spec/tools/queries/
```
**测试覆盖范围**
- 工具验证
- 成功案例，包含最少和可选参数
- 必需参数验证
- 错误处理（身份验证、未找到） [TOOLS.md](TOOLS.md#testing-guide) 获取详细的测试指南。
### 代码质量
```bash
bundle exec rubocop
bundle exec rubocop --autocorrect
```
### 项目结构
```
redmine_mcp_server/
├── lib/
│ ├── redmine_mcp_server.rb # 主应用程序
│ ├── async_redmine_client.rb # 异步红矿API客户端
│ ├── tools/ # MCP工具（操作）
│ │ ├── base_tool.rb
│ │ ├── projects/ # 项目CRUD
│ │ ├── issues/ # 问题操作
│ │ └── ...
│ └── resources/ # MCP资源（数据源）
├── spec/ # RSpec测试
├── Gemfile # Ruby依赖项
├── config.ru Rack配置
└── .env # 环境配置
```
## 架构
```
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
│ │ │ │ │ │
│ AI客户端 │ ◄─MCP──►│MCP服务器 │ ◄─HTTP──►│实例 │
│ (Claude │ │ │ ││ │ │ │ │└─────────────┘ └────────────────── └─────────────┘
```
-客户端**: ClaudeCP兼容的AI助手
- **红矿MCP服务器**: 本将MCP转换为红矿API）
红矿实例**:红矿安装 故障排除
### 连接问题
** “缺少必需环境变量：REDMINE_URL”**
- 确保有一个 `.env` 文件位于目录
- 验证所有必需变量设置
**错误: “连接”或“超时”**
- 检查您的 `INE_URL` 是否可访问
- 验证红矿启用（管理 → 设置 → API）
- 使用API密钥手动测试API访问：`curl -H "X-Redmine-API-Key: YOUR_KEY" https://your-redmine.com/users/current.json`
**错误: “401 未授权” 验证您的API密钥是否正确
- 检查与API密钥关联的用户是否具有
- 必要时生成新的API密钥
### 服务器问题
**错误: “地址已被占用”**
- 另一个进程正在使用端口3100
-env` 中更改端口：`MCP_PORT=3101`
- 或进程：`lsof -ti:3100 | xargs kill -9 安全考虑
- **API 永远不要将 `.env` 文件提交到系统中
- ** 在生产环境中，为红矿HTTPS
- **防火墙**: 仅允许受信任的客户端访问M
- **权限**: 使用API密钥赋予适当的权限（最小原则）
## 贡献贡献！请：
1.仓库
2. 创建一个功能3. 为新功能编写测试. 确保所有测试通过检查
5.取请求
## 许可证
2025 Stoyan Zhekov@zhware.net>
本项目许可证开放使用。
## 致 使用 [mcp_on_rhttps://github.com/rubyoncp_on_ruby) - 由 [Redmine](https.redmine.org/) REST API
- 使用 [Async](httpsry.github.io/async/) 实现高性能并发HTTP通信
- 由 [Falcon](https://socketry.github.io/falcon/) 提供服务，一个现代的异步Web服务器
## 支持
如有问题、疑问或贡献：
- GitHub问题：[创建问题](https://github.com/zh/redmine_mcp_server/issues)
- 文档：[红矿REST API](https://www.redmine.org/projects/redmine/wiki/rest_api)
## 路线图
- [x] 阶段1：项目结构和配置
-] 阶段2：红矿API客户端
- [x] 阶段3：MCP基础架构
- [x] 阶段4：项目CRUD操作
- [x] 阶段4.5：项目复制、成员和- [x] 阶段问题管理工具（13）
- [x] .7：用户管理工具（- [x] 阶段4.8：组管理工具（5个工具）
- [x] 阶段5：时间条目工具（6个工具，包括批量操作）
-] 阶段5.5：管理工具（4个工具）
- [x] 阶段5.性能优化（连接池、指标、批量执行）
- [阶段5.7：（4个工具，用于保存的筛选器）
- [ ] ：Wiki和附件工具
- 阶段7：新闻和工具
- [ ] 阶段8：高级功能（缓存、Webhooks）
- [ ] 阶段9：覆盖
- [ ] ：生产环境部署指南
