JIRA集成服务器

🎯 JIRA MCP服务器

A powerful Model Context Protocol (MCP) server that brings Atlassian JIRA integration directly to any editor or application that supports MCP

✨ 特性

• 🎯 完整的JIRA集成套件

  • 问题管理：针对JIRA问题的完整CRUD操作，并提供全面的现场支持
  • 项目和董事会发现：使用高级筛选浏览项目、董事会和冲刺
  • 智能搜索：JQL和初学者友好的搜索，格式丰富
  • 评论系统：通过逐步披露访问和管理问题评论

• 🏗️ 企业级架构 （v0.5.0中的新功能）

  • 模块化设计：基于功能的架构，关注点明确分离
  • 强大的HTTP客户端：采用专用实用程序类进行重构，以提高可靠性
  • 综合测试：822多项测试，确保稳定性和可靠性
  • 类型安全：完全TypeScript严格模式，具有增强的错误处理功能

• 🔍 强大的搜索和发现

  • 使用JQL（JIRA查询语言）或初学者友好的参数搜索问题
  • 通过元数据和过滤发现项目、董事会和sprint
  • 丰富的标记格式，带有问题预览和直接导航链接
  • 具有作者筛选和日期范围的高级评论检索

• 📝 高级问题管理

  • 通过全面的现场支持创建、更新和过渡问题
  • 时间跟踪、工作日志管理和自定义字段支持
  • ADF（Atlassian文档格式）解析以显示丰富内容
  • 标签、组件和版本的数组操作

🆕 v0.5.0的新增功能

🏗️ 重大建筑大修

• 完成代码重组 采用模块化、领域驱动的架构
• HTTP客户端重构 具有专用的实用程序类别，可提高可靠性
• 关键错误修复 用于阻止正确通信的格式错误的JIRA API URL

🧪 增强测试和质量

• 95多项新测试 为HTTP客户端实用程序和边缘情况添加
• 总共822次测试 确保全面覆盖和稳定性
• 零掉毛警告 具有增强的Biome集成

🔧 技术改进

• 增强的错误处理 具有更好的分类和可操作的消息
• 改进日志记录 具有结构化的调试信息和性能监控
• 类型安全增强 全程严格检查TypeScript

🚀 性能和可靠性

• 优化HTTP请求 更好的连接管理
• 增强的错误恢复 改进了重试逻辑和超时处理
• 向后兼容性 维护-从v0.4.x无缝升级

🚀 快速开始

安装

将此配置添加到MCP客户端：

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-jira@latest"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

开发设置

对于本地开发和测试：

# Clone the repository
git clone https://github.com/Dsazz/mcp-jira.git
cd mcp-jira

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your JIRA credentials

# Build the project
bun run build

# Test with MCP Inspector
bun run inspect

配置

创建一个 .env 包含以下变量的文件：

JIRA_HOST=https://your-instance.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token-here

🔑 关于JIRA API代币的重要提示

• JIRA API令牌可以在 大西洋API代币
• 令牌可能包含特殊字符，包括 = 标志
• 将令牌放在 .env 文件
• 不要在令牌值周围添加引号
• 完全按照Atlassian提供的方式粘贴令牌

🧰 可用工具

JIRA核心工具

问题创建参数

这 jira_create_issue 该工具支持全面的问题创建：

必需:

• projectKey：String-项目密钥（例如。， "PROJ")
• issueType：String-问题类型（例如。， "Task", "Bug", "Story")
• summary：String-问题标题/摘要

可选字段:

• description：字符串-详细描述（支持ADF格式）
• priority：字符串-优先级("Highest", "High", "Medium", "Low", "Lowest")
• assignee：String-受让人用户名或电子邮件
• reporter：String-报告者用户名或电子邮件
• labels：数组-应用于问题的标签
• components：数组-组件名称
• fixVersions：数组-修复版本名称
• affectsVersions：数组-受影响的版本名称
• timeEstimate：String-JIRA格式的时间估计（例如。， "2h", "1d 4h")
• dueDate：String-ISO格式的截止日期
• environment：String-环境描述
• customFields：对象-自定义字段值

例子:

# Basic issue creation
jira_create_issue projectKey:"PROJ" issueType:"Task" summary:"Fix login bug"

