# @choing.dev/jira-mcp

Jira Cloud & Confluence를 AI 에이전트에서 바로 사용할 수 있게 해주는 **MCP (Model Context Protocol) 서버**입니다.

Claude, Cursor 등 MCP를 지원하는 AI 도구에서 JQL 검색, 이슈 생성/수정/전환, 댓글 작성, Confluence 페이지 생성까지 자연어로 수행할 수 있습니다.

## 주요 기능

| 도구 | 설명 |
|---|---|
| `jql_search` | JQL로 이슈 검색 (v3 페이지네이션 지원) |
| `get_issue` | 이슈 상세 조회 |
| `create_issue` | 이슈 생성 (Task, Bug, Story, Epic 등) |
| `update_issue` | 이슈 필드 수정 (제목, 설명, 담당자, 라벨 등) |
| `get_transitions` | 가능한 상태 전환 목록 조회 |
| `transition_issue` | 이슈 상태 전환 (예: To Do → In Progress) |
| `add_comment` | 이슈에 댓글 추가 |
| `list_projects` | 프로젝트 목록 조회 |
| `get_myself` | 현재 사용자 정보 조회 |
| `confluence_create_page` | Confluence 페이지 생성 |

## 빠른 시작

### 1. 환경변수 설정

```bash
export JIRA_INSTANCE_URL="https://your-domain.atlassian.net"
export JIRA_USER_EMAIL="your-email@example.com"
export JIRA_API_KEY="your-api-token"
```

> **API 토큰 발급**: [Atlassian API 토큰 관리](https://id.atlassian.com/manage-profile/security/api-tokens)에서 발급받을 수 있습니다.

### 2. 설치 및 실행

```bash
npx @choing.dev/jira-mcp
```

또는 글로벌 설치:

```bash
npm install -g @choing.dev/jira-mcp
jira-mcp
```

## AI 도구 설정

### Cursor

`.cursor/mcp.json` 파일에 추가:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@choing.dev/jira-mcp"],
      "env": {
        "JIRA_INSTANCE_URL": "https://your-domain.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_KEY": "your-api-token"
      }
    }
  }
}
```

### Claude Desktop

`claude_desktop_config.json`에 추가:

```json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@choing.dev/jira-mcp"],
      "env": {
        "JIRA_INSTANCE_URL": "https://your-domain.atlassian.net",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_KEY": "your-api-token"
      }
    }
  }
}
```

## 도구 상세

### jql_search

JQL 쿼리로 이슈를 검색합니다. Jira REST API v3의 `POST /search/jql`을 사용합니다.

```
"내 프로젝트의 진행 중인 버그를 검색해줘"
→ jql_search { jql: "project = PROJ AND status = 'In Progress' AND issuetype = Bug" }
```

| 파라미터 | 필수 | 설명 |
|---|---|---|
| `jql` | O | JQL 쿼리 문자열 |
| `maxResults` | | 최대 결과 수 (기본: 50) |
| `fields` | | 반환할 필드 목록 |
| `nextPageToken` | | 다음 페이지 토큰 |
| `expand` | | 추가 정보 (changelog, renderedFields 등) |

### get_issue

이슈 키 또는 ID로 상세 정보를 조회합니다.

```
"PROJ-123 이슈 내용 보여줘"
→ get_issue { issueIdOrKey: "PROJ-123" }
```

### create_issue

새 이슈를 생성합니다.

```
"PROJ 프로젝트에 로그인 버그 이슈 만들어줘"
→ create_issue { projectKey: "PROJ", issueType: "Bug", summary: "로그인 실패 버그" }
```

| 파라미터 | 필수 | 설명 |
|---|---|---|
| `projectKey` | O | 프로젝트 키 |
| `issueType` | O | 이슈 유형 (Task, Bug, Story, Epic) |
| `summary` | O | 이슈 제목 |
| `description` | | 이슈 설명 (텍스트 → ADF 자동 변환) |
| `assignee` | | 담당자 계정 ID |
| `labels` | | 라벨 목록 |
| `priority` | | 우선순위 (Highest, High, Medium, Low, Lowest) |
| `parentKey` | | 상위 이슈 키 (하위 작업 생성 시) |
| `customFields` | | 커스텀 필드 객체 |

### update_issue

이슈 필드를 수정합니다. `description`은 ADF(Atlassian Document Format) 객체입니다.

```
"PROJ-123 제목을 '수정된 제목'으로 바꿔줘"
→ update_issue { issueIdOrKey: "PROJ-123", summary: "수정된 제목" }
```

### get_transitions / transition_issue

이슈 상태를 전환합니다. 먼저 `get_transitions`로 가능한 전환을 확인한 후 `transition_issue`를 호출합니다.

```
"PROJ-123을 In Progress로 변경해줘"
→ get_transitions { issueIdOrKey: "PROJ-123" }
→ transition_issue { issueIdOrKey: "PROJ-123", transitionId: "21" }
```

### add_comment

이슈에 댓글을 추가합니다. 텍스트를 입력하면 ADF 형식으로 자동 변환됩니다.

```
"PROJ-123에 '확인 완료' 댓글 달아줘"
→ add_comment { issueIdOrKey: "PROJ-123", body: "확인 완료" }
```

### list_projects

접근 가능한 Jira 프로젝트 목록을 조회합니다.

```
"내 프로젝트 목록 보여줘"
→ list_projects {}
```

### get_myself

현재 인증된 사용자 정보를 조회합니다. 담당자 배정 시 `accountId` 확인에 유용합니다.

### confluence_create_page

Confluence에 새 페이지를 생성합니다. Confluence REST API v2를 사용합니다.

```
"TEAM 스페이스에 회의록 페이지 만들어줘"
→ confluence_create_page { spaceKey: "TEAM", title: "2026-03-10 회의록", bodyHtml: "<h2>안건</h2><p>...</p>" }
```

## 개발

```bash
# 의존성 설치
npm install

# 개발 모드 (tsx)
npm run dev

# 빌드
npm run build

# 빌드 후 실행
npm start
```

## 환경변수

| 변수 | 필수 | 설명 |
|---|---|---|
| `JIRA_INSTANCE_URL` | O | Jira 인스턴스 URL (예: `https://your-domain.atlassian.net`) |
| `JIRA_USER_EMAIL` | O | Atlassian 계정 이메일 |
| `JIRA_API_KEY` | O | Atlassian API 토큰 |

## 기술 스택

- **TypeScript** – 타입 안전한 코드
- **MCP SDK** (`@modelcontextprotocol/sdk`) – Model Context Protocol 구현
- **Jira REST API v3** – 이슈, 프로젝트, 전환 관리
- **Confluence REST API v2** – 페이지 생성
- **stdio 전송** – MCP 클라이언트와 표준 입출력 통신

## 라이선스

[MIT](LICENSE) © choing.dev