Bitbucket Server MCP

Gerencie pull requests no Bitbucket Server.

GitHub
69
Experimente este MCPPatrocinado

Documentação

Bitbucket Server MCP

Servidor MCP (Model Context Protocol) para gerenciamento de Pull Requests do Bitbucket Server. Este servidor fornece ferramentas e recursos para interagir com a API do Bitbucket Server através do protocolo MCP.

smithery badge Bitbucket Server MCP server

✨ Novos Recursos

  • 🔧 Cabeçalhos HTTP Personalizados: Adicione cabeçalhos personalizados a todas as requisições via variável de ambiente BITBUCKET_CUSTOM_HEADERS (útil para tokens Zero Trust ou proxies)
  • 📋 Descoberta de PR: Liste e filtre pull requests por estado, autor ou direção usando list_pull_requests (corrige #14)
  • 🌿 Gerenciamento de Branches: Liste branches com detecção de branch padrão usando list_branches, exclua branches mescladas com delete_branch
  • 📝 Histórico de Commits: Navegue pelo histórico de commits com filtro por branch e autor usando list_commits
  • ✅ Aprovação de PR: Aprove e desaprove pull requests com approve_pull_request e unapprove_pull_request
  • 🔍 Busca Avançada: Pesquise código e arquivos em repositórios com filtro por projeto/repositório usando a ferramenta search
  • 📄 Operações de Arquivo: Leia conteúdos de arquivos e navegue por diretórios de repositórios com get_file_content e browse_repository
  • 💬 Gerenciamento de Comentários: Extraia e filtre comentários de PR com a ferramenta get_comments
  • 🔍 Descoberta de Projetos: Liste todos os projetos Bitbucket acessíveis com list_projects
  • 📁 Navegação de Repositórios: Explore repositórios entre projetos com list_repositories
  • 🔧 Suporte Flexível a Projetos: Torne o projeto padrão opcional - especifique por comando ou use BITBUCKET_DEFAULT_PROJECT
  • 📖 Documentação Aprimorada: README melhorado com exemplos de uso e melhores orientações de configuração

Requisitos

  • Node.js >= 16

Instalação

Instalando via Smithery

Para instalar o Bitbucket Server para Claude Desktop automaticamente via Smithery:

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

Instalação Manual

npm install

Build

npm run build

Recursos

O servidor fornece as seguintes ferramentas para integração abrangente com o Bitbucket Server:

list_projects

Descubra e explore projetos Bitbucket: Lista todos os projetos acessíveis com seus detalhes. Essencial para descoberta de projetos e para encontrar as chaves de projeto corretas para usar em outras operações.

Casos de uso:

  • Encontre projetos disponíveis quando você não sabe a chave exata do projeto
  • Explore a estrutura e as permissões do projeto
  • Descubra novos projetos aos quais você tem acesso

Parâmetros:

  • limit: Número de projetos a retornar (padrão: 25, máximo: 1000)
  • start: Índice inicial para paginação (padrão: 0)

list_repositories

Navegue e descubra repositórios: Explore repositórios em projetos específicos ou em todos os projetos acessíveis. Retorna informações abrangentes do repositório, incluindo URLs de clone e metadados.

Casos de uso:

  • Encontre slugs de repositório para outras operações
  • Explore a estrutura do código-fonte entre projetos
  • Descubra repositórios aos quais você tem acesso
  • Navegue pelos repositórios de um projeto específico

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • limit: Número de repositórios a retornar (padrão: 25, máximo: 1000)
  • start: Índice inicial para paginação (padrão: 0)

create_pull_request

Proponha alterações de código para revisão: Cria um novo pull request para enviar alterações de código, solicitar revisões ou mesclar branches de funcionalidades. Gerencia automaticamente referências de branch e atribuições de revisores.

Casos de uso:

  • Envie desenvolvimento de funcionalidades para revisão
  • Proponha correções de bugs
  • Solicite integração de código de branches de funcionalidades
  • Colabore em alterações de código

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • title (obrigatório): Título claro e descritivo do PR
  • description: Descrição detalhada com contexto (suporta Markdown)
  • sourceBranch (obrigatório): Branch de origem contendo as alterações
  • targetBranch (obrigatório): Branch de destino para mesclagem
  • reviewers: Array de nomes de usuário dos revisores
  • sourceProject: Chave do projeto do repositório de origem (para PRs entre repositórios a partir de forks)
  • sourceRepository: Slug do repositório de origem (para PRs entre repositórios a partir de forks)
  • includeDefaultReviewers: Buscar e incluir automaticamente os revisores padrão configurados para a branch de destino (padrão: true)

update_pull_request

Atualize um pull request com segurança: Modifique o título, a descrição ou os revisores de um pull request existente sem perder metadados. Usa um padrão de leitura-modificação-escrita para preservar todos os campos não alterados explicitamente.

Casos de uso:

  • Corrija o título ou a descrição do PR após a criação
  • Adicione ou substitua revisores sem perder os existentes
  • Atualize os metadados do PR sem afetar o status de aprovação

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request a atualizar
  • title: Novo título (se omitido, o título atual é preservado)
  • description: Nova descrição (se omitida, a descrição atual é preservada)
  • reviewers: Nova lista de revisores como array de nomes de usuário (se omitida, os revisores atuais são preservados)

get_pull_request

Informações abrangentes do PR: Recupera informações detalhadas do pull request, incluindo status, revisores, commits e todos os metadados. Essencial para entender o estado do PR antes de tomar ações.

Casos de uso:

  • Verifique o status de aprovação do PR
  • Revise os detalhes e o progresso do PR
  • Entenda as alterações antes de mesclar
  • Monitore o status do PR

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request

merge_pull_request

Integre alterações aprovadas: Mescla um pull request aprovado na branch de destino. Suporta diferentes estratégias de mesclagem com base nas suas preferências de fluxo de trabalho.

Casos de uso:

  • Conclua o processo de revisão de código
  • Integre funcionalidades aprovadas
  • Aplique correções de bugs nas branches principais
  • Publique alterações de código

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request
  • message: Mensagem personalizada do commit de mesclagem
  • strategy: Estratégia de mesclagem:
    • merge-commit (padrão): Cria commit de mesclagem preservando o histórico
    • squash: Combina todos os commits em um só
    • fast-forward: Move o ponteiro da branch sem commit de mesclagem

decline_pull_request

Rejeite alterações inadequadas: Recusa um pull request que não deve ser mesclado, fornecendo feedback ao autor.

Casos de uso:

  • Rejeite alterações que não atendem aos padrões
  • Feche PRs que conflitam com a direção do projeto
  • Solicite retrabalho significativo
  • Evite integração de código indesejada

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request
  • message: Motivo da recusa (útil para feedback ao autor)

add_comment

Participe da revisão de código: Adiciona comentários a pull requests para feedback de revisão, discussões e colaboração. Suporta conversas em tópicos.

Casos de uso:

  • Forneça feedback de revisão de código
  • Faça perguntas sobre alterações específicas
  • Sugira melhorias
  • Participe de discussões técnicas
  • Documente decisões de revisão

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request
  • text (obrigatório): Conteúdo do comentário (suporta Markdown)
  • parentId: ID do comentário pai para respostas em tópicos
  • state: Estado do comentário: OPEN (padrão, publicado imediatamente) ou PENDING (rascunho, visível apenas para você até a revisão ser publicada)

get_diff

Analise alterações de código: Recupera as diferenças de código mostrando exatamente o que foi adicionado, removido ou modificado no pull request. Suporta truncamento por arquivo para gerenciar diffs grandes de forma eficaz.

Casos de uso:

  • Revise alterações de código específicas
  • Entenda o escopo das modificações
  • Analise o impacto antes de mesclar
  • Inspecione detalhes de implementação
  • Avaliação de qualidade de código
  • Lide com arquivos grandes sem sobrecarregar a saída

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request
  • contextLines: Linhas de contexto ao redor das alterações (padrão: 10)
  • maxLinesPerFile: Número máximo de linhas a exibir por arquivo (opcional, usa a variável de ambiente BITBUCKET_DIFF_MAX_LINES_PER_FILE se não for especificado, defina como 0 para sem limite)

Tratamento de Arquivos Grandes: Quando um arquivo excede o limite de maxLinesPerFile, ele exibe:

  • Cabeçalhos e metadados do arquivo (sempre preservados)
  • Primeiros 60% das linhas permitidas desde o início
  • Mensagem de truncamento com estatísticas do arquivo
  • Últimos 40% das linhas permitidas desde o final
  • Indicação clara de como ver o diff completo

get_reviews

Acompanhe o progresso da revisão: Busca histórico de revisão, status de aprovação e feedback dos revisores para entender o estado da revisão.

Casos de uso:

  • Verifique se o PR está pronto para mesclagem
  • Veja quem revisou as alterações
  • Entenda o feedback da revisão
  • Monitore os requisitos de aprovação
  • Acompanhe o progresso da revisão

get_activities

Recupere atividades do pull request: Obtém a linha do tempo completa de atividades de um pull request, incluindo comentários, revisões, commits e outros eventos.

Casos de uso:

  • Leia discussões de comentários e feedback
  • Revise a linha do tempo completa do PR
  • Acompanhe commits adicionados/removidos do PR
  • Veja o histórico de aprovação e revisão
  • Entenda o ciclo de vida completo do PR

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request

get_comments

Extraia apenas comentários do PR: Filtra as atividades do pull request para retornar apenas os comentários, facilitando o foco no conteúdo da discussão sem revisões ou outras atividades.

Casos de uso:

  • Leia tópicos de discussão do PR
  • Extraia feedback e perguntas
  • Concentre-se no conteúdo dos comentários sem ruído
  • Analise o fluxo da conversa

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for fornecida)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request

