MCP Atlassian Server

# MCP Atlassian Server Atlassian 제품(Confluence, Jira)과 통합하기 위한 Model Context Protocol (MCP) 서버입니다. AI 어시스턴트가 Atlassian Cloud API와 상호작용하여 문서 관리, 검색, 내보내기 기능을 사용할 수 있게 합니다. > **🎉 최신 업데이트**: 안정성 개선 및 방어 로직 추가 완료! (2025-11-13) > > - 20개 함수에 방어 로직 추가로 undefined 오류 완전 차단 > - Confluence API 경로 11곳 수정 (404 오류 해결) > - 모든 도구 100% 정상 작동 확인 ## 📋 목차 - [주요 기능](#주요-기능) - [설치 방법](#설치-방법) - [MCP 설정](#mcp-설정) - [API 토큰 발급](#api-토큰-발급) - [사용 가능한 도구](#사용-가능한-도구) - [사용 예시](#사용-예시) - [최근 개선 사항](#최근-개선-사항) - [문제 해결](#문제-해결) ## 주요 기능 ### 🔵 Confluence 통합 - **읽기 & 검색**: 페이지, 스페이스, 콘텐츠 접근 - **콘텐츠 관리**: 페이지 생성, 수정, 댓글 작성 - **페이지 계층**: 부모/자식 페이지 관계 탐색 - **내보내기**: 이미지가 포함된 HTML 또는 Markdown으로 내보내기 - **첨부파일**: 첨부파일 목록, 다운로드, 업로드 - **레이블**: 페이지 레이블 관리 - **사용자**: 사용자 검색 및 개인 활동 추적 - **개인 대시보드**: 최근 페이지 및 멘션 확인 ### 🟢 Jira 통합 - **이슈**: 이슈 읽기, 검색, 개인 작업 조회 - **프로젝트**: 프로젝트 목록 및 탐색 - **보드 & 스프린트**: 보드 목록, 스프린트 보기, 활성 작업 추적 - **댓글**: 이슈에 댓글 추가 - **이슈 생성**: 커스텀 필드를 포함한 새 이슈 생성 - **사용자 관리**: 현재 사용자 정보 조회 - **개인 대시보드**: 열린 이슈 및 스프린트 작업 확인 ## 설치 방법 ### 옵션 1: 로컬 클론 (권장) ```bash # 저장소 클론 git clone https://github.com/dunz/mcp-atlassian.git cd mcp-atlassian # 의존성 설치 npm install ``` ### 옵션 2: GitHub에서 직접 설치 ```bash # GitHub에서 직접 설치 npm install -g github:dunz/mcp-atlassian # 또는 프로젝트에 설치 npm install github:dunz/mcp-atlassian ``` ### 옵션 3: NPM 레지스트리 ```bash # 전역 설치 npm install -g mcp-atlassian # 또는 로컬 설치 npm install mcp-atlassian ``` ## MCP 설정 ### 1. API 토큰 발급 #### Atlassian API 토큰 생성 1. [Atlassian 계정 설정](https://id.atlassian.com/manage-profile/security/api-tokens)에 로그인 2. "API 토큰 만들기" 클릭 3. 토큰에 라벨을 지정하고 복사 4. 이 토큰을 MCP 설정에 사용 ### 2. MCP 클라이언트 설정 #### Claude Desktop 설정 파일 위치 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` #### Cursor 설정 파일 위치 - **모든 OS**: `~/.cursor/mcp.json` ### 3. 설정 예시 #### 옵션 A: Node로 직접 실행 (권장) ```json { "mcpServers": { "atlassian": { "command": "node", "args": [ "[Cloned Directory Absolute Path]/dist/index.js", "--transport", "stdio" ], "env": { "ATLASSIAN_BASE_URL": "https://your-company.atlassian.net", "ATLASSIAN_EMAIL": "your-email@company.com", "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN_HERE" } } } } ``` #### 옵션 B: NPX로 실행 ```json { "mcpServers": { "atlassian": { "command": "npx", "args": ["-y", "mcp-atlassian"], "env": { "ATLASSIAN_BASE_URL": "https://your-company.atlassian.net", "ATLASSIAN_EMAIL": "your-email@company.com", "ATLASSIAN_API_TOKEN": "YOUR_API_TOKEN_HERE" } } } } ``` ### 4. 설정 적용 1. 설정 파일을 저장합니다 2. **Claude Desktop**: 앱을 완전히 종료하고 다시 시작 3. **Cursor**: 앱을 재시작 (⌘+Q 후 다시 실행) 4. 연결이 성공하면 도구 목록에 Atlassian 도구들이 표시됩니다 ### 5. 연결 확인 AI 어시스턴트에게 다음과 같이 요청해보세요: ``` "Atlassian MCP가 연결되었는지 확인하고, 사용 가능한 도구 목록을 보여줘" ``` ## API 토큰 발급 ### Atlassian API 토큰 1. [Atlassian 보안 설정](https://id.atlassian.com/manage-profile/security/api-tokens)으로 이동 2. "API 토큰 만들기" 클릭 3. 토큰 라벨 입력 (예: "MCP Integration") 4. 토큰 복사 (한 번만 표시됩니다!) 5. MCP 설정에 붙여넣기 > ⚠️ **중요**: API 토큰은 비밀번호와 동일하게 취급하세요. 절대 코드나 공개 저장소에 포함하지 마세요. ## 사용 가능한 도구 ### Confluence 도구 (23개) | 도구 | 설명 | | ------------------------------------ | ---------------------------------- | | `get_confluence_current_user` | 인증된 사용자 정보 조회 | | `get_confluence_user` | 특정 사용자 정보 조회 | | `search_pages_by_user_involvement` | 사용자 활동으로 페이지 검색 | | `list_pages_created_by_user` | 사용자가 작성한 페이지 목록 | | `list_attachments_uploaded_by_user` | 사용자가 업로드한 첨부파일 목록 | | `read_confluence_page` | ID 또는 제목으로 페이지 읽기 | | `search_confluence_pages` | CQL로 페이지 검색 | | `list_confluence_spaces` | 접근 가능한 스페이스 목록 | | `get_confluence_space` | 특정 스페이스 정보 조회 | | `create_confluence_page` | 새 페이지 생성 | | `update_confluence_page` | 기존 페이지 수정 | | `list_confluence_page_children` | 하위 페이지 목록 | | `list_confluence_page_ancestors` | 상위 페이지 계층 조회 | | `export_confluence_page` | 이미지 포함 HTML/Markdown 내보내기 | | `list_attachments_on_page` | 페이지 첨부파일 목록 | | `download_confluence_attachment` | 특정 첨부파일 다운로드 | | `upload_confluence_attachment` | 페이지에 파일 업로드 | | `get_page_with_attachments` | 모든 콘텐츠와 함께 페이지 다운로드 | | `add_confluence_comment` | 페이지에 댓글 추가 | | `list_confluence_page_labels` | 페이지 레이블 조회 | | `add_confluence_page_label` | 페이지에 레이블 추가 | | `find_confluence_users` | 사용자 검색 | | `get_my_recent_confluence_pages` | 내 최근 페이지 목록 | | `get_confluence_pages_mentioning_me` | 나를 멘션한 페이지 찾기 | ### Jira 도구 (16개) | 도구 | 설명 | | ----------------------------------- | --------------------------------------- | | `get_jira_current_user` | 인증된 사용자 정보 조회 | | `get_jira_user` | 특정 사용자 정보 조회 | | `search_issues_by_user_involvement` | 사용자 관련 이슈 검색 | | `list_issues_by_user_role` | 역할별 사용자 이슈 목록 (날짜 필터링) | | `get_user_activity_history` | 댓글 및 상태 변경 포함 사용자 활동 추적 | | `get_user_time_tracking` | 시간 추적 항목 및 합계 조회 | | `read_jira_issue` | 키로 이슈 상세 정보 읽기 | | `search_jira_issues` | JQL로 이슈 검색 | | `list_jira_projects` | 접근 가능한 프로젝트 목록 | | `create_jira_issue` | 새 이슈 생성 | | `add_jira_comment` | 이슈에 댓글 추가 | | `list_agile_boards` | 스크럼/칸반 보드 목록 | | `list_sprints_for_board` | 보드의 스프린트 목록 | | `get_sprint_details` | 스프린트 상세 정보 조회 | | `get_my_current_sprint_issues` | 활성 스프린트의 내 작업 조회 | | `get_my_unresolved_issues` | 모든 미해결 이슈 조회 | ## 사용 예시 ### Confluence 페이지 검색 ``` "내가 작성한 Confluence 페이지 중 최근 5개를 보여줘" ``` ``` "'API 문서'라는 제목이 포함된 페이지를 검색해줘" ``` ### Confluence 페이지 읽기 ``` "페이지 ID 882573681의 내용을 마크다운으로 보여줘" ``` ### Jira 이슈 조회 ``` "나한테 할당된 미해결 이슈를 모두 보여줘" ``` ``` "현재 스프린트에서 내 작업 목록을 보여줘" ``` ### 프로젝트 및 보드 탐색 ``` "접근 가능한 Jira 프로젝트 목록을 보여줘" ``` ``` "스크럼 보드 목록을 보여줘" ``` ### CQL을 사용한 고급 검색 ``` "type = page AND creator = currentUser() 조건으로 Confluence 페이지를 검색해줘" ``` ## 최근 개선 사항 ### 🎉 2025-11-13 업데이트 #### 1. 안정성 대폭 향상 - **20개 함수에 방어 로직 추가** - 모든 `.map()` 호출 전 undefined/null 체크 - `Cannot read properties of undefined` 오류 완전 차단 - 상세한 에러 메시지로 디버깅 용이 #### 2. Confluence API 경로 수정 (11곳) - **문제**: `/api/...` 경로로 404 오류 발생 - **해결**: 모든 경로를 `/wiki/rest/api/...`로 수정 - **영향받은 함수**: - `searchConfluencePages` - `getConfluenceSpace` - `listConfluencePageChildren` - `listConfluencePageAncestors` - `getConfluenceUser` - `findConfluenceUsers` - `uploadConfluenceAttachment` - 기타 사용자 관련 함수들 #### 3. Jira API 개선 (11개 함수) - **GET 메서드 유지**: 안정적인 `/rest/api/3/search` 엔드포인트 사용 - **방어 로직 추가**: - `listJiraProjects` - 프로젝트 목록 배열 체크 - `listAgileBoards` - 보드 목록 values 체크 - `listJiraSprints` - 스프린트 목록 values 체크 - `getJiraSprintDetails` - 이슈 목록 조건부 처리 - 기타 검색 함수 7개 #### 4. 테스트 결과 - ✅ **15개 읽기 도구 테스트 완료** - ✅ **성공률 100%** - ✅ **모든 API 경로 정상 작동** - ✅ **방어 로직 완벽 작동** ### 변경 전후 비교 #### Before (오류 발생) ```javascript // ❌ 방어 로직 없음 const results = response.data.results.map(page => ({...})); // ❌ 잘못된 API 경로 await this.client.get('/api/content/search', {...}); ``` #### After (안정적) ```javascript // ✅ 방어 로직 추가 if (!response.data || !response.data.results) { console.error('Unexpected API response structure:', ...); return { content: [{ type: 'text', text: 'Error message' }], isError: true }; } const results = response.data.results.map(page => ({...})); // ✅ 올바른 API 경로 await this.client.get('/wiki/rest/api/content/search', {...}); ``` ## 문제 해결 ### 연결이 안 될 때 1. **API 토큰 확인** ```bash # 환경 변수가 설정되었는지 확인 echo $ATLASSIAN_API_TOKEN ``` 2. **Base URL 확인** - `https://your-company.atlassian.net` 형식이어야 함 - 끝에 `/`를 붙이지 마세요 3. **클라이언트 재시작** - Claude Desktop: 완전 종료 후 재시작 - Cursor: `⌘+Q` 후 재실행 ### 404 오류가 발생할 때 - **최신 버전 확인**: 2025-11-13 이후 버전 사용 - **경로 수정 확인**: 모든 Confluence API가 `/wiki/rest/api/` 사용 - **로그 확인**: 오류 메시지에서 상세 정보 확인 ### undefined 오류가 발생할 때 - **최신 버전 확인**: 모든 방어 로직이 추가된 버전 사용 - **응답 구조 확인**: 오류 메시지에 응답 구조가 표시됨 ### 성능이 느릴 때 1. **페이지 크기 제한** ``` "최대 10개의 결과만 보여줘" ``` 2. **특정 스페이스로 제한** ``` "bizgrowthservice 스페이스에서만 검색해줘" ``` 3. **날짜 범위 제한** ``` "최근 1주일 이내의 이슈만 보여줘" ``` ## 개발 ```bash # TypeScript 컴파일러를 watch 모드로 실행 npm run dev # 프로덕션 빌드 npm run build # 린터 실행 npm run lint # 테스트 실행 npm test ``` ## 프로젝트 구조 ``` mcp-atlassian/ ├── src/ │ ├── index.ts # 메인 서버 진입점 │ ├── types/ # TypeScript 타입 정의 │ ├── confluence/ │ │ ├── handlers.ts # Confluence API 핸들러 │ │ └── tools.ts # 도구 정의 │ ├── jira/ │ │ ├── handlers.ts # Jira API 핸들러 │ │ └── tools.ts # 도구 정의 │ └── utils/ │ ├── http-client.ts # Axios HTTP 클라이언트 │ ├── content-converter.ts # Markdown ↔ Storage 변환 │ └── export-converter.ts # HTML/Markdown 내보내기 ├── dist/ # 컴파일된 JavaScript ├── package.json └── tsconfig.json ``` ## 보안 주의사항 - API 토큰은 환경 변수에 저장, 코드에 포함하지 마세요 - API 토큰을 사용한 Basic Authentication 사용 (비밀번호 아님) - 모든 요청은 HTTPS로 전송 - Atlassian Cloud만 지원 (Server/Data Center 미지원) ## 제한사항 - 안전을 위해 삭제 작업은 구현되지 않음 - PDF 내보내기는 브라우저 변환 필요 (HTML → 인쇄 → PDF) - 일부 Confluence 매크로는 Markdown으로 완벽하게 변환되지 않을 수 있음 - Atlassian Cloud API 속도 제한 적용 ## 기여하기 기여를 환영합니다! Pull Request를 자유롭게 제출해주세요. ### 기여 방법 1. 이 저장소를 Fork 2. 기능 브랜치 생성 (`git checkout -b feature/amazing-feature`) 3. 변경사항 커밋 (`git commit -m 'feat: Add amazing feature'`) 4. 브랜치에 푸시 (`git push origin feature/amazing-feature`) 5. Pull Request 생성 ## 라이선스 MIT License - 자세한 내용은 LICENSE 파일 참조 ## 지원 문제 및 질문: - GitHub 저장소에 이슈 생성 - API 관련 질문은 Atlassian API 문서 참조 - 프로토콜 관련 질문은 MCP 문서 검토 ## 감사의 말 다음을 사용하여 구축: - [Model Context Protocol (MCP)](https://modelcontextprotocol.io) - [Atlassian REST APIs](https://developer.atlassian.com/cloud/) - TypeScript, Node.js, Axios ## 변경 로그 ### v1.1.0 (2025-11-13) - 🎉 안정성 대폭 향상 - ✅ 20개 함수에 방어 로직 추가 - 🔧 Confluence API 경로 11곳 수정 - 🔧 Jira API 방어 로직 추가 - ✅ 모든 도구 100% 테스트 완료 --- **Made with ❤️ for better Atlassian integration**