Exmuzzy MCP

Jira MCP服务器

一个全面的、生产就绪的模型上下文协议（MCP）服务器，用于无缝集成Jira Cloud。此增强版本为AI代理、自动化系统和自定义应用程序提供了高级功能、强大的错误处理和广泛的工具。

备注这是一把叉子 @orengrinker/jira mcp服务器 进行自定义修改。Oren Grinker的原创作品。

🚀 特性

核心功能

• 董事会管理：列出、过滤和管理包含详细信息的Jira板
• 问题操作：全面创建、更新、搜索、转换和管理问题
• 用户管理：搜索用户、获取用户详细信息和管理分配
• 项目管理：查看项目，获取详细的项目信息
• 时间跟踪：添加和查看具有灵活时间格式的工作日志
• 评论系统：添加支持富格文本的注释（ADF格式）
• 服务器信息：监视服务器状态和运行状况

增强功能

• ⚡️ 性能优化：使用单个请求分组结果优化问题检索（速度快5-6倍）
• 速率限制：智能API请求节流以遵守Jira限制
• 综合录井：可配置的多级日志记录
• 错误处理：具有详细错误消息的稳健错误处理
• 输入验证：彻底验证环境变量和输入
• 模块化架构：具有基于服务的架构的干净、可维护的代码库
• TypeScript支持：具有全面类型定义的完整TypeScript实现
• 丰富的格式：漂亮的标记表和带有直接Jira链接的格式化响应
• 高级搜索：通过有用的示例支持复杂的JQL查询
• AI驱动的工作流程：自动工作流处理和人工智能生成的问题解决方案
• 问题跟踪：针对情境感知操作的智能问题跟踪

🛠️ 需求

• Node.js：18.0.0或更高
• 吉拉云：访问Jira Cloud实例
• API代币：Jira API代币(在此处创建)

⚙️ 环境变量

创建一个 .env 文件或设置这些环境变量：

JIRA_BASE_URL=https://your-company.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-jira-api-token
LOG_LEVEL=INFO  # Optional: ERROR, WARN, INFO, DEBUG

🚀 快速开始

选项1：使用npx（推荐）

# Run directly without installation
npx @orengrinker/jira-mcp-server

# With environment variables
JIRA_BASE_URL=https://company.atlassian.net \
JIRA_EMAIL=user@company.com \
JIRA_API_TOKEN=your-token \
npx @orengrinker/jira-mcp-server

