opik-mcp

Opik + Ollie için Model Context Protocol sunucusu. AI ana bilgisayarınızı (Claude Code, Cursor, VS Code Copilot, MCP Inspector) doğrudan Opik çalışma alanınıza bağlayın — izlemeleri okuyun, puanları günlüğe kaydedin, istem sürümlerini kaydedin ve Ollie'ye araştırma soruları sorun, hepsi sohbetten.

LLM mühendisleri için inşa edildi — Opik'i zaten çalıştıran ve kod yazdıkları AI asistanından yönlendirmek isteyenler için.

Siz:    "Neden 'gpt-4o-rerank-v3' deneyi doğruluk açısından geriye gitti?"
Claude: → ask_ollie → denemi + izlemeleri okur → "Üç izleme başarısız oldu çünkü…"

Siz:    "7f2e… izlemesini yardımcılık üzerinde 0.9 puan ver, sebep 'harika toparlanış'."
Claude: → write(score.create) → bitti

Kurulum

opik-mcp bir Python paketidir (Python 3.13+ gereklidir). Önerilen çalıştırma yöntemi uvx'dir — en son yayınlanan sürümü talep üzerine getirir ve çalıştırır — genel kurulum yok, virtualenv oyunlaştırması yok.

uv bir kez yükleyin:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# veya: brew install uv

Opik çalışma alanınızdan iki şeye ihtiyacınız var:

OPIK_API_KEY — comet.com/api/my/settings/ adresinden alın.
COMET_WORKSPACE — çalışma alanı adınız (küçük harf, URL'de göründüğü gibi). Örn. https://www.comet.com/acme-ai/... → COMET_WORKSPACE=acme-ai. ask_ollie için gerekli; başka yerlerde isteğe bağlı ama önerilen (kapsam ve analizler için kullanılır).

Ön-yayın notu: opik-mcp (Python) henüz PyPI'ye yayınlanmadı. İlk PyPI yayını çıkana kadar, aşağıdaki herhangi bir snippet'teki uvx opik-mcp komutunu şununla değiştirin: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

Claude Code

Sunucuyu bir komutla ekleyin:

claude mcp add --transport stdio opik-mcp \
  --env OPIK_API_KEY=<your-key> \
  --env COMET_WORKSPACE=<your-workspace> \
  -- uvx opik-mcp

Veya doğrudan ~/.claude.json dosyasını düzenleyin:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Claude Code'u yeniden başlatın. /mcp ile doğrulayın — opik-mcp bağlı olarak görünmelidir. Ardından sohbette şunu sorun: "Opik projelerimi listele" — Claude list aracını çağıracak ve çalışma alanınızın projelerini göreceksiniz.

Cursor

~/.cursor/mcp.json (genel) veya .cursor/mcp.json (proje) dosyasını düzenleyin, ya da açın Cmd+Shift+J → Features → Model Context Protocol:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Cursor'u yeniden yükleyin; MCP panelinde opik-mcp yanındaki yeşil nokta bağlantıyı onaylar. Sohbette sorun: "Opik projelerimi listele".

Cursor 60s zaman aşımı. Cursor, ilerleme bildirimleriyle sıfırlanmayan sabit bir araç çağrısı zaman aşımı uygular. Uzun ask_ollie turları Cursor'da başarısız olur. Bkz. Bilinen ana bilgisayar sınırlamaları.

VS Code Copilot

.vscode/mcp.json (çalışma alanınızda) veya Kullanıcı Ayarları JSON:

{
  "servers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_WORKSPACE": "<your-workspace>"
      }
    }
  }
}

Pencereyi yeniden yükleyin; Copilot Sohbet MCP göstergesi sunucuya ulaşıldığında opik-mcp gösterir. Sohbette sorun: "Opik projelerimi listele".

MCP Inspector (manuel test)

OPIK_API_KEY=<your-key> COMET_WORKSPACE=<your-workspace> \
  npx @modelcontextprotocol/inspector uvx opik-mcp

Kendi kendine barındırılan Opik

COMET_URL_OVERRIDE (ve OPIK_URL — Opik varsayılan olmayan bir yolda yaşıyorsa) ekleyin ana bilgisayar yapılandırmasındaki env bloğuna:

{
  "mcpServers": {
    "opik-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opik-mcp"],
      "env": {
        "OPIK_API_KEY": "<your-key>",
        "COMET_URL_OVERRIDE": "https://opik.your-company.com",
        "OPIK_MCP_ANALYTICS_SOURCE": ""
      }
    }
  }
}

ask_ollie ve run_experiment yalnızca Comet Cloud'da kullanılabilir — kendi kendine barındırılan Opik'te bu çağrılar gönderimde başarısız olur, bunun yerine read / list / write komutlarını doğrudan kullanın. OPIK_MCP_ANALYTICS_SOURCE=""'ı ayarlamak, kendi barındırılan kurulumunuzu telemetri olaylarındaki bulut-Comet kaynak etiketi dışında tutar.

