MCP Jira Helper

MCP Jira助手

用于管理Jira工作会话、工作日志和问题转换的CLI工具。使用Node.js和TypeScript构建。

特性

• 工作会议管理：通过自动时间跟踪启动、暂停、恢复和停止工作会话
• 自动工作日志：使用可配置的舍入自动记录Jira问题的时间
• 问题转换：州之间的过渡问题（例如待办事项→ 进行中→ 验证）
• 评论和链接：向问题添加评论和远程链接（如PR URL）
• 跨日处理：自动处理跨越多天的工作会话
• 手动工作日志：为会议或其他活动添加手动工作日志条目

先决条件

• Node.js≥18
• Jira Cloud API代币
• 您的Jira基本URL（例如。， https://your-org.atlassian.net)

设置

1. 安装依赖项:

   npm install

1. 配置环境:

   cp env.example .env

编辑 .env 使用您的Jira凭据：

   JIRA_BASE_URL=https://your-org.atlassian.net
   JIRA_EMAIL=you@example.com
   JIRA_API_TOKEN=your_api_token_here
   TZ=Asia/Taipei
   ROUNDING_MIN=5

1. 获取Jira API代币:

- 首选https://id.atlassian.com/manage-profile/security/api-tokens - 创建新的API令牌 - 将您的电子邮件和生成的令牌复制到 .env

用法

发展模式

npm run dev -- 

生产模式

npm run build
npm start 

命令

开始工作会话

npm run dev -- start ABC-123
npm run dev -- start ABC-123 --to "In Progress"

• 将问题转换为指定状态（默认：“进行中”）
• 添加开始注释
• 开始时间跟踪

暂停/恢复工作会话

npm run dev -- pause
npm run dev -- resume

• 暂停：停止计时器并保存累积时间
• 恢复：从您停止的地方重新启动计时器

停止工作会议

npm run dev -- stop
npm run dev -- stop --pr https://github.com/org/repo/pull/123
npm run dev -- stop --to Verification --pr https://github.com/org/repo/pull/123

• 记录问题的累积时间
• 可选链接PR URL
• 转换到指定状态（默认：“验证”）
• 添加完成注释

手动工作日志输入

npm run dev -- log ABC-123 "2h 30m" "Daily standup meeting"
npm run dev -- log ABC-123 "45m" "Code review"

检查状态

npm run dev -- status

显示当前会话状态和累计时间。

配置

环境变量

• JIRA_BASE_URL：您的Jira实例URL
• JIRA_EMAIL：您的Atlassian帐户电子邮件
• JIRA_API_TOKEN：您的API代币
• TZ：时区（可选，默认为系统时区）
• ROUNDING_MIN：时间四舍五入，单位为分钟（5、10或15）

会话存储

工作会话存储在 .sessions/work_session.json。此文件：

• 跨终端会话持续
• 自动处理跨天工作
• 存储累积时间和会话状态

常见JQL查询

在Jira中使用这些JQL查询来查找相关问题：

• 我正在处理的问题: assignee = currentUser() AND statusCategory = "In Progress" ORDER BY updated DESC
• 我的待办事项: assignee = currentUser() AND statusCategory = "To Do" ORDER BY updated ASC
• 今天的工作日志: worklogAuthor = currentUser() AND worklogDate = startOfDay()

故障排除

身份验证问题

• 在中验证您的电子邮件和API令牌 .env
• 确保API令牌具有必要的权限

转换错误

• 检查可用转换：如果转换失败，该工具将显示可用选项
• 确保您有权限转换问题

时区问题

• 集 TZ 环境变量到您的本地时区
• Jira希望ISO时间戳包含正确的时区信息

项目结构

src/
├── cli.ts          # CLI command definitions
├── config.ts       # Environment configuration
├── jira.ts         # Jira REST API client
└── session.ts      # Work session management

安全说明

• 永不承诺 .env 文件到版本控制
• API令牌应保持安全
• 这 .sessions 目录包含本地会话数据

许可证

国际学生委员会