search

Busca avançada de código e arquivos: Pesquise em repositórios usando a API de busca do Bitbucket com suporte a filtro por projeto/repositório e otimização de consulta. Pesquisa tanto o conteúdo dos arquivos quanto os nomes dos arquivos. Nota: A busca funciona apenas na branch padrão dos repositórios.

Casos de uso:

  • Encontre padrões de código específicos entre projetos
  • Localize arquivos por nome ou conteúdo
  • Pesquise em projetos ou repositórios específicos
  • Filtre por extensões de arquivo

Parâmetros:

  • query (obrigatório): String de consulta de busca
  • project: Chave do projeto Bitbucket para limitar o escopo da busca
  • repository: Slug do repositório para busca específica de repositório
  • type: Otimização de consulta - "file" (envolve a consulta em aspas para correspondência exata de nome de arquivo) ou "code" (comportamento padrão de busca)
  • limit: Número de resultados a retornar (padrão: 25, máximo: 100)
  • start: Índice inicial para paginação (padrão: 0)

Exemplos de sintaxe de consulta:

  • "README.md" - Encontre nome de arquivo exato
  • config ext:yml - Encontre config em arquivos YAML
  • function project:MYPROJECT - Pesquise por "function" em projeto específico
  • bug fix repo:PROJ/my-repo - Pesquise em repositório específico

