Comet Opik MCP Server

ทางการ

สอบถามและวิเคราะห์ Opik logs, traces, prompts และข้อมูลเทเลเมทรีอื่นๆ ทั้งหมดจาก LLMs ของคุณด้วยภาษาธรรมชาติ

เอกสาร

opik-mcp

กำลังย้ายจาก npx opik-mcp เดิมอยู่หรือเปล่า? เซิร์ฟเวอร์ TypeScript ถูกยกเลิก และจะหมดอายุในวันที่ 2026-11-15 เปลี่ยน npx -y opik-mcp เป็น uvx opik-mcp@latest ในการตั้งค่า MCP client ของคุณ คู่มือฉบับเต็ม: legacy/typescript/MIGRATION.md

เซิร์ฟเวอร์ Model Context Protocol สำหรับ Opik + Ollie เชื่อมต่อ AI host ของคุณ (Claude Code, Cursor, VS Code Copilot, MCP Inspector) เข้ากับ พื้นที่ทำงาน Opik ของคุณโดยตรง — อ่าน traces, บันทึกคะแนน, บันทึกเวอร์ชัน prompt และ ถามคำถามเชิงสืบสวนกับ 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 ซึ่งจะดึงและรันเวอร์ชันล่าสุดที่เผยแพร่ตามต้องการ — ไม่ต้องติดตั้งแบบ global ไม่ต้องสลับ 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) ซึ่งถูกต้องสำหรับการติดตั้งแบบ local/OSS; ผู้ใช้คลาวด์ที่มีพื้นที่ทำงานแบบมีชื่อควรตั้งค่านี้ COMET_WORKSPACE ถูกรับเป็น alias ที่เลิกใช้แล้ว