Araçlar

opik-mcp küçük, sonuç odaklı bir yüzey ortaya koymaktadır — tam yaşam döngüsünü kapsayan altı araç (oku → açıklama yap → seç → yaz → tekrarla).

Araç	Amaç
`read`	Kimlik / ad / `opik://` URI ile evrensel okuma
`list`	İsteğe bağlı ad filtresi + sayfalama ile evrensel liste
`ask_ollie`	Opik ürün içi asistanı aracılığıyla araştırma / sentez
`write`	Evrensel yazma — izlemeleri/span'ları günlüğe kaydet, puan ver, yorum yap, istemler kaydet, test paketlerini & deneyleri yönet
`schema`	Yazma işlemi şemalarını içeriye alın (LLM tarafından geçerli yükleri oluşturmak için kullanılır)
`run_experiment`	Değerlendirme deneyini uçtan uca Ollie aracılığıyla çalıştır

`read`

Herhangi bir "bana X'i göster" sorusu için bir araç. entity_type artı id (UUID veya ad verilebilen türler için bir ad) veya tam opik:// URI alır. Bileşik okumalar (trace, prompt) çocuklarını satır içine yerleştirip tam resmi tek bir çağrı ile döndürür.

Desteklenen varlıklar: project, trace, span, test_suite, experiment, prompt. Ad tabanlı arama project, experiment, prompt, test_suite için kullanılabilir (daha yavaş — iki API çağrısı — ve birden çok eşleşme döndürebilir).

read(entity_type="trace", id="7f2e3c8a-…")
read(entity_type="project", id="demo")          # ad araması
read(entity_type="trace", id="opik://traces/7f2e3c8a-…")

`list`

İsteğe bağlı ad filtresi ve sayfalama ile koleksiyon göz atın. Proje kapsamlı türler (trace, test_suite_item, prompt_version) üst UUID gerektirir.

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # ad alt dizesi filtresi
list(entity_type="trace", project_id="<project-uuid>") # bir projenin izlemeleri

`ask_ollie`

Araştırma soruları, varlıklar arası sentez, veya Opik alan uzmanlığına ihtiyaç duyan herhangi bir şey için. Ollie çalışma alanınıza doğrudan okuma erişimine sahiptir ve istendiğinde akış sırasında yazma işlemleri (puanlar, yorumlar, test paket öğeleri, istem sürümleri) yürütebilir.

ask_ollie(query="Neden 'demo' projesindeki span'lar bu hafta geçen haftadan daha yavaş?")
ask_ollie(query="A ve B deneylerini doğruluk üzerinde karşılaştır. A'nın alt 5 izlemesini 0.2 puan ver, sebep yaz.")

Asistanın son metni artı thread_id döndürür. İzleme sırasında bunu geri iletin bağlamı korumak için — Ollie'nin iş parçacıkları arasında hafızası yok.

YOLO modu (varsayılan). Ollie'nin akış sırasında gerçekleştirdiği yazma işlemleri işlem başına onay olmaksızın yürütülür. Her otomatik onay opik_mcp.audit Python günlüğüne JSON denetim satırı olarak kaydedilir. Bunun yerine onay gerektirmek için, OPIK_MCP_AUTO_APPROVE=disabled ayarlayın — Ollie'nin onay istekleri yazılı hatalar olarak ortaya çıkıp manuel olarak yeniden yayınlayabilirsiniz.

Yalnızca Comet Cloud'da kullanılabilir.

`write`

Evrensel yazma gönderici. operation + data geçirin ve gönderici yükü doğrular, uygun REST fiilini uygular, arka uç yanıtını döndürür.

İşlemler:

İşlem	Ne yapar
`trace.create`	Tek bir izleme (veya bir toplu işi) günlüğe kaydet. Span'lar / puanlar / yorumlar için üst.
`trace.update`	Mevcut izlemeyi sonlandır veya değiştir.
`span.create`	Mevcut izlemede bir span günlüğe kaydet (veya toplu işi).
`score.create`	Sayısal geri bildirim puanını izleme, span veya iş parçacığına ekle.
`comment.create`	Serbest metin yorumunu izleme, span veya iş parçacığına ekle.
`prompt_version.save`	Yeni istem sürümünü kaydet (eksikse istem adıyla oluştur).
`test_suite.create`	Değerlendirme test paketi oluştur.
`test_suite_item.upsert`	Test paketine öğe ekle/güncelle (her zaman zarf şekli).
`experiment.create`	Test paketine kapsamlı deney oluştur.
`experiment_item.create`	Trace + veri kümesi öğe satırlarını deneye ekle.