get_file_content

Ler conteúdo de arquivos com paginação: Recupera o conteúdo de arquivos específicos de repositórios com suporte para arquivos grandes por meio de paginação.

Casos de uso:

  • Ler arquivos de código-fonte
  • Visualizar arquivos de configuração
  • Extrair conteúdo de documentação
  • Inspecionar versões específicas de arquivos

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • filePath (obrigatório): Caminho do arquivo no repositório
  • branch: Branch ou hash de commit (opcional, padrão: main/master)
  • limit: Máximo de linhas por solicitação (padrão: 100, máximo: 1000)
  • start: Número da linha inicial para paginação (padrão: 0)

browse_repository

Explorar estrutura do repositório: Navega por arquivos e diretórios em repositórios para entender a organização do projeto e localizar arquivos específicos.

Casos de uso:

  • Explorar a estrutura do repositório
  • Navegar por árvores de diretórios
  • Encontrar arquivos e pastas
  • Entender a organização do projeto

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • path: Caminho do diretório para navegar (opcional, padrão: raiz)
  • branch: Branch ou hash de commit (opcional, padrão: main/master)
  • limit: Máximo de itens a retornar (padrão: 50)

list_pull_requests

Descobrir e filtrar pull requests: Lista pull requests em um repositório com filtros por estado, autor e direção. Retorna metadados do PR, incluindo título, autor, branches, revisores e status.

