@droplinkperformance/bitbucket-mcp-server

프로바이더에 종속되지 않고 AI 리뷰를 우선시하는 Bitbucket Cloud용 Model Context Protocol(MCP) 서버입니다.

이 서버의 핵심 가치는 Bitbucket API에 대한 CRUD가 아니라 AI 기반 코드 리뷰 및 PR 분석입니다. 모든 주요 의존성(SCM 접근, 캐시, 토큰 저장, 속도 제한, LLM, 이벤트)은 프로바이더 중립적 인터페이스 뒤에 숨겨져 있어, 동일한 비즈니스 로직이 유스 케이스, 에이전트, 도메인 계약을 변경하지 않고도 GitHub / GitLab / Azure DevOps 및 OpenAI / Anthropic / Gemini / Bedrock을 대상으로 할 수 있습니다.

상태: Phase 1. 로드맵을 참조하세요.

기능 (Phase 1)

• 이중 전송: stdio(Cursor / Claude Desktop) 및 Streamable HTTP(Node http, 원격/프로덕션용).

• ToolRegistry를 통한 자동 도구 검색 — 수동 등록 불필요.

• 모든 도구에 명시적인 BitbucketContext(workspace + 선택적 repository) — 멀티 워크스페이스 지원.

• 복원력 있는 BitbucketClient: 인증 주입, 자동 페이지네이션, 재시도/백오프, 속도 제한 처리, 캐싱, 비밀 값 마스킹.

• 두 가지 인증 전략: OAuth 2.0(Authorization Code, 순환 refresh token 영구 저장) 및 Bearer 토큰.

• 큰 PR을 청크로 나누고 표준 ReviewResult를 반환하는 CodeReviewAgent 기반 AI 코드 리뷰(analyze_pull_request).

• 플러그형 LLM 프로바이더(OpenAI / Anthropic / Gemini / Bedrock), 캐시(memory / Redis), 토큰 저장소(file / memory / Redis).

도구

모든 도구 입력은 workspace(BITBUCKET_DEFAULT_WORKSPACE가 설정된 경우 선택 사항)와, 해당되는 경우 repository를 받습니다.

Related MCP server: Atlassian Bitbucket MCP Server

아키텍처

src/
  index.ts            entry: chooses transport
  container.ts        composition root (the only place wiring concretes)
  mcp/                McpServer + ToolRegistry (auto-discovery) + transports
  tools/              thin MCP adapters (*.tool.ts) -> call exactly one use-case
  application/        use-cases (CQRS-ish: command|query) with Input/Output DTOs
  agents/             autonomous workflows implementing Agent<TInput,TOutput>
  domain/             provider-agnostic types, repository contracts, ReviewResult
  repositories/bitbucket/  Bitbucket implementations of the contracts
  clients/bitbucket/  resilient REST client
  auth/               AuthProvider (+ token/oauth) and TokenStore implementations
  cache/              CacheProvider (+ memory/redis)
  ratelimit/          RateLimitStrategy (+ bitbucket)
  llm/                LlmProvider (+ openai/anthropic/gemini/bedrock)
  events/             EventBus (+ in-memory)
  services/           reusable services (masking, chunking)
  telemetry/          OpenTelemetry bootstrap + metrics
  infrastructure/     config, logger, http, attachments
  shared/             errors, result envelope, http-status, BitbucketContext

흐름: tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient. 에이전트는 LlmProvider와 EventBus를 사용할 수도 있습니다. 도구에는 비즈니스 로직이 포함되지 않습니다.

요구 사항

• Node.js 23+

설치

@droplinkperformance/bitbucket-mcp-server로 게시됩니다.

npx -y @droplinkperformance/bitbucket-mcp-server

소스에서 설치:

npm install
npm run build

릴리스

main으로의 병합은 .github/workflows/release.yml을 실행합니다: 테스트, 빌드, 그다음 semantic-release. 병합에 Conventional Commits이 포함된 경우에만 버전 지정 및 npm 게시가 이루어집니다.

다른 메시지의 경우 게시가 생략됩니다. GitHub 시크릿 NPM_TOKEN(droplinkperformance 조직용 npm Automation 토큰)이 필요합니다.

