Content
# opendtect-mcp
**Model Context Protocol (MCP) server that drives [OpendTect](https://dgbes.com/software/opendtect/) headlessly** — SEG‑Y import, 3D horizon auto‑tracking, ASCII export, and horizon‑agreement scoring.
It wraps two OpendTect surfaces, both public and documented:
- **`odpy`** (OpendTect's Python framework, Apache‑2.0) for database/survey introspection.
- the **Command Driver** (`od_main --cmd script.odcmd`) for GUI actions (import / track / export).
A pure‑Python scoring layer that turns two tracked horizons into quantitative numbers.
> **Not affiliated with, endorsed by, or sponsored by dGB Earth Sciences.** "OpendTect" is a trademark of dGB Earth Sciences; it is used here only to describe interoperability. This project ships **no** OpendTect code or data — it invokes a separately‑installed OpendTect via its documented interfaces.
---
## What it exposes (MCP tools)
| Tool | Needs OD? | What it does |
|---|---|---|
| `survey_info` | introspection | OD install + active survey + readiness check (**start here**) |
| `list_objects` | odpy | list DB objects of a translator group (`Seismic Data`, `Horizon`, …) |
| `import_segy` | Command Driver | import a 3D post‑stack SEG‑Y into the survey |
| `autotrack_horizon` | Command Driver | *(experimental, M2)* seed + auto‑track a 3D horizon |
| `export_horizon_ascii` | Command Driver | export a tracked horizon to ASCII `.xyt` |
| `read_horizon` | no | parse an exported horizon (pick count + extent) |
| `compare_horizons` | no | **score baseline vs candidate tracking**: coverage, holes, RMS pick deviation, verdict |
The GUI‑action tools accept `dry_run=True` to return the generated `.odcmd` **without executing**, so you can calibrate menu labels for your OD version safely.
---
## Install
```bash
cd opendtect-mcp
pip install -e . # or: pip install -e ".[dev]" for tests
```
Python ≥ 3.10. `odpy` ships with OpendTect; if it isn't on your Python path, `pip install odpy` or run this server with OpendTect's bundled Python.
## Configure
All via env (auto‑detects common install locations otherwise) — see `.env.example`:
```bash
export OPENDTECT_BIN=/path/to/od_main
export OPENDTECT_DATA_ROOT=/path/to/SurveyDataRoot
export OPENDTECT_SURVEY=YourSurvey
```
Verify:
```bash
python -c "from opendtect_mcp.config import ODConfig; import json; print(json.dumps(ODConfig.from_env().check(), indent=2))"
```
## Connect to an MCP client (e.g. Claude Code)
Add to your MCP config (`.mcp.json` in a project, or the user‑level config):
```json
{
"mcpServers": {
"opendtect": {
"command": "opendtect-mcp",
"env": {
"OPENDTECT_BIN": "/path/to/od_main",
"OPENDTECT_DATA_ROOT": "/path/to/SurveyDataRoot",
"OPENDTECT_SURVEY": "YourSurvey"
}
}
}
}
```
Then ask the assistant to call `survey_info` first.
---
## Status & calibration
- ✅ **Works now, no OD:** `read_horizon`, `compare_horizons`, all `dry_run` script generation, the unit tests (`pytest`).
- ✅ **M0/M1 (introspection + import/export):** functional; the `.odcmd` **menu labels are version‑specific** and may need one‑time calibration (see `odcmd_templates.py`, lines marked `# CALIBRATE`). Use `dry_run=True`, run against your OD, read `odcmdlog.txt`, adjust labels.
- 🚧 **M2 (`autotrack_horizon`):** scaffolded; seed placement is the trickiest GUI op to script and needs calibration before `dry_run=False`.
The Command Driver navigates the GUI by label, so a given OD **version** only needs calibrating once — keep validated strings in `odcmd_templates.py`.
See **`examples/horizon_tracking_comparison.md`** for the end‑to‑end baseline‑vs‑candidate tracking workflow.
## Layout
```
opendtect_mcp/
config.py env-driven OD/survey resolution + readiness check
command_driver.py write+run .odcmd, parse odcmdlog.txt
odcmd_templates.py parameterized .odcmd builders (← calibrate here)
odpy_bridge.py odpy dbman/common wrappers (degrade gracefully)
horizon_io.py ASCII horizon parse + agreement scoring (no OD)
server.py FastMCP server + tool definitions
tests/ no-OD unit tests
examples/ workflow guide
```