Casos de uso:

  • Encontrar PRs abertos em um repositório
  • Listar seus próprios pull requests
  • Ver PRs aguardando revisão
  • Obter uma visão geral de PRs mesclados ou recusados
  • Monitorar a atividade de PRs em um projeto

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • state: Filtrar por estado do PR — OPEN (padrão), MERGED, DECLINED ou ALL
  • author: Filtrar por nome de usuário do autor (correspondência exata)
  • direction: INCOMING (PRs direcionados a este repositório, padrão) ou OUTGOING (PRs originados deste repositório)
  • limit: Número de PRs a retornar (padrão: 25, máximo: 1000)
  • start: Índice inicial para paginação (padrão: 0)

list_branches

Explorar branches do repositório: Lista branches em um repositório com filtragem opcional. Identifica o branch padrão e mostra informações do commit mais recente de cada branch.

Casos de uso:

  • Encontrar nomes de branches para criação de PR ou checkout
  • Verificar a existência de um branch antes de operações
  • Identificar o branch padrão
  • Pesquisar branches por nome

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • filterText: Filtrar branches por nome (correspondência parcial sem diferenciar maiúsculas/minúsculas)
  • limit: Número de branches a retornar (padrão: 25, máximo: 1000)
  • start: Índice inicial para paginação (padrão: 0)

list_commits

Navegar pelo histórico de commits: Lista commits em um repositório com filtragem opcional por branch e autor. Use para revisar alterações, acompanhar contribuições ou entender a evolução de um branch.

Casos de uso:

  • Revisar alterações recentes em um branch
  • Encontrar commits de um autor específico
  • Acompanhar o histórico de commits antes de mesclar
  • Entender a evolução de um branch

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • branch: Nome do branch para listar commits (padrão: branch padrão do repositório)
  • author: Filtrar por nome ou e-mail do autor (correspondência parcial sem diferenciar maiúsculas/minúsculas, aplicada no lado do cliente)
  • limit: Número de commits a retornar (padrão: 25, máximo: 1000)
  • start: Índice inicial para paginação (padrão: 0)

delete_branch

Limpar branches mesclados: Exclui um branch de um repositório. Inclui uma verificação de segurança para evitar a exclusão do branch padrão.

Casos de uso:

  • Limpar branches de funcionalidade após a mesclagem do PR
  • Remover branches obsoletos ou abandonados
  • Manutenção e higiene do repositório

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • branch (obrigatório): Nome do branch a excluir

approve_pull_request

Aprovar alterações de código: Aprova um pull request como o usuário autenticado atual. Registra sua aprovação no PR, sinalizando que as alterações estão prontas para mesclagem.

Casos de uso:

  • Aprovar pull requests revisados
  • Sinalizar prontidão para mesclagem
  • Concluir o fluxo de revisão de código

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request a aprovar

unapprove_pull_request

Retirar aprovação: Remove sua aprovação de um pull request. Use quando precisar retirar uma aprovação anterior após descobrir problemas ou quando o PR tiver sido alterado.

Casos de uso:

  • Retirar aprovação após descobrir problemas
  • Remover aprovação quando o escopo do PR mudar
  • Corrigir aprovações acidentais

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request do qual remover a aprovação

edit_comment

Editar um comentário existente: Modifica o texto de um comentário em um pull request. Funciona com comentários publicados e pendentes (rascunho). Requer a versão do comentário para bloqueio otimista.

