Rust Jira MCP 服务器
一个高性能的基于Rust的模型上下文协议(MCP)服务器,用于全面集成Jira API。该服务器通过MCP兼容的客户端,为问题管理、项目配置、批量操作和Zephyr测试管理提供了广泛的工具支持。
🚀 快速入门```bash
Clone and build
git clone https://github.com/GarthDB/rust-jira-mcp.git
cd rust-jira-mcp
cargo build --release
Configure your credentials
cp env.example .env
Edit .env with your Jira credentials
Run the server
cargo run --release
## 🧪 测试与开发
这个项目包含一个基于xtask的全面测试框架,用于安全开发和测试:
### 测试命令```bash
# Test MCP operations
cargo run --package xtask -- test --suite read-only --project DNA
cargo run --package xtask -- test --suite issues --project DNA
cargo run --package xtask -- test --suite write --safe
# Collect test fixtures from live API
cargo run --package xtask -- collect-fixtures --project DNA
# Generate synthetic test data
cargo run --package xtask -- generate-fixtures --project TEST-MCP
# Run comprehensive test suite
cargo run --package xtask -- test-suite --project TEST-MCP
# Clean up test data
cargo run --package xtask -- cleanup --project TEST-MCP
Makefile 快捷键```bash
Quick test commands
make test-readonly # Run read-only tests
make test-issues # Run issue tests
make test-write # Run write tests (safe project only)
make test-suite # Run comprehensive test suite
make test-cleanup # Clean up test data
Fixture management
make collect-fixtures # Collect real API data
make generate-fixtures # Generate synthetic data
### 安全特性
- **安全测试**使用 `--safe` 标志或 `TEST-MCP` 写操作项目
- **数据匿名化**在测试数据中自动对敏感数据进行匿名化处理
- **清理**操作后自动清理测试数据
## 📖 文档
- **文档索引** - 完整的文档概览与导航
- **入门指南** - 完整的安装与使用指南
- **API 文档** 完整API参考(使用rustdoc生成)
- **配置指南** - 全面的配置管理
- **配置示例** - 详细的配置示例
- **工具示例** - 所有MCP工具的详细示例
- **故障排除指南** - 常见问题及解决方案
- **性能指南** - 优化和基准测试
## 特点/特性
### 核心Jira操作
- **问题管理**创建、阅读、更新、搜索和转移问题
- **评论**在问题上添加和检索评论
- **认证**测试Jira API的连接性和身份验证
### 项目配置和元数据(新增!)
- **项目配置**检索详细的项目配置设置
- **问题类型**获取特定项目可用的工单类型
- **问题类型元数据**获取特定问题类型的详细信息
- **项目组成部分**检索与项目相关的组件
- **优先级与状态**获取所有可用的优先级和状态
- **自定义字段**检索自定义字段定义
- **综合元数据**在一次调用中获取所有项目元数据
## 安装
1. 克隆仓库:```bash
git clone
cd rust-jira-mcp
- 构建项目:```bash
cargo build --release
3. 在配置文件或环境变量中设置您的Jira凭据。
## 配置
该服务器包含一个全面的配置管理系统,支持环境变量、配置文件、密钥管理以及热加载功能。
### 🔐 认证设置
服务器支持 **两种认证方法** 并根据您的令牌格式自动检测应使用哪一个:
#### 方法1:Adobe Jira(使用Bearer Token认证)
对于Adobe Jira实例,请直接使用您的Bearer令牌:```bash
# Required for Adobe Jira
JIRA_EMAIL=your.email@adobe.com
JIRA_PERSONAL_ACCESS_TOKEN=YOUR_ADOBE_JIRA_TOKEN_HERE
JIRA_API_BASE_URL=https://jira.corp.adobe.com/rest/api/2
方法2:标准Jira(基本认证)
对于标准的 Atlassian Jira 实例,请使用基本身份验证:```bash
Required for Standard Jira
JIRA_EMAIL=your.email@company.com
JIRA_PERSONAL_ACCESS_TOKEN=your_standard_pat_token
JIRA_API_BASE_URL=https://your-company.atlassian.net/rest/api/2
### 🧠 智能身份验证检测
服务器会自动检测您的认证方式:
- **Bearer Token(携带者令牌)**如果你的令牌长度较长(>20个字符)且不包含冒号
- **基本认证(Basic Auth)**如果你的令牌较短或包含冒号(例如 `user:password`)
### 快速入门
创建一个 `.env` 在项目根目录中的文件:```bash
# Required - Choose one based on your Jira instance
JIRA_EMAIL=your.email@company.com
JIRA_PERSONAL_ACCESS_TOKEN=your_token_here
# Optional
JIRA_API_BASE_URL=https://your-company.atlassian.net/rest/api/2
JIRA_DEFAULT_PROJECT=PROJ
JIRA_MAX_RESULTS=50
JIRA_TIMEOUT_SECONDS=30
🔍 测试您的身份验证
测试您的身份验证设置:```bash
Test with curl (Adobe Jira - Bearer)
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://jira.corp.adobe.com/rest/api/2/myself"
Test with curl (Standard Jira - Basic)
curl -u "your.email@company.com:YOUR_TOKEN" \
"https://your-company.atlassian.net/rest/api/2/myself"
Test with the MCP server
cargo run --release
Then call the test_jira_auth tool
### 配置特性
- ✅ **环境变量**通过环境变量支持所有配置
- ✅ **配置文件**支持 TOML、YAML 和 JSON 配置文件
- ✅ **密钥管理**安全处理敏感数据,提供多种存储选项
- ✅ **配置验证**全面验证,附带详细错误信息
- ✅ **热加载**当文件发生变化时自动重新加载配置
- ✅ **多个来源**支持多个配置源并具有优先级排序
- ✅ **默认值**所有配置选项的合理默认值
### 配置源(优先级顺序)
1. 环境变量(最高优先级)
1. .env 文件
1. 自定义配置文件(通过指定 `JIRA_CONFIG_FILE`)
1. config/default.toml(配置/默认.toml)
1. 默认值(最低优先级)
## 可用工具
### 核心工具
- `test_jira_auth` 使用Jira API测试认证
- `search_jira_issues` - 使用JQL搜索问题
- `create_jira_issue` - 创建新问题
- `update_jira_issue` - 更新现有问题
- `get_jira_issue` - 获取问题详情
- `get_jira_comments` - 获取问题评论
- `add_jira_comment` - 在问题上添加评论
- `get_jira_transitions` - 获取可用的转换
- `transition_jira_issue` - 过渡到新状态的问题
### 项目配置和元数据工具
- `get_project_config` - 获取项目配置详情
- `get_project_issue_types` - 获取项目的议题类型
- `get_issue_type_metadata` - 获取详细的议题类型信息
- `get_project_components` - 获取项目组件
- `get_priorities_and_statuses` - 获取所有优先级和状态
- `get_custom_fields` - 获取自定义字段定义
- `get_project_metadata` - 获取全面的项目元数据
### 冲刺管理工具(新推出!)
- `get_sprint` - 通过冲刺ID获取冲刺详情
- `create_sprint` - 创建一个新的冲刺(或迭代)
- `add_issues_to_sprint` - 将问题添加到冲刺中
- `get_sprint_issues` - 获取冲刺(Sprint)中的所有问题
- `start_sprint` - 开始冲刺(将状态设置为活跃)
- `close_sprint` - 结束一个冲刺(将状态设置为已结束)
- `get_board_sprints` - 获取看板的所有冲刺(Sprint)
## 使用示例
### 基本问题操作```json
{
"method": "tools/call",
"params": {
"name": "search_jira_issues",
"arguments": {
"jql": "project = TEST AND status = Open",
"max_results": 10
}
}
}
项目元数据操作```json
{
"method": "tools/call",
"params": {
"name": "get_project_metadata",
"arguments": {
"project_key": "TEST"
}
}
}
### 获取项目的工单类型```json
{
"method": "tools/call",
"params": {
"name": "get_project_issue_types",
"arguments": {
"project_key": "TEST"
}
}
}
获取所有优先级和状态```json
{
"method": "tools/call",
"params": {
"name": "get_priorities_and_statuses",
"arguments": {}
}
}
### 冲刺管理运营```json
{
"method": "tools/call",
"params": {
"name": "get_sprint_issues",
"arguments": {
"sprint_id": 12345,
"max_results": 50
}
}
}
运行服务器
作为一个独立的二进制文件```bash
cargo run --release
### 作为MCP服务器
服务器实现了MCP协议,可以与任何兼容MCP的客户端一起使用。
## 示例
查看 `examples/` 使用示例目录:
- `project_metadata_example.rs` - 展示新的项目配置和元数据工具
- `simple_config_example.rs` - 展示基本的配置管理用法
- `configuration_example.rs` - 全面的配置系统演示
## 测试
运行测试套件:```bash
cargo test
发展
项目结构```
src/
├── config/ # Configuration management
├── error/ # Error handling
├── jira/ # Jira API client
│ ├── client.rs # Main client implementation
│ └── operations/ # Specific operation modules
├── mcp/ # MCP server implementation
│ ├── server.rs # MCP server
│ └── tools.rs # Tool implementations
├── types/ # Type definitions
└── utils/ # Utility functions
### 添加新工具
1. 实现工具结构体 `src/mcp/tools.rs`
1. 将该工具添加到服务器注册中 `src/mcp/server.rs`
1. 将工具定义添加到 `list_tools()` 方法
1. 在(相应位置)添加对应的客户端方法 `src/jira/client.rs` 如需
## 覆盖范围
该项目使用全面的测试工具,保持了高测试覆盖率:
### 覆盖状态
- **总体覆盖率**~75%(不包括测试工具)
- **目标覆盖率**百分之八十
- **应用程序代码**70-75%的覆盖率
### 覆盖工具```bash
# Quick coverage check
make coverage-check
# Detailed analysis
make coverage-analyze
# Get test suggestions for a module
make coverage-suggest MODULE=main
# Open HTML coverage report
make coverage-dashboard
覆盖监测
- Codecov.io(可译为“科德科夫点IO”,但通常直接保留原名,因其为专有名词)持续覆盖监测
- GitHub Actions在PR(Pull Request,拉取请求)中自动生成覆盖率报告
- 覆盖徽章README中的实时覆盖状态
做出贡献
- 为仓库创建分支(或“克隆仓库”)
- 创建一个特性分支
- 进行你的更改
- 添加测试(目标覆盖率80%+)
- 跑
make coverage-check验证覆盖范围 - 提交一个拉取请求
覆盖范围要求
- 新功能必须保持或提高整体覆盖率
- 关键模块(main.rs、jira_client、mcp_tools)的覆盖率应达到80%以上
- 使用
make coverage-suggest MODULE=作为指导
许可证
[在此添加您的许可证信息]
更新日志
版本 0.1.0
- 初始发布,包含核心Jira操作功能
- 添加了项目配置和元数据工具
- 全面的MCP服务器实现
- 全面测试覆盖
