Bitbucket Depoları'nı AI'ye Bağlayın

Bitbucket ile çalışma şeklinizi dönüştürün - Claude, Cursor AI ve diğer AI asistanlarını doğrudan depoları, pull request'leri ve kodunuza bağlayın. Anında içgörü elde edin, kod incelemelerini otomatikleştirin ve geliştirme akışınızı hızlandırın.

Neler Yapabilirsiniz?

• AI'ye kod hakkında soru sorun: "Ana depomdaki son commit nedir?"
• PR içgörüleri alın: "İncelenmesi gereken tüm açık pull request'leri göster"
• Codebase'inizi arayın: "Authentication fonksiyonunu kullanan tüm JavaScript dosyalarını bul"
• Kod değişikliklerini gözden geçirin: "Feature branch'im ile main arasındaki farkları karşılaştır"
• Pull request'leri yönetin: "Yeni-feature branch'i için bir PR oluştur"
• İş akışlarını otomatikleştirin: "PR #123'e test sonuçlarını gösteren bir yorum ekle"

Kimler İçin?

• Developers - kod incelemesi ve depo yönetiminde AI desteği isteyenler
• Team Leads - proje durumu ve pull request aktivitesi hakkında hızlı içgörü almak isteyenler
• DevOps Engineers - depo iş akışlarını ve branch yönetimini otomatikleştirmek isteyenler
• Herkes - Bitbucket'i doğal dille kullanmak isteyen kişiler

Gereksinimler

• Node.js 18.0.0 veya daha yüksek sürüm
• Bitbucket Cloud hesabı (Bitbucket Server/Data Center değil)
• Kimlik doğrulama: Scoped API Token (önerilen) veya App Password (eski)

Hızlı Başlangıç

2 dakika içinde başlayın:

1. Bitbucket Kimlik Bilgilerinizi Alın

ÖNEMLİ: Bitbucket App Passwords'lar kullanımdan kaldırılıyor ve Haziran 2026'da silinecektir. Yeni kurulumlar için Scoped API Tokens kullanmanızı öneriyoruz.

Seçenek A: Scoped API Token (Önerilen - Gelecek-Proof)

Bitbucket app password'ları kullanımdan kaldırıyor. Bunun yerine yeni scoped API token'larını kullanın:

1. Atlassian API Tokens adresine gidin
2. "Create API token with scopes" butonuna tıklayın
3. Ürün olarak "Bitbucket" seçin
4. Uygun scope'ları seçin:
   • Sadece okunur erişim için: repository, workspace
   • Tam işlevsellik için: repository, workspace, pullrequest
5. Oluşturulan token'ı kopyalayın (ATATT ile başlayan)
6. Kullanıcı adı olarak Atlassian e-postanızla kullanın

Seçenek B: App Password (Eski - Kullanımdan Kaldırılacak)

Bir Bitbucket App Password oluşturun (eski yöntem):

1. Bitbucket App Passwords adresine gidin
2. "Create app password" tıklayın
3. "AI Assistant" gibi bir ad verin
4. Şu izinleri seçin:
   • Workspaces: Read
   • Repositories: Read (AI'nin PR/yorum oluşturması istiyorsanız Write)
   • Pull Requests: Read (PR yönetimi için Write)

2. Hemen Deneyin

# Kimlik bilgilerinizi ayarlayın (bir yöntemi seçin)

# Yöntem 1: Scoped API Token (önerilen - gelecek-proof)
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"  # ATATT ile başlayan token

# VEYA Yöntem 2: Eski App Password (Haziran 2026'da kullanımdan kaldırılacak)
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"

# Workspace'lerinizi listeleyin
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

# Workspace'te depoları listeleyin
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace"

# Depo için pull request'leri alın
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo/pullrequests"

# JMESPath filtreleme ile depo detaylarını alın
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo" --jq "{name: name, language: language}"

AI Asistanlarına Bağlanın

Claude Desktop Kullanıcıları İçin

Bunu Claude konfigürasyon dosyanıza ekleyin (~/.claude/claude_desktop_config.json):

Seçenek 1: Scoped API Token (önerilen - gelecek-proof)

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
      }
    }
  }
}

