Tamandua

Hace que el asistente de codificación que ya usas — Claude Code, Copilot, Codex, un modelo local — sea más barato y preciso en SWAT+.

No es un asistente. Construye un índice de solo hechos del código fuente Fortran de SWAT+, a partir únicamente del análisis estático, y lo sirve como herramientas MCP y como un archivo en tu checkout. Procedimientos con ubicaciones, el grafo de llamadas, E/S de archivos con números de unidad, escrituras de variables por ruta de campo, cabeceras de bucles con sus variables de índice, tipos derivados con las unidades y el significado que la fuente documenta en línea. Nada en él está escrito por un modelo.

Por qué merece la pena: al pedirle que enumerara los bucles en hru_control, un asistente que trabaja a partir del código fuente en bruto leyó las 890 líneas y produjo una tabla ordenada de 18 — de 21. Nada en la respuesta sugería que estuviera incompleta. Aquí las preguntas exhaustivas son exhaustivas por construcción, y cada fila lleva su archivo y línea.

• Estado actual: docs/status.md ← empieza aquí

• Decisiones: docs/decisions.md

• Dependencias fijadas: docs/pins.toml

Úsalo

Si solo quieres las herramientas — sin checkout de SWAT+ ni parser:

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

El paquete etiquetado incluye la instantánea fijada de hechos de SWAT+. El futuro nombre de distribución en PyPI es swatplus-tamandua (tamandua ya pertenece a un proyecto no relacionado). Apunta tu asistente al servidor sin rutas específicas de la máquina:

// .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"]
    }
  }
}

Si tienes un checkout de SWAT+ y el parser, apunta el servidor directamente a la fuente:

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

El proceso en ejecución calcula la huella del árbol de trabajo de Fortran antes de cada solicitud. Solo reanaliza después de una edición, de modo que la siguiente respuesta sigue el código fuente sin reconstrucción manual ni reinicio del servidor.

Para producir un archivo de hechos portátil para otra persona:

cd <your swatplus checkout> && swatplus-build

Eso escribe swatplus-facts.json y nada más. Un servidor iniciado con --facts detecta cuando ese archivo se reemplaza y recarga la instantánea completa más reciente sin reiniciarse. La instantánea de la versión incluida en el paquete permanece estática por diseño.

Si tu herramienta no puede ejecutar un servidor MCP, swatplus-build --markdown también genera SWATPLUS_INDEX.md y apunta todos los archivos de instrucciones del asistente (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md) hacia él, para que se consulte con grep en su lugar. Esa es la alternativa de respaldo, no la opción por defecto.

La comprobación calcula el hash del árbol de trabajo, no del último commit — las preguntas se hacen sobre código que se está editando, que es justo cuando una comprobación basada en commits consideraría actual un índice obsoleto.

Related MCP server: fw-context-mcp

Se complementa con dataselector

swatplus-dataselector cubre la otra mitad: qué significa una columna en un archivo de entrada y qué contiene un conjunto de datos TxtInOut real. Los dos no se solapan — este sabe lo que hace el Fortran, aquel sabe lo que contienen los archivos. Ejecuta ambos y dile a tu asistente cuál sirve para qué.

Estructura

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

Desarrollo

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)

El parser es solo una dependencia de tiempo de compilación: el archivo de hechos incluido permite que el servidor instalado funcione sin él ni el código fuente de SWAT+ (ver D-8). Pasa --facts para usar otra instantánea o --source para construir en vivo desde un checkout.

# 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

Etiquetar v*.*.* ejecuta .github/workflows/release.yml, que construye ambos contra los commits fijados, elimina los checkouts, verifica que la instantánea sigue respondiendo y la publica.

Principios

Solo hechos — si lo ha escrito un modelo, no entra en el índice. Cada afirmación lleva su archivo y línea. Mide antes de concluir; los hallazgos se recogen en docs/*_experiment.md junto con el script que los generó. Ocho defectos en este trabajo se encontraron mediante el uso ordinario y ninguno mediante un banco de pruebas, así que prefiere ejecutar la herramienta a razonar sobre ella.