Skip to main content
Glama
swatplus-mcp

swatplus-mcp

by tugraskan

Tamandua

Macht den Coding-Assistenten, den du bereits verwendest — Claude Code, Copilot, Codex, ein lokales Modell — günstiger und genauer bei SWAT+.

Es ist kein Assistent. Es erstellt einen reinen Faktenindex des SWAT+-Fortran-Quellcodes, allein durch statische Analyse, und stellt ihn als MCP-Tools und als Datei in deinem Checkout bereit. Prozeduren mit Fundstellen, der Aufrufgraph, Datei-I/O mit Unit-Nummern, Schreibzugriffe auf Variablen nach Feldpfad, Schleifenköpfe mit ihren Indexvariablen, abgeleitete Typen mit den Einheiten und der Bedeutung, die der Quellcode inline dokumentiert. Nichts darin ist von einem Modell geschrieben.

Warum der Aufwand: Bittet man einen Assistenten, die Schleifen in hru_control aufzulisten, las er alle 890 Zeilen des rohen Quellcodes und erzeugte eine ordentliche Tabelle mit 18 — von 21. Nichts in der Antwort ließ darauf schließen, dass sie unvollständig war. Vollständigkeitsfragen sind hier konstruktionsbedingt vollständig, und jede Zeile trägt ihre Datei und Zeile.

Verwendung

Wenn du nur die Werkzeuge möchtest — ohne SWAT+-Checkout und ohne Parser:

pip install "git+https://github.com/tugraskan/Tamandua.git@v0.1.1"

Das getaggte Paket enthält den gepinnten SWAT+-Fakten-Snapshot. Der zukünftige PyPI-Distributionsname ist swatplus-tamandua (tamandua gehört bereits einem nicht verwandten Projekt). Richte deinen Assistenten ohne maschinenspezifische Pfade auf den Server aus:

// .mcp.json (Claude Code) — VS Code uses .vscode/mcp.json, where these
// entries nest inside a top-level "servers" object instead.
{
  "mcpServers": {
    "swatplus-source": {
      "command": "swatplus-mcp",
      "args": ["--compact"]
    }
  }
}

Wenn du ein SWAT+-Checkout und den Parser hast, richte den Server direkt auf den Quellcode aus:

swatplus-mcp --source /path/to/swatplus --compact

Der laufende Prozess erstellt vor jeder Anfrage einen Fingerabdruck des Fortran-Arbeitsbaums. Er parst nur nach einer Änderung neu, sodass die nächste Antwort dem Quellcode folgt, ohne manuelles Neuerstellen oder Serverneustart.

Um eine portable Fakten-Datei für jemand anderen zu erzeugen:

cd <your swatplus checkout> && swatplus-build

Das schreibt swatplus-facts.json und sonst nichts. Ein mit --facts gestarteter Server bemerkt, wenn diese Datei ersetzt wird, und lädt den neuesten vollständigen Snapshot ohne Neustart neu. Der im Paket gebündelte Release-Snapshot bleibt konstruktionsbedingt statisch.

Wenn dein Tool keinen MCP-Server ausführen kann, rendert swatplus-build --markdown zusätzlich SWATPLUS_INDEX.md und verweist jede Assistenten-Instruktionsdatei (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) darauf, stattdessen per grep durchsucht zu werden. Das ist der Fallback, nicht der Standard.

Die Prüfung hasht den Arbeitsbaum, nicht den letzten Commit — Fragen werden zu Code gestellt, der gerade bearbeitet wird, also genau dann, wenn eine Commit-basierte Prüfung einen veralteten Index als aktuell einstufen würde.

Related MCP server: Open Mind

Passt zu dataselector

swatplus-dataselector deckt die andere Hälfte ab: was eine Spalte in einer Eingabedatei bedeutet und was in einem echten TxtInOut-Datensatz enthalten ist. Die beiden überschneiden sich nicht — dieses hier weiß, was der Fortran-Code tut, jenes weiß, was die Dateien enthalten. Führe beide aus und sag deinem Assistenten, welches wofür zuständig ist.

Aufbau

tamandua/
├── index/             # build the facts, render, install pointers, snapshot
│   ├── build.py       #   static analysis -> SourceIndex
│   ├── snapshot.py    #   read/write swatplus-facts.json, so serving needs no parser
│   ├── render.py      #   SOURCE_INDEX.md
│   ├── install.py     #   assistant instruction-file pointers
│   └── scope.py       #   loop nesting, for conditional breakpoints
├── mcp/server.py      # 14 read-only tools over the same objects
├── mcp/client.py      # generic MCP stdio client (talk to another server)
├── output/reader.py   # query a run's output files
└── config.py          # loads docs/pins.toml

Entwicklung

export SWATPLUS_SOURCE=/path/to/swatplus
export SWATPLUS_REFERENCE_CORPUS=/path/to/swatplus-reference-corpus  # the parser
python -m pip install -e ".[dev]"
pytest                       # 151 pass, 9 skipped (128/32 without the parser)

Der Parser ist nur eine Buildzeit-Abhängigkeit: Die gebündelte Fakten-Datei lässt den installierten Server ohne ihn und ohne den SWAT+-Quellcode laufen (siehe D-8). Übergib --facts, um einen anderen Snapshot zu verwenden, oder --source, um live aus einem Checkout zu bauen.

# build the publishable artifacts
swatplus-build --facts dist/swatplus-facts.json --out dist/SWATPLUS_INDEX.md

# serve them with nothing else installed
swatplus-mcp --facts dist/swatplus-facts.json