npm 릴리스가 성공하면 동일한 워크플로가 메타데이터를 MCP Registry에 io.github.droplinkperformance/bitbucket-mcp-server로 게시합니다(OIDC, 추가 시크릿 불필요). github.com/mcp는 해당 레지스트리에서 동기화합니다. 서버가 나타나지 않으면 partnerships@github.com로 이메일을 보내세요.

첫 릴리스에서 0.x 버전을 유지하려면 첫 conventional 병합 전에 현재 커밋에 태그를 지정하세요(git tag v0.1.0 && git push origin v0.1.0). 그렇지 않으면 semantic-release는 1.0.0부터 시작합니다.

구성

.env.example을 .env로 복사하고 값을 입력하세요. Node.js 내장 플래그로 로드합니다:

node --env-file=.env dist/index.js

주요 변수:

인증

Bearer(OAuth 액세스 토큰): BITBUCKET_ACCESS_TOKEN만 설정하세요(ATATT가 아닌 토큰).

API 토큰(권장, ATATT…): BITBUCKET_ACCESS_TOKEN 및 BITBUCKET_EMAIL을 설정하세요(Bitbucket → Personal settings → Email aliases에서 확인할 수 있는 사용자의 Atlassian 계정 이메일). API 토큰은 Bearer가 아닌 HTTP Basic 인증을 사용합니다.

앱 비밀번호(레거시, 2026년 6월까지): BITBUCKET_ACCESS_TOKEN과 BITBUCKET_USERNAME(사용자의 Bitbucket 사용자 이름)을 설정하세요.

OAuth 2.0(Authorization Code): BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET을 설정하세요. 토큰은 구성된 TOKEN_STORE에 영구 저장됩니다. Bitbucket은 refresh token을 순환시키며, 서버는 모든 갱신 시 새 토큰을 영구 저장합니다. 헤드리스 부팅을 위해서는 이전에 발급된 BITBUCKET_REFRESH_TOKEN을 제공하세요.

사용되는 Bitbucket OAuth 엔드포인트: authorize https://bitbucket.org/site/oauth2/authorize, token https://bitbucket.org/site/oauth2/access_token. authorize URL은 OAuthProvider.buildAuthorizeUrl()로 생성할 수 있고, 반환된 ?code=는 OAuthProvider.loginWithCode(code)를 통해 교환됩니다.

LLM 프로바이더

LLM_PROVIDER와 해당 키를 설정하세요:

LLM_PROVIDER=openai      # OPENAI_API_KEY
LLM_PROVIDER=anthropic   # ANTHROPIC_API_KEY
LLM_PROVIDER=gemini      # GEMINI_API_KEY
LLM_PROVIDER=bedrock     # AWS creds + BEDROCK_MODEL_ID (needs @aws-sdk/client-bedrock-runtime)

ioredis(Redis 프로바이더)와 @aws-sdk/client-bedrock-runtime(Bedrock)은 선택 사항이며 지연 로드됩니다 — 선택한 경우에만 필요합니다.

실행

stdio

MCP_TRANSPORT=stdio node --env-file=.env dist/index.js

Streamable HTTP

MCP_TRANSPORT=http HTTP_PORT=3000 node --env-file=.env dist/index.js
# health:   GET  http://localhost:3000/health
# endpoint: POST http://localhost:3000/mcp

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Cursor

~/.cursor/mcp.json(또는 프로젝트의 .cursor/mcp.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BITBUCKET_ACCESS_TOKEN": "ATATT-your-api-token",
        "BITBUCKET_EMAIL": "you@company.com",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_ACCESS_TOKEN": "your-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

개발

npm run dev          # tsx watch (stdio)
npm run typecheck
npm run lint
npm test
npm run test:coverage

로드맵

• Phase 1 (이번 릴리스): 인증, 추상화, BitbucketClient, 도구 자동 검색, PR 도구, analyze_pull_request.

• Phase 2: Pipelines 및 전체 텍스트 페이지네이션 로그, pipeline-investigator 에이전트, auto_review_pull_request(드라이런/인라인 댓글 게시).

• Phase 3: 나머지 CRUD — 리포지토리, 커밋, 브랜치, 태그, 이슈, 워크스페이스, 멤버, 검색.

• Phase 4: analyze_dotnet_pull_request(dotnet-review 에이전트), 고급 에이전트, 자동화 워크플로.

• Phase 5: Docker, Compose, Helm, 프로덕션 배포 가이드.

라이선스

MIT