Casos de uso:

  • Corrigir erros de digitação ou formatação em comentários de revisão
  • Atualizar informações em um comentário existente
  • Reformatar comentários (por exemplo, para o estilo Conventional Comments)

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request ao qual o comentário pertence
  • commentId (obrigatório): ID do comentário a editar
  • text (obrigatório): Novo conteúdo de texto (suporta Markdown)
  • version (obrigatório): Versão atual do comentário para bloqueio otimista (da resposta de get_comments ou add_comment)

delete_comment

Excluir um comentário: Remove um comentário de um pull request. Requer a versão do comentário para bloqueio otimista.

Casos de uso:

  • Remover comentários publicados incorretamente
  • Limpar comentários de rascunho que não são mais necessários

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request ao qual o comentário pertence
  • commentId (obrigatório): ID do comentário a excluir
  • version (obrigatório): Versão atual do comentário para bloqueio otimista

publish_review

Publicar uma revisão em lote: Publica todos os comentários pendentes (rascunho) de uma só vez, opcionalmente definindo seu status de revisão e adicionando um comentário geral. É o equivalente a clicar em "Concluir revisão" na interface do Bitbucket.

Casos de uso:

  • Publicar todos os comentários de revisão em rascunho em uma única ação
  • Aprovar um PR juntamente com comentários de revisão
  • Solicitar alterações com status "precisa de ajustes" e feedback

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request
  • commentText: Comentário geral opcional para a revisão
  • participantStatus: Status de revisão opcional: APPROVED (pronto para mesclar) ou NEEDS_WORK (alterações necessárias). Omita para feedback geral.

get_code_insights

Recuperar resultados de análise CI/CD: Busca relatórios de Code Insights (SonarQube, varreduras de segurança, etc.) e suas anotações para um pull request.

Casos de uso:

  • Verificar o status do quality gate do SonarQube
  • Revisar descobertas de varreduras de segurança
  • Inspecionar métricas de cobertura de código
  • Ver anotações de análise CI/CD por arquivo

Parâmetros:

  • project: Chave do projeto Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT se não for informada)
  • repository (obrigatório): Slug do repositório
  • prId (obrigatório): ID do pull request

get_dashboard_pull_requests

Painel de PRs entre repositórios: Lista pull requests em todos os repositórios do usuário autenticado. Use para ver PRs que você precisa revisar, PRs que você criou ou PRs em que você participa, sem precisar especificar cada projeto e repositório.

Casos de uso:

  • Ver todos os PRs aguardando sua revisão
  • Listar seus próprios PRs abertos em todos os projetos
  • Encontrar PRs mesclados recentemente em que você participou
  • Obter uma visão geral da sua carga de trabalho de PRs

Parâmetros:

  • state: Filtrar por estado do PR: OPEN (padrão), MERGED, DECLINED ou ALL
  • role: Filtrar pelo seu papel: AUTHOR, REVIEWER ou PARTICIPANT
  • participantStatus: Filtrar pelo seu status de revisão: APPROVED, UNAPPROVED ou NEEDS_WORK
  • order: Ordem de classificação: OLDEST ou NEWEST (padrão)
  • closedSince: Incluir apenas PRs fechados atualizados após este timestamp (epoch ms)
  • limit: Número de PRs a retornar (padrão: 25)
  • start: Índice inicial para paginação (padrão: 0)

Exemplos de Uso

Listando Projetos e Repositórios

# List all accessible projects
list_projects

# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
list_repositories

# List repositories in a specific project
list_repositories --project "MYPROJECT"

# List projects with pagination
list_projects --limit 10 --start 0

Operações de Pesquisa e Arquivos

# Search for README files across all projects
search --query "README" --type "file" --limit 10

# Search for specific code patterns in a project
search --query "function getUserData" --type "code" --project "MYPROJECT"

# Search with file extension filter
search --query "config ext:yml" --project "MYPROJECT"

# Browse repository structure
browse_repository --project "MYPROJECT" --repository "my-repo"

