Agent: "What's the status of PROJ-42? Add a comment with the progress update."
  ↓
a2atlassian → get issue, add comment, transition to In Progress
  ↓
Agent: "Done — PROJ-42 updated and moved to In Progress."

왜 a2atlassian인가요?

기존 Atlassian MCP 서버(Rovo, sooperset)는 Docker, .env 파일, mcp-remote 브리지가 필요합니다. 이들은 72개의 도구를 에이전트 컨텍스트에 덤프하며, 조용히 실패하는 알려진 문제들이 있습니다. a2atlassian은 이 모든 문제를 해결합니다:

Docker 불필요 — pip install a2atlassian으로 설치 완료
사전 구성된 연결 — --register를 사용하여 .mcp.json에 프로젝트를 정의하면 에이전트가 즉시 작동합니다
기본 읽기 전용 — 쓰기 권한은 연결별로 선택적으로 활성화합니다
연결 범위 지정 — --scope를 통해 에이전트가 볼 수 있는 프로젝트를 제한합니다
간결한 출력 — 목록에는 TSV(토큰 30-60% 절감), 단일 엔티티에는 JSON을 사용합니다
동적 도구 로딩 — 지연된 도구를 지원하는 MCP 클라이언트(예: Claude Code)는 필요할 때 도구를 로드하여 컨텍스트를 가볍게 유지합니다
오류 보강 — 잘못된 필드 이름에 대한 제안, JQL 오타 수정, 문제 자동 해결 기능을 제공합니다
비밀 정보는 환경 변수에 유지 — 설정의 ${ATLASSIAN_TOKEN}은 런타임에만 확장됩니다

빠른 시작

# Recommended — installs globally as a CLI tool
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

MCP 서버로 사용 (권장)

Claude Code (사전 구성된 연결 사용):

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp \
  --register myproject https://mysite.atlassian.net user@company.com '${ATLASSIAN_TOKEN}'

Claude Code (최소 설정 — 에이전트가 필요할 때 login 호출):

claude mcp add -s user a2atlassian -- uvx --from a2atlassian a2atlassian-mcp

Claude Desktop / Cursor / 모든 MCP 클라이언트 (.mcp.json):

{
  "mcpServers": {
    "a2atlassian": {
      "command": "uvx",
      "args": [
        "--from", "a2atlassian", "a2atlassian-mcp",
        "--register", "myproject", "https://mysite.atlassian.net",
        "user@company.com", "${ATLASSIAN_TOKEN}"
      ],
      "env": {
        "ATLASSIAN_TOKEN": "your-api-token-here"
      }
    }
  }
}

다중 프로젝트:

{
  "args": [
    "--from", "a2atlassian", "a2atlassian-mcp",
    "--register", "myproject", "https://mysite.atlassian.net", "user@a.com", "${TOKEN_A}",
    "--register", "personal", "https://personal.atlassian.net", "user@b.com", "${TOKEN_B}"
  ]
}

범위가 지정된 연결 (에이전트를 특정 저장된 프로젝트로 제한):

{
  "args": ["--from", "a2atlassian", "a2atlassian-mcp", "--scope", "myproject"]
}

--register는 메모리 내 임시 연결을 생성합니다(프로세스 수명 동안 유지, 파일 기록 없음). --scope는 표시되는 저장된 연결을 필터링합니다. 둘 다 폭발 반경을 제한합니다.

CLI로 사용

# Save a connection (validates by calling /myself)
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN"

# Enable writes
a2atlassian login -p myproject \
  --url https://mysite.atlassian.net \
  --email user@company.com \
  --token "$ATLASSIAN_TOKEN" \
  --no-read-only

# List / remove connections
a2atlassian connections
a2atlassian logout -p myproject

MCP 도구

연결 관리

도구	설명
`login`	연결 저장 — `/myself`를 호출하여 유효성 검사
`logout`	저장된 연결 제거
`list_connections`	연결 목록 표시 (비밀 정보 노출 없음)

Jira — 읽기

도구	설명
`jira_get_issue`	키로 이슈 가져오기 — 전체 필드, 상태, 담당자 포함
`jira_search`	페이지 매김을 포함한 JQL 검색 — 기본적으로 간결한 TSV 출력
`jira_get_comments`	이슈의 모든 댓글 가져오기
`jira_get_transitions`	사용 가능한 상태 전환 확인

Jira — 쓰기 (읽기-쓰기 연결 필요)

도구	설명
`jira_add_comment`	댓글 추가 (위키 마크업, API v2)
`jira_edit_comment`	기존 댓글 업데이트
`jira_transition_issue`	이슈를 새 상태로 이동

출력 형식

모든 도구는 format 매개변수를 허용합니다:

형식	기본 대상	설명
`toon`	목록 (검색, 댓글)	헤더가 있는 TSV — 데이터 구조는 한 번만, 데이터는 여러 번. JSON보다 토큰 30-60% 절감
`json`	단일 엔티티 (get_issue)	메타데이터 봉투가 포함된 표준 JSON

