| name | jira-setup |
| description | Interactive setup wizard — Jira credentials for this workspace (jira-cli) and optional MCP registration. Triggers: jira setup, setup jira; Jira 설정, 자격증명 설정. |
| user-invocable | false |
| argument-hint | [--mcp] |
| allowed-tools | ["Read","Bash","AskUserQuestion"] |
jira-setup: Workspace Jira Setup Wizard
Language Rule: 프로젝트 CLAUDE.md의 Conventions 섹션 참고 (한국어 출력).
Overview
이 워크스페이스의 Jira 자격증명을 메인 레포 .jira-context.json의 jira 블록에 기록하고 연결을 검증하는 위자드. v0.61.0부터 플러그인의 모든 Jira 호출은 scripts/jira-cli.py가 하므로 MCP 서버 등록은 선택(--mcp 인자 또는 Step 5에서 요청 시 — 대화 중 ad-hoc Jira 질의를 MCP 도구로 하고 싶을 때만).
- 자격증명은 워크스페이스 단위다 — 다른 워크스페이스가 알 필요 없는 값을 전역 설정에 두지 않는다.
- 토큰은
.jira-context.json에만 저장되며 이 파일은 .gitignore 대상이다 (config set이 미등록이면 등록까지 한다).
- 위자드 출력·요약에 토큰 값을 절대 표시하지 않는다 (
config show가 마스킹한 값만).
Step 1: Prerequisites
python3 --version
git rev-parse --git-common-dir 2>/dev/null && echo IN_GIT_REPO
python3가 없으면 설치 안내 후 중단. git 레포가 아니면 "플러그인은 git 레포 안에서 동작합니다" 안내 후 중단.
Step 2: 기존 설정 확인
skills/_shared/script-lookup.md로 SCRIPT_NAME="jira-cli.py" 1회 해석 후:
python3 "<scripts>/jira-cli.py" config show
url·username·apiToken(마스킹)이 모두 있으면 → 사용자에게 선택: 연결 테스트만 / 재설정 / 취소.- 없으면 →
python3 "<scripts>/jira-cli.py" whoami를 한 번 실행해 본다. jira-cli는 환경변수·레거시 MCP 설정(.mcp.json, ~/.claude.json, settings)에서 자격증명을 찾으면 자동으로 jira 블록에 기입하므로(stderr에 "기입함" 안내), 성공하면 Step 4로 바로 간다. 실패하면 Step 3.
Step 3: 자격증명 수집
AskUserQuestion으로 수집 (토큰 입력은 사용자가 직접 — 위자드가 값을 되풀이해 출력하지 않는다):
기록:
python3 "<scripts>/jira-cli.py" config set "<url>" "<email>" "<token>" [<PROJECT>]
출력의 gitignoreUpdated: true면 ".gitignore에 .jira-context.json을 추가했습니다"를 알린다 (정보 — 경고 아님).
Step 4: 연결 검증
python3 "<scripts>/jira-cli.py" whoami
| 결과 | 진단 |
|---|
{"accountId", "displayName", ...} | 성공 → Step 5 |
jira-cli: 401 Unauthorized | 토큰/이메일 오류 — Step 3 재수집 |
jira-cli: 404 | URL 오류 (도메인·끝 슬래시) |
jira-cli: 네트워크 오류 | URL 도달 불가 — VPN/프록시 확인 |
기본 프로젝트를 설정했으면 python3 "<scripts>/jira-cli.py" search "assignee = currentUser()" --limit 1로 프로젝트 접근도 확인한다.
Step 5: (선택) MCP 서버 등록
--mcp 인자가 있거나 사용자가 요청할 때만. 대화 중 mcp__atlassian__* 도구로 ad-hoc 질의를 하고 싶은 경우용이며, 플러그인 워크플로에는 필요 없다.
claude mcp add atlassian \
-e JIRA_URL="<url>" -e JIRA_USERNAME="<email>" -e JIRA_API_TOKEN="<token>" \
[-e JIRA_PROJECTS_FILTER="<PROJECT>"] \
-- uvx mcp-atlassian
전제: Python 3.10+ 와 uv(uv --version). 등록 후 세션 재시작이 필요하고, 세션 시작 직후 서버가 늦게 붙으면 /mcp에서 재연결해야 할 수 있음을 안내한다.
Step 6: 완료 요약
---
✅ **Jira Setup Complete**
- 워크스페이스: <메인 레포 경로>
- Jira: <url> (<displayName>)
- 기본 프로젝트: <PROJECT | 없음>
- 자격증명 저장: .jira-context.json `jira` 블록 (gitignore ✓)
- MCP 서버: <등록됨 | 미등록 (플러그인 동작에 불필요)>
**Next**: `/jira-task init <이슈키|N>` 으로 작업 큐를 잡거나, `/jira-task create`로 이슈를 만드세요.
---