Das Setzen eines Tags v*.*.* führt .github/workflows/release.yml aus, das beides gegen die gepinnten Commits baut, die Checkouts löscht, prüft, dass der Snapshot weiterhin antwortet, und ihn veröffentlicht.

Prinzipien

Nur Fakten — wenn ein Modell es geschrieben hat, gehört es nicht in den Index. Jede Aussage trägt ihre Datei und Zeile. Erst messen, dann schlussfolgern; Erkenntnisse liegen in docs/*_experiment.md zusammen mit dem Skript, das sie erzeugt hat. Acht Fehler in dieser Arbeit wurden durch normale Nutzung gefunden und keiner durch eine Testumgebung; bevorzuge es also, das Ding laufen zu lassen, anstatt darüber nachzudenken.

Available Tools

15 tools
breakpointB

Where to stop to watch a variable, and on what condition: the routines that assign it, the loops enclosing each assignment, and their index variables. Relevant scanner warnings are returned separately when present.

Inputs: variable (required).

calleesA

Routines this procedure calls. Exhaustive, not truncated.

Inputs: procedure (required).

callersA

Routines that call this procedure. Exhaustive over the whole tree, never sampled or truncated -- one result means exactly one caller, not a partial list.

Inputs: procedure (required).

call_pathC

How execution reaches a procedure, from an entry point down.

Inputs: procedure (required).

describe_typeB

Every field of a derived type, with units, meaning and declaration -- what a state object like aqu_d actually contains, including whether a component is a scalar or a dimension(:), allocatable array.

Inputs: name (required).

file_ioA

Which routines open/read/write a file, with unit numbers and lines. Resolves output files opened via open_output_file. Exhaustive over the whole tree, not truncated.

Inputs: file (required).

find_procedureA

Locate a SWAT+ procedure: source file, line range, module, module imports and only lists, every argument and local declaration with source line/type/initial/inline units and meaning, and select-case vocabularies. All stored fields are returned, never sampled or truncated. Returns advisory scanner warnings in a second content block when this procedure has any; these are not compiler errors.

Inputs: name (required).

loopsA

Loop headers in a procedure with their index variables and start/end lines, for setting a conditional breakpoint. Exhaustive -- every loop in the procedure, not a sample. Relevant scanner warnings are returned separately when present.

Inputs: procedure (required).

module_variableA

A variable declared in a module body -- its declaring module, type, full declaration (so an allocatable array is distinguishable from a scalar), line, units and meaning. This is the program's global state: a state object like aqu_d is a module-level instance, which describe_type cannot confirm exists. Where a bare name is declared in more than one module, every candidate is returned rather than one being chosen. Falls back to a name and documented-meaning search when there is no exact match. Exhaustive, not truncated.

Inputs: name (required), module.

provenanceA

Which SWAT+ checkout and commit this index describes, its compile-check status, and scanner-warning count.

Inputs: no named parameters.

read_outputA

Summarise a column of a run's output file: count, first, last, min and max with where they occurred, and how many values went negative.

Inputs: file (required), column (required), where, label_by.

scope_atA

Which loops enclose a given line of a procedure, outermost first -- the variables live at that point. Relevant scanner warnings are returned separately when present.

Inputs: line (required), procedure (required).

search_fieldsA

Find a variable from ordinary words. Searches what the source says each field means, e.g. 'recharge' or 'lateral flow', and returns identifiers with units.

Inputs: text (required).

unit_usersA

Routines using a Fortran unit number, and the file each use targets. Optionally filter by operation. Exhaustive, not truncated.

Inputs: unit (required), op.

writersA

Routines that assign a variable, with line numbers and the complete logical assignment statement for derived-type paths when the RHS sidecar is installed. Exhaustive over the whole tree, never sampled or truncated. Relevant scanner warnings are returned separately when present.

Inputs: variable (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    Each tool targets a distinct analysis query (type description, module variables, call graph, file I/O, unit numbers, writers, loops, provenance). Minor overlap exists in the loop/scope cluster (breakpoint, scope_at, loops all touch enclosing loops and conditions) and in describe_type vs module_variable, but the descriptions explicitly delineate them.

    Naming Consistency4/5

    All names are snake_case, which is consistent casing. Verb styles vary somewhat (verb_noun like describe_type/find_procedure vs bare nouns like callers/writers/loops/provenance), but every name is short, readable and semantically descriptive.

    Tool Count5/5

    15 tools sit squarely in the well-scoped range for a static-analysis server, and each one covers a distinct query surface (variables, types, control flow, call graph, I/O, provenance) rather than duplicating effort.

    Completeness4/5

    The surface covers variable/type introspection, control flow, the call graph in both directions, file/unit I/O, output reading, and provenance -- a strong read-only analysis toolkit. Minor gaps like enumerating all procedures in a module or listing modules could exist, but core navigation workflows are covered.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A local, SQLite-backed code index for Claude Code, exposed over MCP, enabling targeted code retrieval without external APIs.
      112 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that builds a deterministic, source-traceable knowledge index of any codebase, enabling glossary lookup, code graphs, and exact-token search with every fact linked to its source file and line.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients such as Claude Desktop and Claude Code to query an indexed source repository through path-guarded tools for hybrid keyword-and-vector code search, file snippets, symbol explanations, reference lookups, and test-skeleton suggestions. Serves those results over stdio with cited file:line locations so agents can answer questions about a codebase and drive grounded code review.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to search local repositories and retrieve bounded, cited source chunks, look up full indexed chunks, and inspect index statistics through read-only MCP tools over stdio.
      MIT