CircleCI MCP Server

resmi

Yapay zeka ajanlarının CircleCI'dan gelen derleme hatalarını düzeltmesini sağlar.

GitHub
86

Dokümantasyon

CircleCI MCP Sunucusu

License: Apache 2.0 CircleCI npm

Model Context Protocol (MCP), büyük dil modelleri (LLM'ler) ile harici sistemler arasındaki bağlamı yönetmek için yeni, standartlaştırılmış bir protokoldür. Bu depoda, CircleCI için bir MCP Sunucusu sunuyoruz.

IDE'nizden ayrılmadan, doğal dil kullanarak CircleCI ile etkileşim kurmak için Cursor, Windsurf, Copilot, Claude veya herhangi bir MCP uyumlu istemciyi kullanın.

Araçlar

AraçAçıklama
analyze_diffGit farklarını imleç kurallarına göre ihlaller için analiz edin
config_helperCircleCI yapılandırmanızı doğrulayın ve rehberlik alın
create_prompt_templateYapay zeka uygulamaları için yapılandırılmış istem şablonları oluşturun
download_usage_api_dataCircleCI Kullanım API'sinden kullanım verilerini indirin
find_flaky_testsTest yürütme geçmişini analiz ederek dengesiz testleri belirleyin
find_underused_resource_classesYetersiz kullanılan işlem kaynaklarına sahip işleri bulun
get_build_failure_logsCircleCI derlemelerinden ayrıntılı hata günlüklerini alın
get_job_test_resultsCircleCI işleri için test meta verilerini ve sonuçlarını alın
get_latest_pipeline_statusBir dal için en son işlem hattının durumunu alın
list_artifactsBir CircleCI işi tarafından üretilen yapıtları listeleyin
list_component_versionsBir CircleCI bileşeni için tüm sürümleri listeleyin
list_followed_projectsTakip ettiğiniz tüm CircleCI projelerini listeleyin
recommend_prompt_template_testsİstem şablonları için test senaryoları oluşturun
rerun_workflowBir iş akışını baştan veya başarısız işten itibaren yeniden çalıştırın
run_evaluation_testsBir CircleCI işlem hattında değerlendirme testlerini çalıştırın
run_pipelineBir işlem hattını çalıştırmak için tetikleyin
run_rollback_pipelineBir proje için geri alma işlemini tetikleyin

Kurulum

Ekip / merkezi dağıtım: Kuruluşunuz için geliştirici başına veya paylaşılan CircleCI belirteçleriyle tek bir paylaşılan uzak sunucu (Kubernetes, Docker, vb.) çalıştırmak için Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın.

Cursor

Ön koşullar:

Yerel bir MCP Sunucusunda NPX Kullanma

Cursor MCP yapılandırmanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

CIRCLECI_BASE_URL isteğe bağlıdır — yalnızca şirket içi müşteriler için gereklidir. MAX_MCP_OUTPUT_LENGTH isteğe bağlıdır — MCP yanıtları için maksimum çıktı uzunluğu (varsayılan: 50000).

Yerel bir MCP Sunucusunda Docker Kullanma

Cursor MCP yapılandırmanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın. Kullanıcı başına istemci yapılandırmasını kullanın ve Cursor MCP yapılandırmanıza ekleyin (Cursor Settings → MCP).

VS Code

Ön koşullar:

Yerel bir MCP Sunucusunda NPX Kullanma

Projenizdeki .vscode/mcp.json dosyasına aşağıdakini ekleyin:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

💡 Girdiler ilk sunucu başlatıldığında istenir, ardından VS Code tarafından güvenli bir şekilde saklanır.

Yerel bir MCP Sunucusunda Docker Kullanma

Projenizdeki .vscode/mcp.json dosyasına aşağıdakini ekleyin:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "circleci-base-url",
      "description": "CircleCI Base URL",
      "default": "https://circleci.com"
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}",
        "CIRCLECI_BASE_URL": "${input:circleci-base-url}"
      }
    }
  }
}

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın. .vscode/mcp.json içindeki kullanıcı başına istemci yapılandırmasını kullanın.