Seçenek 2: Eski App Password (Haziran 2026'da kullanımdan kaldırılacak)

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
        "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Claude Desktop'u yeniden başlatın, status bar'da bitbucket server'ını göreceksiniz.

Diğer AI Asistanları İçin

Çoğu AI asistanı MCP'yi destekler. Aşağıdakilerden birini yapabilirsiniz:

Seçenek 1: npx kullanın (önerilen - her zaman en son sürüm): AI asistanınızı şu komutu çalıştıracak şekilde yapılandırın: npx -y @aashari/mcp-server-atlassian-bitbucket

Seçenek 2: Global olarak yükleyin:

npm install -g @aashari/mcp-server-atlassian-bitbucket

Ardından AI asistanınızı STDIO transport'u ile MCP server'ını kullanacak şekilde yapılandırın.

Desteklenen AI asistanları:

• Claude Desktop (resmi destek)
• Cursor AI
• Continue.dev
• Cline
• MCP uyumlu herhangi bir client

Alternatif: Konfigürasyon Dosyası

Sistem geneline yapılandırma için ~/.mcp/configs.json oluşturun:

Seçenek 1: Scoped API Token (önerilen - gelecek-proof)

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_scoped_api_token",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

Seçenek 2: Eski App Password (Haziran 2026'da kullanımdan kaldırılacak)

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
      "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

Alternatif konfigürasyon anahtarları: Sistem ayrıca "atlassian-bitbucket", "@aashari/mcp-server-atlassian-bitbucket" veya "mcp-server-atlassian-bitbucket" değerlerini "bitbucket" yerine kabul eder.

Kullanılabilir Araçlar

Bu MCP server, herhangi bir Bitbucket API endpoint'ine erişebilen 6 genel araç sağlar:

Araç	Açıklama	Parametreler
bb_get	Herhangi bir Bitbucket API endpoint'ine GET (veri oku)	path, queryParams?, jq?, outputFormat?
bb_post	Herhangi bir endpoint'e POST (kaynak oluştur)	path, body, queryParams?, jq?, outputFormat?
bb_put	Herhangi bir endpoint'e PUT (kaynakları değiştir)	path, body, queryParams?, jq?, outputFormat?
bb_patch	Herhangi bir endpoint'e PATCH (kısmi güncellemeler)	path, body, queryParams?, jq?, outputFormat?
bb_delete	Herhangi bir endpoint'ten DELETE (kaynakları kaldır)	path, queryParams?, jq?, outputFormat?
bb_clone	Depoyu yerel olarak klonla	workspaceSlug?, repoSlug, targetPath

Araç Parametreleri

Tüm API araçları şu ortak parametreleri destekler:

• path (gerekli): / ile başlayan API endpoint yolu (/2.0 ön eki otomatik eklenir)
• queryParams (isteğe bağlı): Query parametreleri için anahtar-değer çiftleri (ör. {"pagelen": "25", "page": "2"})
• jq (isteğe bağlı): Yanıtı filtrelemek/dönüştürmek için JMESPath ifadesi - token maliyetini azaltmak için kesinlikle öneriliyor
• outputFormat (isteğe bağlı): "toon" (varsayılan, %30-60 daha az token) veya "json"
• body (POST/PUT/PATCH için gerekli): JSON nesnesi olarak request body

Yaygın API Yolları

Tüm yollara otomatik olarak /2.0 ön eki eklenir. Tam Bitbucket Cloud REST API 2.0 referansı: https://developer.atlassian.com/cloud/bitbucket/rest/

Workspace'ler & Depoları:

• /workspaces - Tüm workspace'leri listele
• /repositories/{workspace} - Workspace'teki depoları listele
• /repositories/{workspace}/{repo} - Depo detaylarını al
• /repositories/{workspace}/{repo}/refs/branches - Branch'leri listele
• /repositories/{workspace}/{repo}/refs/branches/{branch_name} - Branch'i al/sil
• /repositories/{workspace}/{repo}/commits - Commit'leri listele
• /repositories/{workspace}/{repo}/commits/{commit} - Commit detaylarını al
• /repositories/{workspace}/{repo}/src/{commit}/{filepath} - Dosya içeriğini al

Pull Request'ler:

• /repositories/{workspace}/{repo}/pullrequests - PR'leri listele (GET) veya PR oluştur (POST)
• /repositories/{workspace}/{repo}/pullrequests/{id} - PR'yi al/güncelle/sil
• /repositories/{workspace}/{repo}/pullrequests/{id}/diff - PR diff'ini al
• /repositories/{workspace}/{repo}/pullrequests/{id}/comments - PR yorumlarını listele/ekle
• /repositories/{workspace}/{repo}/pullrequests/{id}/approve - PR'yi onayla (POST) veya onayı kaldır (DELETE)
• /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes - Değişiklik talep et (POST)
• /repositories/{workspace}/{repo}/pullrequests/{id}/merge - PR'yi merge et (POST)
• /repositories/{workspace}/{repo}/pullrequests/{id}/decline - PR'yi reddet (POST)

Karşılaştırmalar:

• /repositories/{workspace}/{repo}/diff/{source}..{destination} - Branch'leri/commit'leri karşılaştır

Diğer Kaynaklar:

• /repositories/{workspace}/{repo}/issues - Issue'ları listele/yönet
• /repositories/{workspace}/{repo}/downloads - İndirmeleleri listele/yönet
• /repositories/{workspace}/{repo}/pipelines - Bitbucket Pipelines'ı erişle
• /repositories/{workspace}/{repo}/deployments - Deployment'ları görüntüle

TOON Çıktı Formatı

TOON Nedir? Token-Oriented Object Notation, LLM'ler için iyileştirilmiş ve JSON'a kıyasla %30-60 token tüketimini azaltan bir formattır. Tabular array'ler ve minimal sözdizimi kullanırken tüm verileri korur.

Varsayılan davranış: Tüm araçlar varsayılan olarak TOON formatını döndürür. Gerekirse outputFormat: "json" ile bunu geçersiz kılabilirsiniz.

Örnek karşılaştırma:

JSON (verbose):
{
  "values": [
    {"name": "repo1", "slug": "repo-1"},
    {"name": "repo2", "slug": "repo-2"}
  ]
}

TOON (efficient):
values:
  name  | slug
  repo1 | repo-1
  repo2 | repo-2

Daha fazla bilgi: https://github.com/toon-format/toon

JMESPath Filtreleme

Tüm araçlar, belirli verileri ayıklamak ve token maliyetini daha da azaltmak için isteğe bağlı JMESPath (jq) filtrelemesini destekler:

Önemli: Yanıtları filtrelemek için her zaman jq kullanın! Filtrelenmemiş API yanıtları çok büyük olabilir ve token açısından pahalıdır.

# Sadece depo adlarını al
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace" \
  --jq "values[].name"

# PR başlıklarını ve durumlarını al (özel nesne şekli)
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --jq "values[].{title: title, state: state, author: author.display_name}"

# Sadece ilk sonucu al
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace" \
  --jq "values[0]"

# Bir öğe ile şema keşfet, sonra filtrele
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/workspaces" \
  --query-params '{"pagelen": "1"}'

Yaygın JMESPath örüntüleri:

• values[*].fieldName - Tüm öğelerden tek bir alan ayıkla
• values[*].{key1: field1, key2: field2} - Özel nesne şekli oluştur
• values[0] - İlk öğeyi al
• values[:5] - İlk 5 öğeyi al
• values[?state=='OPEN'] - Şarta göre filtrele

Tam JMESPath referansı: https://jmespath.org

Gerçek Dünya Örnekleri

Depoları Keşfedin

AI asistanınıza şunu sorun:

• "Ana workspace'imdeki tüm depoları listele"
• "Backend-api deposu hakkında detayları göster"
• "Feature-auth branch'inin commit geçmişi nedir?"
• "Main branch'ten src/config.js dosyasının içeriğini al"

Pull Request'leri Yönetin

AI asistanınıza şunu sorun:

• "İncelenmesi gereken tüm açık pull request'leri göster"
• "Pull request #42 hakkında detayları al, kod değişikliklerini de dahil et"
• "Feature-login'den main branch'e bir pull request oluştur"
• "PR #15'e testlerin geçtiğini söyleyen bir yorum ekle"
• "Pull request #33'ü onayla"

Branch'ler ve Kod ile Çalış

AI asistanınıza şunu sorun:

• "Feature branch'imi main ile karşılaştır"
• "User-service deposundaki tüm branch'leri listele"
• "abc123 ile def456 commit'leri arasındaki farkları göster"

Gelişmiş Kullanım

Maliyet Optimizasyonu İpuçları

1. JMESPath filtrelemesini her zaman kullanın - Token kullanımını en aza indirmek için yalnızca gerekli alanları ayıklayın
2. Pagination'u akıllıca kullanın - pagelen query parametresini sonuçları sınırlamak için ayarlayın (ör. {"pagelen": "10"})
3. Şemayı önce keşfedin - Sunucu tarafında filtreleme olmadan bir öğeyi getirerek mevcut alanları görün, ardından sonraki çağrıları filtreleyin
4. TOON formatını kullanın - Varsayılan TOON formatı JSON'a kıyasla %30-60 token tasarrufu sağlar
5. Filtreleme için Query parametreleri - Sonuçlar döndürülmeden önce sunucu tarafında filtreleme yapmak için Bitbucket'ın q parametresini kullanın

Query Parameter Örnekleri

# PR'leri duruma göre filtrele
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"state": "OPEN", "pagelen": "5"}' \
  --jq "values[*].{id: id, title: title}"

# PR'leri başlığa göre ara
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"q": "title~\"bug\""}' \
  --jq "values[*].{id: id, title: title}"

