Bitbucket

Servidor Bitbucket Model Context Protocol (MCP)

Um servidor Model Context Protocol (MCP) de alto desempenho e sem estado, escrito em Rust, que traz todo o poder da API REST do Bitbucket Cloud para seus agentes de IA e ferramentas de automação com LLM.

Ao conectar o Bitbucket Cloud ao padrão MCP, o bitbucket-mcp permite que agentes inteligentes (como Claude, Cursor, Copilot ou Antigravity) inspecionem, gerenciem e automatizem com segurança repositórios, pull requests, issues e pipelines de CI/CD de forma autônoma.

---

🚀 Recursos

• Suporte completo ao Bitbucket Cloud: Interaja com Repositórios, Workspaces, Branches, Commits, Pull Requests, Issues, Pipelines, Deployments e Webhooks.
• Compatível com o protocolo MCP: Construído estritamente com base nas especificações padrão do protocolo MCP 2024-11-05.
• Extremamente rápido e leve: Escrito em Rust, utilizando operações assíncronas altamente otimizadas e a stack rustls para máximo desempenho e pegada mínima.
• Seguro por padrão: Arquitetura completamente sem estado. A autenticação é feita por meio de tokens oficiais da API do Bitbucket, transmitidos com segurança pelo ambiente.
• Pronto para Docker: Imagens oficiais estão disponíveis no GitHub Container Registry (GHCR) para integrações instantâneas de plug-and-play.

---

🏗️ Arquitetura e Como Funciona

O bitbucket-mcp utiliza a crate Rust rmcp para expor uma interface JSON-RPC padrão aos clientes de IA. Quando um agente de IA solicita uma ação (como recuperar o diff de um pull request), o servidor traduz essa solicitação em uma chamada de API REST estritamente tipada para api.bitbucket.org.

Validação rigorosa de esquema

Diferentemente de servidores mais simples baseados em Node.js, esta implementação em Rust usa schemars para gerar esquemas JSON rigorosos e fortemente tipados para suas ferramentas. Isso garante compatibilidade com os LLMs de IA mais rigorosos e de nível empresarial (como os Structured Outputs da OpenAI), evitando erros de esquema com tipagem frouxa durante a descoberta de ferramentas.

---

🛠️ Pré-requisitos

1. Credenciais do Bitbucket: Você precisa de uma conta no Bitbucket Cloud e de uma App Password / Token de API.
   • Crie uma App Password com escopos como repository:read, pullrequest:read, pullrequest:write, issue:write, etc.
2. Docker (recomendado) ou o toolchain Rust (se for compilar a partir do código-fonte).

---

📦 Instalação e Início Rápido

Opção A: Usando Docker (recomendado)

Você pode executar a imagem Docker pré-compilada diretamente. Ela aceita JSON-RPC via stdio.

docker run -i --rm \
  -e BITBUCKET_API_USERNAME="your-atlassian-email@example.com" \
  -e BITBUCKET_API_TOKEN="your-app-password" \
  ghcr.io/ibrahimogod/bitbucket-mcp:latest

Opção B: Compilando localmente (Cargo)

Se você preferir executar nativamente sem Docker:

# 1. Clone the repository
git clone https://github.com/Ibrahimogod/bitbucket-mcp.git
cd bitbucket-mcp

# 2. Build the optimized release binary
cargo build --release

# 3. Export credentials and run
export BITBUCKET_API_USERNAME="your-atlassian-email@example.com"
export BITBUCKET_API_TOKEN="your-app-password"
./target/release/bitbucket_stdio

---

🔌 Integração com Clientes de IA

Integração com Cursor

Para configurar o Cursor para iniciar o servidor MCP do Bitbucket automaticamente, adicione o seguinte ao seu ~/.cursor/mcp.json global ou .cursor/mcp.json no nível do projeto:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_API_USERNAME",
        "-e", "BITBUCKET_API_TOKEN",
        "ghcr.io/ibrahimogod/bitbucket-mcp:latest"
      ],
      "env": {
        "BITBUCKET_API_USERNAME": "<your-email>",
        "BITBUCKET_API_TOKEN": "<your-app-password>"
      }
    }
  }
}

Integração com Claude Desktop

Para o aplicativo Claude Desktop, edite seu arquivo de configuração (geralmente encontrado em ~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_API_USERNAME",
        "-e", "BITBUCKET_API_TOKEN",
        "ghcr.io/ibrahimogod/bitbucket-mcp:latest"
      ],
      "env": {
        "BITBUCKET_API_USERNAME": "<your-email>",
        "BITBUCKET_API_TOKEN": "<your-app-password>"
      }
    }
  }
}

---

🤝 Contribuindo

Contribuições são bem-vindas! Certifique-se de que seu código siga a formatação padrão do Rust (cargo fmt) e passe em todos os testes (cargo test).

Se você quiser adicionar suporte a um novo endpoint do Bitbucket Cloud:

1. Defina a struct de entrada em src/common/bitbucket.rs usando #[derive(JsonSchema, Deserialize)].
2. Adicione a lógica do manipulador da ferramenta anotada com #[rmcp::tool(description = "...")].
3. Certifique-se de adicionar testes mapeando o novo endpoint.

📄 Licença

Este projeto está licenciado sob a Licença MIT.