选项2:Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["@orengrinker/jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

选项3：全局安装

npm install -g @orengrinker/jira-mcp-server
jira-mcp-server

方案4：地方发展

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install
npm run build
node dist/index.js

🧰 可用工具

电路板工具

• get_boards -按类型和项目列出所有具有可选过滤功能的电路板
• get_board_details -获取全面的董事会信息
• get_board_issues -使用高级过滤选项解决电路板问题

问题工具

• get_my_issues_grouped ⚡️ 新的和优化的 -将您的未决问题按状态分组到一个请求中（比其他选项快5-6倍）
• search_issues -使用具有灵活参数的JQL搜索问题
• get_issue_details -获取全面的问题信息
• create_issue -在全面的现场支持下创建新问题
• update_issue -更新现有问题
• transition_issue -在状态之间移动问题
• add_comment -添加支持富格文本的评论
• complete_issue -通过人工智能生成的解决方案和工作流处理来解决/完成问题

用户工具

• get_current_user -获取经过身份验证的用户信息
• search_users -按姓名、电子邮件或用户名查找用户
• get_user_details -获取详细的用户信息

项目工具

• get_projects -列出所有可访问的项目
• get_project_details -获取全面的项目信息

时间跟踪工具

• add_worklog -以灵活的格式记录工作时间
• get_worklogs -查看问题的工作日志

系统工具

• get_server_info -获取服务器状态和信息

💡 用法示例

使用Claude或Cursor的自然语言命令

一旦配置了Claude Desktop或Cursor，您就可以使用自然语言命令：

"Show me all my open issues in high priority"
"Create a new bug in PROJECT-X about login issues"
"Move ticket ABC-123 to In Progress"
"Log 2 hours of work on ABC-456 for code review"
"Add a comment to ABC-789 saying the fix is deployed"
"Show me all Scrum boards for the mobile project"
"Get details for issue ABC-100 including comments and worklogs"
"List all projects I have access to"
"Close issue ABC-123" or "Complete ABC-123"

⚡️ 优化问题查看（推荐）

为了在查看任务时获得最佳性能，请使用优化的分组视图：

# In Claude or Cursor
"/jira"  # Shows all your open issues grouped by status

# This uses get_my_issues_grouped which:
# - Makes only 1 API request (vs 6+ with traditional methods)
# - Groups issues by status automatically
# - Provides direct links to Jira
# - Shows quick action menu
# - 5-6x faster response time

有关Cursor中的详细设置说明，请参阅：

• 快速开始: CURSOR_QUICK_START.md
• 完整提示: CURSOR_JIRA_PROMPT.md

与MCP检查器一起使用

# List all boards
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  get_boards

# Search for your issues
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  search_issues \
  '{"jql": "assignee=currentUser() AND status!=Done"}'

# Create a new issue
npx @modelcontextprotocol/inspector \
  npx @orengrinker/jira-mcp-server \
  create_issue \
  '{"projectKey": "PROJ", "issueType": "Task", "summary": "New task from MCP"}'

JQL查询示例

# Your open issues
assignee = currentUser() AND status != Done

# Recent issues in a project
project = "MYPROJ" AND created >= -7d

# High priority bugs
priority = High AND issuetype = Bug

# Issues due this week
duedate >= startOfWeek() AND duedate = -1d

# Epic issues with their child stories
"Epic Link" = PROJ-123 OR parent = PROJ-123

🔧 配置

获取Jira API代币

1. 首选 Atlassian帐户设置
2. 点击“创建API令牌”
3. 给它一个描述性的名称（例如“MCP服务器”）
4. 复制生成的令牌
5. 在环境变量中使用它

需要权限

您的Jira用户应该具有：

• 浏览项目权限
• 创建问题权限（用于创建问题）
• 编辑问题权限（用于更新和转换）
• 问题许可工作（用于工作日志）
• 添加评论权限

🏗️ 发展

设置

git clone https://github.com/OrenGrinker/jira-mcp-server.git
cd jira-mcp-server
npm install

开发脚本

npm run dev          # Start development server with hot reload
npm run build        # Build for production
npm run clean        # Clean build directory
npm run start        # Start production server
npm run test         # Run tests (when available)

项目结构

src/
├── index.ts              # Main server entry point
├── jiraApiClient.ts      # Enhanced API client
├── toolRegistry.ts       # Tool registration and routing
├── types/
│   └── index.ts         # TypeScript type definitions
├── services/
│   ├── index.ts         # Service exports
│   ├── boardService.ts  # Board operations
│   ├── issueService.ts  # Issue operations
│   ├── userService.ts   # User operations
│   ├── projectService.ts # Project operations
│   ├── worklogService.ts # Worklog operations
│   └── serverService.ts  # Server operations
└── utils/
    ├── logger.ts        # Logging utility
    ├── rateLimiter.ts   # Rate limiting
    ├── validation.ts    # Input validation
    └── formatters.ts    # Response formatting

🔍 故障排除

常见问题

1. 认证失败

- 验证您的API令牌和电子邮件是否正确 - 检查您的Jira基本URL是否正确（对于云，应以.atlassian.net结尾） - 确保您的API令牌尚未过期

1. 权限不足

- 验证您的Jira用户是否具有所需的权限 - 检查特定操作的项目级权限

1. 网络错误

- 验证您的Jira基本URL是否可访问 - 检查防火墙和代理设置 - 确保您正在使用HTTPS

1. 速率限制

- 服务器包括内置的速率限制 - 如果达到Jira的速率限制，请等待并重试 - 考虑减少并发请求

调试模式

默认情况下启用DEBUG日志记录 以帮助诊断问题。日志显示：

• 所有Jira API请求（URL、方法、参数）
• 响应状态和摘要（项目总数、计数）
• MCP工具执行（参数、结果预览）
• 错误跟踪和详细消息

要更改日志级别，请设置环境变量：

export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARN, ERROR (default: DEBUG)

MCP服务器日志

通过Cursor运行MCP服务器时，您可以在此处找到日志：

macOS：

# View live MCP logs with DEBUG output
tail -f ~/Library/Application\ Support/Cursor/logs/*/window*/exthost/anysphere.cursor-mcp/MCP\ user-jira.log

# Or list all log directories
ls -lt ~/Library/Application\ Support/Cursor/logs/

窗户：

%APPDATA%\Cursor\logs\

Linux：

~/.config/Cursor/logs/

调试输出示例：

[DEBUG] [JiraApiClient] Making GET request to: https://job.sbertroika.ru/rest/api/2/search?jql=...
[DEBUG] [JiraApiClient] Response status: 200 OK
[DEBUG] [JiraApiClient] Response summary: { total: 176, issuesCount: 176 }
[DEBUG] [JiraMCPServer] MCP result sent to Cursor: { type: 'text', textLength: 15521 }

日志包括：

• 连接状态 以及身份验证详细信息
• API请求 包含完整的URL和参数
• API响应 带有状态代码和数据摘要
• MCP协议 消息和工具执行流程
• 错误痕迹 具有详细的上下文

🧪 测试

使用Make命令

该项目包括一个全面的 Makefile 为了便于测试：

# Show all available commands
make help

# Run all tests
make test-all

# Test specific functionality
make test-grouped          # Test get_my_issues_grouped (preview)
make test-grouped-full     # Test get_my_issues_grouped (full output)
make test-priorities       # Check Jira priorities
make test-current-user     # Get current user info
make test-my-issues        # Test search_issues

# Test specific issue
make test-issue-detail ISSUE_KEY=RIVER-123

# Test user search
make test-search-users QUERY=Агафонов

# View logs
make logs                  # Real-time log viewing
make logs-errors           # Show only errors

# Development
make build                 # Build project
make lint                  # Run linter
make format                # Format code
make typecheck             # Type checking

手动测试

# Test the server connection
JIRA_BASE_URL=https://your-company.atlassian.net \
JIRA_EMAIL=your@email.com \
JIRA_API_TOKEN=your-token \
node dist/index.js

🤝 贡献

我们欢迎捐款！请遵循以下指南：

1. 分叉存储库
2. 创建要素分支: git checkout -b feature/amazing-feature
3. 进行更改 遵循我们的编码标准
4. 添加测试 对于新功能
5. 运行构建: npm run build
6. 提交更改: git commit -m 'Add amazing feature'
7. 推送到分支: git push origin feature/amazing-feature
8. 打开拉取请求

编码标准

• 遵循TypeScript的最佳实践
• 使用有意义的变量和函数名
• 为公共API添加JSDoc注释
• 遵循常规提交消息
• 确保所有构建都通过

📊 演出

• ⚡️ 优化问题检索新 get_my_issues_grouped 函数将API调用从6个减少到1个（速度快5-6倍）
• 速率限制：内置速率限制尊重Jira API限制
• 连接池：高效的HTTP连接管理
• 错误恢复：瞬态故障的自动重试逻辑
• 内存效率高：大型数据集的流式响应

性能比较

🔐 安全

• 无凭据存储：仅使用环境变量
• 输入验证：所有输入都经过验证和消毒
• 安全默认值：遵循安全最佳实践
• 审计跟踪：用于调试的全面日志记录

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🔗 链接

• GitHub存储库:
• NPM包: @orengrinker/jira mcp服务器
• Jira Cloud REST API: 文档
• 模型上下文协议: 规格说明
• 创建API令牌: Atlassian指南

🆘 支持

• 问题:
• 文档：查看此README和内联代码文档
• 功能请求：打开带有“增强”标签的问题

🏆 致谢

• 与 模型上下文协议SDK
• 受到MCP社区和最佳实践的启发
• 感谢所有提供反馈的贡献者和用户