mcp-jira

<div align="center"> # 🎯 JIRA MCP Server [](https://www.typescriptlang.org/) [](https://bun.sh/) [](https://www.atlassian.com/software/jira) [](https://opensource.org/licenses/MIT) [](https://modelcontextprotocol.io) <p align="center"> <b>一个强大的模型上下文协议 (MCP) 服务器，可将 Atlassian JIRA 集成直接引入到任何支持 MCP 的编辑器或应用程序</b> </p> </div> --- ## ✨ 功能 - 🎯 **完整的 JIRA 集成套件** - **问题管理**：对 JIRA 问题进行完整的 CRUD 操作，并提供全面的字段支持 - **项目和看板发现**：浏览项目、看板和冲刺，并具有高级筛选功能 - **智能搜索**：JQL 和初学者友好的搜索，具有丰富的格式 - **评论系统**：访问和管理问题评论，并逐步披露 - 🏗️ **企业级架构** _(v0.5.0 中的新功能)_ - **模块化设计**：基于功能的架构，具有清晰的关注点分离 - **强大的 HTTP 客户端**：经过重构，具有专用的实用程序类，以提高可靠性 - **全面的测试**：822+ 个测试，确保稳定性和可靠性 - **类型安全**：完整的 TypeScript 严格模式，具有增强的错误处理 - 🔍 **强大的搜索与发现** - 使用 JQL (JIRA Query Language) 或初学者友好的参数搜索问题 - 项目、看板和冲刺发现，具有元数据和筛选 - 丰富的 markdown 格式，带有问题预览和直接导航链接 - 高级评论检索，带有作者筛选和日期范围 - 📝 **高级问题管理** - 创建、更新和转换问题，并提供全面的字段支持 - 时间跟踪、工作日志管理和自定义字段支持 - 用于丰富内容显示的 ADF (Atlassian Document Format) 解析 - 用于标签、组件和版本的数组操作 ## 🆕 v0.5.0 中的新功能 ### 🏗️ 主要架构改革 - **完整的代码重组**，采用模块化、领域驱动的架构 - **HTTP 客户端重构**，具有专用的实用程序类，以提高可靠性 - **关键错误修复**，修复了阻止正确通信的格式错误的 JIRA API URL ### 🧪 增强的测试与质量 - 为 HTTP 客户端实用程序和边缘情况添加了 **95+ 个新测试** - **总共 822 个测试**，确保全面的覆盖和稳定性 - 通过增强的 Biome 集成，**零 linting 警告** ### 🔧 技术改进 - **增强的错误处理**，具有更好的分类和可操作的消息 - **改进的日志记录**，具有结构化的调试信息和性能监控 - **类型安全增强**，在整个过程中进行严格的 TypeScript 检查 ### 🚀 性能与可靠性 - **优化的 HTTP 请求**，具有更好的连接管理 - **增强的错误恢复**，具有改进的重试逻辑和超时处理 - **保持向后兼容性** - 从 v0.4.x 无缝升级 ## 🚀 快速开始 ### 安装 将此配置添加到您的 MCP 客户端： ```json { "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" } } } } ``` ### 开发设置 对于本地开发和测试： ```bash # 克隆存储库 git clone https://github.com/Dsazz/mcp-jira.git cd mcp-jira # 安装依赖项 bun install # 设置环境变量 cp .env.example .env # 使用您的 JIRA 凭据编辑 .env # 构建项目 bun run build # 使用 MCP Inspector 进行测试 bun run inspect ``` ### 配置 创建一个包含以下变量的 `.env` 文件： ```ini JIRA_HOST=https://your-instance.atlassian.net JIRA_USERNAME=your-email@example.com JIRA_API_TOKEN=your-jira-api-token-here ``` > **🔑 关于 JIRA API 令牌的重要说明** > > - 可以在 [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens) 生成 JIRA API 令牌 > - 令牌可能包含特殊字符，包括 `=` 符号 > - 将令牌放在 `.env` 文件中的单行上 > - 不要将引号添加到令牌值周围 > - 完全按照 Atlassian 提供的粘贴令牌 ## 🧰 可用工具 ### 核心 JIRA 工具 | Tool | Description | Parameters | Returns | | -------------------------- | ----------------------------------------------------------------- | ------------------------------------ | ---------------------------------- | | `jira_get_assigned_issues` | 检索分配给您的所有问题 | None | Markdown 格式的问题列表 | | `jira_get_issue` | 获取有关特定问题的详细信息 | `issueKey`: 问题键（例如，PD-312） | Markdown 格式的问题详细信息 | | `jira_get_issue_comments` | 检索具有可配置选项的特定问题的评论 | 请参阅下面的评论参数 | Markdown 格式的评论 | | `jira_create_issue` | 创建具有全面字段支持的新 JIRA 问题 | 请参阅问题创建参数 | Markdown 格式的创建结果 | | `jira_update_issue` | 使用字段更改和状态转换更新现有问题 | 请参阅问题更新参数 | Markdown 格式的更新结果 | | `jira_get_projects` | 检索和浏览具有筛选选项的 JIRA 项目 | 请参阅项目参数 | Markdown 格式的项目列表 | | `jira_get_boards` | 获取具有高级筛选的 JIRA 看板（Scrum/Kanban） | 请参阅看板参数 | Markdown 格式的看板列表 | | `jira_get_sprints` | 检索敏捷项目管理的冲刺信息 | 请参阅冲刺参数 | Markdown 格式的冲刺列表 | | `jira_add_worklog` | 将时间跟踪条目添加到问题 | 请参阅下面的工作日志参数 | Markdown 格式的工作日志结果 | | `jira_get_worklogs` | 检索具有日期筛选的问题的工作日志条目 | 请参阅下面的工作日志参数 | Markdown 格式的工作日志列表 | | `jira_update_worklog` | 更新现有工作日志条目 | 请参阅下面的工作日志参数 | Markdown 格式的更新结果 | | `jira_delete_worklog` | 从问题中删除工作日志条目 | 请参阅下面的工作日志参数 | Markdown 格式的删除结果 | | `jira_get_current_user` | 获取当前经过身份验证的用户信息 | None | Markdown 格式的用户详细信息 | | `search_jira_issues` | 使用 JQL 或帮助程序参数搜索 JIRA 问题 | 请参阅下面的搜索参数 | Markdown 格式的搜索结果 | #### 问题创建参数 `jira_create_issue` 工具支持全面的问题创建： **必需**： - `projectKey`：字符串 - 项目键（例如，`"PROJ"`） - `issueType`：字符串 - 问题类型（例如，`"Task"`、`"Bug"`、`"Story"`） - `summary`：字符串 - 问题标题/摘要 **可选字段**： - `description`：字符串 - 详细描述（支持 ADF 格式） - `priority`：字符串 - 优先级（`"Highest"`、`"High"`、`"Medium"`、`"Low"`、`"Lowest"`） - `assignee`：字符串 - 受让人用户名或电子邮件 - `reporter`：字符串 - 报告人用户名或电子邮件 - `labels`：数组 - 要应用于问题的标签 - `components`：数组 - 组件名称 - `fixVersions`：数组 - 修复版本名称 - `affectsVersions`：数组 - 受影响的版本名称 - `timeEstimate`：字符串 - JIRA 格式的时间估算（例如，`"2h"`、`"1d 4h"`） - `dueDate`：字符串 - ISO 格式的截止日期 - `environment`：字符串 - 环境描述 - `customFields`：对象 - 自定义字段值 **示例**： ``` # 基本问题创建 jira_create_issue projectKey:"PROJ" issueType:"Task" summary:"修复登录错误" # 包含所有字段的全面问题 jira_create_issue projectKey:"PROJ" issueType:"Bug" summary:"严重登录问题" description:"用户无法登录" priority:"High" assignee:"john.doe" labels:["urgent","security"] timeEstimate:"4h" ``` #### 问题更新参数 `jira_update_issue` 工具支持全面的问题更新： **必需**： - `issueKey`：字符串 - 问题键（例如，`"PROJ-123"`） **字段更新**（任意组合）： - `summary`：字符串 - 更新问题标题 - `description`：字符串 - 更新描述 - `priority`：字符串 - 更改优先级 - `assignee`：字符串 - 重新分配问题 - `reporter`：字符串 - 更改报告人 - `timeEstimate`：字符串 - 更新时间估算 - `timeSpent`：字符串 - 记录花费的时间 - `dueDate`：字符串 - 更新截止日期 - `environment`：字符串 - 更新环境 **数组操作**（添加/删除/设置）： - `labels`：对象 - 修改标签（`{operation: "add|remove|set", values: ["label1", "label2"]}`） - `components`：对象 - 修改组件 - `fixVersions`：对象 - 修改修复版本 - `affectsVersions`：对象 - 修改受影响的版本 **状态转换**： - `status`：字符串 - 转换为新状态（例如，`"In Progress"`、`"Done"`） **工作日志**： - `worklog`：对象 - 添加工作日志条目（`{timeSpent: "2h", comment: "已修复问题"}`） **示例**： ``` # 更新基本字段 jira_update_issue issueKey:"PROJ-123" summary:"已更新标题" priority:"High" # 添加标签和转换状态 jira_update_issue issueKey:"PROJ-123" labels:'{operation:"add",values:["urgent"]}' status:"In Progress" # 记录工作并添加评论 jira_update_issue issueKey:"PROJ-123" worklog:'{timeSpent:"2h",comment:"已完成测试"}' ``` #### 项目参数 `jira_get_projects` 工具支持项目发现： **可选参数**： - `maxResults`：数字（1-100，默认值：50） - 限制结果数 - `startAt`：数字（默认值：0） - 分页偏移量 - `expand`：数组 - 要包含的其他字段（`["description", "lead", "issueTypes", "url", "projectKeys"]`） **示例**： ``` # 获取所有项目 jira_get_projects # 获取包含其他详细信息的项目 jira_get_projects expand:["description","lead","issueTypes"] maxResults:20 ``` #### 看板参数 `jira_get_boards` 工具支持看板管理： **可选参数**： - `maxResults`：数字（1-100，默认值：50） - 限制结果数 - `startAt`：数字（默认值：0） - 分页偏移量 - `type`：字符串 - 看板类型（`"scrum"`、`"kanban"`） - `name`：字符串 - 按看板名称筛选 - `projectKeyOrId`：字符串 - 按项目筛选 **示例**： ``` # 获取所有看板 jira_get_boards # 获取特定项目的 Scrum 看板 jira_get_boards type:"scrum" projectKeyOrId:"PROJ" # 按名称搜索看板 jira_get_boards name:"Sprint Board" maxResults:10 ``` #### 冲刺参数 `jira_get_sprints` 工具支持冲刺管理： **必需**： - `boardId`：数字 - 从中获取冲刺的看板 ID **可选参数**： - `maxResults`：数字（1-100，默认值：50） - 限制结果数 - `startAt`：数字（默认值：0） - 分页偏移量 - `state`：字符串 - 冲刺状态（`"active"`、`"closed"`、`"future"`） **示例**： ``` # 获取看板的所有冲刺 jira_get_sprints boardId:123 # 仅获取活动冲刺 jira_get_sprints boardId:123 state:"active" # 获取包含分页的冲刺 jira_get_sprints boardId:123 maxResults:10 startAt:20 ``` #### 工作日志参数 工作日志工具支持全面的时间跟踪： **`jira_add_worklog` 参数**： **必需**： - `issueKey`：字符串 - 问题键（例如，`"PROJ-123"`） - `timeSpent`：字符串 - JIRA 格式的花费时间（例如，`"2h"`、`"1d 4h"`、`"30m"`） **可选**： - `comment`：字符串 - 描述所做工作的评论 - `started`：字符串 - 工作开始时间（ISO 日期格式，默认为现在） - `visibility`：对象 - 可见性设置（`{type: "group", value: "jira-developers"}`） **`jira_get_worklogs` 参数**： **必需**： - `issueKey`：字符串 - 问题键（例如，`"PROJ-123"`） **可选**： - `startedAfter`：字符串 - 筛选在此日期之后开始的工作日志（ISO 格式） - `startedBefore`：字符串 - 筛选在此日期之前开始的工作日志（ISO 格式） **`jira_update_worklog` 参数**： **必需**： - `issueKey`：字符串 - 问题键（例如，`"PROJ-123"`） - `worklogId`：字符串 - 要更新的工作日志 ID **可选**（任意组合）： - `timeSpent`：字符串 - 更新花费时间 - `comment`：字符串 - 更新评论 - `started`：字符串 - 更新开始时间 **`jira_delete_worklog` 参数**： **必需**： - `issueKey`：字符串 - 问题键（例如，`"PROJ-123"`） - `worklogId`：字符串 - 要删除的工作日志 ID **示例**： ``` # 添加工作日志条目 jira_add_worklog issueKey:"PROJ-123" timeSpent:"2h" comment:"已修复身份验证错误" # 获取问题的所有工作日志 jira_get_worklogs issueKey:"PROJ-123" # 获取上周的工作日志 jira_get_worklogs issueKey:"PROJ-123" startedAfter:"2025-05-29T00:00:00.000Z" # 更新工作日志 jira_update_worklog issueKey:"PROJ-123" worklogId:"12345" timeSpent:"3h" comment:"已更新工作描述" # 删除工作日志 jira_delete_worklog issueKey:"PROJ-123" worklogId:"12345" ``` #### 评论参数 `jira_get_issue_comments` 工具支持使用以下参数逐步披露： **必需**： - `issueKey`：字符串 - 问题键（例如，`"PROJ-123"`） **基本选项**： - `maxComments`：数字（1-100，默认值：10） - 要检索的最大评论数 - `orderBy`：字符串（`"created"` 或 `"updated"`，默认值：`"created"`） - 评论的排序顺序 **高级选项**： - `includeInternal`：布尔值（默认值：false） - 包括内部/受限评论 - `authorFilter`：字符串 - 按作者姓名或电子邮件筛选评论 - `dateRange`：对象 - 按日期范围筛选： - `from`：字符串（ISO 日期） - 开始日期 - `to`：字符串（ISO 日期） - 结束日期 **示例**： ``` # 基本用法 - 获取 10 条最新评论 jira_get_issue_comments PROJ-123 # 获取更多评论，并具有特定的排序 jira_get_issue_comments PROJ-123 maxComments:25 orderBy:"updated" # 高级筛选 jira_get_issue_comments PROJ-123 authorFilter:"john.doe" includeInternal:true ``` #### 搜索参数 `search_jira_issues` 工具支持两种模式： **专家模式 (JQL)**： - `jql`：直接 JQL 查询字符串（例如，`"project = PROJ AND status = Open"`） **初学者模式（帮助程序参数）**： - `assignedToMe`：布尔值 - 仅显示分配给当前用户的问题 - `project`：字符串 - 按项目键筛选 - `status`：字符串或数组 - 按状态筛选（例如，`"Open"` 或 `["Open", "In Progress"]`） - `text`：字符串 - 在摘要和描述字段中搜索 **常用选项**： - `maxResults`：数字（1-50，默认值：25） - 限制结果数 - `fields`：数组 - 指定要检索的字段（可选） ## 🛠️ 开发工具 ### 代码质量工具 该项目使用 [Biome](https://biomejs.dev/) 进行代码格式化和 linting，提供： - 快速、统一的格式化和 linting - TypeScript 优先的工具 - 无需配置 - 一致的代码样式强制执行 ```bash # 格式化代码 bun run format # 检查代码是否存在问题 bun run check # 类型检查 bun run typecheck # 运行测试 bun test ``` ### MCP Inspector <details> <summary>单击以展开 MCP Inspector 详细信息</summary> MCP Inspector 是一个强大的工具，用于测试和调试您的 MCP 服务器。 ```bash # 运行 Inspector（无需单独的构建步骤） bun run inspect ``` Inspector 自动执行以下操作： - 从 `.env` 加载环境变量 - 清理占用的端口（5175、3002） - 在需要时构建项目 - 使用您的配置启动 MCP 服务器 - 启动 Inspector UI 请访问 http://localhost:5175?proxyPort=3002 上的 Inspector 如果您遇到端口冲突： ```bash bun run cleanup-ports ``` #### 使用 Inspector 进行调试 Inspector UI 允许您： - 查看所有可用的 MCP 功能 - 执行工具并检查响应 - 分析 JSON 通信 - 使用不同的参数进行测试 有关更多详细信息，请参阅 [MCP Inspector GitHub 存储库](https://github.com/modelcontextprotocol/inspector)。 </details> ### 与 Claude Desktop 集成 <details> <summary>单击以展开 Claude Desktop 集成</summary> 直接使用 Claude 测试您的 MCP 服务器： 1. 构建： ```bash bun run build # 必须先构建项目才能运行它 ``` 2. 配置 Claude Desktop： ```bash nano ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 3. 添加 MCP 配置： ```json { "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" } } } } ``` 4. 重新启动 Claude Desktop 并使用以下命令进行测试： ``` Show me my assigned JIRA issues. ``` </details> ## 🔌 与 Cursor IDE 集成 > **⚠️ 重要提示：** 在与 Cursor IDE 或 Claude Desktop 集成之前，您必须使用 `bun run build` 构建项目。 将此 MCP Server 添加到您的 Cursor IDE 的 MCP 配置中： ```json { "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/ # 核心功能和配置 │ ├── errors/ # 错误处理实用程序 │ ├── logging/ # 日志记录基础设施 │ ├── responses/ # 响应格式化 │ ├── server/ # MCP server 实现 │ ├── tools/ # 基础工具接口 │ └── utils/ # 核心实用程序 ├── features/ # 功能实现 │ └── jira/ # JIRA API 集成 │ ├── api/ # JIRA API 客户端 │ ├── formatters/ # 响应格式化程序 │ ├── tools/ # MCP tool 实现 │ └── utils/ # JIRA-specific 实用程序 └── test/ # 测试实用程序和模拟 ├── mocks/ # 模拟工厂 └── utils/ # 测试助手 ``` ### NPM 脚本 | Command | Description | | ------------------- | -------------------------------------------------- | | `bun dev` | 在具有热重载的开发模式下运行服务器 | | `bun build` | 构建用于生产的项目 | | `bun start` | 启动生产服务器 | | `bun format` | 使用 Biome 格式化代码 | | `bun lint` | 使用 Biome 检查代码 | | `bun check` | 在代码上运行 Biome 检查 | | `bun typecheck` | 运行 TypeScript 类型检查 | | `bun test` | 运行测试 | | `bun inspect` | 启动用于调试的 MCP Inspector | | `bun cleanup-ports` | 清理开发服务器使用的端口 | ## 📝 贡献 欢迎贡献！ 有关详细信息，请参阅我们的 [Contributing Guide](CONTRIBUTING.md)： - 开发工作流程 - 分支策略 - 提交消息格式 - 拉取请求流程 - 代码样式指南 ## 📘 资源 - [Model Context Protocol Documentation](https://modelcontextprotocol.io) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [MCP Specification](https://spec.modelcontextprotocol.io/specification/) - [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - [JIRA REST API Documentation](https://developer.atlassian.com/cloud/jira/platform/rest/v2/) ## 📄 许可证 [MIT](LICENSE) © Stanislav Stepanenko --- <div align="center"> _{用 ❤️ 构建，为了更好的开发者体验} </div>