@droplinkperformance/bitbucket-mcp-server

Servidor de Model Context Protocol (MCP) para Bitbucket Cloud, agnóstico respecto al proveedor y centrado en la revisión con IA.

El valor principal de este servidor es la revisión de código asistida por IA y el análisis de pull requests, no las operaciones CRUD contra la API de Bitbucket. Cada dependencia importante (acceso SCM, caché, almacenamiento de tokens, limitación de tasa, LLM, eventos) está oculta tras una interfaz agnóstica respecto al proveedor, de modo que la misma lógica de negocio pueda apuntar más adelante a GitHub / GitLab / Azure DevOps y a OpenAI / Anthropic / Gemini / Bedrock sin cambios en los casos de uso, agentes o contratos de dominio.

Estado: Fase 1. Consulta la Hoja de ruta.

Características (Fase 1)

• Transportes duales: stdio (Cursor / Claude Desktop) y Streamable HTTP (Node http, para remoto/producción).

• Herramientas de descubrimiento automático mediante un ToolRegistry: no hay registro manual.

• BitbucketContext explícito (workspace + repository opcional) en cada herramienta: preparado para múltiples espacios de trabajo.

• BitbucketClient resiliente: inyección de autenticación, paginación automática, reintentos/backoff, gestión de límites de tasa, caché y enmascaramiento de secretos.

• Dos estrategias de autenticación: OAuth 2.0 (código de autorización, con persistencia rotatoria del token de refresco) y token Bearer.

• Revisión de código con IA (analyze_pull_request) respaldada por un CodeReviewAgent que divide los PR grandes en fragmentos y devuelve un ReviewResult estándar.

• Proveedor de LLM conectable (OpenAI / Anthropic / Gemini / Bedrock), caché (memoria / Redis) y almacén de tokens (archivo / memoria / Redis).

Herramientas

Todas las entradas de las herramientas aceptan workspace (opcional si se define BITBUCKET_DEFAULT_WORKSPACE) y, cuando corresponda, repository.

Related MCP server: Atlassian Bitbucket MCP Server

Arquitectura

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

Flujo: tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient. Los agentes también pueden usar LlmProvider y EventBus. Las herramientas nunca contienen lógica de negocio.

Requisitos

• Node.js 23+

Instalación

Publicado como @droplinkperformance/bitbucket-mcp-server.

npx -y @droplinkperformance/bitbucket-mcp-server

Desde el código fuente:

npm install
npm run build

Publicación

Las fusiones (merges) a main ejecutan .github/workflows/release.yml: pruebas, compilación y, después, semantic-release. El versionado y la publicación en npm solo ocurren cuando la fusión incluye Conventional Commits:

El resto de mensajes omiten la publicación. Se requiere el secreto de GitHub NPM_TOKEN (token de automatización de npm para la organización droplinkperformance).

Tras una publicación npm correcta, el mismo flujo de trabajo publica metadatos en el MCP Registry como io.github.droplinkperformance/bitbucket-mcp-server (OIDC, sin secreto adicional). github.com/mcp se sincroniza desde ese registro; si el servidor no aparece, escribe a partnerships@github.com.

Para permanecer en 0.x en la primera versión, etiqueta el commit actual (git tag v0.1.0 && git push origin v0.1.0) antes de la primera fusión convencional; de lo contrario, semantic-release comenzará en 1.0.0.

Configuración

Copia .env.example a .env y completa los valores. Cárgalo con la opción integrada de Node:

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

Variables clave:

Autenticación

Bearer (token de acceso OAuth): establece solo BITBUCKET_ACCESS_TOKEN (tokens que no son ATATT).

Token de API (recomendado, ATATT…): establece BITBUCKET_ACCESS_TOKEN y BITBUCKET_EMAIL (el correo de tu cuenta de Atlassian desde Bitbucket → Configuración personal → Alias de correo). Los tokens de API usan autenticación HTTP Basic, no Bearer.

Contraseña de aplicación (heredada, hasta junio de 2026): establece BITBUCKET_ACCESS_TOKEN y BITBUCKET_USERNAME (tu nombre de usuario de Bitbucket).

OAuth 2.0 (código de autorización): establece BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET. El TOKEN_STORE configurado persiste los tokens; Bitbucket rota los tokens de refresco y el servidor persiste el nuevo en cada renovación. Para un arranque sin interfaz (headless), proporciona un BITBUCKET_REFRESH_TOKEN obtenido previamente.

Los endpoints OAuth de Bitbucket utilizados son: autorización https://bitbucket.org/site/oauth2/authorize, token https://bitbucket.org/site/oauth2/access_token. La URL de autorización se puede construir con OAuthProvider.buildAuthorizeUrl() y el ?code= devuelto se intercambia mediante OAuthProvider.loginWithCode(code).

Proveedor de LLM

Establece LLM_PROVIDER y la clave correspondiente:

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 (proveedores Redis) y @aws-sdk/client-bedrock-runtime (Bedrock) son opcionales y se cargan de forma diferida (lazy): solo se necesitan cuando se seleccionan.

Ejecución

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 (o .cursor/mcp.json del proyecto):

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

Desarrollo

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

Hoja de ruta

• Fase 1 (esta versión): autenticación, abstracciones, BitbucketClient, descubrimiento automático de herramientas, herramientas de PR, analyze_pull_request.

• Fase 2: Pipelines + registros paginados de texto completo, agente pipeline-investigator, auto_review_pull_request (dry-run / publicar comentarios en línea).

• Fase 3: CRUD restante: repositorios, commits, ramas, etiquetas, incidencias, espacios de trabajo, miembros, búsqueda.

• Fase 4: analyze_dotnet_pull_request (agente dotnet-review), agentes avanzados, flujos de automatización.

• Fase 5: Docker, Compose, Helm, guía de despliegue en producción.

Licencia

MIT