Comet Opik

आधिकारिक

अपने Opik लॉग, ट्रेस, प्रॉम्प्ट और अपने LLMs से प्राप्त सभी अन्य टेलीमेट्री डेटा को प्राकृतिक भाषा में क्वेरी और विश्लेषण करें।

GitHub

212

Comet Opik MCP के साथ आप क्या कर सकते हैं?

प्रोजेक्ट, प्रयोग और ट्रेस ब्राउज़ करें — वैकल्पिक नाम फ़िल्टर और पेजिनेशन के साथ अपने वर्कस्पेस को एक्सप्लोर करने के लिए list का उपयोग करें।
किसी भी एंटिटी को ID, नाम या URI द्वारा निरीक्षण करें — प्रोजेक्ट, ट्रेस, स्पैन, प्रयोग, प्रॉम्प्ट या टेस्ट सूट पर read कॉल करें, जिसमें चाइल्ड एंटिटी स्वचालित रूप से शामिल हों।
Ollie से रिग्रेशन की जांच करने या प्रयोगों की तुलना करने के लिए कहें — ask_ollie क्रॉस-एंटिटी उत्तरों को संश्लेषित करता है और मिड-स्ट्रीम ट्रेस पर स्कोर या टिप्पणी कर सकता है।
स्कोर, टिप्पणियाँ, ट्रेस और स्पैन लॉग करें — चैट से सीधे score.create, trace.create या span.create जैसे write ऑपरेशन भेजें।
प्रॉम्प्ट वर्ज़न सेव करें और टेस्ट सूट प्रबंधित करें — prompt_version.save, test_suite.create या test_suite_item.upsert के साथ write का उपयोग करें।
एंड-टू-एंड मूल्यांकन प्रयोग चलाएं — run_experiment आपके द्वारा निर्दिष्ट प्रॉम्प्ट, टेस्ट सूट और स्कोरर्स का उपयोग करके Ollie के माध्यम से पूर्ण मूल्यांकन निष्पादित करता है।

दस्तावेज़

opik-mcp

पुराने npx opik-mcp से माइग्रेट कर रहे हैं? TypeScript सर्वर अब पदावनत (deprecated) है और 2026-11-15 को बंद हो जाएगा। अपने MCP क्लाइंट कॉन्फ़िग में npx -y opik-mcp को uvx opik-mcp@latest से बदलें। पूरी गाइड: legacy/typescript/MIGRATION.md.

Opik + Ollie के लिए मॉडल कॉन्टेक्स्ट प्रोटोकॉल सर्वर। अपने AI होस्ट (Claude Code, Cursor, VS Code Copilot, MCP Inspector) को सीधे अपने Opik वर्कस्पेस से जोड़ें — ट्रेसेस पढ़ें, स्कोर लॉग करें, प्रॉम्प्ट वर्ज़न सेव करें, और Ollie से जांच-पड़ताल वाले सवाल पूछें, सब कुछ चैट से।

उन LLM इंजीनियरों के लिए बनाया गया है जो पहले से Opik चलाते हैं और इसे उसी AI असिस्टेंट से संचालित करना चाहते हैं जिसके साथ वे कोड करते हैं।

You:    "Why did the experiment 'gpt-4o-rerank-v3' regress on factuality?"
Claude: → ask_ollie → reads experiment + traces → "Three traces failed because…"

You:    "Score trace 7f2e… 0.9 on helpfulness with reason 'great recovery'."
Claude: → write(score.create) → done

इंस्टॉल करें

opik-mcp एक Python पैकेज है (Python 3.13+ आवश्यक)। इसे चलाने का अनुशंसित तरीका uvx है, जो मांग पर नवीनतम प्रकाशित संस्करण प्राप्त करता है और चलाता है — कोई ग्लोबल इंस्टॉल नहीं, कोई virtualenv उलझन नहीं।

uv को एक बार इंस्टॉल करें:

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

