Servidor MCP de Bitbucket

Un servidor del Model Context Protocol orientado a producción para recuperar metadatos de solicitudes de extracción y diferencias de Bitbucket Cloud y Bitbucket Server/Data Center, con comentarios de solicitudes de extracción opcionales.

Funciones

• Compatible con Bitbucket Cloud y Bitbucket Server/Data Center autoalojado.

• Expone herramientas específicas para metadatos de solicitudes de extracción, diferencias, discusión de revisiones y comentarios generales o en línea.

• Compatible con tokens de portador y autenticación básica.

• Devuelve diferencias sin procesar y datos estructurados de archivos modificados cuando Bitbucket los proporciona.

• Excluye archivos, carpetas o tipos de archivo generados mediante patrones globales configurables.

• Limita las diferencias grandes sin romper los caracteres UTF-8.

• Usa stdio sin escribir registros que rompan el protocolo en la salida estándar.

• Mantiene la creación de comentarios deshabilitada de forma predeterminada y no aprueba, combina ni modifica solicitudes de extracción de ninguna otra manera.

Related MCP server: Atlassian Bitbucket MCP Server

Inicio rápido

Requiere una versión LTS compatible de Node.js (Node.js 22 o posterior).

git clone https://github.com/inceon/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env

Establezca BITBUCKET_URL y BITBUCKET_TOKEN en la configuración de su cliente MCP y, a continuación, inicie el servidor compilado con node dist/index.js. El servidor no carga archivos .env por sí mismo a propósito; los clientes MCP deben pasar las variables de entorno directamente.

Autenticación

La autenticación de portador es la predeterminada y se recomienda para tokens de acceso personal de Bitbucket Server/Data Center:

BITBUCKET_URL=https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN=your-personal-access-token
BITBUCKET_AUTH_TYPE=bearer

Para tokens de API de Bitbucket Cloud o contraseñas de aplicación que requieran autenticación básica:

BITBUCKET_URL=https://api.bitbucket.org
BITBUCKET_TOKEN=your-api-token-or-app-password
BITBUCKET_AUTH_TYPE=basic
BITBUCKET_USERNAME=your-bitbucket-username

Conceda a la credencial únicamente los permisos necesarios para las herramientas que habilite. La creación de comentarios requiere permiso para crear comentarios en solicitudes de extracción. Nunca confirme credenciales ni incluya tokens reales en informes de incidencias.

Variables de entorno

El servidor escribe errores de inicio solo en el error estándar y redacta las credenciales configuradas de los fragmentos de error HTTP de Bitbucket.

Configuración de MCP

Configuración de Claude Desktop:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Configuración de config.toml de Codex:

[mcp_servers.bitbucket]
command = "node"
args = ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://api.bitbucket.org"
BITBUCKET_TOKEN = "your-token"

Herramientas disponibles

get_pull_request

Devuelve metadatos de la solicitud de extracción, incluidos su descripción, estado, autor, revisores, ramas, marcas de tiempo y enlaces.

{
  "name": "get_pull_request",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123
  }
}

get_pull_request_comments

Devuelve los debates generales y en línea existentes como objetos de comentario nativos del proveedor. Úselo antes de publicar un hallazgo de revisión para tener en cuenta los comentarios existentes. commentsStatus.complete es falso con el motivo max_comments o max_pages cuando se alcanzan los límites de recuperación configurados.

get_pull_request_commits

Devuelve las confirmaciones nativas del proveedor actualmente en la solicitud de extracción. Úselo para rastrear un hallazgo hasta su confirmación de origen o para verificar si un trabajo posterior lo aborda. commitsStatus.complete es falso con el motivo max_commits o max_pages cuando se alcanzan los límites de recuperación configurados.

get_pull_request_diff

Devuelve una diferencia de revisión de estilo git y archivos modificados estructurados cuando estén disponibles.

{
  "name": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJECT_KEY",
    "repository": "my-repository",
    "pull_request_id": 123,
    "ignore_patterns": ["dist/**", "**/*.generated.ts", "package-lock.json"],
    "path": "src/service.ts",
    "context": 5,
    "ignore_whitespace": true,
    "renames": true
  }
}

