Comet Opik

ทางการ

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

GitHub

217

คุณทำอะไรได้บ้างด้วย Comet Opik MCP?

Browse and search your Opik workspace — list projects, experiments, traces, spans, prompts, or test suites with optional name filters and pagination via list.
Inspect any entity by ID, name, or URI — retrieve full details (including inlined children for traces and prompts) using read with opik:// URIs or UUIDs.
Log traces, scores, comments, and prompt versions — create or update traces and spans, attach feedback scores, save prompt versions, and manage test suites through write.
Ask Ollie investigative questions about your LLM observability data — query ask_ollie to compare experiments, diagnose regressions, or synthesize cross-entity insights with optional mid-stream scoring.
Run evaluation experiments end-to-end — trigger run_experiment with a prompt, test suite, and scorers to execute and log a full evaluation run.
Introspect write operation schemas — use schema to retrieve the exact JSON shape and required fields for any write operation before constructing a payload.

เอกสาร

Opik MCP Server

เซิร์ฟเวอร์ Model Context Protocol (MCP) อย่างเป็นทางการสำหรับ Opik แพลตฟอร์มการสังเกตการณ์และประเมินผล LLM แบบโอเพนซอร์ส สร้างโดย Comet เชื่อมต่อโฮสต์ AI ของคุณ (Claude Code, Cursor, VS Code Copilot, MCP Inspector) เข้ากับ พื้นที่ทำงาน Opik ของคุณโดยตรง: อ่านเทรซ, บันทึกคะแนน, บันทึกเวอร์ชันพร้อมท์ และถาม Ollie ผู้ช่วย AI ในผลิตภัณฑ์ของ Opik ด้วยคำถามเชิงสืบสวน ทั้งหมดนี้ จากการแชท

สร้างขึ้นสำหรับวิศวกร LLM ที่ใช้งาน Opik อยู่แล้วและต้องการขับเคลื่อนมันจาก ผู้ช่วย AI ตัวเดียวกับที่ใช้เขียนโค้ด

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

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 ถูกรับเป็นนามแฝงที่เลิกใช้แล้ว

หมายเหตุก่อนเผยแพร่: 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 ดู ข้อจำกัดโฮสต์ที่ทราบ

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 แบบโฮสต์เอง

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

{
  "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="" จะยกเลิกป้ายกำกับแหล่งที่มา cloud-Comet บนอีเวนต์เทเลเมทรีสำหรับการติดตั้งของคุณ

เครื่องมือ

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

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

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

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

`write`

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

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

การดำเนินการ	สิ่งที่ทำ
`trace.create`	บันทึกเทรซเดียว (หรือเป็นชุด) หลักสำหรับสแปน / คะแนน / ความคิดเห็น
`trace.update`	สรุปหรือแก้ไขเทรซที่มีอยู่
`span.create`	บันทึกสแปนบนเทรซที่มีอยู่ (หรือเป็นชุด)
`score.create`	แนบคะแนนความคิดเห็นที่เป็นตัวเลขกับเทรซ, สแปน, หรือเธรด
`comment.create`	แนบความคิดเห็นแบบข้อความอิสระกับเทรซ, สแปน, หรือเธรด
`prompt_version.save`	บันทึกเวอร์ชันพร้อมท์ใหม่ (สร้างพร้อมท์ตามชื่อหากไม่มี)
`test_suite.create`	สร้างชุดทดสอบการประเมินผล
`test_suite_item.upsert`	อัปเดตหรือแทรกรายการลงในชุดทดสอบ (ใช้รูปแบบ envelope เสมอ)
`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`

รันการทดลองประเมินผลแบบ end-to-end ผ่าน Ollie รับ experiment_config dict เดียวที่สะท้อนรูปร่างการทดลองของ 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 สามารถเชื่อมโยงกับ id ที่เสถียรแทนที่จะเป็นชื่อพื้นที่ทำงาน (ที่เปลี่ยนแปลงได้)
`COMET_URL_OVERRIDE`	`https://www.comet.com`	ตั้งค่าเป็นโฮสต์ Comet ที่โฮสต์เองของคุณ หรือ `https://dev.comet.com` สำหรับ staging
`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`	`true` เพื่อเปิดใช้งาน uvicorn `--reload` (สำหรับการพัฒนาเท่านั้น)
`OPIK_MCP_AS_URL`	ไม่ได้ตั้งค่า	URL เซิร์ฟเวอร์การอนุญาต OAuth ที่โฆษณาใน `/.well-known/oauth-protected-resource` (RFC 9728) และใช้เป็นเป้าหมายพร็อกซีสำหรับโพรบการค้นหา AS จำเป็นสำหรับโฮสต์ MCP เพื่อเริ่มต้นการเต้นรำ OAuth ผ่าน HTTP
`OPIK_MCP_RESOURCE_URI`	ไม่ได้ตั้งค่า	URI สาธารณะตามรูปแบบบัญญัติของเซิร์ฟเวอร์นี้ โฆษณาเป็น `resource` ในข้อมูลเมตาทรัพยากรที่ได้รับการป้องกัน และใช้เพื่อรับคำใบ้ `WWW-Authenticate`
`OPIK_MCP_LOG_LEVEL`	`INFO`	เกณฑ์ของล็อกเกอร์ stderr

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

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

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

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

Ollie / การเรียกที่นาน

ตัวแปร	ค่าเริ่มต้น	หมายเหตุ
`OPIK_MCP_AUTO_APPROVE`	`enabled`	`disabled` เพื่อต้องการการอนุมัติต่อการกระทำก่อนที่การเขียนระหว่างสตรีมของ Ollie จะดำเนินการต่อ บนโฮสต์ที่โฆษณาความสามารถ 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`	จังหวะ watchdog — ปล่อยสัญญาณ `notifications/progress` เมื่อพ็อดเงียบ เพื่อป้องกันการหมดเวลาของโฮสต์
`OPIK_MCP_STREAM_IDLE_TIMEOUT_S`	`300.0`	เพดานตายตัวสำหรับความเงียบของพ็อดก่อนที่ `ask_ollie` จะยกเลิก `0` ปิดใช้งาน (สำหรับการดีบักเท่านั้น)

เทเลเมทรี

เหตุการณ์การใช้งานแบบไม่ระบุตัวตน (เฉพาะประเภทเหตุการณ์และเวลา — ไม่มีเนื้อหาคิวรี) ค่าแฮช 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 ทุก 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 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` (โหมด wrapper สำหรับนักพัฒนา 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`

โครงสร้างที่เก็บ:

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