swatplus-mcp
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 beginnenEntscheidungen:
docs/decisions.mdAbhä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 --compactDer 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-buildDas 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.tomlEntwicklung
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.jsonDas 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 toolsbreakpointB
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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
MCP server for querying Forkast documentation
Stateless TS/JS compiler facts for agents: references, imports, impact. No repo index or OAuth.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA local, SQLite-backed code index for Claude Code, exposed over MCP, enabling targeted code retrieval without external APIs.112 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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