# mcp-bitbucket

Serwer [MCP](https://modelcontextprotocol.io) (stdio) do Bitbucket Cloud REST API 2.0. Działa z Cursorem: pull requesty, pipeline’y, logi, clone.

Narzędzia są zgodne z typowym zestawem `bb_get` / `bb_post` / `bb_put` / `bb_patch` / `bb_delete` / `bb_clone`.

## Wymagania

- Node.js 18+
- Scoped API Token Atlassian (App Passwords nie działają)

Token: [id.atlassian.com → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).  
Przydatne zakresy: odczyt repozytorium, pull requestów, pipeline’ów i użytkownika (`read:repository:bitbucket`, `read:pullrequest:bitbucket`, `read:pipeline:bitbucket`, `read:user:bitbucket`). Do zapisu dodaj odpowiednie `write:*`.

## Instalacja

```bash
git clone https://github.com/genkis/mcp-bitbucket.git
cd mcp-bitbucket
npm install
```

Skopiuj `.env.example` do `.env` i uzupełnij wartości **lokalnie**. Pliku `.env` nie commituj.

## Cursor (`~/.cursor/mcp.json`)

Token i e-mail trzymaj tylko w lokalnej konfiguracji Cursora, nie w tym repozytorium.

```json
{
  "mcpServers": {
    "bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/index.js"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "your-scoped-api-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}
```

Po zmianie przeładuj serwery MCP w Cursorze.

Zmienne:

| Zmienna | Opis |
|---|---|
| `ATLASSIAN_USER_EMAIL` | E-mail konta Atlassian |
| `ATLASSIAN_API_TOKEN` | Scoped API Token |
| `BITBUCKET_DEFAULT_WORKSPACE` | Domyślny workspace (używany przez `bb_clone`) |

Aliasy: `BITBUCKET_USERNAME`, `BITBUCKET_API_TOKEN`.

## Narzędzia

Prefiks `/2.0` jest dodawany automatycznie. Ścieżka zaczyna się od `/`, np. `/workspaces`.

| Narzędzie | Zastosowanie |
|---|---|
| `bb_get` | Odczyt (PR, pipeline’y, logi, pliki) |
| `bb_post` | Tworzenie (PR, komentarz, merge) |
| `bb_put` | Pełna podmiana zasobu |
| `bb_patch` | Częściowa aktualizacja |
| `bb_delete` | Usuwanie / decline PR |
| `bb_clone` | `git clone` (SSH, potem HTTPS) |

Parametry wspólne: `path`, opcjonalnie `queryParams`, `jq` (JMESPath), `outputFormat` (`toon` albo `json`). `bb_post` / `bb_put` / `bb_patch` wymagają `body`.

Przykłady ścieżek:

- `/workspaces`
- `/repositories/{workspace}/{repo}/pullrequests/{id}`
- `/repositories/{workspace}/{repo}/pullrequests/{id}/diff`
- `/repositories/{workspace}/{repo}/pipelines/?pagelen=50&sort=-created_on`
- `/repositories/{workspace}/{repo}/pipelines/{uuid}/steps/{stepUuid}/log`

Filtr `jq` warto stosować zawsze przy listach, żeby nie ciągnąć całego JSON-a do modelu.

## Bezpieczeństwo

- Nie commituj tokenów, `.env` ani `mcp.json` z sekretami.
- Ten serwer tylko przekazuje żądania do `api.bitbucket.org` z Basic Auth (e-mail + token).
- Logi i błędy nie wypisują tokenu.