# Depoları role göre filtrele
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace" \
  --query-params '{"role": "owner", "pagelen": "10"}'

# Güncelleme tarihine göre sırala
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"sort": "-updated_on"}' \
  --jq "values[*].{id: id, title: title, updated: updated_on}"

Büyük Yanıtlarla Çalışmak

Büyük yükler döndüren API'lerle uğraşırken:

1. Sparse fieldset'leri kullanın - fields query parametresini ekleyin: {"fields": "values.name,values.slug"}
2. Sonuçları sayfalandırın - pagelen ve page parametrelerini kullanın
3. Kaynakta filtreleyin - Sunucu tarafında filtreleme yapmak için Bitbucket'ın q parametresini kullanın
4. JQ ile post-işlem yapın - JMESPath ile yanıtı daha fazla filtreleyin

Tüm teknikleri birleştiren örnek:

npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"state": "OPEN", "pagelen": "10", "fields": "values.id,values.title,values.state"}' \
  --jq "values[*].{id: id, title: title}"

AI Etkileşimleri İçin En İyi Uygulamalar

1. Yolları belirli olarak kullanın - Tam workspace/repo slug'ları kullanın (büyük/küçük harfe duyarlı)
2. CLI'de önce test edin - MCP bağlamında kullanmadan önce yolları ve kimlik doğrulamayı doğrulayın
3. Açıklayıcı JQ filtreleri kullanın - AI'nin daha iyi anlaması için anlamlı alan adlarını ayıklayın
4. Sorun giderme için DEBUG'u etkinleştirin - Bitbucket API'sine tam olarak ne gönderildiğini görün
5. API limitlerini kontrol edin - Bitbucket Cloud'un hız limitleri vardır; çağrıları azaltmak için filtreleme kullanın