# Comprehensive issue with all fields
jira_create_issue projectKey:"PROJ" issueType:"Bug" summary:"Critical login issue" description:"Users cannot log in" priority:"High" assignee:"john.doe" labels:["urgent","security"] timeEstimate:"4h"

问题更新参数

这 jira_update_issue 该工具支持全面的问题更新：

必需:

• issueKey：String-问题密钥（例如。， "PROJ-123")

现场更新 （任意组合）：

• summary：String-更新问题标题
• description：String-更新描述
• priority：String-更改优先级
• assignee：字符串-重新分配问题
• reporter：字符串-更改报告器
• timeEstimate：String-更新时间估计
• timeSpent：String-记录花费的时间
• dueDate：String-更新截止日期
• environment：String-更新环境

阵列操作 （添加/删除/设置）：

• labels：对象-修改标签({operation: "add|remove|set", values: ["label1", "label2"]})
• components：对象-修改组件
• fixVersions：对象-修改修复版本
• affectsVersions：对象-修改受影响的版本

状态转换:

• status：String-转换到新状态（例如。， "In Progress", "Done")

工作日志:

• worklog：对象-添加工作日志条目({timeSpent: "2h", comment: "Fixed issue"})

例子:

# Update basic fields
jira_update_issue issueKey:"PROJ-123" summary:"Updated title" priority:"High"

# Add labels and transition status
jira_update_issue issueKey:"PROJ-123" labels:'{operation:"add",values:["urgent"]}' status:"In Progress"

# Log work and add comment
jira_update_issue issueKey:"PROJ-123" worklog:'{timeSpent:"2h",comment:"Completed testing"}'

项目参数

这 jira_get_projects 该工具支持项目发现：

可选参数:

• maxResults：数字（1-100，默认值：50）-限制结果数量
• startAt：数字（默认值：0）-分页偏移
• expand：Array-要包含的其他字段(["description", "lead", "issueTypes", "url", "projectKeys"])

例子:

# Get all projects
jira_get_projects

# Get projects with additional details
jira_get_projects expand:["description","lead","issueTypes"] maxResults:20

电路板参数

这 jira_get_boards 该工具支持板管理：

可选参数:

• maxResults：数字（1-100，默认值：50）-限制结果数量
• startAt：数字（默认值：0）-分页偏移
• type：字符串-板类型("scrum", "kanban")
• name：String-按板名筛选
• projectKeyOrId：String-按项目筛选

例子:

# Get all boards
jira_get_boards

# Get Scrum boards for specific project
jira_get_boards type:"scrum" projectKeyOrId:"PROJ"

# Search boards by name
jira_get_boards name:"Sprint Board" maxResults:10

Sprint参数

这 jira_get_sprints 该工具支持sprint管理：

必需:

• boardId：Number-用于获取冲刺的板ID

可选参数:

• maxResults：数字（1-100，默认值：50）-限制结果数量
• startAt：数字（默认值：0）-分页偏移
• state：String-Sprint状态("active", "closed", "future")

例子:

# Get all sprints for a board
jira_get_sprints boardId:123

# Get only active sprints
jira_get_sprints boardId:123 state:"active"

# Get sprints with pagination
jira_get_sprints boardId:123 maxResults:10 startAt:20

工作日志参数

工作日志工具支持全面的时间跟踪：

jira_add_worklog 参数:

必需:

• issueKey：String-问题密钥（例如。， "PROJ-123")
• timeSpent：String-以JIRA格式花费的时间（例如。， "2h", "1d 4h", "30m")

可选的:

• comment：String-描述已完成工作的注释
• started：String-工作开始时（ISO日期格式，默认为现在）
• visibility：对象-可见性设置({type: "group", value: "jira-developers"})

jira_get_worklogs 参数:

必需:

• issueKey：String-问题密钥（例如。， "PROJ-123")

可选的:

• startedAfter：String-在此日期之后开始筛选工作日志（ISO格式）
• startedBefore：String-筛选在此日期之前开始的工作日志（ISO格式）

jira_update_worklog 参数:

必需:

• issueKey：String-问题密钥（例如。， "PROJ-123")
• worklogId：String-要更新的工作日志ID

可选的 （任意组合）：

• timeSpent：String-花费的更新时间
• comment：String-更新注释
• started：String-更新开始时间

jira_delete_worklog 参数:

必需:

• issueKey：String-问题密钥（例如。， "PROJ-123")
• worklogId：String-要删除的工作日志ID