Claude Desktop

Ön koşullar:

Yerel bir MCP Sunucusunda NPX Kullanma

claude_desktop_config.json dosyanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Yerel bir MCP Sunucusunda Docker Kullanma

claude_desktop_config.json dosyanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın. Claude Desktop ve CLI istemcileri bölümünde gösterildiği gibi bir sarmalayıcı betik oluşturun, ardından claude_desktop_config.json dosyanızı ona yönlendirin.

Yapılandırma dosyanızı bulmak veya oluşturmak için Claude Desktop ayarlarını açın, sol kenar çubuğunda Geliştirici seçeneğine tıklayın, ardından Yapılandırmayı Düzenle seçeneğine tıklayın. Yapılandırma dosyası şu konumdadır:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Daha fazla bilgi için: https://modelcontextprotocol.io/quickstart/user

Claude Code

Ön koşullar:

Yerel bir MCP Sunucusunda NPX Kullanma

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci@latest

Yerel bir MCP Sunucusunda Docker Kullanma

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -e CIRCLECI_BASE_URL=https://circleci.com -- docker run --rm -i -e CIRCLECI_TOKEN -e CIRCLECI_BASE_URL circleci/mcp-server-circleci

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu ve oradaki Claude Code istemci kurulumuna bakın.

Windsurf

Ön koşullar:

Yerel bir MCP Sunucusunda NPX Kullanma

Windsurf mcp_config.json dosyanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci@latest"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Yerel bir MCP Sunucusunda Docker Kullanma

Windsurf mcp_config.json dosyanıza aşağıdakini ekleyin:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CIRCLECI_TOKEN",
        "-e",
        "CIRCLECI_BASE_URL",
        "-e",
        "MAX_MCP_OUTPUT_LENGTH",
        "circleci/mcp-server-circleci"
      ],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      }
    }
  }
}

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın. Windsurf mcp_config.json dosyanızdaki kullanıcı başına istemci yapılandırmasını kullanın.

Daha fazla bilgi için: https://docs.windsurf.com/windsurf/mcp

Amazon Q Developer CLI

Ön koşullar:

Amazon Q Developer'da MCP istemci yapılandırması, mcp.json adlı bir dosyada JSON formatında saklanır. İki yapılandırma düzeyi desteklenir:

  • Genel: ~/.aws/amazonq/mcp.json — tüm çalışma alanları için geçerlidir
  • Çalışma Alanı: .amazonq/mcp.json — geçerli çalışma alanına özeldir

Her iki dosya da mevcutsa, içerikleri birleştirilir. Çakışma durumunda, çalışma alanı yapılandırması önceliklidir.

Yerel bir MCP Sunucusunda NPX Kullanma

~/.aws/amazonq/mcp.json dosyasını düzenleyin veya aşağıdaki içerikle .amazonq/mcp.json oluşturun:

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      },
      "timeout": 60000
    }
  }
}

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın. Claude Desktop ve CLI istemcileri bölümünde gösterildiği gibi bir sarmalayıcı betik kullanın, ardından q mcp add ile kaydedin.

IDE'de Amazon Q Developer

Ön koşullar:

Yerel bir MCP Sunucusunda NPX Kullanma

~/.aws/amazonq/mcp.json dosyasını düzenleyin veya aşağıdaki içerikle .amazonq/mcp.json oluşturun:

{
  "mcpServers": {
    "circleci-local": {
      "command": "npx",
      "args": [
        "-y",
        "@circleci/mcp-server-circleci@latest"
      ],
      "env": {
        "CIRCLECI_TOKEN": "YOUR_CIRCLECI_TOKEN",
        "CIRCLECI_BASE_URL": "https://circleci.com",
        "MAX_MCP_OUTPUT_LENGTH": "50000"
      },
      "timeout": 60000
    }
  }
}

Kendi Kendine Yönetilen Uzak MCP Sunucusu Kullanma