# Browse specific directory
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"

# Read file contents
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json" --limit 20

# Read specific lines from a large file
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "docs/CHANGELOG.md" --start 100 --limit 50

Trabalhando com Pull Requests

# Create a pull request (using default project)
create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"

# Create a pull request with specific project
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"

# Get pull request details
get_pull_request --repository "my-repo" --prId 123

# Get only comments from a PR (no reviews/commits)
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123

# Get full PR activity timeline
get_activities --repository "my-repo" --prId 123

# Merge a pull request with squash strategy
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: New functionality (#123)"

Descobrindo Pull Requests

# List open PRs in a repository (default state: OPEN)
list_pull_requests --repository "my-repo"

# List all PRs regardless of state
list_pull_requests --repository "my-repo" --state "ALL"

# Find PRs by a specific author
list_pull_requests --repository "my-repo" --author "john.doe"

# List merged PRs with pagination
list_pull_requests --repository "my-repo" --state "MERGED" --limit 10 --start 0

Gerenciamento de Branches

# List all branches in a repository
list_branches --repository "my-repo"

# Filter branches by name
list_branches --project "MYPROJECT" --repository "my-repo" --filterText "feature"

# Delete a merged branch
delete_branch --repository "my-repo" --branch "feature/completed-work"

Histórico de Commits

# List recent commits on the default branch
list_commits --repository "my-repo"

# List commits on a specific branch
list_commits --repository "my-repo" --branch "develop" --limit 10

# Filter commits by author
list_commits --repository "my-repo" --author "john.doe"

# Combine branch and author filters
list_commits --project "MYPROJECT" --repository "my-repo" --branch "main" --author "jane"

Fluxo de Aprovação de PR

# Approve a pull request
approve_pull_request --repository "my-repo" --prId 123

# Remove your approval
unapprove_pull_request --repository "my-repo" --prId 123

# Full workflow: review diff, approve, merge
get_diff --repository "my-repo" --prId 123
approve_pull_request --repository "my-repo" --prId 123
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash"

Dependências

  • @modelcontextprotocol/sdk - SDK para implementação do protocolo MCP
  • axios - Cliente HTTP para requisições de API
  • winston - Framework de logging

Configuração

O servidor requer configuração no arquivo de configurações MCP do VSCode. Aqui está um exemplo de configuração:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        // Authentication (choose one):
        // Option 1: Personal Access Token
        "BITBUCKET_TOKEN": "your-access-token",
        // Option 2: Username/Password
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        // Optional: Default project
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}

Variáveis de Ambiente

  • BITBUCKET_URL (obrigatório): URL base da sua instância do Bitbucket Server
  • Autenticação (uma das seguintes é obrigatória):
    • BITBUCKET_TOKEN: Token de acesso pessoal
    • BITBUCKET_USERNAME e BITBUCKET_PASSWORD: Credenciais de autenticação básica
  • BITBUCKET_DEFAULT_PROJECT (opcional): Chave de projeto padrão a ser usada quando não especificada nas chamadas de ferramentas
  • BITBUCKET_DIFF_MAX_LINES_PER_FILE (opcional): Máximo padrão de linhas a exibir por arquivo em diffs. Defina para evitar que arquivos grandes sobrecarreguem a saída. Pode ser substituído pelo parâmetro maxLinesPerFile nas chamadas de get_diff.
  • BITBUCKET_LOG_PATH (opcional): Caminho personalizado para o arquivo de log (padrão: ~/.bitbucket-server-mcp/bitbucket.log)
  • BITBUCKET_READ_ONLY (opcional): Defina como true para habilitar o modo somente leitura
  • BITBUCKET_CUSTOM_HEADERS (opcional): Lista separada por vírgulas de cabeçalhos HTTP personalizados para adicionar a todas as requisições (formato: Header-Name=value,Another-Header=value2). Útil para tokens Zero Trust ou cabeçalhos de proxy

