Product and engineering specs only. Plans and working notes stay local.
One design doc per feature. Pick the doc by the question you hold; the last column says which paths it owns, so a boundary question is settled here.
| Feature | Answers | Owns |
|---|---|---|
| tool-surface | How read, list and schema behave, what a host receives on initialize, and the wire contract the conformance suite pins. |
src/opik_mcp/read_list/ root modules except project_scope.py and sample.py, entities/__init__.py, entities/trace.py, span.py, thread.py, prompt.py, src/opik_mcp/server/tools/ except write.py and read_skill.py, src/opik_mcp/server/app/instance.py, src/opik_mcp/instructions.py, tests/server/test_instructions.py, the files in tests/read_list/ not named for another feature’s entity, tests/conformance/ except test_skill_resources.py, tests/hermetic/ shared files (the stub, fixtures/, servers.py, reads/answers.py) and the tests/hermetic/reads/ files of its entities |
| cost-intelligence | When the AI Spend feature turns on and what it adds to what a host sees. | src/opik_mcp/cost_intelligence/, src/opik_mcp/features/, src/opik_mcp/read_list/visibility.py, src/opik_mcp/read_list/entities/spend/, src/opik_mcp/client/ai_spend.py, src/opik_mcp/server/tools/feature_surface.py, tests/cost_intelligence/, tests/read_list/test_visibility.py, tests/read_list/test_spend.py, tests/client/test_ai_spend.py, tests/hermetic/stub_spend.py, tests/hermetic/fixtures/ai_spend_*.json, tests/conformance/test_cost_intelligence_surface.py, tests/skills/test_cost_intelligence_skills.py, tests/hermetic/reads/test_cost_intelligence.py |
| writes | How write(operation, data) goes from arguments to a backend call and back, and what an error looks like. |
src/opik_mcp/writes/ except the evaluation and diagnostics operation hooks, src/opik_mcp/server/tools/write.py, tests/writes/, tests/hermetic/writes/ except the evaluation and diagnostics files |
| experiment-flows | Experiments, datasets and cases: the comparison table, finding a case, the evaluation writes. | src/opik_mcp/read_list/entities/experiment.py, src/opik_mcp/read_list/entities/dataset/, src/opik_mcp/read_list/sample.py, src/opik_mcp/writes/operations/evaluation.py, their tests |
| project-overview | read('project') and list('project_metric'): the summary, the vocabulary, the series. |
src/opik_mcp/read_list/entities/project/, src/opik_mcp/read_list/entities/project_metric/, src/opik_mcp/read_list/entities/score_name.py, src/opik_mcp/read_list/entities/online_rule.py, their tests |
| diagnostics | Agent Insights issues and jobs: listing, reading, closing, enabling. | src/opik_mcp/read_list/entities/agent_insights_issue/, src/opik_mcp/writes/operations/diagnostics.py, src/opik_mcp/read_list/project_scope.py, their tests |
| skills | The skills, read_skill, and the pack published as comet-ml/opik-skills. |
src/opik_mcp/skills/, src/opik_mcp/skills_catalog.py, src/opik_mcp/skills_resources.py, src/opik_mcp/server/tools/read_skill.py, scripts/build_skills_pack.py, scripts/skills_trigger_eval.py, the pack jobs in .github/workflows/ci.yaml, .claude-plugin/, tests/skills/, tests/conformance/test_skill_resources.py |
| hosted-auth | Bearer tokens, API keys, identity and the HTTP app the Docker image serves. | src/opik_mcp/server/http/, src/opik_mcp/server/app/factory.py, src/opik_mcp/server/app/session.py, src/opik_mcp/identity/context.py, src/opik_mcp/identity/oauth.py, src/opik_mcp/identity/account.py, src/opik_mcp/identity/caller.py, src/opik_mcp/identity/store.py, the OAuth and HTTP fields of src/opik_mcp/config.py, the oauth, http, health and identity tests |
| analytics | Product events, error kinds and error tracking. | src/opik_mcp/analytics/, src/opik_mcp/error_kinds.py, src/opik_mcp/error_tracking.py, the props functions in src/opik_mcp/server/tools/, src/opik_mcp/server/app/lifespan.py, the analytics and Sentry fields of src/opik_mcp/config.py, scripts/capture_bi_listener.py, tests/analytics/, tests/server/test_error_tracking.py, tests/repo/test_telemetry_disabled_in_tests.py |
| release | From a merge to main to PyPI, the image and the chart. |
.github/workflows/ except live.yaml, .github/release-drafter.yml, .github/dependabot.yml, Dockerfile, .dockerignore, helm/, the version, docker-* and install-branch targets in Makefile, version.txt, the generated _version.py, the [tool.hatch.*] blocks in pyproject.toml, scripts/dev/install_branch.py, tests/hermetic/test_wheel_contents.py, tests/repo/test_install_branch.py |
| runtime | How the process starts, is configured and talks to Opik. | src/opik_mcp/__main__.py, src/opik_mcp/config.py except the OAuth, HTTP and transport-security fields (hosted-auth) and the analytics and Sentry fields (analytics), src/opik_mcp/client/, tests/client/test_client.py, tests/client/test_read.py, tests/client/test_search.py, tests/server/test_config.py, tests/client/test_connection_per_tool_call.py |
| live-e2e | Whether each tool returns what the user asked for against a real Opik: the seeded fixture, the per-PR and nightly runs, and the Slack alert. | tests/live/, scripts/seed_e2e_backend.py, scripts/live_alert.py, .github/workflows/live.yaml, tests/repo/test_seed_e2e_backend.py, tests/repo/test_live_alert.py |
A PR that changes a feature’s behaviour updates its design doc. These files are public: no customer or workspace names, internal links or secrets.