Kendi Kendine Yönetilen Uzak MCP Sunucusu bölümüne bakın. Claude Desktop ve CLI istemcileri bölümünde gösterildiği gibi bir sarmalayıcı betik kullanın, ardından MCP yapılandırma kullanıcı arayüzü aracılığıyla ekleyin:

  1. MCP yapılandırma kullanıcı arayüzüne erişin
  2. + sembolünü seçin
  3. Kapsamı seçin: genel veya yerel
  4. Bir ad girin (örn. circleci-remote-mcp)
  5. Aktarım protokolünü seçin: stdio
  6. Betiğinize giden komut yolunu girin
  7. Kaydet seçeneğine tıklayın
Smithery

CircleCI MCP Sunucusunu Smithery aracılığıyla Claude Desktop için otomatik olarak kurmak üzere:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Kendi Kendine Yönetilen Uzak MCP Sunucusu

MCP sunucusunu merkezi olarak çalıştırın (örneğin Kubernetes veya Docker üzerinde), böylece ekibiniz tek bir dağıtımı paylaşır. Geliştiricilerin nasıl kimlik doğrulayacağını seçin:

Bir dağıtım modu seçin

ModNe zaman kullanılırSunucu kurulumuİstemci kurulumuCircleCI denetim izi
Kullanıcı başına belirteçler (önerilir)SSO destekli Kişisel API Belirteçlerine sahip ekiplerREQUIRE_REQUEST_TOKEN=true, sunucu PAT'si yokHer geliştirici kendi PAT'sini iletirGeliştirici başına
Paylaşılan belirteç (geçici)Hızlı kullanıma sunma, tek hizmet kimliği uygunSunucuda CIRCLECI_TOKEN, REQUIRE_REQUEST_TOKEN=false (açıkça devre dışı bırakma)Yetkilendirme başlığı gerekmezTek paylaşılan kimlik

Güvenlik: İstek kimlik doğrulaması uzak modda varsayılan olarak açıktır. Paylaşılan belirteç modu bunu devre dışı bırakır (REQUIRE_REQUEST_TOKEN=false), böylece her arayan, kimlik bilgisi olmadan sunucunun CIRCLECI_TOKEN kimliği gibi hareket edebilir. Yalnızca tamamen güvendiğiniz bir ağda etkinleştirin ve aksi takdirde kullanıcı başına belirteçleri tercih edin. TLS'yi bir giriş noktasında sonlandırmak şifreleme sağlar, kimlik doğrulama değil.

1. Sunucuyu dağıtın

Her iki mod da uzak HTTP modunu kullanır (start=remote). 8000 bağlantı noktasını (veya seçtiğiniz bağlantı noktasını) yayınlayın.

Kullanıcı başına belirteçler (önerilir):

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e REQUIRE_REQUEST_TOKEN=true \
  circleci/mcp-server-circleci

Paylaşılan belirteç (geçici):

docker run --rm -p 8000:8000 \
  -e start=remote \
  -e port=8000 \
  -e CIRCLECI_TOKEN=your-shared-circleci-pat \
  -e REQUIRE_REQUEST_TOKEN=false \
  circleci/mcp-server-circleci

Ortam değişkenleri:

DeğişkenAçıklama
start=remoteStdio yerine HTTP+SSE MCP sunucusunu başlatır
portKonteyner içindeki dinleme bağlantı noktası (varsayılan: 8000)
REQUIRE_REQUEST_TOKENAuthorization: Bearer veya Circle-Token başlığı olmayan istekleri reddeder. Varsayılan olarak gereklidir; kimlik doğrulanmamış isteklere izin vermek için REQUIRE_REQUEST_TOKEN=false olarak ayarlayın (paylaşılan belirteç modu)
CIRCLECI_TOKENKullanıcı başına başlıklar gönderilmediğinde tüm istekler için paylaşılan yedek PAT
CIRCLECI_BASE_URLİsteğe bağlı — yalnızca şirket içi için gereklidir (varsayılan: https://circleci.com)
DISABLE_TELEMETRY=trueKullanım metrikleri dışa aktarımından çıkın

Sunucu, istek başına belirteçleri şu yollarla kabul eder:

  • Authorization: Bearer <circleci-pat>
  • Circle-Token: <circleci-pat>

Bir istemci bir başlık belirteci gönderirse, sunucudaki CIRCLECI_TOKEN yerine öncelikli olur.

Bir istek sırasında kaydedilen telemetri metrikleri, o istekle aynı belirteç kullanılarak dışa aktarılır.

2. İstemcileri yapılandırın

Çoğu MCP istemcisi yalnızca yerel (stdio) süreçleri destekler. Bunları uzak sunucunuza bağlamak için üçüncü taraf bir stdio-HTTP köprüsü olan mcp-remote kullanın.

URL şeması: Yerel test için http://localhost:8000/mcp ile --allow-http kullanın. Üretimde, TLS'yi giriş/dengeleyicinizde sonlandırın ve --allow-http olmadan https://your-host/mcp kullanın.

Windows: --header değerlerinde iki nokta üst üste etrafında boşluk bırakmaktan kaçının. Tam Bearer <token> değerini bir ortam değişkenine koyun.

Güvenlik: Örnekler kolaylık sağlamak için npx kullanır. Üretim veya ekip dağıtımları için MCP yapılandırmanızda belirli bir sürümü sabitleyin (örneğin mcp-remote yerine [email protected]). 0.1.16 altındaki sürümleri kullanmayın (CVE-2025-6514).

İstemci yapılandırması: kullanıcı başına belirteçler

Her geliştirici, her istekte kendi CircleCI Kişisel API Belirtecini iletir:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "CircleCI API Token",
      "password": true
    }
  ],
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer ${input:circleci-token}"
      }
    }
  }
}

http://localhost:8000/mcp kısmını ekibinizin sunucu URL'si ile değiştirin. Cursor ve VS Code ${input:...} istemlerini destekler; diğer istemciler AUTH_HEADER değerini doğrudan ayarlayabilir.

İstemci yapılandırması: paylaşılan token

Sunucuda CIRCLECI_TOKEN ayarlandığında ve REQUIRE_REQUEST_TOKEN=false ile başlatıldığında (istek kimlik doğrulaması varsayılan olarak açıktır ve açıkça devre dışı bırakılması gerekir), istemcilerin bir token göndermesine gerek kalmaz:

{
  "mcpServers": {
    "circleci-mcp-server-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--allow-http"
      ]
    }
  }
}

Claude Desktop ve CLI istemcileri

Bir sarmalayıcı betik oluşturun (örn. circleci-remote-mcp.sh):

#!/bin/bash
export AUTH_HEADER="Bearer your-circleci-token"
npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"

Çalıştırılabilir yapın (chmod +x circleci-remote-mcp.sh), ardından MCP yapılandırmanızdan buna başvurun:

{
  "mcpServers": {
    "circleci-remote-mcp-server": {
      "command": "/full/path/to/circleci-remote-mcp.sh"
    }
  }
}

Claude Code

claude mcp add circleci-mcp-server \
  -e AUTH_HEADER="Bearer your-circleci-token" \
  -- npx mcp-remote http://localhost:8000/mcp --allow-http --header "Authorization:${AUTH_HEADER}"

Paylaşılan token sunucusu kullanırken --header ve AUTH_HEADER öğelerini atlayın.

3. Dağıtımı doğrulayın

# Health check (no auth required)
curl http://localhost:8000/ping

# Should return 401 when REQUIRE_REQUEST_TOKEN=true and no token is sent
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Should return 200 with a valid Bearer token and MCP Accept headers
curl -s -o /dev/null -w "%{http_code}\n" -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-circleci-pat" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Demo

Çalışırken izleyin

Örnek: "Dalımdaki en son başarısız pipeline'ı bul ve günlükleri getir" — daha fazla örnek için wiki sayfasına bakın.

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

Araç Detayları

analyze_diff

Kural ihlallerini belirlemek için git diff'lerini imleç kurallarına göre analiz eder.

Sağlayın:

  • Git diff içeriği (örn. git diff --cached, git diff HEAD)
  • .cursorrules veya .cursor/rules dosyasından depo kuralları