Observação: Com o novo suporte opcional a projetos, agora você pode:

  • Definir BITBUCKET_DEFAULT_PROJECT para trabalhar com um projeto específico por padrão
  • Usar list_projects para descobrir projetos disponíveis
  • Usar list_repositories para navegar por repositórios entre projetos
  • Substituir o projeto padrão especificando o parâmetro project em qualquer chamada de ferramenta

Modo Somente Leitura

O servidor suporta um modo somente leitura para implantações em que você deseja impedir qualquer modificação nos seus repositórios Bitbucket. Quando habilitado, apenas operações seguras e não modificadoras estão disponíveis.

Para habilitar o modo somente leitura: Defina a variável de ambiente BITBUCKET_READ_ONLY=true

Ferramentas disponíveis no modo somente leitura:

  • list_projects - Navegar e listar projetos
  • list_repositories - Navegar e listar repositórios
  • get_pull_request - Visualizar detalhes de pull requests
  • list_pull_requests - Listar e filtrar pull requests
  • get_diff - Visualizar alterações de código e diffs
  • get_reviews - Visualizar histórico e status de revisões
  • get_activities - Visualizar linha do tempo de pull requests
  • get_comments - Visualizar comentários de pull requests
  • search - Pesquisar código e arquivos em repositórios
  • get_file_content - Ler conteúdo de arquivos
  • browse_repository - Navegar pela estrutura do repositório
  • list_branches - Listar branches do repositório
  • list_commits - Navegar pelo histórico de commits
  • get_code_insights - Recuperar relatórios e anotações de análise CI/CD
  • get_dashboard_pull_requests - Listar PRs em todos os repositórios do usuário autenticado

Ferramentas desativadas no modo somente leitura:

  • create_pull_request - Criar novos pull requests
  • update_pull_request - Atualizar título, descrição ou revisores de pull requests
  • merge_pull_request - Mesclar pull requests
  • decline_pull_request - Recusar pull requests
  • add_comment - Adicionar comentários a pull requests
  • add_comment_inline - Adicionar comentários inline a pull requests
  • edit_comment - Editar comentários existentes
  • delete_comment - Excluir comentários
  • publish_review - Publicar revisões em lote
  • delete_branch - Excluir branches
  • approve_pull_request - Aprovar pull requests
  • unapprove_pull_request - Remover aprovações de PRs

Comportamento:

  • Quando BITBUCKET_READ_ONLY não está definido ou está definido com qualquer valor diferente de true, todas as ferramentas funcionam normalmente (compatível com versões anteriores)
  • Quando BITBUCKET_READ_ONLY=true, as operações de escrita são filtradas e retornarão um erro se chamadas
  • Isso é perfeito para implantações em produção, integração CI/CD ou qualquer cenário em que você precise de acesso Bitbucket seguro e somente leitura

Logging

O servidor registra todas as operações usando Winston para fins de depuração e monitoramento.

Localização do arquivo de log (em ordem de prioridade):

  1. Variável de ambiente BITBUCKET_LOG_PATH — caminho personalizado
  2. ~/.bitbucket-server-mcp/bitbucket.log — localização padrão

O diretório de log é criado automaticamente se não existir.

Exemplo: Defina um caminho de log personalizado na sua configuração MCP:

{
  "env": {
    "BITBUCKET_LOG_PATH": "/var/log/bitbucket-mcp/server.log"
  }
}

Cabeçalhos HTTP personalizados

Você pode adicionar cabeçalhos HTTP personalizados a todas as solicitações de API usando a variável de ambiente BITBUCKET_CUSTOM_HEADERS. Isso é útil para tokens de segurança Zero Trust, cabeçalhos de proxy ou qualquer outro cabeçalho exigido pela sua infraestrutura.

Formato: Pares chave-valor separados por vírgula, onde os valores podem conter sinais de igual:

Header-Name=value,Another-Header=value2

Exemplo de cabeçalho único:

{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Zero-Trust-Token=your-token-here"
  }
}

Exemplo de múltiplos cabeçalhos:

{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Custom-Header=value1,X-Proxy-Auth=token123"
  }
}