regional-ocean-debugger-mcp

regional-ocean-debugger-mcp

MCP server for debugging regional ocean (MOM6 + CESM) model runs.

Combines practical log analysis tools with a searchable knowledge base of expert interview transcripts, giving an LLM agent both the ability to inspect model output files and access to domain-expert guidance.

Tools

| Tool | Purpose | |------|---------| | read_run_log(case_dir, component, lines) | Read recent CESM/MOM6 run log lines | | find_errors(case_dir) | Scan all logs for FATAL/NaN/CFL/etc. | | classify_error(error_text) | Match error against known MOM6 failure modes | | read_mom6_params(case_dir, filter) | Read MOM_input + MOM_override | | diff_params(case_dir_a, case_dir_b) | Compare MOM_input between two cases | | check_cfl(case_dir) | Evaluate CFL stability from MOM_input timestep settings | | suggest_timestep(resolution_deg) | Recommend DT and DT_THERM for a given resolution | | read_diag_table(case_dir) | Parse enabled MOM6 diagnostics | | suggest_diagnostics(symptoms) | Suggest useful diagnostics for a given problem | | query_domain_knowledge(question) | Search expert interview knowledge base | | get_parameter_advice(param_name) | Look up guidance for a specific MOM6 parameter |

Resources

| URI | Content | |-----|---------| | ocean://case/{case_dir}/params | Parsed MOM_input as KEY=VALUE | | ocean://case/{case_dir}/errors | Extracted errors from recent logs | | ocean://knowledge/index | Summary of knowledge base contents |

Knowledge Base

Domain knowledge comes from expert interviews on regional MOM6 modelling (private repo: AidanJanney/RegionalMOM6_InterviewTranscripts). Topics include: OBC setup, tidal forcing, bathymetry, stability, BGC, grid design, and regional ocean dynamics.

The transcripts are a git submodule in data/transcripts/. After cloning this repo:

git submodule update --init data/transcripts

Setup

pip install -e .
# with the transcripts submodule:
git submodule update --init data/transcripts

Running

regional-ocean-debugger-mcp
# or
python server.py

Add to .mcp.json:

{
  "mcpServers": {
    "ocean-debugger": {
      "command": "python",
      "args": ["/path/to/MCP_regional_ocean_debugger/server.py"]
    }
  }
}

Design

• Stateless: reads from the filesystem per call
• No ML dependencies: knowledge search is keyword-based (fast, transparent, works without GPU)
• Composable: use find_errors → classify_error → query_domain_knowledge in sequence for triage
• Private data: transcripts submodule is private; do not make public without authorisation

CESM / MOM6 paths on Derecho

Cases: ~/croc_cases/ MOM_input: <case_dir>/run/MOM_input or <case_dir>/Buildconf/momconf/MOM_input diag_table: <case_dir>/run/diag_table