Güven puanları ve açıklamalarla birlikte ayrıntılı ihlal raporları döndürür.

Şunlar için kullanışlıdır:

  • Commit öncesi kod kalite kontrolleri
  • Ekip kodlama standartlarıyla tutarlılığı sağlama
  • Kod incelemesinden önce kural ihlallerini yakalama
config_helper

Rehberlik ve doğrulama sağlayarak CircleCI yapılandırma görevlerine yardımcı olur.

  • .circleci/config.yml dosyanızı sözdizimi ve anlamsal hatalara karşı doğrular
  • Ayrıntılı doğrulama sonuçları ve yapılandırma önerileri sağlar
  • Örnek: "CircleCI yapılandırmamı doğrula"
create_prompt_template

Özellik gereksinimlerine dayalı olarak AI özellikli uygulamalar için yapılandırılmış istem şablonları oluşturur.

  • Kullanıcı gereksinimlerini optimize edilmiş istem şablonlarına dönüştürür
  • Yapılandırılmış bir şablon ve gerekli girdi parametrelerini tanımlayan bir bağlam şeması döndürür
  • Örnek: "Yaşa ve konuya göre uyku öncesi hikayeleri oluşturmak için bir istem şablonu oluştur"
download_usage_api_data

Belirli bir organizasyon için CircleCI Kullanım API'sinden kullanım verilerini indirir. Esnek tarih girişini kabul eder (örn., "Mart 2025" veya "geçen ay"). Yalnızca bulut özelliğidir.

Seçenek 1: Aşağıdakileri sağlayarak yeni bir dışa aktarma işi başlatın:

  • orgId, startDate, endDate (en fazla 32 gün), outputDir

Seçenek 2: Aşağıdakileri sağlayarak mevcut bir dışa aktarma işini kontrol edin/indirin:

  • orgId, jobId, outputDir

Belirtilen zaman aralığı için CircleCI kullanım verilerini içeren bir CSV dosyası döndürür.

[!NOTE] Kullanım verileri, maliyet optimizasyonu analizi için find_underused_resource_classes aracına beslenebilir.

find_flaky_tests

Test yürütme geçmişini analiz ederek CircleCI projenizdeki kararsız testleri belirler. CircleCI'daki kararsız test algılama özelliğinden yararlanır.

Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "my-project için kararsız testleri getir"

  2. CircleCI Proje URL'si Kullanarak:

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü ve git remote URL'si sağlayarak yerel çalışma alanınızdan çalışır
    • Örnek: "Mevcut projemdeki kararsız testleri bul"

Çıktı modları:

  • Metin (varsayılan): Kararsız test ayrıntılarını metin biçiminde döndürür
  • Dosya (FILE_OUTPUT_DIRECTORY ortam değişkeni gerektirir): Kararsız test ayrıntılarını içeren bir dizin oluşturur
find_underused_resource_classes

Ortalama veya maksimum CPU/RAM kullanımı belirli bir eşiğin altında olan işleri bulmak için bir CircleCI kullanım verisi CSV dosyasını analiz eder (varsayılan: %40).

download_usage_api_data aracından elde edilen bir CSV dosyası sağlayın.

Proje ve iş akışına göre düzenlenmiş, az kullanılan işlerin bir markdown listesini döndürür — maliyet optimizasyonu fırsatlarını belirlemek için kullanışlıdır.

get_build_failure_logs

CircleCI derlemelerinden ayrıntılı hata günlüklerini alır. Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "main dalındaki my-project için derleme hatalarını getir"

  2. CircleCI URL'leri Kullanarak:

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü, git remote URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır
    • Örnek: "Mevcut dalımdaki en son başarısız pipeline'ı bul"

Araç, aşağıdakileri içeren biçimlendirilmiş günlükler döndürür:

  • İş adları
  • Adım adım yürütme ayrıntıları
  • Hata mesajları ve bağlam
get_job_test_results