आपको अपने Opik वर्कस्पेस से दो चीज़ों की आवश्यकता होगी:

OPIK_API_KEY — इसे comet.com/api/my/settings/ से प्राप्त करें।
OPIK_WORKSPACE — आपका वर्कस्पेस नाम (लोअरकेस, जैसा URL में दिखता है)। उदा. https://www.comet.com/acme-ai/... → OPIK_WORKSPACE=acme-ai। वैकल्पिक — डिफ़ॉल्ट default (Opik SDK परंपरा) है, जो स्थानीय/OSS इंस्टॉल के लिए सही है; नामित वर्कस्पेस वाले क्लाउड उपयोगकर्ताओं को इसे सेट करना चाहिए। COMET_WORKSPACE को एक पदावनत उपनाम के रूप में स्वीकार किया जाता है।

प्री-रिलीज़ नोट: opik-mcp (Python) अभी तक PyPI पर प्रकाशित नहीं हुआ है। जब तक पहला PyPI रिलीज़ नहीं आ जाता, नीचे किसी भी स्निपेट में uvx opik-mcp को इससे बदलें: uvx --from git+https://github.com/comet-ml/opik-mcp.git opik-mcp

OPIK_WORKSPACE वैकल्पिक है। नीचे किसी भी स्निपेट में OPIK_WORKSPACE लाइन/की को छोड़ दें और सर्वर default वर्कस्पेस का उपयोग करता है (स्थानीय/OSS इंस्टॉल के लिए सही)। इसे केवल तभी सेट करें जब आप किसी नामित क्लाउड वर्कस्पेस से कनेक्ट करते हैं।

Claude Code

एक कमांड से सर्वर जोड़ें:

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

या सीधे ~/.claude.json संपादित करें:

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

Claude Code को पुनरारंभ करें। /mcp से सत्यापित करें — opik-mcp कनेक्टेड दिखना चाहिए। फिर, चैट में पूछें: "list my Opik projects" — Claude list टूल को कॉल करेगा और आपको अपने वर्कस्पेस के प्रोजेक्ट दिखाई देंगे।

Cursor

~/.cursor/mcp.json (ग्लोबल) या .cursor/mcp.json (प्रोजेक्ट) संपादित करें, या Cmd+Shift+J → Features → Model Context Protocol खोलें:

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

Cursor को पुनः लोड करें; MCP पैनल में opik-mcp के बगल में हरी बिंदी कनेक्शन की पुष्टि करती है। चैट में पूछें: "list my Opik projects"।

Cursor 60s टाइमआउट। Cursor एक हार्ड टूल-कॉल टाइमआउट लागू करता है जो प्रगति सूचनाओं पर रीसेट नहीं होता। लंबे ask_ollie टर्न Cursor पर विफल हो जाएंगे। देखें ज्ञात होस्ट सीमाएं।

VS Code Copilot

अपने वर्कस्पेस (या User Settings JSON) में .vscode/mcp.json:

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

विंडो को पुनः लोड करें; सर्वर के पहुंच योग्य होने पर Copilot Chat MCP संकेतक opik-mcp दिखाता है। चैट में पूछें: "list my Opik projects"।

MCP Inspector (मैन्युअल परीक्षण)

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

स्व-होस्टेड Opik

अपने होस्ट कॉन्फ़िग में उसी env ब्लॉक में COMET_URL_OVERRIDE (और OPIK_URL यदि Opik गैर-डिफ़ॉल्ट पथ पर रहता है) जोड़ें:

{
  "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 और run_experiment केवल Comet Cloud पर उपलब्ध हैं — स्व-होस्टेड पर वे कॉल डिस्पैच पर विफल हो जाएंगे, इसलिए सीधे read / list / write का उपयोग करें। OPIK_MCP_ANALYTICS_SOURCE="" सेट करने पर आपका इंस्टॉल टेलीमेट्री ईवेंट पर क्लाउड-कॉमेट स्रोत लेबल से बाहर हो जाता है।

टूल्स

opik-mcp एक छोटी, परिणाम-उन्मुख सतह प्रस्तुत करता है — छह टूल जो पूर्ण जीवनचक्र को कवर करते हैं (पढ़ें → एनोटेट करें → क्यूरेट करें → लेखक करें → पुनरावृत्ति करें)।

टूल	उद्देश्य
`read`	id / नाम / `opik://` URI द्वारा सार्वभौमिक पठन
`list`	वैकल्पिक नाम फ़िल्टर + पृष्ठांकन के साथ सार्वभौमिक सूची
`ask_ollie`	Opik इन-प्रोडक्ट असिस्टेंट के माध्यम से जांच / संश्लेषण
`write`	सार्वभौमिक लेखन — ट्रेस/स्पैन लॉग करें, स्कोर करें, टिप्पणी करें, प्रॉम्प्ट सहेजें, परीक्षण सूट और प्रयोग प्रबंधित करें
`schema`	लेखन-संचालन स्कीमा का आत्मनिरीक्षण (मान्य पेलोड बनाने के लिए LLM द्वारा उपयोग किया जाता है)
`run_experiment`	Ollie के माध्यम से एंड-टू-एंड मूल्यांकन प्रयोग चलाएं

`read`

किसी भी "मुझे X दिखाओ" प्रश्न के लिए एक टूल। एक entity_type और एक id (UUID या, नाम योग्य प्रकारों के लिए, एक नाम) या एक पूर्ण opik:// URI लेता है। समग्र पठन (trace, prompt) अपने चिल्ड्रन को इनलाइन करते हैं ताकि एक ही कॉल पूरी तस्वीर लौटाए।

समर्थित इकाइयां: project, trace, span, test_suite, experiment, prompt। नाम-आधारित लुकअप project, experiment, prompt, test_suite के लिए उपलब्ध है (धीमा — दो API कॉल — और कई मिलान लौटा सकता है)।

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

`list`

वैकल्पिक नाम फ़िल्टर और पृष्ठांकन के साथ एक संग्रह ब्राउज़ करें। प्रोजेक्ट-स्कोप्ड प्रकारों (trace, test_suite_item, prompt_version) को उनके जनक UUID की आवश्यकता होती है।

list(entity_type="experiment", page=1, size=25)
list(entity_type="experiment", name="rerank")          # name substring filter
list(entity_type="trace", project_id="<project-uuid>") # traces of one project

`ask_ollie`

जांच-पड़ताल वाले प्रश्नों, क्रॉस-एंटिटी संश्लेषण, या किसी भी चीज़ के लिए जिसे Opik डोमेन विशेषज्ञता की आवश्यकता हो। Ollie के पास आपके वर्कस्पेस तक सीधी पठन पहुंच है और कहे जाने पर मध्य-स्ट्रीम लेखन (स्कोर, टिप्पणियां, परीक्षण-सूट आइटम, प्रॉम्प्ट संस्करण) निष्पादित कर सकता है।

ask_ollie(query="Why are spans in project 'demo' slower this week than last?")
ask_ollie(query="Compare experiments A and B on factuality. Score the bottom 5 traces of A 0.2 with reason.")

असिस्टेंट का अंतिम पाठ और एक thread_id लौटाता है। संदर्भ बनाए रखने के लिए अनुवर्ती कार्रवाइयों पर इसे वापस पास करें — Ollie के पास थ्रेड्स में कोई मेमोरी नहीं है।

YOLO मोड (डिफ़ॉल्ट)। Ollie मध्य-स्ट्रीम में जो लेखन करता है वह प्रति-क्रिया पुष्टि के बिना निष्पादित होता है। प्रत्येक ऑटो-अनुमोदन opik_mcp.audit Python लॉगर पर एक JSON ऑडिट पंक्ति के रूप में लॉग किया जाता है। इसके बजाय पुष्टि की आवश्यकता के लिए, OPIK_MCP_AUTO_APPROVE=disabled सेट करें — Ollie के पुष्टि अनुरोध तब टाइप्ड त्रुटियों के रूप में सामने आते हैं जिन्हें आप मैन्युअल रूप से पुनः जारी कर सकते हैं।

केवल Comet Cloud पर उपलब्ध।

`write`

सार्वभौमिक लेखन डिस्पैचर। operation + data पास करें और डिस्पैचर पेलोड को मान्य करता है, सही REST क्रिया लागू करता है, और बैकएंड प्रतिक्रिया लौटाता है।

संचालन:

संचालन	यह क्या करता है
`trace.create`	एकल ट्रेस (या बैच) लॉग करें। स्पैन / स्कोर / टिप्पणियों के लिए जनक।
`trace.update`	मौजूदा ट्रेस को अंतिम रूप दें या संशोधित करें।
`span.create`	मौजूदा ट्रेस पर स्पैन लॉग करें (या बैच)।
`score.create`	ट्रेस, स्पैन, या थ्रेड पर संख्यात्मक फीडबैक स्कोर संलग्न करें।
`comment.create`	ट्रेस, स्पैन, या थ्रेड पर मुक्त-पाठ टिप्पणी संलग्न करें।
`prompt_version.save`	नया प्रॉम्प्ट संस्करण सहेजें (यदि अनुपलब्ध हो तो नाम से प्रॉम्प्ट बनाता है)।
`test_suite.create`	मूल्यांकन परीक्षण सूट बनाएं।
`test_suite_item.upsert`	परीक्षण सूट में आइटम अपसर्ट करें (हमेशा लिफाफा आकार)।
`experiment.create`	परीक्षण सूट के दायरे में प्रयोग बनाएं।
`experiment_item.create`	प्रयोग में ट्रेस + dataset_item पंक्तियां संलग्न करें।

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

`schema`

किसी भी लेखन संचालन को कॉल करने से पहले उसके सटीक JSON आकार और आवश्यक फ़ील्ड का निरीक्षण करें — उपयोगी जब आप सुनिश्चित नहीं हैं कि data कैसा दिखना चाहिए। स्कीमा, OAuth स्कोप, और एक मान्य उदाहरण लौटाता है। शुद्ध लुकअप, कोई बैकएंड कॉल नहीं।

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

`run_experiment`

Ollie के माध्यम से एंड-टू-एंड मूल्यांकन प्रयोग चलाएं। एक एकल experiment_config डिक्ट लेता है जो Opik के प्रयोग आकार (प्रॉम्प्ट, परीक्षण सूट, स्कोरर) को दर्शाता है; Ollie रन निष्पादित करता है और परिणामों को Opik प्रयोग के रूप में वापस लिखता है।

run_experiment(experiment_config={
  "test_suite_name": "qa-eval-v2",
  "prompt_name": "welcome-msg",
  # … see `schema(operation="experiment.create")` for the full shape
})

केवल Comet Cloud पर उपलब्ध।

कॉन्फ़िगरेशन

प्रत्येक सेटिंग एक पर्यावरण चर है। आवश्यक बोल्ड में।

पहचान / एंडपॉइंट

चर	डिफ़ॉल्ट	नोट्स
`OPIK_API_KEY`	—	`ask_ollie` और किसी भी प्रमाणित पठन/लेखन के लिए आवश्यक।
`OPIK_WORKSPACE`	`default`	वर्कस्पेस नाम। वैकल्पिक — `default` (Opik SDK परंपरा) पर वापस आता है। नामित वर्कस्पेस वाले क्लाउड उपयोगकर्ताओं को इसे सेट करना चाहिए।
`COMET_WORKSPACE`	—	`OPIK_WORKSPACE` के लिए पदावनत उपनाम (पिछड़ा संगत)। यदि दोनों सेट हैं तो `OPIK_WORKSPACE` जीतता है।
`COMET_WORKSPACE_ID`	—	वैकल्पिक वर्कस्पेस UUID। सेट होने पर एनालिटिक्स ईवेंट में मुहर लगाई जाती है ताकि BI (परिवर्तनीय) वर्कस्पेस नाम के बजाय एक स्थिर आईडी पर जुड़ सके।
`COMET_URL_OVERRIDE`	`https://www.comet.com`	अपने स्व-होस्टेड Comet होस्ट पर सेट करें, या स्टेजिंग के लिए `https://dev.comet.com`।
`OPIK_URL`	`COMET_URL_OVERRIDE` + `/opik/api` से व्युत्पन्न	केवल तभी ओवरराइड करें जब Opik Comet UI से भिन्न होस्ट/पथ पर रहता हो।
`OPIK_DEFAULT_PROJECT_NAME`	अनसेट	सेट होने पर, प्रति-सत्र `instructions` ब्लॉब LLM को बताता है कि इसे हर टूल कॉल पर `project_name` के रूप में पास करें जब तक उपयोगकर्ता कोई भिन्न प्रोजेक्ट नाम न दे।

सर्वर / ट्रांसपोर्ट

चर	डिफ़ॉल्ट	नोट्स
`OPIK_MCP_TRANSPORT`	`stdio`	होस्ट-लॉन्च के लिए `stdio`, पोर्ट पर सुनने के लिए `streamable-http`।
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn बाइंड होस्ट (केवल `streamable-http`)।
`OPIK_MCP_PORT`	`8080`	uvicorn बाइंड पोर्ट (केवल `streamable-http`)।
`OPIK_MCP_RELOAD`	`false`	uvicorn `--reload` सक्षम करने के लिए `true` (केवल dev)।
`OPIK_MCP_AS_URL`	अनसेट	OAuth प्राधिकरण सर्वर URL, `/.well-known/oauth-protected-resource` (RFC 9728) में विज्ञापित और AS-डिस्कवरी प्रोब के लिए प्रॉक्सी लक्ष्य के रूप में उपयोग किया जाता है। MCP होस्ट के लिए HTTP पर OAuth नृत्य बूटस्ट्रैप करने हेतु आवश्यक।
`OPIK_MCP_RESOURCE_URI`	अनसेट	इस सर्वर का कैनोनिकल सार्वजनिक URI, संरक्षित-संसाधन मेटाडेटा में `resource` के रूप में विज्ञापित और `WWW-Authenticate` संकेत प्राप्त करने के लिए उपयोग किया जाता है।
`OPIK_MCP_LOG_LEVEL`	`INFO`	stderr लॉगर सीमा।

ट्रांसपोर्ट चुनना

opik-mcp HTTP ट्रांसपोर्ट पर कोई स्थानीय क्रेडेंशियल सत्यापन नहीं करता: कोई भी सुगठित Authorization: Bearer … (एक Opik API कुंजी या एक opik_mcp_at_… OAuth एक्सेस टोकन) शब्दशः opik-backend को अग्रेषित किया जाता है, जो प्रमाणीकरण प्रवर्तन का एकल बिंदु है। परिनियोजन आकार द्वारा ट्रांसपोर्ट चुनें:

परिदृश्य	ट्रांसपोर्ट
MCP क्लाइंट और Opik एक ही मशीन पर (स्थानीय OSS इंस्टॉल)	stdio (अनुशंसित — सरलतम, कोई पोर्ट नहीं, कोई OAuth सेटअप नहीं)
स्थानीय MCP क्लाइंट → दूरस्थ Opik (Comet cloud / स्व-होस्टेड)	`OPIK_API_KEY` के साथ stdio, या OAuth के साथ HTTP (`OPIK_MCP_AS_URL` बैकएंड की ओर इंगित)
होस्टेड opik-mcp opik-backend के समान किनारे के पीछे	HTTP — बियरर्स प्रति अनुरोध बैकएंड द्वारा मान्य किए जाते हैं

स्थानीय OSS इंस्टॉल के लिए नोट: OSS बैकएंड अनुरोधों को प्रमाणित नहीं करता, इसलिए इसके सामने एक HTTP opik-mcp उतना ही खुला है जितना OSS REST API स्वयं। साझा नेटवर्क पर डिफ़ॉल्ट 127.0.0.1 बाइंड रखें (और stdio को प्राथमिकता दें)।

Ollie / लंबी कॉल

चर	डिफ़ॉल्ट	नोट्स
`OPIK_MCP_AUTO_APPROVE`	`enabled`	Ollie के मध्य-स्ट्रीम लेखन आगे बढ़ने से पहले प्रति-क्रिया अनुमोदन की आवश्यकता के लिए `disabled`। MCP `elicitation` क्षमता का विज्ञापन करने वाले होस्ट पर उपयोगकर्ता को हां/ना प्रॉम्प्ट दिखता है; कम बुद्धिमान होस्ट पर अनुरोध एक टाइप्ड त्रुटि के रूप में सामने आता है जिसे आप मैन्युअल रूप से पुनः जारी कर सकते हैं।
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	Ollie का मध्य-स्ट्रीम पुष्टि प्रॉम्प्ट रद्द माने जाने से पहले उपयोगकर्ता के लिए कितनी देर प्रतीक्षा कर सकता है। `0` सीमा को अक्षम करता है (केवल डिबग)।
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	Ollie पॉड कोल्ड-स्टार्ट पोल कैप।
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	कोल्ड-स्टार्ट पोल अंतराल।
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	वॉचडॉग ताल — जब पॉड शांत होता है तो `notifications/progress` टिक उत्सर्जित करता है, होस्ट टाइमआउट को दूर रखता है।
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	`ask_ollie` निरस्त होने से पहले पॉड मौन पर कठोर सीमा। `0` अक्षम करता है (केवल डिबग)।

टेलीमेट्री

अनाम उपयोग ईवेंट (केवल ईवेंट प्रकार + समय — कोई क्वेरी सामग्री नहीं)। आपकी API कुंजी का एक SHA-256 डाइजेस्ट शामिल है ताकि समर्थन आपका खाता ढूंढ सके; कच्ची कुंजी कभी प्रक्रिया नहीं छोड़ती। ऑप्ट आउट: OPIK_MCP_ANALYTICS_ENABLED=false।

चर	डिफ़ॉल्ट	नोट्स
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	सभी टेलीमेट्री अक्षम करने के लिए `false` पर सेट करें।
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	स्टेजिंग के लिए ओवरराइड।
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	हर ईवेंट पर टैग (`prod` / `staging` / `dev`)।
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	रिसीवर इसका उपयोग `on_prem=False` चिह्नित करने के लिए करता है। ऑन-प्रेम इंस्टॉल को `""` या अपने डोमेन पर ओवरराइड करना चाहिए।
`OPIK_MCP_ANALYTICS_CONNECT_TIMEOUT_S`	`5.0`	HTTP कनेक्ट टाइमआउट।
`OPIK_MCP_ANALYTICS_TOTAL_TIMEOUT_S`	`10.0`	HTTP कुल अनुरोध टाइमआउट।

ज्ञात होस्ट सीमाएँ

MCP स्पेक होस्ट को notifications/progress पर अपने टूल-कॉल टाइमआउट को रीसेट करने देता है — opik-mcp प्रति Ollie SSE ईवेंट एक उत्सर्जित करता है और साथ ही 15-सेकंड का वॉचडॉग हार्टबीट भी। वास्तविकता असमान है:

Claude Code — कोई प्रलेखित टूल-कॉल टाइमआउट नहीं; हार्टबीट कॉल को message_end तक जीवित रखता है। अनुशंसित।
Cursor — 60s का कठोर टाइमआउट जो प्रगति पर रीसेट नहीं होता (अपस्ट्रीम बग)। लंबे Ollie टर्न विफल होंगे। ask_ollie क्वेरीज़ को केंद्रित रखें।
MCP Inspector — MAX_TOTAL_TIMEOUT कुल अवधि को सीमित करता है (डिफ़ॉल्ट 60s)। लंबे ऑपरेशन के लिए इंस्पेक्टर UI में इसे बढ़ाएँ।

यदि कोई कॉल अटक जाए, तो OPIK_MCP_LOG_LEVEL=DEBUG सेट करें — हार्टबीट विफलताएँ (आमतौर पर होस्ट डिस्कनेक्ट) opik_mcp.ask_ollie पर डीबग स्तर पर लॉग की जाती हैं।

समस्या निवारण

OPIK_API_KEY is required to use ask_ollie — चर सर्वर प्रक्रिया तक नहीं पहुँच रहा है। Claude Code / Cursor / VS Code में, env चर केवल तब लागू होते हैं जब MCP सर्वर कॉन्फ़िग के env ब्लॉक के अंदर हों, आपके शेल में नहीं। संपादन के बाद होस्ट को पुनरारंभ करें।

ask_ollie 2 मिनट के बाद "pod not ready" लौटाता है — Ollie पॉड कोल्ड-स्टार्ट OPIK_MCP_POD_READY_TIMEOUT_S से अधिक हो गया। पुनः प्रयास करें — दूसरी कॉल आमतौर पर एक गर्म पॉड पर पहुँचती है।

ask_ollie / run_experiment स्व-होस्टेड Opik पर डिस्पैच त्रुटि के साथ विफल होता है — वे उपकरण केवल Comet Cloud पर उपलब्ध हैं। स्व-होस्टेड पर सीधे read / list / write का उपयोग करें।

Cursor कॉल 60s पर टाइमआउट हो जाती है — Cursor का ज्ञात बग, opik-mcp नहीं। या तो Ollie क्वेरी को छोटा करें, या वही ऑपरेशन Claude Code पर चलाएँ जिसकी कोई कठोर सीमा नहीं है।

विकास

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

सामान्य लक्ष्य:

लक्ष्य	यह क्या करता है
`make install`	`uv sync --extra dev`
`make run`	MCP सर्वर चलाएँ (डिफ़ॉल्ट रूप से stdio)।
`make run-dev`	DEBUG लॉगिंग + uvicorn `--reload` के साथ चलाएँ।
`make dev`	`mcp dev` (इंस्पेक्टर dev-मोड रैपर) के माध्यम से चलाएँ।
`make inspect`	चल रहे सर्वर के विरुद्ध MCP इंस्पेक्टर लॉन्च करें।
`make test`	`uv run pytest -q`।
`make test-live`	`dev.comet.com` के विरुद्ध लाइव एंड-टू-एंड (`OPIK_API_KEY` + `OPIK_WORKSPACE` सेट करें)।
`make lint`	`ruff check` + प्रारूप जाँच।
`make format`	`ruff format` + `ruff check --fix`।
`make typecheck`	`mypy`।
`make check`	`lint + typecheck + test`।

रेपो लेआउट:

opik-mcp/
├── src/opik_mcp/        ← server, tools, ask_ollie, analytics
├── tests/               ← pytest suites
├── scripts/             ← live-BE smoke + MCP-session smoke
├── legacy/typescript/   ← deprecated v2 TS server
├── pyproject.toml
└── Makefile

सहायता प्राप्त करें

बग और सुविधा अनुरोधों के लिए एक मुद्दा खोलें
SDK / बैकएंड दस्तावेज़ीकरण के लिए Opik डॉक्स
प्रश्नों के लिए Comet समुदाय Slack

v2 से अपग्रेड कर रहे हैं? लीगेसी TypeScript सर्वर अभी भी npm पर opik-mcp@^2 (npx -y opik-mcp) के रूप में शिप होता है; स्रोत legacy/typescript/ के अंतर्गत संरक्षित है। समर्थन नीति के लिए legacy/typescript/DEPRECATED.md देखें।

लाइसेंस

Apache-2.0.