CLI Komutları

CLI, MCP araçlarını doğrudan terminal erişimi için yansıtır. Tüm komutlar JSON çıkışı döndürür (TOON değil - TOON yalnızca MCP modunda geçerlidir).

Kullanılabilir Komutlar

# Yardım al
npx -y @aashari/mcp-server-atlassian-bitbucket --help

# GET isteği
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/workspaces" \
  --jq "values[*].{name: name, slug: slug}"

# Query parametreleri ile GET
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --query-params '{"state": "OPEN", "pagelen": "10"}' \
  --jq "values[*].{id: id, title: title}"

# POST isteği (PR oluştur)
npx -y @aashari/mcp-server-atlassian-bitbucket post \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --body '{"title": "My PR", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}' \
  --jq "{id: id, title: title}"

# Query parametreleri ile POST
npx -y @aashari/mcp-server-atlassian-bitbucket post \
  --path "/repositories/myworkspace/myrepo/pullrequests/42/comments" \
  --body '{"content": {"raw": "Looks good!"}}' \
  --query-params '{"fields": "id,content"}' \
  --jq "{id: id, content: content.raw}"

# PUT isteği (kaynağı değiştir)
npx -y @aashari/mcp-server-atlassian-bitbucket put \
  --path "/repositories/myworkspace/myrepo" \
  --body '{"description": "Updated description", "is_private": true}'