La salida de la diferencia está disponible tanto como texto JSON compatible con versiones anteriores como structuredContent de MCP, con un esquema de salida anunciado. Incluye:

• provider, pull_request_id, rawDiff, rawDiffBytes y rawDiffSource. rawDiffSource es provider_raw para Cloud o server_structured para una respuesta de Server/Data Center normalizada localmente.

• truncated más truncationReason: input_limit cuando se alcanzó el límite de lectura de Cloud ascendente, output_limit cuando el resultado filtrado superó BITBUCKET_MAX_DIFF_BYTES, o provider_limit cuando Server/Data Center marcó su diferencia estructurada como truncada.

• Las entradas opcionales de files contienen solo path, status normalizado y oldPath para cambios de nombre o copias. filesStatus obligatorio informa la integridad; complete es falso con el motivo max_files, max_pages o unsupported, y returned refleja las entradas filtradas realmente devueltas.

• Metadatos opcionales de ignored cuando las exclusiones están activas.

Resultado completo:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 128,
  "rawDiffSource": "provider_raw",
  "files": [],
  "filesStatus": { "available": true, "complete": true, "returned": 0 },
  "truncated": false
}

Resultado parcial acotado:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 200000,
  "rawDiffSource": "provider_raw",
  "files": [{ "path": "src/service.ts", "status": "modified" }],
  "filesStatus": {
    "available": true,
    "complete": false,
    "returned": 1,
    "reason": "max_pages"
  },
  "truncated": true,
  "truncationReason": "output_limit"
}

rawDiff truncado es un prefijo de revisión seguro para UTF-8, no necesariamente una línea, fragmento o parche aplicable completo.

Las páginas de archivos estructurados se siguen hasta que se completan o se alcanza un límite de archivos/páginas configurado, y luego se normalizan a metadatos de revisión compactos en lugar de devolver hashes, enlaces y estructuras de ruta duplicadas del proveedor. Un endpoint diffstat o changes no disponible se informa solo después de un HTTP 404. Los errores de autorización, límite de velocidad, servidor, respuesta malformada, tiempo de espera y transporte hacen fallar la llamada a la herramienta en lugar de omitir silenciosamente los metadatos.

rawDiff de Cloud conserva la respuesta sin procesar del proveedor. Server/Data Center usa la respuesta estructurada /diff y normaliza sus archivos, fragmentos, segmentos y líneas en texto de revisión de estilo git; esto evita errores específicos de versión de la ruta de exportación .diff separada. rawDiffSource hace explícita esa distinción.

path es compatible con ambos proveedores y es la forma preferida de revisar solicitudes de extracción grandes archivo por archivo; los metadatos de files devueltos se limitan a la misma ruta. renames es solo de Cloud. context se asigna a context de Cloud y contextLines de Server/Data Center. ignore_whitespace se asigna a ignore_whitespace de Cloud y whitespace=ignore-all de Server/Data Center. Cuando no están presentes, estos controles no alteran los valores predeterminados del proveedor.

Los patrones usan rutas relativas al repositorio y admiten *, ** y ?. Un patrón sin /, como package-lock.json o *.png, coincide con ese nombre de archivo en cualquier lugar. Una barra final excluye un directorio de forma recursiva. Cuando las exclusiones están activas, la respuesta incluye ignored.patterns, ignored.files e ignored.rawDiffFiltered. Un valor falso de rawDiffFiltered significa que un proveedor de Cloud devolvió un formato de diferencia que no es git y que no se pudo filtrar de forma segura; la respuesta se conserva en lugar de eliminar contenido silenciosamente.

add_pull_request_comment

Crea un comentario general, a nivel de archivo o en línea en una solicitud de extracción. Esta operación de escritura solo está disponible cuando BITBUCKET_ENABLE_WRITE_TOOLS=true está establecido en el entorno del servidor MCP.

Comentario general:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "The implementation looks good. Please add a regression test for the empty input case."
  }
}

Comentario en línea sobre una línea añadida:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "Please handle an empty value here.",
    "file_path": "src/service.ts",
    "line": 42,
    "line_type": "added"
  }
}