CircleCI işleri için test meta verilerini alır, IDE'nizden ayrılmadan test sonuçlarını analiz etmenizi sağlar. Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Örnek: "main dalındaki my-project için test sonuçlarını getir"

  2. CircleCI URL'si Kullanarak:

    • İş URL'si: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789
    • İş Akışı URL'si: https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def
    • Pipeline URL'si: https://app.circleci.com/pipelines/github/org/repo/123

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü, git remote URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır

Araç şunları döndürür:

  • Tüm testlerin özeti (toplam, başarılı, başarısız)
  • Başarısız testler hakkında ayrıntılı bilgi: ad, sınıf, dosya, hata mesajı, süre
  • Zamanlama ile başarılı testlerin listesi
  • Test sonucuna göre filtreleme

[!NOTE] Test meta verileri CircleCI yapılandırmanızda yapılandırılmalıdır. Kurulum talimatları için Test Verilerini Toplama sayfasına bakın.

get_latest_pipeline_status

Belirli bir dal için en son pipeline'ın durumunu alır. Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Örnek: "main dalındaki my-project için en son pipeline'ın durumunu getir"

  2. CircleCI Proje URL'si Kullanarak:

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü, git remote URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır

Örnek çıktı:

---
Workflow: build
Status: success
Duration: 5 minutes
Created: 4/20/2025, 10:15:30 AM
Stopped: 4/20/2025, 10:20:45 AM
---
Workflow: test
Status: running
Duration: unknown
Created: 4/20/2025, 10:21:00 AM
Stopped: in progress
list_artifacts

Bir CircleCI işi tarafından üretilen yapıtların listesini alır. Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "main dalındaki my-project için yapıtları listele"

  2. CircleCI URL'si Kullanarak:

    • İş URL'si: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
    • İş Akışı URL'si: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
    • Pipeline URL'si: https://app.circleci.com/pipelines/gh/organization/project/123

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü, git remote URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır

Şunlar için kullanışlıdır:

  • Derleme yapıtları (ikili dosyalar, raporlar, günlükler) için indirme URL'lerini bulma
  • Bir pipeline çalıştırması tarafından hangi yapıtların üretildiğini kontrol etme
list_component_versions

Bir ortamdaki belirli bir CircleCI bileşeni için tüm sürümleri listeler. Dağıtım durumunu, commit bilgilerini ve zaman damgalarını içerir.

Sağlanmazsa araç, bileşeni ve ortamı seçmenizi isteyecektir.

Şunlar için kullanışlıdır:

  • Hangi sürümün şu anda canlı olduğunu belirleme
  • Geri alma işlemleri için hedef sürümleri seçme
  • Dağıtım ayrıntılarını alma (pipeline, iş akışı, iş)
list_followed_projects

Kullanıcının CircleCI'da takip ettiği tüm projeleri listeler.

  • Erişiminiz olan tüm projeleri projectSlug ile birlikte gösterir
  • Örnek: "CircleCI projelerimi listele"

Örnek çıktı:

Projects followed:
1. my-project (projectSlug: gh/organization/my-project)
2. another-project (projectSlug: gh/organization/another-project)

[!NOTE] projectSlug (proje adı değil), diğer birçok CircleCI aracı için gereklidir.

recommend_prompt_template_tests

Beklenen sonuçları ürettiklerinden emin olmak için istem şablonları için test senaryoları oluşturur.

  • İstem şablonunuza ve bağlam şemanıza dayalı olarak çeşitli test senaryoları oluşturur
  • Çeşitli parametre kombinasyonlarına sahip önerilen test senaryolarından oluşan bir dizi döndürür
  • Örnek: "Uyku öncesi hikaye istem şablonum için testler oluştur"
rerun_workflow

Bir iş akışını baştan veya başarısız olan işten itibaren yeniden çalıştırır.

Yeni oluşturulan iş akışının kimliğini ve onu izlemek için bir bağlantı döndürür.

run_evaluation_tests

Bir CircleCI pipeline'ında değerlendirme testlerini ("İstem Testleri" olarak da bilinir) çalıştırır. Uygun bir CircleCI yapılandırması oluşturur ve bunu kullanarak bir pipeline tetikler.

Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Önce projelerinizi almak için list_followed_projects kullanın, ardından:
    • Örnek: "main dalındaki my-project için değerlendirme testlerini çalıştır"

  2. CircleCI URL'si Kullanarak:

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü, git remote URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır

Araç, istem şablonu dosyalarını kabul eder ve tetiklenen pipeline'ı izlemek için bir URL döndürür.

[!NOTE] Projenin birden fazla pipeline tanımı varsa, araç seçmeniz için mevcut pipeline'ların bir listesini döndürecektir.

run_pipeline

Bir pipeline'ı çalıştırmak için tetikler. Bu araç üç şekilde kullanılabilir:

  1. Proje Slug'ı ve Dal Kullanarak (Önerilen):

    • Örnek: "main dalındaki my-project için pipeline'ı çalıştır"

  2. CircleCI URL'si Kullanarak:

  3. Yerel Proje Bağlamı Kullanarak:

    • Çalışma alanı kökü, git remote URL'si ve dal adı sağlayarak yerel çalışma alanınızdan çalışır

Araç, pipeline yürütmesini izlemek için bir bağlantı döndürür.

run_rollback_pipeline Bir CircleCI projesi için geri alma işlemini tetikler. Araç, etkileşimli olarak size şu adımlarda rehberlik eder:
  1. Proje Seçimi — seçim yapmanız için takip edilen projeleri listeler
  2. Ortam Seçimi — mevcut ortamları listeler (yalnızca bir tane varsa otomatik seçer)
  3. Bileşen Seçimi — mevcut bileşenleri listeler (yalnızca bir tane varsa otomatik seçer)
  4. Sürüm Seçimi — mevcut sürümleri gösterir; geri alma için hedefi seçersiniz
  5. Geri Alma Modu Tespiti — bir geri alma ardışık düzeninin yapılandırılıp yapılandırılmadığını kontrol eder
  6. Geri Almayı Yürüt — iki seçenek:
    • Ardışık Düzen Geri Alması: geri alma ardışık düzenini tetikler
    • İş Akışı Yeniden Çalıştırma: iş akışı kimliğini kullanarak önceki bir iş akışını yeniden çalıştırır
  7. Onay — yürütmeden önce özetler ve onay ister

Sorun Giderme

Hızlı Çözümler

En yaygın sorunlar:

  1. Paket önbelleklerini temizleyin:

    npx clear-npx-cache
npm cache clean --force

  2. En son sürüme zorlayın: Yapılandırmanıza @latest ekleyin:

    "args": ["-y", "@circleci/mcp-server-circleci@latest"]

  3. IDE'nizi tamamen yeniden başlatın (sadece pencereyi yeniden yüklemeyin)

Kimlik Doğrulama Sorunları
  • Geçersiz belirteç hataları: Kişisel API Belirteçleri sayfasından CIRCLECI_TOKEN doğrulayın
  • İzin hataları: Belirtecin projelerinize okuma erişimi olduğundan emin olun
  • Ortam değişkenleri yüklenmiyor: echo $CIRCLECI_TOKEN (Mac/Linux) veya echo %CIRCLECI_TOKEN% (Windows) ile test edin
Bağlantı ve Ağ Sorunları
  • Temel URL: CIRCLECI_BASE_URL adresinin https://circleci.com olduğunu doğrulayın
  • Kurumsal ağlar: Bir güvenlik duvarının arkasındaysanız npm proxy ayarlarını yapılandırın
  • Güvenlik duvarı engellemesi: Güvenlik yazılımının paket indirmelerini engelleyip engellemediğini kontrol edin
Sistem Gereksinimleri
  • Node.js sürümü: node --version ile >= 18.0.0 olduğundan emin olun
  • Node.js'i güncelleyin: Uyumluluk sorunları yaşıyorsanız en son LTS sürümünü değerlendirin
  • Paket yöneticisi: npm/pnpm'in çalıştığını doğrulayın: npm --version
