jira-setup

name	jira-setup
description	Interactive setup wizard for Jira MCP server registration and connection validation. Triggers: jira setup, setup jira; Jira 설정, MCP 등록.
user-invocable	false
argument-hint
allowed-tools	["Read","Bash","mcp__atlassian__jira_get_user_profile","mcp__atlassian__jira_search"]

jira-setup: Interactive Jira Setup Wizard

Language Rule: 프로젝트 CLAUDE.md의 Conventions 섹션 참고 (한국어 출력).

Overview

Jira MCP 서버(atlassian)를 Claude Code에 등록하는 대화형 설정 위자드.

Step 1: Prerequisites Check

1-1. uv 설치 확인

uv --version

실패 시:

❌ uv가 설치되어 있지 않습니다.

설치 방법:
  Windows (PowerShell): irm https://astral.sh/uv/install.ps1 | iex
  macOS/Linux:          curl -LsSf https://astral.sh/uv/install.sh | sh

설치 후 터미널을 재시작하고 /jira setup을 다시 실행하세요.

→ 중단

1-2. Python 3.10+ 확인

python --version 2>/dev/null || python3 --version 2>/dev/null

Windows Store stub 회피: python --version이 "Python 3.x.x"를 반환하지 않고 아무것도 출력하지 않거나 Microsoft Store를 열려고 하면 stub으로 간주. uv python list로 대체 확인.

Python 3.10 미만이거나 없으면:

❌ Python 3.10 이상이 필요합니다.

현재 버전: <버전 또는 "없음">

uv로 Python 설치:
  uv python install 3.11

또는 python.org에서 직접 설치하세요.

→ 중단

사전 요건 통과 시: ✅ 사전 요건 확인 완료 (uv <버전>, Python <버전>)

Step 2: Check Existing Registration

.claude/settings.local.json과 ~/.claude/settings.json 검사:

cat .claude/settings.local.json 2>/dev/null
cat ~/.claude/settings.json 2>/dev/null

mcpServers 키 아래 atlassian 항목이 존재하면 이미 등록된 것으로 판단.

이미 등록된 경우, 선택지를 안내:

ℹ️ Jira MCP 서버(atlassian)가 이미 등록되어 있습니다.

어떻게 하시겠습니까?
1. 연결 테스트만 실행
2. 자격증명 재설정 (기존 설정 덮어쓰기)
3. 취소

AskUserQuestion 도구로 사용자에게 선택 요청:

• "연결 테스트" 선택 → Step 5로 바로 이동
• "재설정" 선택 → Step 3부터 진행
• "취소" 선택 → 종료

Step 3: Collect Credentials

AskUserQuestion 도구로 아래 정보를 수집한다.

필수 항목:

1. JIRA_URL — Jira Cloud URL

   • 예시: https://your-domain.atlassian.net
   • 확인: https://로 시작하고 atlassian.net을 포함해야 함

2. JIRA_USERNAME — Atlassian 계정 이메일

   • 예시: [e-mail]

3. JIRA_API_TOKEN — API 토큰

   • 발급 링크: https://id.atlassian.com/manage-profile/security/api-tokens
   • 입력값을 화면에 표시하지 않도록 안내

선택 항목 (별도 질문):

4. JIRA_PROJECTS_FILTER — 접근 허용 프로젝트 키 (쉼표 구분)

   • 예시: PROJ 또는 PROJ,DEV
   • 비워두면 모든 프로젝트 접근 가능

5. JIRA_DEFAULT_PROJECT — 기본 프로젝트 키 (JQL 쿼리에 자동 포함)

   • 예시: PROJ
   • 비워두면 프로젝트 필터링 없음

Step 4: Register MCP Server

수집한 자격증명으로 MCP 서버를 등록:

claude mcp add atlassian \
  -e JIRA_URL="<JIRA_URL>" \
  -e JIRA_USERNAME="<JIRA_USERNAME>" \
  -e JIRA_API_TOKEN="<JIRA_API_TOKEN>" \
  -- uvx mcp-atlassian

JIRA_PROJECTS_FILTER가 입력되었으면 -e JIRA_PROJECTS_FILTER="<값>" 추가.

참고: JIRA_DEFAULT_PROJECT는 MCP 서버가 아닌 플러그인 자체에서 사용하는 변수이므로, .claude/settings.local.json 또는 CLAUDE.md에 별도로 기록 안내.

등록 후: ✅ MCP 서버 등록 완료

Step 5: Validate Connection

mcp__atlassian__jira_get_user_profile 호출로 연결 검증.

성공 시:

✅ 연결 성공!

사용자: <displayName> (<emailAddress>)
계정 ID: <accountId>

Jira MCP 서버가 정상적으로 연결되었습니다.
이제 /jira-task 워크플로를 사용할 수 있습니다.

실패 시 오류 진단:

오류 패턴	원인	해결책
401 Unauthorized	API 토큰 또는 이메일 오류	JIRA_USERNAME과 JIRA_API_TOKEN 재확인
404 Not Found	JIRA_URL 오류	URL 형식 확인 (https://domain.atlassian.net)
connection refused	네트워크 문제	인터넷 연결 및 방화벽 확인
uvx not found	uv 미설치 또는 PATH 오류	uv --version 재확인

❌ 연결 실패

오류: <오류 메시지>
원인: <진단 결과>
해결책: <구체적인 조치>

자격증명을 수정하려면 /jira setup을 다시 실행하세요.

Step 6: Post-Setup Summary

─────────────────────────────────────────
🎉 Jira 설정 완료
─────────────────────────────────────────
MCP 서버: atlassian (uvx mcp-atlassian)
연결 계정: <이메일>
Jira URL: <JIRA_URL>

다음 단계:
  /jira              — 연결 상태 및 사용 가능한 명령 확인
  /jira-task init    — 할당된 작업 목록 가져오기
─────────────────────────────────────────