หมายเหตุก่อนเผยแพร่: 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 (ถูกต้องสำหรับ การติดตั้งแบบ local/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 (global) หรือ .cursor/mcp.json (project) หรือเปิด 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 ใหม่; จุดสีเขียวข้าง opik-mcp ในแผง MCP ยืนยัน การเชื่อมต่อ ถามในการแชท: "list my Opik projects"

Cursor หมดเวลา 60 วินาที Cursor บังคับใช้การหมดเวลาการเรียกเครื่องมือแบบตายตัวที่ไม่ รีเซ็ตเมื่อมีการแจ้งเตือนความคืบหน้า การเรียก ask_ollie ที่ใช้เวลานานจะล้มเหลวบน Cursor ดู ข้อจำกัดของ host ที่รู้จัก

VS Code Copilot

.vscode/mcp.json ในพื้นที่ทำงานของคุณ (หรือ User Settings JSON):

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

โหลดหน้าต่างใหม่; ตัวบ่งชี้ MCP ของ Copilot Chat แสดง opik-mcp เมื่อ เซิร์ฟเวอร์พร้อมใช้งาน ถามในการแชท: "list my Opik projects"

MCP Inspector (การทดสอบด้วยตนเอง)

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

Opik แบบ self-hosted

เพิ่ม COMET_URL_OVERRIDE (และ OPIK_URL หาก Opik อยู่ที่พาธที่ไม่ใช่ค่าเริ่มต้น) ลงใน บล็อก env เดียวกันในการตั้งค่า host ของคุณ:

{
  "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 เท่านั้น — บน self-hosted การเรียกเหล่านั้นจะล้มเหลวเมื่อ dispatch ดังนั้นให้ใช้ read / list / write โดยตรง การตั้งค่า OPIK_MCP_ANALYTICS_SOURCE="" จะทำให้การติดตั้งของคุณไม่ใช้ ป้ายกำกับแหล่งที่มา cloud-Comet บนเหตุการณ์ telemetry

เครื่องมือ

opik-mcp เปิดเผยพื้นผิวที่เล็กและมุ่งเน้นผลลัพธ์ — หกเครื่องมือที่ครอบคลุม วงจรชีวิตทั้งหมด (อ่าน → ใส่คำอธิบายประกอบ → คัดสรร → เขียน → ทำซ้ำ)

เครื่องมือ	วัตถุประสงค์
`read`	อ่านแบบสากลด้วย id / ชื่อ / `opik://` URI
`list`	รายการแบบสากลพร้อมตัวกรองชื่อที่เป็นทางเลือก + การแบ่งหน้า
`ask_ollie`	สืบสวน / สังเคราะห์ผ่านผู้ช่วยในผลิตภัณฑ์ Opik
`write`	เขียนแบบสากล — บันทึก traces/spans, ให้คะแนน, แสดงความคิดเห็น, บันทึก prompts, จัดการ test suites และ experiments
`schema`	ตรวจสอบ schema การดำเนินการเขียน (ใช้โดย LLM เพื่อสร้าง payload ที่ถูกต้อง)
`run_experiment`	รันการทดลอง evaluation แบบ end-to-end ผ่าน 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 ของ parent

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 มีสิทธิ์อ่านโดยตรงไปยังพื้นที่ทำงานของคุณและสามารถ ดำเนินการเขียน (คะแนน, ความคิดเห็น, รายการ test-suite, เวอร์ชัน prompt) ระหว่างสตรีม เมื่อถูกถาม

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 ดำเนินการระหว่างสตรีมจะทำงานโดยไม่มี การยืนยันต่อการกระทำ การอนุมัติอัตโนมัติแต่ละครั้งจะถูกบันทึกเป็นแถวตรวจสอบ JSON บน logger Python opik_mcp.audit หากต้องการการยืนยันแทน ให้ตั้งค่า OPIK_MCP_AUTO_APPROVE=disabled — คำขอยืนยันของ Ollie จะปรากฏเป็น ข้อผิดพลาดแบบมีประเภทที่คุณสามารถออกใหม่ด้วยตนเองได้

มีให้ใช้งานบน Comet Cloud เท่านั้น

`write`

ตัวกระจายการเขียนแบบสากล ส่ง operation + data แล้วตัวกระจาย จะตรวจสอบ payload ใช้ REST verb ที่ถูกต้อง และส่งคืน การตอบสนองจาก backend

การดำเนินการ:

การดำเนินการ	สิ่งที่ทำ
`trace.create`	บันทึก trace เดียว (หรือ batch) Parent สำหรับ spans / scores / comments
`trace.update`	สรุปหรือแก้ไข trace ที่มีอยู่
`span.create`	บันทึก span บน trace ที่มีอยู่ (หรือ batch)
`score.create`	แนบคะแนน feedback แบบตัวเลขกับ trace, span หรือ thread
`comment.create`	แนบความคิดเห็นแบบข้อความอิสระกับ trace, span หรือ thread
`prompt_version.save`	บันทึกเวอร์ชัน prompt ใหม่ (สร้าง prompt ด้วยชื่อหากไม่มี)
`test_suite.create`	สร้าง test suite สำหรับ evaluation
`test_suite_item.upsert`	Upsert รายการลงใน test suite (ใช้รูปแบบ envelope เสมอ)
`experiment.create`	สร้าง experiment ที่มีขอบเขตกับ test suite
`experiment_item.create`	แนบแถว trace + dataset_item กับ experiment

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

`schema`

ตรวจสอบรูปแบบ JSON ที่แน่นอนและฟิลด์ที่จำเป็นของการดำเนินการเขียนใดๆ ก่อน ที่คุณจะเรียกใช้ — มีประโยชน์เมื่อคุณไม่แน่ใจว่า data ควรมีลักษณะอย่างไร ส่งคืน schema, ขอบเขต OAuth และตัวอย่างที่ตรวจสอบแล้วหนึ่งรายการ การค้นหาล้วนๆ ไม่มีการเรียก backend

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

`run_experiment`

รันการทดลอง evaluation แบบ end-to-end ผ่าน Ollie รับ experiment_config dict เดียวที่สะท้อนรูปแบบ experiment ของ Opik (prompt, test suite, scorers); Ollie ดำเนินการรันและเขียนผลลัพธ์กลับเป็น experiment ของ 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 เท่านั้น

การกำหนดค่า

ทุกการตั้งค่าเป็น environment variable ตัวที่จำเป็นแสดงเป็น ตัวหนา

ข้อมูลประจำตัว / endpoint

ตัวแปร	ค่าเริ่มต้น	หมายเหตุ
`OPIK_API_KEY`	—	จำเป็นสำหรับ `ask_ollie` และการอ่าน/เขียนที่รับรองความถูกต้องใดๆ
`OPIK_WORKSPACE`	`default`	ชื่อพื้นที่ทำงาน ทางเลือก — ตกกลับไปที่ `default` (แบบแผน Opik SDK) ผู้ใช้คลาวด์ที่มีพื้นที่ทำงานแบบมีชื่อควรตั้งค่านี้
`COMET_WORKSPACE`	—	alias ที่เลิกใช้แล้วสำหรับ `OPIK_WORKSPACE` (ความเข้ากันได้ย้อนหลัง) `OPIK_WORKSPACE` จะชนะหากตั้งค่าทั้งคู่
`COMET_WORKSPACE_ID`	—	UUID พื้นที่ทำงานที่เป็นทางเลือก ถูกประทับลงในเหตุการณ์ analytics เมื่อตั้งค่า เพื่อให้ BI สามารถ join ด้วย id ที่เสถียรแทนชื่อพื้นที่ทำงาน (ที่เปลี่ยนแปลงได้)
`COMET_URL_OVERRIDE`	`https://www.comet.com`	ตั้งค่าเป็น Comet host แบบ self-hosted ของคุณ หรือ `https://dev.comet.com` สำหรับ staging
`OPIK_URL`	มาจาก `COMET_URL_OVERRIDE` + `/opik/api`	แทนที่เฉพาะเมื่อ Opik อยู่ที่ host/path ที่แตกต่างจาก Comet UI
`OPIK_DEFAULT_PROJECT_NAME`	ไม่ได้ตั้งค่า	เมื่อตั้งค่า blob `instructions` ต่อเซสชันจะบอกให้ LLM ส่งค่านี้เป็น `project_name` ในทุกการเรียกเครื่องมือ เว้นแต่ผู้ใช้จะระบุโปรเจกต์อื่น

เซิร์ฟเวอร์ / การขนส่ง

ตัวแปร	ค่าเริ่มต้น	หมายเหตุ
`OPIK_MCP_TRANSPORT`	`stdio`	`stdio` สำหรับ host-launched, `streamable-http` เพื่อฟังบนพอร์ต
`OPIK_MCP_HOST`	`127.0.0.1`	uvicorn bind host (เฉพาะ `streamable-http`)
`OPIK_MCP_PORT`	`8080`	uvicorn bind port (เฉพาะ `streamable-http`)
`OPIK_MCP_RELOAD`	`false`	`true` เพื่อเปิดใช้งาน uvicorn `--reload` (สำหรับ dev เท่านั้น)
`OPIK_MCP_AS_URL`	ไม่ได้ตั้งค่า	URL เซิร์ฟเวอร์การอนุญาต OAuth ที่โฆษณาใน `/.well-known/oauth-protected-resource` (RFC 9728) และใช้เป็นเป้าหมายพร็อกซีสำหรับการตรวจสอบ AS-discovery จำเป็นสำหรับ MCP hosts เพื่อเริ่มต้นการเต้นรำ OAuth ผ่าน HTTP
`OPIK_MCP_RESOURCE_URI`	ไม่ได้ตั้งค่า	URI สาธารณะแบบ canonical ของเซิร์ฟเวอร์นี้ โฆษณาเป็น `resource` ใน metadata ทรัพยากรที่ได้รับการป้องกัน และใช้เพื่อรับคำใบ้ `WWW-Authenticate`
`OPIK_MCP_LOG_LEVEL`	`INFO`	เกณฑ์ logger stderr

การเลือกการขนส่ง

opik-mcp ดำเนินการ ไม่มีการตรวจสอบความถูกต้องของข้อมูลประจำตัวในเครื่อง บนการขนส่ง HTTP: ใดๆ Authorization: Bearer … ที่มีรูปแบบดี (คีย์ Opik API หรือ opik_mcp_at_… โทเค็นการเข้าถึง OAuth) จะถูกส่งต่อ verbatim ไปยัง opik-backend ซึ่งเป็น จุดเดียวของการบังคับใช้การรับรองความถูกต้อง เลือกการขนส่งตามรูปแบบการปรับใช้:

สถานการณ์	การขนส่ง
MCP client และ Opik บนเครื่องเดียวกัน (การติดตั้ง OSS ในเครื่อง)	stdio (แนะนำ — ง่ายที่สุด ไม่มีพอร์ต ไม่ต้องตั้งค่า OAuth)
MCP client ในเครื่อง → Opik ระยะไกล (Comet cloud / self-hosted)	stdio พร้อม `OPIK_API_KEY` หรือ HTTP พร้อม OAuth (`OPIK_MCP_AS_URL` ชี้ไปที่ backend)
opik-mcp ที่โฮสต์อยู่หลัง edge เดียวกับ opik-backend	HTTP — bearers ถูกตรวจสอบโดย backend ต่อคำขอ

หมายเหตุสำหรับการติดตั้ง OSS ในเครื่อง: OSS backend ไม่รับรองความถูกต้องของคำขอ ดังนั้น opik-mcp แบบ HTTP ที่อยู่ข้างหน้ามันจึงเปิดกว้างเท่ากับ OSS REST API เอง คงค่าเริ่มต้น 127.0.0.1 bind (และเลือกใช้ stdio) บนเครือข่ายที่ใช้ร่วมกัน

Ollie / การเรียกที่ใช้เวลานาน

ตัวแปร	ค่าเริ่มต้น	หมายเหตุ
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` เพื่อต้องการการอนุมัติต่อการกระทำก่อนที่การเขียนระหว่างสตรีมของ Ollie จะดำเนินการต่อ บน hosts ที่โฆษณาความสามารถ MCP `elicitation` ผู้ใช้จะเห็นพรอมต์ใช่/ไม่ใช่; บน hosts ที่ฉลาดน้อยกว่า คำขอจะปรากฏเป็นข้อผิดพลาดแบบมีประเภทที่คุณสามารถออกใหม่ด้วยตนเองได้
`OPIK_MCP_ELICIT_TIMEOUT_SECONDS`	`60`	ระยะเวลาที่พรอมต์การยืนยันระหว่างสตรีมของ Ollie อาจรอผู้ใช้ก่อนที่จะถูกถือว่าเป็นการยกเลิก `0` ปิดใช้งานขอบเขต (สำหรับ debug เท่านั้น)
`OPIK_MCP_POD_READY_TIMEOUT_S`	`120`	เพดานการสำรวจการเริ่มต้นเย็นของ Ollie pod
`OPIK_MCP_POD_READY_INTERVAL_S`	`2`	ช่วงเวลาการสำรวจการเริ่มต้นเย็น
`OPIK_MCP_HEARTBEAT_INTERVAL_S`	`15.0`	จังหวะ watchdog — ปล่อยสัญญาณ `notifications/progress` เมื่อ pod เงียบ เพื่อป้องกันการหมดเวลาของ host
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	เพดานตายตัวของความเงียบของ pod ก่อนที่ `ask_ollie` จะยกเลิก `0` ปิดใช้งาน (สำหรับ debug เท่านั้น)

Telemetry

เหตุการณ์การใช้งานแบบไม่ระบุตัวตน (ประเภทเหตุการณ์ + เวลาเท่านั้น — ไม่มีเนื้อหาคำถาม) ไดเจสต์ SHA-256 ของคีย์ API ของคุณถูกรวมไว้เพื่อให้ฝ่ายสนับสนุนสามารถค้นหาบัญชีของคุณได้; คีย์ดิบ ไม่เคยออกจากกระบวนการ การยกเลิก: OPIK_MCP_ANALYTICS_ENABLED=false

ตัวแปร	ค่าเริ่มต้น	หมายเหตุ
`OPIK_MCP_ANALYTICS_ENABLED`	`true`	ตั้งค่าเป็น `false` เพื่อปิดใช้งานการส่งข้อมูลทางไกลทั้งหมด
`OPIK_MCP_ANALYTICS_URL`	`https://stats.comet.com/notify/event/`	การเขียนทับสำหรับสภาพแวดล้อม staging
`OPIK_MCP_ANALYTICS_ENVIRONMENT`	`prod`	แท็กในทุกเหตุการณ์ (`prod` / `staging` / `dev`)
`OPIK_MCP_ANALYTICS_SOURCE`	`comet.com`	ตัวรับใช้ค่านี้เพื่อทำเครื่องหมาย `on_prem=False` การติดตั้งแบบ on-prem ควรเขียนทับเป็น `""` หรือโดเมนของตนเอง
`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 บวกกับ สัญญาณ heartbeat แบบ watchdog ทุก 15 วินาที ความเป็นจริงนั้นไม่สม่ำเสมอ:

Claude Code — ไม่มีระยะหมดเวลาการเรียกใช้เครื่องมือที่ระบุไว้; heartbeat ทำให้การเรียก ยังคงอยู่จนกว่า message_end แนะนำให้ใช้
Cursor — ระยะหมดเวลาตายตัว 60 วินาทีที่ ไม่ รีเซ็ตเมื่อมีความคืบหน้า (บั๊กต้นทาง) การเรียก Ollie ที่ใช้เวลานานจะล้มเหลว ควรให้คิวรี ask_ollie กระชับ
MCP Inspector — MAX_TOTAL_TIMEOUT จำกัดระยะเวลาทั้งหมด (ค่าเริ่มต้น 60 วินาที) เพิ่มค่าใน UI ของ Inspector สำหรับการดำเนินการที่ใช้เวลานาน

หากการเรียกค้าง ให้ตั้งค่า OPIK_MCP_LOG_LEVEL=DEBUG — ความล้มเหลวของ heartbeat (โดยปกติคือการตัดการเชื่อมต่อของโฮสต์) จะถูกบันทึกบน opik_mcp.ask_ollie ที่ระดับ debug

การแก้ไขปัญหา

OPIK_API_KEY is required to use ask_ollie — ตัวแปรไปไม่ถึง กระบวนการเซิร์ฟเวอร์ ใน Claude Code / Cursor / VS Code ตัวแปรสภาพแวดล้อมจะมีผลเฉพาะเมื่ออยู่ภายใน บล็อก env ของการกำหนดค่าเซิร์ฟเวอร์ MCP ไม่ใช่ในเชลล์ของคุณ รีสตาร์ท โฮสต์หลังจากแก้ไข

ask_ollie คืนค่า "pod not ready" หลังจาก 2 นาที — การเริ่มต้นแบบ cold-start ของ Ollie pod เกิน OPIK_MCP_POD_READY_TIMEOUT_S ลองใหม่ — การเรียกครั้งที่สอง มักจะไปยัง pod ที่อุ่นแล้ว

ask_ollie / run_experiment ล้มเหลวด้วยข้อผิดพลาด dispatch บน Opik แบบ self-hosted — เครื่องมือเหล่านั้นมีให้ใช้งานบน Comet Cloud เท่านั้น ใช้ read / list / write โดยตรงบน self-hosted

การเรียก Cursor หมดเวลาที่ 60 วินาที — เป็นบั๊กที่ทราบของ Cursor ไม่ใช่ opik-mcp อาจ ลดระยะเวลาคิวรี Ollie หรือรันการดำเนินการเดียวกันบน Claude Code ซึ่งไม่มี ขีดจำกัดตายตัว

การพัฒนา

git clone [email protected]: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` (wrapper โหมด dev ของ Inspector)
`make inspect`	เปิด MCP Inspector กับเซิร์ฟเวอร์ที่กำลังรันอยู่
`make test`	`uv run pytest -q`
`make test-live`	การทดสอบ end-to-end สดกับ `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`

โครงสร้างของ repo:

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

ขอความช่วยเหลือ

เปิด issue สำหรับบั๊กและคำขอฟีเจอร์
เอกสาร Opik สำหรับเอกสาร SDK / แบ็กเอนด์
Comet community Slack สำหรับคำถาม

กำลังอัปเกรดจาก v2 อยู่หรือไม่? เซิร์ฟเวอร์ TypeScript รุ่นเก่ายังคงเผยแพร่บน npm ในชื่อ opik-mcp@^2 (npx -y opik-mcp); ซอร์สโค้ดถูกเก็บรักษาไว้ภายใต้ legacy/typescript/ ดู legacy/typescript/DEPRECATED.md สำหรับ นโยบายการสนับสนุน

ใบอนุญาต

Apache-2.0