write(operation="score.create", data={
  "target": "trace",
  "target_id": "7f2e3c8a-…",
  "name": "helpfulness",
  "value": 0.9,
  "reason": "great recovery"
})

`schema`

Yazma işlemini çağırmadan önce — tam JSON şeklini ve gerekli alanlarını inceleyin — data neye benzemeli bilmiyorsanız yararlı. Şemayı, OAuth kapsamını, ve geçerli bir örnek döndürür. Saf arama, arka uç çağrısı yok.

schema(operation="score.create")
schema(operation="prompt_version.save")

`run_experiment`

Değerlendirme deneyini uçtan uca Ollie aracılığıyla çalıştırın. Opik'in deney şeklini (istem, test paketi, puanlayıcılar) yansıtan tek bir experiment_config sözlüğü alır; Ollie çalışmayı yürütür ve sonuçları Opik deneyine geri yazar.

run_experiment(experiment_config={
  "test_suite_name": "qa-eval-v2",
  "prompt_name": "welcome-msg",
  # … tam şekil için `schema(operation="experiment.create")` öğesine bakın
})

Yalnızca Comet Cloud'da kullanılabilir.

Yapılandırma

Her ayar bir ortam değişkenidir. Gerekli olanlar kalın'da.

Kimlik / uç nokta

