Jira票务管理CLI

Jira票证管理CLI

使用Jira Cloud REST API查看、搜索和状态切换我的票证的简单CLI工具。

设置

1. 创建虚拟环境并安装依赖性 （推荐）

   在MacOS等系统中，如果系统Python是PEP668（externally-managed-environment），则使用虚拟环境是安全的。

   复制

   cd ~/jira-helper
   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

   如果不使用虚拟环境：

   复制

   pip install -r requirements.txt
   # 또는
   pip install requests python-dotenv
   

2. 环境变量

   • .env.example复制 .env 创建（在项目中使用）或 ~/.config/jira-helper/.env （全局使用）
   • 输入Jira Cloud URL、电子邮件和API令牌
   复制

   cp .env.example .env
   # .env 편집: JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN
   

   API令牌发放： Atlassian API令牌在中创建（使用代替密码）

使用方法

打开并运行虚拟环境：

cd ~/jira-helper
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python jira_cli.py list

要在没有虚拟环境的情况下一次性运行，请直接指定项目的Python:

~/jira-helper/.venv/bin/python ~/jira-helper/jira_cli.py list

命令示例

# 내 미완료 티켓 목록 (기본)
python jira_cli.py list

# 내 완료 티켓만
python jira_cli.py list --status done

# 전체(미완료+완료)
python jira_cli.py list --status all

# 티켓 상세 보기
python jira_cli.py show PROJ-123

# JQL로 검색
python jira_cli.py search "project = MYPROJ AND status = 'In Progress'"
python jira_cli.py search "assignee = currentUser() ORDER BY updated DESC" -n 10

# 티켓 착수 (In Progress로 전환)
python jira_cli.py start PROJ-123

# 티켓 상태 변경 (Resolved, Closed 등)
python jira_cli.py transition PROJ-123 Resolved

# 티켓 생성 (프로젝트, 제목; --type, -d, --assign-me 선택)
python jira_cli.py create PROJ "새 작업 제목"
python jira_cli.py create PROJ "버그 요약" --type Bug -d "재현 절차" --assign-me
# CLOSET Bug는 config 기본값 적용. 덮어쓰기: --custom-fields '{"customfield_10648":{"id":"12601"}}'

# 티켓 수정 (제목·설명·담당자)
python jira_cli.py edit PROJ-123 -s "새 제목"
python jira_cli.py edit PROJ-123 -d "새 설명" --assign-me

Shell别名（可选）

~/.zshrc添加到 jira list可以像这样使用。要在虚拟环境中使用Python：

alias jira='~/jira-helper/.venv/bin/python ~/jira-helper/jira_cli.py'

如果您在没有虚拟环境的情况下使用系统Python：

alias jira='python ~/jira-helper/jira_cli.py'

在其他项目中使用

在任何目录中 jira 要使用命令 全局安装哇 全局设置写就可以了。

1.全局安装

pipx （建议：作为专用虚拟环境安装，与其他软件包隔离）：

pipx install ~/jira-helper
# 또는 GitHub 클론 후
git clone https://github.com/your-id/jira-helper.git && pipx install ./jira-helper
# 개발 중 변경 반영하려면: pipx install -e ~/jira-helper

点 （在现有虚拟环境中安装）：

cd ~/jira-helper
pip install -e .

安装后 jira 命令在PATH中注册。

2.加载设置的顺序

CLI按以下顺序查找设置文件：

1. JIRA_ENV 为环境变量指定的文件路径
2. 当前目录的 .env
3. ~/.config/jira helper/.env （全局默认值）

在其他项目中使用相同的Jira时，只需保留一个全局设置即可。

mkdir -p ~/.config/jira-helper
cp ~/jira-helper/.env.example ~/.config/jira-helper/.env
# ~/.config/jira-helper/.env 편집

如果您只想为特定项目使用不同的Jira（不同的URL/帐户），请在该项目目录中 .env如果存在，则只有在该目录中运行时才使用该设置。

3.使用示例

cd ~/any-project
jira list
jira show PROJ-123

用作MCP服务器（Cursor等）

注册为模型上下文协议（MCP）服务器时，Cursor将 “帮我查一下吉拉的门票目录”，**可以像“出示PROJ-123门票”**一样用自然语言请求。

全局MCP（用于所有Cursor项目）

1. 使用pipx进行全局安装 （仅一次）：

   复制

   pipx install -e ~/jira-helper
   

   jira, jira-mcp 命令在PATH中注册。

2. 全局设置文件 (~/.config/jira-helper/.env):

   复制

   mkdir -p ~/.config/jira-helper
   cp ~/jira-helper/.env.example ~/.config/jira-helper/.env
   # ~/.config/jira-helper/.env 에 JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN 입력
   

   MCP服务器当前目录 .env如果没有，则使用此文件。

3. Cursor全局MCP设置 (~/.cursor/mcp.json):

   mcpServers在中添加以下内容：

   复制

   "jira-helper": {
     "command": "jira-mcp"
   }
   

   重新启动Cursor后，可以在所有工作空间中写入jira-helper MCP。

特定于项目的MCP（仅此项目）

如果您只想在该项目中使用MCP，请使用项目虚拟环境中的Python mcp_server.py直接运行。（无全局安装）

1. 依赖性安装

   复制

   cd ~/jira-helper
   pip install -e .
   # (mcp는 기본 의존성에 포함됨)
   

2. 在Cursor中注册MCP服务器 （项目 .cursor/mcp.json)

   复制

   {
     "mcpServers": {
       "jira-helper": {
         "command": "~/jira-helper/.venv/bin/python",
         "args": ["~/jira-helper/mcp_server.py"]
       }
     }
   }
   

   如果克隆到了其他路径，请切换到该路径。

交付工具

具有Bug等必要自定义字段的项目（例如CLOSET）
config/required_fields.json如果存在默认值，则会自动应用。选项值·覆盖方法 docs/MCP_REQUIRED_FIELDS.md 参考。

设置与CLI相同 JIRA_ENV, .env（当前目录）， ~/.config/jira helper/.env 按顺序加载。

在Cursor中参考票证

如果在代码工作时说“请根据PROJ-123票证进行修改”，请使用此CLI show PROJ-123 可以参考结果进行操作。
打开MCP服务器后，Cursor将直接 jira_show 可以调用等获取票证内容。
如果愿意的话 .cursor/rules您还可以在中添加在提交/分支中包含Jira票号的规则。