feat: full thread support in the MCP (read, list, lifecycle, annotate) — OPIK-7443

[awkoy]

Full thread support in the MCP (OPIK-7443)

Makes thread a first-class Opik entity across the MCP tool surface. Before this
PR, threads were only a write/annotate target (and even that was broken for real
threads — see the fix below). Now an agent can read, list, annotate,
and close/reopen a thread through one uniform, self-documenting contract.

The contract (why it's good LLM UX)

One rule everywhere: pass the thread_id string you see in list('thread') /
read('thread'), plus the project (id or name). The server absorbs every
backend asymmetry so the model never juggles identifiers:

Surface	Tool call
Read a thread as a conversation	read('thread', <thread_id>, project_id|project_name) → {thread, messages, messagesTruncated}; each message = one turn's trace input/output + a trace_id to read('trace', …)
List a project's threads	list('thread', project_id|project_name)
Score / comment a thread	write score.create / comment.create with target="thread", target_id=<thread_id string> + project
Close / reopen	write thread.close / thread.open with {thread_id, project}

What's in here (4 commits)

• feat(read/list) — thread as a readable/listable entity.
  read('thread', …) returns metadata + the messages list (traces filtered by
  thread_id, up to 200 inlined, sorted ascending). list('thread', project_id=…)
  enumerates a project's threads. New client methods get_thread
  (POST …/threads/retrieve), list_threads, list_traces(filters=…), and a
  _post_json read helper. URI/link parsing: opik://projects/<p>/threads/<t>
  and pasted Opik web thread URLs (looks_like_thread_url). read gains
  project_id/project_name (a thread_id is unique only within a project).

• feat(write) — thread.close / thread.open lifecycle.
  Two write operations toggling thread status (active ↔ inactive), via the
  universal write tool. The dispatcher's _build_request is an explicit
  if name == … chain (no generic fallthrough — a branchless op would hit a
  RuntimeError), so both got a real branch. Verified against opik-backend:
  these are PUT (not POST) and return 204.

• fix(write) — thread score/comment by thread_id string.
  score.create/comment.create typed target_id as UUID, so annotating any
  real thread failed with uuid_parsing (thread_ids are user-supplied strings).
  Now a shared _AnnotationTarget base validates per target: UUID for
  trace/span (canonicalized), the thread_id string for thread, with a required
  project. For comment, the dispatcher resolves the string thread_id → the
  thread's model UUID (the BE's POST /threads/{id}/comments needs the UUID) so
  the caller never sees the asymmetry.

• feat(list) — project_name for trace/thread lists.
  list('thread'/'trace') now accepts project_name as an alternative to
  project_id, matching every other thread tool and removing a forced
  list('project') UUID round-trip.

Verification

• Reviewed against opik-backend source for every endpoint/identifier
  (TracesResource @PUT /threads/{open,close}, addThreadComment(@PathParam UUID),
  FeedbackScoreBatchItemThread project fields, the thread_id filter operator).
  Multi-agent adversarial review on each phase caught and fixed real issues
  pre-merge (POST→PUT verb, string-vs-UUID identifiers, a missed schema.json
  snapshot, a silent message-load degrade, non-404 resolve errors bypassing the
  write envelope).
• Live E2E on dev.comet.com through the built server over MCP stdio:
  create a thread → list (by id and by name) → read (turns in order) →
  score + comment by string id (comment resolves to the model-UUID path) →
  read back (both annotations present) → close (inactive) → open (active).
  All green.
• ruff + strict mypy (src + tests) clean; 1143 tests pass; conformance
  snapshots (read/list/write/schema) regenerated.

Notes

• Not in scope (deliberately): destructive thread.delete, feedback-score
  delete, thread tag updates, thread stats. Clean follow-ups.
• No breaking changes to existing surfaces; trace/span score & comment behavior
  is unchanged (target_id UUID still required and now canonicalized).

🤖 Generated with Claude Code