# PATCH isteği (kısmi güncelleme)
npx -y @aashari/mcp-server-atlassian-bitbucket patch \
  --path "/repositories/myworkspace/myrepo/pullrequests/123" \
  --body '{"title": "Updated PR title"}'

# DELETE isteği
npx -y @aashari/mcp-server-atlassian-bitbucket delete \
  --path "/repositories/myworkspace/myrepo/refs/branches/old-branch"

# Depoyu klonla
npx -y @aashari/mcp-server-atlassian-bitbucket clone \
  --workspace-slug myworkspace \
  --repo-slug myrepo \
  --target-path /absolute/path/to/parent/directory

CLI Seçenekleri

get ve delete komutları için:

• -p, --path <path> (gerekli) - API endpoint yolu
• -q, --query-params <json> (isteğe bağlı) - JSON string olarak Query parametreleri
• --jq <expression> (isteğe bağlı) - JMESPath filtre ifadesi

post, put ve patch komutları için:

• -p, --path <path> (gerekli) - API endpoint yolu
• -b, --body <json> (gerekli) - JSON string olarak Request body
• -q, --query-params <json> (isteğe bağlı) - JSON string olarak Query parametreleri
• --jq <expression> (isteğe bağlı) - JMESPath filtre ifadesi

clone komutu için:

• --workspace-slug <slug> (isteğe bağlı) - Workspace slug'ı (sağlanmazsa varsayılanı kullanır)
• --repo-slug <slug> (gerekli) - Depo slug'ı
• --target-path <path> (gerekli) - Deponun klonlanacağı üst dizine giden mutlak yol

Hata Ayıklama

Debug Modu Etkinleştirin

Detaylı günlüğe kayıt görmek için DEBUG ortam değişkenini ayarlayın:

# CLI testi için
DEBUG=true npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

# Claude Desktop için - config'e ekleyin
{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "DEBUG": "true",
        "ATLASSIAN_USER_EMAIL": "...",
        "ATLASSIAN_API_TOKEN": "..."
      }
    }
  }
}

Log dosyaları: MCP modunda çalışırken, loglar ~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log dosyasına yazılır

HTTP Modu ile Test Edin

İnteraktif hata ayıklama için server'ı HTTP modunda çalıştırın ve MCP Inspector'ı kullanın:

# Kimlik bilgilerini önce ayarlayın
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_token"
export DEBUG=true

# MCP Inspector ile HTTP server başlatın
npx -y @aashari/mcp-server-atlassian-bitbucket
# Ardından başka bir terminal'de:
PORT=3000 npm run mcp:inspect

Bu, araçları test etmek ve request/response verilerini görmek için görsel bir arayüz açar.

Yaygın Sorunlar

Server Claude Desktop'ta görünmüyor:

1. Config dosyası sözdizimini kontrol edin (geçerli JSON)
2. Claude Desktop'u tamamen yen