@droplinkperformance/bitbucket-mcp-server

Providerunabhängiger, KI-Review-first Model Context Protocol (MCP)-Server für Bitbucket Cloud.

Der primäre Wert dieses Servers liegt in der KI-gestützten Code-Review- und Pull-Request-Analyse, nicht in CRUD-Operationen gegen die Bitbucket-API. Jede wesentliche Abhängigkeit (SCM-Zugriff, Cache, Token-Speicherung, Rate Limiting, LLM, Events) ist hinter einer providerunabhängigen Schnittstelle verborgen, sodass dieselbe Geschäftslogik später GitHub / GitLab / Azure DevOps und OpenAI / Anthropic / Gemini / Bedrock ansprechen kann, ohne Änderungen an Use-Cases, Agents oder Domain-Verträgen.

Status: Phase 1. Siehe Roadmap.

Funktionen (Phase 1)

• Duale Transporte: stdio (Cursor / Claude Desktop) und Streamable HTTP (Node http, für Remote-/Produktionsumgebungen).

• Automatisch erkannte Tools über eine ToolRegistry – keine manuelle Registrierung.

• Expliziter BitbucketContext (workspace + optional repository) für jedes Tool – Multi-Workspace-fähig.

• Robuster BitbucketClient: Auth-Injektion, automatische Paginierung, Retry/Backoff, Rate-Limit-Handling, Caching, Secret-Masking.

• Zwei Auth-Strategien: OAuth 2.0 (Authorization Code, mit rotierender Refresh-Token-Persistenz) und Bearer-Token.

• KI-Code-Review (analyze_pull_request), unterstützt von einem CodeReviewAgent, der große PRs in Blöcke zerlegt und ein standardisiertes ReviewResult zurückgibt.

• Steckbare LLM-Provider (OpenAI / Anthropic / Gemini / Bedrock), Cache (memory / Redis) und Token-Speicher (file / memory / Redis).

Tools

Alle Tool-Eingaben akzeptieren workspace (optional, wenn BITBUCKET_DEFAULT_WORKSPACE gesetzt ist) und, wo zutreffend, repository.

Related MCP server: Atlassian Bitbucket MCP Server

Architektur

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

Ablauf: tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient. Agents können auch den LlmProvider und den EventBus verwenden. Tools enthalten niemals Geschäftslogik.

Voraussetzungen

• Node.js 23+

Installation

Veröffentlicht als @droplinkperformance/bitbucket-mcp-server.

npx -y @droplinkperformance/bitbucket-mcp-server

Aus dem Quellcode:

npm install
npm run build

Release

Bei Merges in main wird .github/workflows/release.yml ausgeführt: Tests, Build, dann semantic-release. Versionierung und npm-Publish erfolgen nur, wenn der Merge Conventional Commits enthält:

Andere Nachrichten überspringen das Publish. Das GitHub-Secret NPM_TOKEN (npm-Automation-Token für die Organisation droplinkperformance) ist erforderlich.

Nach einem erfolgreichen npm-Release veröffentlicht derselbe Workflow Metadaten im MCP Registry als io.github.droplinkperformance/bitbucket-mcp-server (OIDC, kein zusätzliches Secret). github.com/mcp wird aus diesem Registry synchronisiert; wenn der Server nicht erscheint, senden Sie eine E-Mail an partnerships@github.com.

Um für das erste Release bei 0.x zu bleiben, taggen Sie den aktuellen Commit (git tag v0.1.0 && git push origin v0.1.0) vor dem ersten konventionellen Merge; andernfalls beginnt semantic-release bei 1.0.0.

Konfiguration

Kopieren Sie .env.example nach .env und füllen Sie die Werte aus. Laden Sie es mit dem eingebauten Node-Flag:

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

Wichtige Variablen:

Authentifizierung

Bearer (OAuth-Zugriffstoken): setzen Sie nur BITBUCKET_ACCESS_TOKEN (nicht-ATATT-Tokens).

API-Token (empfohlen, ATATT…): setzen Sie BITBUCKET_ACCESS_TOKEN und BITBUCKET_EMAIL (Ihre Atlassian-Konto-E-Mail aus Bitbucket → Persönliche Einstellungen → E-Mail-Aliase). API-Tokens verwenden HTTP-Basic-Auth, nicht Bearer.

App-Passwort (Legacy, bis Juni 2026): setzen Sie BITBUCKET_ACCESS_TOKEN und BITBUCKET_USERNAME (Ihren Bitbucket-Benutzernamen).

OAuth 2.0 (Authorization Code): setzen Sie BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET. Tokens werden vom konfigurierten TOKEN_STORE persistiert; Bitbucket rotiert Refresh-Tokens, und der Server persistiert das neue Token bei jedem Refresh. Für den Headless-Start geben Sie ein zuvor erhaltenes BITBUCKET_REFRESH_TOKEN an.

Verwendete Bitbucket-OAuth-Endpunkte: authorize https://bitbucket.org/site/oauth2/authorize, token https://bitbucket.org/site/oauth2/access_token. Die Authorize-URL kann aus OAuthProvider.buildAuthorizeUrl() erstellt und das zurückgegebene ?code= über OAuthProvider.loginWithCode(code) eingetauscht werden.

LLM-Provider

Setzen Sie LLM_PROVIDER und den passenden Schlüssel:

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-Provider) und @aws-sdk/client-bedrock-runtime (Bedrock) sind optional und werden lazy geladen – nur erforderlich, wenn ausgewählt.

Ausführen

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 (oder .cursor/mcp.json im Projekt):

{
  "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-..."
      }
    }
  }
}

Entwicklung

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

Roadmap

• Phase 1 (dieses Release): Auth, Abstraktionen, BitbucketClient, automatische Tool-Erkennung, PR-Tools, analyze_pull_request.

• Phase 2: Pipelines + Volltext-Logs mit Paginierung, pipeline-investigator-Agent, auto_review_pull_request (Dry-Run / Inline-Kommentare veröffentlichen).

• Phase 3: Restliches CRUD – Repositories, Commits, Branches, Tags, Issues, Workspaces, Mitglieder, Suche.

• Phase 4: analyze_dotnet_pull_request (dotnet-review-Agent), erweiterte Agents, Automatisierungs-Workflows.

• Phase 5: Docker, Compose, Helm, Leitfaden für Produktions-Deployments.

Lizenz

MIT