例子:

# Add worklog entry
jira_add_worklog issueKey:"PROJ-123" timeSpent:"2h" comment:"Fixed authentication bug"

# Get all worklogs for an issue
jira_get_worklogs issueKey:"PROJ-123"

# Get worklogs from last week
jira_get_worklogs issueKey:"PROJ-123" startedAfter:"2025-05-29T00:00:00.000Z"

# Update worklog
jira_update_worklog issueKey:"PROJ-123" worklogId:"12345" timeSpent:"3h" comment:"Updated work description"

# Delete worklog
jira_delete_worklog issueKey:"PROJ-123" worklogId:"12345"

注释参数

这 jira_get_issue_comments 该工具支持使用以下参数进行渐进式披露：

必需:

• issueKey：String-问题密钥（例如。， "PROJ-123")

基本选项:

• maxComments：Number（1-100，默认值：10）-要检索的最大评论数
• orderBy：字符串("created" 或 "updated"，默认值： "created")-评论的排序顺序

高级选项:

• includeInternal：布尔值（默认值：false）-包括内部/受限注释
• authorFilter：String-按作者姓名或电子邮件过滤评论
• dateRange：对象-按日期范围筛选：
  • from：字符串（ISO日期）-开始日期
  • to：字符串（ISO日期）-结束日期

例子:

# Basic usage - get 10 most recent comments
jira_get_issue_comments PROJ-123

# Get more comments with specific ordering
jira_get_issue_comments PROJ-123 maxComments:25 orderBy:"updated"

# Advanced filtering
jira_get_issue_comments PROJ-123 authorFilter:"john.doe" includeInternal:true

搜索参数

这 search_jira_issues 该工具支持两种模式：

专家模式（JQL）:

• jql：直接JQL查询字符串（例如。， "project = PROJ AND status = Open")

初学者模式（辅助参数）:

• assignedToMe：Boolean-仅显示分配给当前用户的问题
• project：String-按项目键筛选
• status：字符串或数组-按状态过滤（例如。， "Open" 或 ["Open", "In Progress"])
• text：字符串-在摘要和描述字段中搜索

常用选项:

• maxResults：数字（1-50，默认值：25）-限制结果数量
• fields：Array-指定要检索的字段（可选）

🛠️ 开发工具

代码质量工具

该项目使用 生物群系 对于代码格式化和linting，提供：

• 快速、统一的格式化和linting
• TypeScript第一工具
• 无需配置
• 一致的代码风格执行

# Format code
bun run format

# Check code for issues
bun run check

# Type check
bun run typecheck

# Run tests
bun test

MCP检查员

# Run the inspector (no separate build step needed)
bun run inspect

bun run cleanup-ports

与Claude Desktop集成

🔌 与Cursor IDE集成

⚠️ 重要提示： 您必须使用以下内容构建项目 bun run build 在与Cursor IDE或Claude Desktop集成之前。

将此MCP服务器添加到Cursor IDE的MCP配置中：

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {
        "JIRA_USERNAME": "your-jira-username",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "JIRA_HOST": "your-jira-host.atlassian.net"
      }
    }
  }
}

📁 项目结构

src/
├── core/                    # Core functionality and configurations
│   ├── errors/             # Error handling utilities
│   ├── logging/            # Logging infrastructure
│   ├── responses/          # Response formatting
│   ├── server/             # MCP server implementation
│   ├── tools/              # Base tool interfaces
│   └── utils/              # Core utilities
├── features/               # Feature implementations
│   └── jira/              # JIRA API integration
│       ├── api/           # JIRA API client
│       ├── formatters/    # Response formatters
│       ├── tools/         # MCP tool implementations
│       └── utils/         # JIRA-specific utilities
└── test/                  # Test utilities and mocks
    ├── mocks/             # Mock factories
    └── utils/             # Test helpers

NPM脚本

📝 贡献

我们欢迎捐款！请查看我们的 贡献指南 有关以下内容的详细信息：

• 开发工作流程
• 分枝策略
• 提交消息格式
• 拉取请求流程
• 代码风格指南

📘 资源

• 模型上下文协议文档
• MCP TypeScript SDK
• MCP规范
• MCP检查员
• JIRA REST API文档

📄 许可证

麻省理工学院 ©斯坦尼斯拉夫·斯捷潘涅科