Use los valores de line_type added, removed o context. Las líneas añadidas se asignan de forma predeterminada al lado new, las líneas eliminadas al lado old y las líneas de contexto a new; establezca line_side explícitamente para colocar un comentario de contexto en old. Proporcione file_path sin campos de línea para un comentario a nivel de archivo. Para archivos renombrados en Server/Data Center, source_file_path puede identificar la ruta anterior.

El usuario autenticado de Bitbucket se convierte en el autor del comentario. Revise el espacio de trabajo, el repositorio, el ID de la solicitud de extracción y el texto del comentario de destino antes de aprobar la llamada a la herramienta en su cliente MCP.

Comportamiento del proveedor

El host de la URL determina el proveedor. bitbucket.org y api.bitbucket.org usan Bitbucket Cloud; todos los demás hosts usan Server/Data Center.

Las URL de Cloud se normalizan a un prefijo de API /2.0 y usan:

• /repositories/{workspace}/{repository}/pullrequests/{id}

• /repositories/{workspace}/{repository}/pullrequests/{id}/diff

• /repositories/{workspace}/{repository}/pullrequests/{id}/diffstat

• /repositories/{workspace}/{repository}/pullrequests/{id}/comments (GET; POST cuando está habilitado)

• /repositories/{workspace}/{repository}/pullrequests/{id}/commits (GET)

Las URL de Server/Data Center conservan una ruta de contexto como /bitbucket, se normalizan a un prefijo /rest/api/1.0 y usan:

• /projects/{project}/repos/{repository}/pull-requests/{id}

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff (diferencia estructurada normalizada a texto de revisión de estilo git)

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path} (diferencia estructurada con ámbito de ruta)

• /projects/{project}/repos/{repository}/pull-requests/{id}/changes

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; POST cuando está habilitado)

• /projects/{project}/repos/{repository}/pull-requests/{id}/commits (GET)

La solicitud opcional de diffstat o changes informa filesStatus.reason: "unsupported" después de un HTTP 404. Otros errores HTTP, de tiempo de espera, de transporte y de análisis hacen fallar la llamada a la herramienta para que los metadatos incompletos no se confundan con una respuesta completa.

MCP de Atlassian Rovo

Atlassian documenta una acción bitbucketPullRequest.diff solo para Cloud, pero no publica su esquema de argumentos, forma de salida, paginación, filtrado ni contrato de truncamiento. Por lo tanto, este servidor mantiene las APIs directas de Bitbucket como autoritativas. Un adaptador de Rovo solo debe añadirse tras validar un esquema tools/list en vivo y una respuesta de diff controlada; debe permanecer configurado explícitamente y no puede sustituir el soporte de Server/Data Center. Consulta la página de herramientas compatibles de Atlassian.

Hoja de ruta

Las áreas previstas para futuras versiones incluyen:

• Añadir manejo de reintentos y diagnósticos más claros de límite de tasa.

• Proporcionar salida normalizada de pull requests manteniendo el acceso a campos específicos del proveedor.

• Añadir herramientas de solo lectura para listar pull requests y recuperar el estado de compilación.

• Ofrecer un transporte HTTP Streamable opcional manteniendo stdio como predeterminado.

• Publicar lanzamientos versionados con rutas de instalación y actualización más sencillas.

Las operaciones de escritura permanecerán deshabilitadas por defecto. No se planean operaciones de aprobación, fusión u otras de alto impacto en Bitbucket. Las ideas y propuestas de implementación son bienvenidas a través de GitHub issues.

Desarrollo

npm run dev        # Run directly from TypeScript
npm run build      # Compile to dist/
npm test           # Run the test suite once
npm run test:watch # Run tests in watch mode
npm run check      # Build and test, matching CI

El registro de comandos mantiene cada herramienta MCP aislada en src/tools. Consulta CONTRIBUTING.md antes de abrir una pull request.

Seguridad

Este servidor maneja las credenciales en memoria y las envía únicamente al BITBUCKET_URL configurado. Revisa esa URL cuidadosamente antes de iniciar el servidor. Habilitar herramientas de escritura permite que los clientes MCP conectados publiquen comentarios en PR como el usuario autenticado de Bitbucket. Para informar de una vulnerabilidad de forma privada, sigue SECURITY.md.

Licencia

Publicado bajo la Licencia MIT.