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.

• Wo wir stehen: docs/status.md ← hier beginnen

• Entscheidungen: docs/decisions.md

• Abhängigkeits-Pins: docs/pins.toml

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: fw-context-mcp

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.