목록 응답은 TOON에서 영감을 받은 간결한 TSV 스타일 형식(헤더 행 + 탭으로 구분된 값)을 사용합니다. 이는 a2db가 사용하는 방식과 동일하며, 열 이름은 한 번만 나타나고 그 뒤에는 값만 나옵니다. 50개 이슈 검색 결과의 경우, 일반적으로 JSON 대비 40-60%의 토큰을 절약합니다.

TSV 예시 (검색 결과):

# search (23 results, 50ms, truncated: False)
key	summary	assignee	status
PROJ-142	Fix auth timeout	Alice Smith	In Progress
PROJ-141	Add search filters	Bob Jones	To Do

JSON 예시 (단일 이슈):

{
  "data": {"key": "PROJ-142", "fields": {"summary": "Fix auth timeout", ...}},
  "count": 1,
  "truncated": false,
  "time_ms": 85
}

오류 보강

문제가 발생하면 a2atlassian이 에이전트에게 해결 방법을 알려줍니다:

Field 'asignee' does not exist
Did you mean: assignee?

Connection 'myproject' is read-only.
Run: a2atlassian login -p myproject --read-only false

자동으로 처리되는 문제들:

담당자는 표시 이름이 필요함 (712020: 계정 ID가 아님) — 힌트와 함께 자동 감지
상위 필드는 일반 문자열이어야 함 — {"key": "PROJ-14"}가 자동으로 "PROJ-14"로 정규화됨
이슈 유형 변환은 API를 통해 지원되지 않음 — 명확한 Jira UI 지침 제공

보안

기본 읽기 전용

모든 연결은 읽기 전용으로 시작합니다. 쓰기 도구는 실행 전에 연결 플래그를 확인합니다:

Connection 'myproject' is read-only.
Re-run 'a2atlassian login -p myproject --read-only false' to enable writes.

인간 운영자가 쓰기 권한을 제어하며, 에이전트가 제어하지 않습니다.

자격 증명 저장

login을 통해 저장된 연결은 ~/.config/a2atlassian/connections/에 TOML 파일로 저장됩니다:

파일 권한: 0600 (소유자만 읽기/쓰기 가능)
${ATLASSIAN_TOKEN} 구문 — 환경 변수 참조는 그대로 저장되며 런타임에 확장됨
출력에 비밀 정보 없음 — list_connections는 프로젝트 이름, URL, 모드만 표시하며 토큰은 절대 표시하지 않음
임시 모드 — --register는 자격 증명을 메모리에만 유지하며 디스크에 기록하지 않음

연결 범위 지정

--scope를 사용하여 특정 MCP 인스턴스가 액세스할 수 있는 저장된 연결을 제한하세요:

# Project config — only myproject visible, even if other connections are saved
uvx --from a2atlassian a2atlassian-mcp --scope myproject

프로젝트 수준의 MCP 설정(.claude/mcp.json)은 전역 설정을 재정의하며, 각 저장소는 자신의 연결만 볼 수 있습니다.

속도 제한

Atlassian의 속도 제한(429) 및 일시적인 서버 오류(500)에 대해 지수 백오프를 사용한 재시도 기능이 내장되어 있습니다. 오류를 노출하기 전에 1초 및 3초 간격으로 두 번 재시도합니다.

비교

기능	a2atlassian	Rovo (공식)	sooperset/mcp-atlassian
설정	`pip install`	OAuth + Docker	Docker + .env + mcp-remote
컨텍스트 내 도구	10 (1단계)	~72	~72
연결 관리	TOML + `--register` + `--scope`	세션별 OAuth	.env 파일
다중 프로젝트	예 (범위 지정)	아니요	설정당 하나의 .env
기본 읽기 전용	예 (연결별)	아니요	아니요
출력 형식	TSV + JSON	JSON	JSON
오류 보강	필드 제안, 문제 자동 수정	일반 오류	일반 오류
문제 처리	자동 수정 (담당자, 상위)	문서화된 해결 방법	문서화된 해결 방법
속도 제한	내장 재시도	아니요	아니요
CLI	예	아니요	아니요
라이선스	Apache 2.0	독점	MIT

로드맵

1단계 (현재): Jira 핵심 — 이슈 가져오기/검색, 댓글(CRUD), 전환. 두 번째 중요 경로.

2단계: 전체 Jira 표면 — 스프린트, 보드, 링크, 프로젝트, 필드, 작업 로그, 첨부 파일, 관찰자.

3단계: Confluence — 페이지, 댓글, 첨부 파일, 라벨, 검색.

환경별 설정

로컬 (macOS / Linux)

# Recommended
uv tool install a2atlassian

# Or with pip
pip install a2atlassian

# CLI
a2atlassian login -p myproject --url https://mysite.atlassian.net --email me@co.com --token "$TOKEN"

# Or add as MCP server (see Quick Start)

CI / 자동화

uv tool install a2atlassian

# Pre-configured — no login needed
uvx --from a2atlassian a2atlassian-mcp --register ci https://mysite.atlassian.net ci-user@co.com "${CI_ATLASSIAN_TOKEN}"

개발

make bootstrap   # Install deps + hooks
make check       # Lint + test + security (full gate)
make test        # Tests with coverage
make lint        # Lint only (never modifies files)
make fix         # Auto-fix + lint

라이선스

Apache 2.0

a2atlassian