Bitbucket Server MCP

Bitbucket Server 풀 리퀘스트 관리를 위한 MCP(Model Context Protocol) 서버입니다. 이 서버는 MCP 프로토콜을 통해 Bitbucket Server API와 상호작용할 수 있는 도구와 리소스를 제공합니다.

✨ 새로운 기능

• 🔧 사용자 지정 HTTP 헤더: BITBUCKET_CUSTOM_HEADERS 환경 변수를 통해 모든 요청에 사용자 지정 헤더를 추가할 수 있습니다 (Zero Trust 토큰이나 프록시에 유용).

• 📋 PR 검색: list_pull_requests를 사용하여 상태, 작성자 또는 방향별로 풀 리퀘스트를 나열하고 필터링할 수 있습니다 (fixes #14).

• 🌿 브랜치 관리: list_branches로 기본 브랜치 감지를 포함한 브랜치 목록을 확인하고, delete_branch로 병합된 브랜치를 삭제할 수 있습니다.

• 📝 커밋 기록: list_commits를 사용하여 브랜치 및 작성자 필터링을 통해 커밋 기록을 탐색할 수 있습니다.

• ✅ PR 승인: approve_pull_request 및 unapprove_pull_request를 사용하여 풀 리퀘스트를 승인하거나 승인을 취소할 수 있습니다.

• 🔍 고급 검색: search 도구를 사용하여 프로젝트/저장소 필터링을 통해 저장소 전체에서 코드와 파일을 검색할 수 있습니다.

• 📄 파일 작업: get_file_content 및 browse_repository를 사용하여 파일 내용을 읽고 저장소 디렉토리를 탐색할 수 있습니다.

• 💬 댓글 관리: get_comments 도구로 PR 댓글을 추출하고 필터링할 수 있습니다.

• 🔍 프로젝트 검색: list_projects를 사용하여 접근 가능한 모든 Bitbucket 프로젝트를 나열할 수 있습니다.

• 📁 저장소 탐색: list_repositories를 사용하여 프로젝트 전반의 저장소를 탐색할 수 있습니다.

• 🔧 유연한 프로젝트 지원: 기본 프로젝트를 선택 사항으로 변경 - 명령별로 지정하거나 BITBUCKET_DEFAULT_PROJECT를 사용할 수 있습니다.

• 📖 향상된 문서: 사용 예시와 더 나은 구성 가이드가 포함된 개선된 README.

Related MCP server: Bitbucket MCP Server

요구 사항

• Node.js >= 16

설치

Smithery를 통한 설치

Smithery를 통해 Claude Desktop용 Bitbucket Server를 자동으로 설치하려면:

npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude

수동 설치

npm install

빌드

npm run build

기능

이 서버는 포괄적인 Bitbucket Server 통합을 위해 다음과 같은 도구를 제공합니다:

list_projects

Bitbucket 프로젝트 검색 및 탐색: 접근 가능한 모든 프로젝트를 세부 정보와 함께 나열합니다. 프로젝트 검색 및 다른 작업에 사용할 올바른 프로젝트 키를 찾는 데 필수적입니다.

사용 사례:

• 정확한 프로젝트 키를 모를 때 사용 가능한 프로젝트 찾기

• 프로젝트 구조 및 권한 탐색

• 접근 권한이 있는 새로운 프로젝트 발견

매개변수:

• limit: 반환할 프로젝트 수 (기본값: 25, 최대: 1000)

• start: 페이지네이션을 위한 시작 인덱스 (기본값: 0)

list_repositories

저장소 탐색 및 검색: 특정 프로젝트 내 또는 접근 가능한 모든 프로젝트의 저장소를 탐색합니다. 복제 URL 및 메타데이터를 포함한 포괄적인 저장소 정보를 반환합니다.

사용 사례:

• 다른 작업을 위한 저장소 슬러그 찾기

• 프로젝트 전반의 코드베이스 구조 탐색

• 접근 권한이 있는 저장소 발견

• 특정 프로젝트의 저장소 탐색

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• limit: 반환할 저장소 수 (기본값: 25, 최대: 1000)

• start: 페이지네이션을 위한 시작 인덱스 (기본값: 0)

create_pull_request

검토를 위한 코드 변경 제안: 코드 변경 사항을 제출하거나, 검토를 요청하거나, 기능 브랜치를 병합하기 위한 새로운 풀 리퀘스트를 생성합니다. 브랜치 참조 및 검토자 할당을 자동으로 처리합니다.

사용 사례:

• 검토를 위해 기능 개발 제출

• 버그 수정 제안

• 기능 브랜치에서 코드 통합 요청

• 코드 변경 사항에 대한 협업

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• title (필수): 명확하고 설명적인 PR 제목

• description: 맥락을 포함한 상세 설명 (Markdown 지원)

• sourceBranch (필수): 변경 사항이 포함된 소스 브랜치

• targetBranch (필수): 병합할 대상 브랜치

• reviewers: 검토자 사용자 이름 배열

• sourceProject: 소스 저장소의 프로젝트 키 (포크에서 교차 저장소 PR용)

• sourceRepository: 소스 저장소의 슬러그 (포크에서 교차 저장소 PR용)

• includeDefaultReviewers: 대상 브랜치에 구성된 기본 검토자를 자동으로 가져와 포함 (기본값: true)

update_pull_request

안전하게 풀 리퀘스트 업데이트: 메타데이터 손실 없이 기존 풀 리퀘스트의 제목, 설명 또는 검토자를 수정합니다. 명시적으로 변경되지 않은 모든 필드를 보존하기 위해 읽기-수정-쓰기 패턴을 사용합니다.

사용 사례:

• 생성 후 PR 제목이나 설명 수정

• 기존 검토자를 잃지 않고 검토자 추가 또는 교체

• 승인 상태에 영향을 주지 않고 PR 메타데이터 업데이트

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 업데이트할 풀 리퀘스트 ID

• title: 새 제목 (생략 시 현재 제목 유지)

• description: 새 설명 (생략 시 현재 설명 유지)

• reviewers: 사용자 이름 배열로 된 새 검토자 목록 (생략 시 현재 검토자 유지)

get_pull_request

포괄적인 PR 정보: 상태, 검토자, 커밋 및 모든 메타데이터를 포함한 상세한 풀 리퀘스트 정보를 검색합니다. 작업을 수행하기 전에 PR 상태를 파악하는 데 필수적입니다.

사용 사례:

• PR 승인 상태 확인

• PR 세부 정보 및 진행 상황 검토

• 병합 전 변경 사항 파악

• PR 상태 모니터링

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

merge_pull_request

승인된 변경 사항 통합: 승인된 풀 리퀘스트를 대상 브랜치에 병합합니다. 워크플로우 선호도에 따라 다양한 병합 전략을 지원합니다.

사용 사례:

• 코드 검토 프로세스 완료

• 승인된 기능 통합

• 메인 브랜치에 버그 수정 적용

• 코드 변경 사항 릴리스

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

• message: 사용자 지정 병합 커밋 메시지

• strategy: 병합 전략:

  • merge-commit (기본값): 기록을 보존하는 병합 커밋 생성

  • squash: 모든 커밋을 하나로 결합

  • fast-forward: 병합 커밋 없이 브랜치 포인터 이동

decline_pull_request

부적절한 변경 사항 거부: 병합해서는 안 되는 풀 리퀘스트를 거부하고 작성자에게 피드백을 제공합니다.

사용 사례:

• 기준을 충족하지 않는 변경 사항 거부

• 프로젝트 방향과 충돌하는 PR 닫기

• 상당한 재작업 요청

• 원치 않는 코드 통합 방지

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

• message: 거부 사유 (작성자 피드백에 유용)

add_comment

코드 검토 참여: 검토 피드백, 토론 및 협업을 위해 풀 리퀘스트에 댓글을 추가합니다. 스레드 대화를 지원합니다.

사용 사례:

• 코드 검토 피드백 제공

• 특정 변경 사항에 대한 질문

• 개선 사항 제안

• 기술 토론 참여

• 검토 결정 문서화

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

• text (필수): 댓글 내용 (Markdown 지원)

• parentId: 스레드 답글을 위한 상위 댓글 ID

• state: 댓글 상태: OPEN (기본값, 즉시 게시) 또는 PENDING (초안, 검토가 게시될 때까지 본인에게만 보임)

get_diff

코드 변경 사항 분석: 풀 리퀘스트에서 정확히 무엇이 추가, 제거 또는 수정되었는지 보여주는 코드 차이를 검색합니다. 대규모 diff를 효과적으로 관리하기 위해 파일별 잘림을 지원합니다.

사용 사례:

• 특정 코드 변경 사항 검토

• 수정 범위 파악

• 병합 전 영향 분석

• 구현 세부 정보 검사

• 코드 품질 평가

• 압도적인 출력 없이 대용량 파일 처리

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

• contextLines: 변경 사항 주변의 컨텍스트 라인 (기본값: 10)

• maxLinesPerFile: 파일당 표시할 최대 라인 수 (선택 사항, 지정되지 않으면 BITBUCKET_DIFF_MAX_LINES_PER_FILE 환경 변수 사용, 제한 없음을 위해 0으로 설정)

대용량 파일 처리: 파일이 maxLinesPerFile 제한을 초과하면 다음이 표시됩니다:

• 파일 헤더 및 메타데이터 (항상 보존)

• 시작 부분에서 허용된 라인의 첫 60%

• 파일 통계가 포함된 잘림 메시지

• 끝 부분에서 허용된 라인의 마지막 40%

• 전체 diff를 보는 방법에 대한 명확한 표시

get_reviews

검토 진행 상황 추적: 검토 상태를 파악하기 위해 검토 기록, 승인 상태 및 검토자 피드백을 가져옵니다.

사용 사례:

• PR이 병합 준비가 되었는지 확인

• 누가 변경 사항을 검토했는지 확인

• 검토 피드백 파악

• 승인 요구 사항 모니터링

• 검토 진행 상황 추적

get_activities

풀 리퀘스트 활동 검색: 댓글, 검토, 커밋 및 기타 이벤트를 포함한 풀 리퀘스트의 전체 활동 타임라인을 가져옵니다.

사용 사례:

• 댓글 토론 및 피드백 읽기

• 전체 PR 타임라인 검토

• PR에서 추가/제거된 커밋 추적

• 승인 및 검토 기록 확인

• 전체 PR 수명 주기 파악

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

get_comments

PR 댓글만 추출: 풀 리퀘스트 활동을 필터링하여 댓글만 반환하므로 검토나 다른 활동 없이 토론 내용에 집중하기 쉽습니다.

사용 사례:

• PR 토론 스레드 읽기

• 피드백 및 질문 추출

• 노이즈 없이 댓글 내용에 집중

• 대화 흐름 분석

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소 슬러그

• prId (필수): 풀 리퀘스트 ID

search

고급 코드 및 파일 검색: 프로젝트/저장소 필터링 및 쿼리 최적화를 지원하는 Bitbucket 검색 API를 사용하여 저장소 전체를 검색합니다. 파일 내용과 파일 이름을 모두 검색합니다. 참고: 검색은 저장소의 기본 브랜치에서만 작동합니다.

사용 사례:

• 프로젝트 전반에서 특정 코드 패턴 찾기

• 이름이나 내용으로 파일 찾기

• 특정 프로젝트나 저장소 내에서 검색

• 파일 확장자로 필터링

매개변수:

• query (필수): 검색 쿼리 문자열

• project: 검색 범위를 제한할 Bitbucket 프로젝트 키

• repository: 저장소별 검색을 위한 저장소 슬러그

• type: 쿼리 최적화 - "file" (정확한 파일 이름 일치를 위해 쿼리를 따옴표로 묶음) 또는 "code" (기본 검색 동작)

• limit: 반환할 결과 수 (기본값: 25, 최대: 100)

• start: 페이지네이션을 위한 시작 인덱스 (기본값: 0)

쿼리 구문 예시:

• "README.md" - 정확한 파일 이름 찾기

• config ext:yml - YAML 파일에서 설정 찾기

• function project:MYPROJECT - 특정 프로젝트에서 "function" 검색

• bug fix repo:PROJ/my-repo - 특정 저장소에서 검색

get_file_content

페이지네이션을 사용하여 파일 내용 읽기: 페이지네이션을 통해 대용량 파일을 지원하며 저장소에서 특정 파일의 내용을 검색합니다.

사용 사례:

• 소스 코드 파일 읽기

• 설정 파일 보기

• 문서 내용 추출

• 특정 파일 버전 검사

매개변수:

• project: Bitbucket 프로젝트 키 (선택 사항, 제공되지 않으면 BITBUCKET_DEFAULT_PROJECT 사용)

• repository (필수): 저장소