IDE'ye Özgü Sorunlar
  • Yapılandırma dosyası konumu: İşletim sisteminiz için yolu iki kez kontrol edin
  • Sözdizimi hataları: Yapılandırma dosyanızdaki JSON sözdizimini doğrulayın
  • Konsol günlükleri: Belirli hatalar için IDE geliştirici konsolunu kontrol edin
  • Farklı bir IDE deneyin: Sorunu izole etmek için desteklenen başka bir düzenleyicide test edin
İşlem Sorunları

Asılı kalan işlemler — mevcut MCP işlemlerini sonlandırın:

# Mac/Linux:
pkill -f "mcp-server-circleci"

# Windows:
taskkill /f /im node.exe

Bağlantı noktası çakışmaları: Bağlantı engellenmiş gibi görünüyorsa IDE'nizi yeniden başlatın.

Gelişmiş Hata Ayıklama
  • Paketi doğrudan test edin: npx @circleci/mcp-server-circleci@latest --help
  • Ayrıntılı günlükleme: DEBUG=* npx @circleci/mcp-server-circleci@latest
  • Docker yedeği: npx sürekli başarısız olursa Docker kurulumunu deneyin

Hâlâ yardıma mı ihtiyacınız var?

  1. Benzer sorunlar için GitHub Sorunları sayfasını kontrol edin
  2. Sorun bildirirken işletim sisteminizi, Node sürümünüzü ve IDE'nizi ekleyin
  3. IDE konsolundan ilgili hata mesajlarını paylaşın

Telemetri

Sunucu, araç kullanımını izlemek için OpenTelemetry metriklerini destekler. DISABLE_TELEMETRY=true ayarlamadığınız sürece metrikler dışa aktarılır. Uzak dağıtımlarda metrikler, istekle aynı belirteci kullanır (kullanıcı başına PAT veya paylaşılan sunucu PAT'i).

MetrikAçıklama
circleci.mcp.tool.invocationsAraç çağrılma sayısı
circleci.mcp.tool.duration_msMilisaniye cinsinden yürütme süresi
circleci.mcp.tool.errorsHata sayısı

Geliştirme

Başlarken

  1. Depoyu klonlayın:

    git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci

  2. Bağımlılıkları yükleyin:

    pnpm install

  3. Projeyi derleyin:

    pnpm build

Docker Konteyneri Oluşturma

Docker konteynerini yerel olarak şu komutla oluşturabilirsiniz:

docker build -t circleci:mcp-server-circleci .

Bu, herhangi bir MCP istemcisiyle kullanabileceğiniz circleci:mcp-server-circleci olarak etiketlenmiş bir Docker imajı oluşturacaktır.

Yerel stdio modu (tek geliştirici, belirteç istemcide):

docker run --rm -i \
  -e CIRCLECI_TOKEN=your-circleci-token \
  -e CIRCLECI_BASE_URL=https://circleci.com \
  circleci/mcp-server-circleci

Uzak mod (bir ekip için merkezi sunucu): Kendi Kendine Yönetilen Uzak MCP Sunucusu sayfasına bakın.

MCP Inspector ile Geliştirme

MCP Sunucusu üzerinde yineleme yapmanın en kolay yolu MCP inspector kullanmaktır. MCP inspector hakkında daha fazla bilgiyi https://modelcontextprotocol.io/docs/tools/inspector adresinde bulabilirsiniz.

  1. Geliştirme sunucusunu başlatın:

    pnpm watch # Keep this running in one terminal

  2. Ayrı bir terminalde inspector'ı başlatın:

    pnpm inspector

  3. Ortamı yapılandırın:

    • Inspector kullanıcı arayüzündeki Ortam Değişkenleri bölümüne CIRCLECI_TOKEN ekleyin
    • Belirtecin CircleCI projelerinize okuma erişimi olması gerekir
    • İsteğe bağlı olarak CircleCI Temel URL'nizi ayarlayın (varsayılan https://circleci.com)

Test

  • Test paketini çalıştırın:

    pnpm test

  • Geliştirme sırasında testleri izleme modunda çalıştırın:

    pnpm test:watch

Daha ayrıntılı katkı yönergeleri için CONTRIBUTING.md sayfasına bakın.