Tamandua

Делает уже используемого вами ассистента для программирования — Claude Code, Copilot, Codex, локальную модель — дешевле и точнее при работе со SWAT+.

Это не ассистент. Он строит индекс, содержащий только факты, по исходному коду SWAT+ на Fortran, исключительно на основе статического анализа, и предоставляет его как инструменты MCP и как файл в вашей рабочей копии. Процедуры с указанием расположения, граф вызовов, файловый ввод-вывод с номерами юнитов, записи переменных по путям полей, заголовки циклов с их индексными переменными, производные типы с единицами измерения и значением, задокументированными прямо в исходнике. Ничто в нём не написано моделью.

Зачем это нужно: когда ассистента попросили перечислить циклы в hru_control, он, работая с необработанным исходником, прочитал все 890 строк и выдал аккуратную таблицу из 18 — из 21. Ничто в ответе не указывало на неполноту. Здесь исчерпывающие вопросы исчерпывающие по построению, и каждая строка содержит свой файл и номер строки.

• Где что находится: docs/status.md ← начинайте здесь

• Решения: docs/decisions.md

• Зафиксированные зависимости: docs/pins.toml

Использование

Если вам нужны только инструменты — без рабочей копии SWAT+ и без парсера:

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

В тегированном пакете содержится зафиксированный снимок фактов SWAT+. Будущее имя дистрибутива на PyPI — swatplus-tamandua (tamandua уже принадлежит стороннему проекту). Укажите вашему ассистенту на сервер без каких-либо машинно-зависимых путей:

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

Если у вас есть рабочая копия SWAT+ и парсер, укажите серверу прямо на исходники:

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

Работающий процесс снимает отпечаток рабочего дерева Fortran перед каждым запросом. Он запускает повторный разбор только после правки, так что следующий ответ соответствует исходнику без ручной пересборки или перезапуска сервера.

Чтобы создать переносимый файл фактов для кого-то ещё:

cd <your swatplus checkout> && swatplus-build

Эта команда записывает swatplus-facts.json и больше ничего. Сервер, запущенный с --facts, замечает, когда этот файл заменяется, и перезагружает новейший полный снимок без перезапуска. Входящий в пакет релизный снимок остаётся статичным по замыслу.

Если ваш инструмент не умеет запускать MCP-сервер, swatplus-build --markdown также создаёт SWATPLUS_INDEX.md и указывает на него каждый файл инструкций для ассистента (CLAUDE.md, AGENTS.md, .github/copilot-instructions.md), чтобы вместо этого можно было искать grep’ом. Это запасной вариант, а не вариант по умолчанию.

Проверка хеширует рабочее дерево, а не последний коммит — вопросы задаются о редактируемом коде, и именно тогда проверка на основе коммита назвала бы устаревший индекс актуальным.

Related MCP server: fw-context-mcp

Работает в паре с dataselector

swatplus-dataselector закрывает вторую половину: что означает колонка во входном файле и что находится в реальном наборе данных TxtInOut. Эти два инструмента не пересекаются — этот знает, что делает Fortran, а тот знает, что содержат файлы. Запустите оба и объясните вашему ассистенту, какой из них для чего.

Структура

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

Разработка

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)

Парсер — зависимость только на этапе сборки: встроенный файл фактов позволяет установленному серверу работать и без него, и без исходников SWAT+ (см. D-8). Передайте --facts, чтобы использовать другой снимок, или --source, чтобы собрать на лету из рабочей копии.

# 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

Создание тега v*.*.* запускает .github/workflows/release.yml, который собирает обе части по зафиксированным коммитам, удаляет рабочие копии, проверяет, что снимок по-прежнему отвечает на запросы, и публикует его.

Принципы

Только факты — если это написала модель, этому не место в индексе. Каждое утверждение снабжено файлом и номером строки. Сначала измеряйте, потом делайте выводы; результаты находятся в docs/*_experiment.md вместе со скриптом, который их получил. Восемь дефектов в этой работе были обнаружены при обычном использовании, и ни один — каким-либо стендом, поэтому предпочитайте запуск этой штуки размышлениям о ней.