Değişken	Varsayılan	Notlar
`OPIK_API_KEY`	—	`ask_ollie` ve doğrulanmış okuma/yazma için gerekli.
`COMET_WORKSPACE`	—	Çalışma alanı adı. `ask_ollie` için gerekli.
`COMET_WORKSPACE_ID`	—	İsteğe bağlı çalışma alanı UUID. Ayarlandığında analitik olaylarına damgalanır; BI kararlı kimlikle katılabilir — değişken çalışma alanı adı yerine.
`COMET_URL_OVERRIDE`	`https://www.comet.com`	Kendi kendine barındırılan Comet ana bilgisayarınıza, veya hazırlık için `https://dev.comet.com` ayarlayın.
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api` türetilmiş	Yalnızca Opik Comet UI'dan farklı konakta/yolda yaşıyorsa geçersiz kılın.
`OPIK_DEFAULT_PROJECT_NAME`	ayarlanmamış	Ayarlandığında, oturum başına `instructions` blobu LLM'ye her araç çağrısında bu değeri `project_name` olarak geçmesini söyler — kullanıcı farklı proje adlandırmadığı sürece.

Sunucu / aktarım

Değişken	Varsayılan	Notlar
`OPIK_MCP_TRANSPORT`	`stdio`	Konak tarafından başlatılan `stdio`, port dinlemek için `streamable-http`.
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn bağlama konağı (`streamable-http` yalnızca).
`OPIK_MCP_PORT`	`8080`	uvicorn bağlama portu (`streamable-http` yalnızca).
`OPIK_MCP_RELOAD`	`false`	uvicorn `--reload` etkinleştirmek için `true` (geliştirme yalnızca).
`OPIK_MCP_DEV_TOKEN`	`dev-token-123`	HTTP aktarımının gerektirdiği taşıyıcı belirteci.
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr günlükçü eşiği.

Ollie / uzun çağrılar

Değişken	Varsayılan	Notlar
`OPIK_MCP_AUTO_APPROVE`	`enabled`	Ollie'nin akış sırasında yazma işlemlerinin ilerlemesi için işlem başına onay gereklidir. MCP `elicitation` yeteneğini yayan ana bilgisayarlarda kullanıcı evet/hayır istemini görür; daha saf ana bilgisayarlarda istek yazılı hata olarak ortaya çıkıp manuel olarak yeniden yayınlayabilirsiniz.
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie'nin akış sırasında onay istemi kullanıcıdan yanıt bekleyebilir — sonrası iptal olarak ele alınır. `0` sınırı devre dışı bırakır (yalnızca hata ayıklama).
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie pod soğuk başlatma yoklama sınırı.
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	Soğuk başlatma yoklama aralığı.
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	İzleme hızı — pod sessizken `notifications/progress` işareti yayar, ana bilgisayar zaman aşımlarını canlı tutar.
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	Pod sessizliğinde sabit tavan — `ask_ollie` iptal etmeden. `0` devre dışı bırakır (yalnızca hata ayıklama).

Telemetri

Anonim kullanım olayları (olay türü + zamanlama yalnızca — sorgu içeriği yok). API anahtarınızın SHA-256 özeti destek tarafından hesabı bulabilmesi için dahil edilir; ham anahtar asla işlemden çıkmaz. Devre dışı bırak: OPIK_MCP_ANALYTICS_ENABLED=false.

Değişken	Varsayılan	Notlar
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	Tüm telemetriyi devre dışı bırakmak için `false` ayarlayın.
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	Hazırlık için geçersiz kılın.
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	Her olayda etiket (`prod` / `staging` / `dev`).
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	Alıcı bunu `on_prem=False` işaretlemek için kullanır. Kendi kendine barındırılan kurulumlar `""` veya kendi etki alanlarına geçersiz kılmalı.
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP bağlantı zaman aşımı.
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP toplam istek zaman aşımı.

Bilinen ana bilgisayar sınırlamaları

MCP belirtimi ana bilgisayarlara araç çağrısı zaman aşımlarını notifications/progress üzerinde sıfırlamasına izin verir — opik-mcp Ollie SSE olayı başına bir tane artı 15 saniyelik izleme kalp atışı yayar. Gerçeklik eşitsizdir:

Claude Code — belgelenen araç çağrısı zaman aşımı yok; kalp atışı çağrıyı message_end kadar canlı tutar. Önerilir.
Cursor — ilerleme bildirimleriyle sıfırlanmayan sabit 60s zaman aşımı (yukarı akış hatası). Uzun Ollie turları başarısız olur. ask_ollie sorgularını odaklanmış tutun.
MCP Inspector — MAX_TOTAL_TIMEOUT toplam süreyi sınırlar (varsayılan 60s). Uzun işlemler için Inspector UI'da artırın.

Bir çağrı sıkışırsa, OPIK_MCP_LOG_LEVEL=DEBUG ayarlayın — kalp atışı başarısızlıkları (genellikle ana bilgisayar bağlantısı kesintileri) opik_mcp.ask_ollie üzerinde hata ayıklama düzeyinde günlüğe kaydedilir.

Sorun Giderme

OPIK_API_KEY is required to use ask_ollie — değişken sunucu işlemine ulaşmıyor. Claude Code / Cursor / VS Code'da ortam değişkenleri yalnızca MCP sunucu yapılandırmasının env bloğu içinde uygulanır, kabuğunuz değil. Düzenledikten sonra ana bilgisayarı yeniden başlatın.

ask_ollie 2 dakika sonra "pod not ready" döndürür — Ollie pod soğuk başlatması OPIK_MCP_POD_READY_TIMEOUT_S aşmıştır. Yeniden deneyin — ikinci çağrı genellikle sıcak pod'u isabet ettirir.

ask_ollie / run_experiment kendi kendine barındırılan Opik'te gönderim hatası ile başarısız olur — bu araçlar yalnızca Comet Cloud'da kullanılabilir. Kendi kendine barındırılan sistemde read / list / write komutlarını doğrudan kullanın.

Cursor çağrısı 60s'de zaman aşımına uğrar — Cursor'un bilinen hatası, opik-mcp değil. Ya Ollie sorgusunu kısaltın ya da aynı işlemi Claude Code'da çalıştırın — sabit sınır yok.

Geliştirme

git clone git@github.com:comet-ml/opik-mcp.git
cd opik-mcp
make install        # uv sync --extra dev
make check          # lint + typecheck + test
make run-dev        # uvicorn with --reload + DEBUG logs
make inspect        # MCP Inspector against the running server

Yaygın hedefler:

Hedef	Ne yapar
`make install`	`uv sync --extra dev`
`make run`	MCP sunucusunu çalıştır (varsayılan stdio).
`make run-dev`	DEBUG günlüğe + uvicorn `--reload` ile çalıştır.
`make dev`	`mcp dev` aracılığıyla çalıştır (Inspector geliştirme modu sarmalayıcısı).
`make inspect`	Çalışan sunucuya karşı MCP Inspector başlat.
`make test`	`uv run pytest -q`.
`make test-live`	`dev.comet.com`'a karşı canlı uçtan uca (`OPIK_API_KEY` + `COMET_WORKSPACE` ayarlayın).
`make lint`	`ruff check` + format kontrolü.
`make format`	`ruff format` + `ruff check --fix`.
`make typecheck`	`mypy`.
`make check`	`lint + typecheck + test`.

Depo düzeni:

opik-mcp/
├── src/opik_mcp/        ← sunucu, araçlar, ask_ollie, analizler
├── tests/               ← pytest paketleri
├── scripts/             ← canlı-BE fumarası + MCP oturumu fumarası
├── legacy/typescript/   ← kullanım dışı v2 TS sunucusu
├── pyproject.toml
└── Makefile

Yardım Alın

Hatalar ve özellik istekleri için sorun açın
SDK / arka uç belgeleri için Opik belgeleri
Sorular için Comet toplumu Slack

v2'den yükseltiliyor mu? Eski TypeScript sunucusu npm üzerinde opik-mcp@^2 (npx -y opik-mcp) olarak yayınlanmaya devam ediyor; kaynak legacy/typescript/ altında saklanıyor. Destek politikası için legacy/typescript/DEPRECATED.md öğesine bakın.

Lisans

Apache-2.0.

comet-ml/opik-mcp

Bu MCP sunucusu hakkında