Atlassian AI Toolkit

AI 우선 SDK, CLI, Atlassian Jira 및 Confluence용 MCP 서버

Atlassian Cloud API용 타입 SDK, 에이전트 네이티브 CLI, MCP 서버를 포함하는 Bun 모노레포입니다.

패키지

Related MCP server: MCP Atlassian

CLI 설치

권장: 독립 실행형 바이너리

Node.js, npm, PATH 충돌 없음. Bun으로 빌드된 단일 파일입니다.

macOS 및 Linux:

curl -fsSL https://raw.githubusercontent.com/spenserhale/atlassian-ai-toolkit/main/scripts/install.sh | sh

스크립트가 OS와 아키텍처를 감지하여 최신 릴리스에서 일치하는 바이너리를 다운로드하고, SHA256을 검증한 후 $HOME/.local/bin/atlassian에 설치합니다.

ATLASSIAN_AI_TOOLKIT_VERSION=v0.1.0으로 버전을 고정하거나 ATLASSIAN_AI_TOOLKIT_INSTALL=$HOME/bin으로 설치 디렉터리를 변경할 수 있습니다.

Windows: 최신 릴리스에서 atlassian-windows-x64.exe를 다운로드하여 PATH에 추가하세요.

사용 가능한 바이너리: atlassian-linux-{x64,arm64}, atlassian-darwin-{x64,arm64}, atlassian-windows-x64.exe.

업그레이드

최신 GitHub 릴리스에서 설치된 바이너리를 제자리에서 업그레이드합니다 (먼저 SHA256을 검증합니다):

atlassian upgrade            # apply the latest release
atlassian upgrade --dry-run  # only show current vs latest

Windows에서는 업그레이드 전에 실행 중인 인스턴스를 닫거나 최신 릴리스에서 exe를 다시 다운로드하세요.

셸 별칭

더 짧은 명령을 위해 셸 프로필(~/.zshrc 또는 ~/.bashrc)에 다음 별칭을 추가하세요:

alias jira='atlassian jira'
alias conf='atlassian confluence'

그러면 jira get PROJ-123은 atlassian jira get PROJ-123을 실행하고, conf get 123456은 atlassian confluence get 123456을 실행합니다.

구성

셸에서 Atlassian Cloud 자격 증명을 설정하세요:

export ATLASSIAN_SITE_URL="https://your-site.atlassian.net"
export ATLASSIAN_EMAIL="you@example.com"
export ATLASSIAN_API_TOKEN="your-api-token"

https://id.atlassian.com/manage-profile/security/api-tokens에서 범위가 지정된 API 토큰을 생성하세요.

첨부 파일

하나 이상의 파일을 Jira 이슈에 업로드합니다. 여러 업로드에는 --file을 반복하세요. 저장된 파일 이름은 파일의 기본 이름이며 MIME 유형은 확장자에서 유추됩니다.

# Attach a single file
atlassian jira attach PROJ-123 --file ./screenshot.png

# Attach several files and print the API response
atlassian jira attach PROJ-123 --file ./error.log --file ./har-capture.har --json

MCP 도구 jira_add_attachment는 동일한 paths와 에이전트가 인라인으로 생성하는 콘텐츠를 위한 files 배열(filename, content, encoding: utf8 | base64)을 사용합니다.

Confluence 페이지는 호출당 첨부 파일 하나를 사용합니다:

atlassian confluence attachment upload --page 123456 --file ./diagram.png

사이트에서 첨부 파일이 활성화되어 있어야 하며, 업로드는 사이트의 최대 첨부 파일 크기 제한을 따릅니다.

파괴적 작업

기본적으로 삭제 미리 보기를 표시합니다. 실제 삭제에는 --force와 가져온 리소스에서 일치하는 --confirm 값이 필요합니다.

# Preview the permanent Jira delete
atlassian jira delete PROJ-123

# Permanently delete the Jira issue
atlassian jira delete PROJ-123 --force --confirm PROJ-123

# Preview moving a Confluence page to trash
atlassian confluence delete 123456

# Move a Confluence page to trash
atlassian confluence delete 123456 --force --confirm 123456

# Permanently purge an already-trashed Confluence page
atlassian confluence delete 123456 --purge --force --confirm 123456

소스에서 시작하기

# Install dependencies
bun install

# Build all packages
bun run build

# Run the CLI
bun run dev:cli -- --help

# Run the MCP server (stdio mode for Claude Desktop)
bun run dev:mcp

토큰은 워크플로에 필요한 최소한의 Jira 및 Confluence 권한으로 범위를 지정해야 합니다. 타사 참조 구현은 refs/ 아래에 있으며, 이 저장소가 검토되지 않은 코드를 로컬 자격 증명으로 공급하거나 실행하지 않도록 의도적으로 gitignore되어 있습니다.

아키텍처

packages/sdk/     <-- Types, API client, business logic (foundation)
    ^       ^
    |       |
packages/cli/   packages/mcp/
    (Stricli)    (FastMCP)

CLI와 MCP 서버는 모두 SDK의 얇은 래퍼입니다. REST API가 변경되면 SDK를 업데이트하면 두 소비자가 자동으로 수정됩니다.

개발

# Run tests across all packages
bun test

# Build a specific package
cd packages/sdk && bun run build

새 API 작업 추가

1. packages/sdk/src/types.ts에 타입 추가

2. packages/sdk/src/client.ts에 클라이언트 메서드 추가

3. packages/cli/src/commands/에 CLI 명령 추가

4. packages/mcp/src/tools/에 MCP 도구 추가

파괴적 작업은 기본적으로 미리 보기 경로를 사용해야 하며 CLI에서는 명시적 --force 플래그, MCP 도구에서는 force: true가 필요합니다.