<p align="center">
  <img src="assets/EPD_MEPhI.png" alt="Serpent2" height="110">
  &nbsp;&nbsp;&nbsp;&nbsp;
  <img src="assets/KI_logo.svg.webp" alt="" height="110">
</p>

<h1 align="center">Serpent2-mcp</h1>

<p align="center">MCP-сервер для Serpent2. Даёт ИИ-агенту точный синтаксис карт, проверку входов и
запуск расчётов. </p>

## Установка

Нужен установленный [uv](https://docs.astral.sh/uv/) и **своя лицензионная копия Serpent** — бинарник
и библиотека сечений в репозиторий не входят.

```bash
git clone https://github.com/ShuwiOwO/Serpent2-mcp && cd Serpent2-mcp

cp /путь/к/sss2 bin/sss2 && chmod +x bin/sss2    # свой бинарник
cp -R /путь/к/xsdata/* libraries/                # своя библиотека сечений

./setup.sh                                       # установка и настройка
```

`setup.sh` проверит окружение, перепривяжет пути внутри библиотеки, поставит
Python-окружение и прогонит эталонный расчёт.

В Claude Code сервер нужно
один раз одобрить (при запуске в папке или вручную через команду`/mcp`); OpenCode подхватывает сервер автоматически.

---

## Инструменты

| Инструмент | Что делает |
|---|---|
| `docs_card` | **точный** синтаксис карты или `set`-опции: блок из мануала, источник, примеры |
| `docs_search` | семантический поиск по документации |
| `zaid_check` | проверка на наличие нуклида в локальной библиотеке |
| `lint` | статическая проверка входа без запуска: карты, типы поверхностей, связки `ene`/`fun`/`srcrate`/`gcu` |
| `run` | запуск расчета в папке `runs/` (режимы `norun` / `smoke` / `full`) |
| `results` | чтение и разбор `_res.m`  и `_det*.m`|
| `env_info` | выводит версию Serpent2, число нуклидов в библиотеках, состояние индексов |
| `list_cards` | список известных карт и `set`-опций |

---

## Устройство

```
serpent2-mcp/
├── bin/           ← ваш бинарник (sss2)                     
├── libraries/     ← ваша библиотека сечений      
├── projects/      ← рабочие проекты
├── runs/          ← изолированные папки для запусков расчетов
├── examples/      ← эталонные задачи для проверки работоспособности
├── tools/         ← сервер, линтер, парсеры, RAG
├── datasets/      ← индекс карт + документация в markdown
├── rag_store/     ← готовый векторный индекс
├── .mcp.json      ← для Claude Code
└── opencode.json  ← для OpenCode
```

Документация собрана в двух версиях: **wiki 2.1.x** для старой версии, **docs 2.2.5** — современный мануал. `docs_card` по
умолчанию отдаёт документацию для 2.1.x.

---

## Проверка и возможные ошибки

```bash
.venv/bin/python tools/serpent_mcp_server_test.py   # Ручной запуск MCP
.venv/bin/python tools/serpent_lint_test.py         # Проверка работы линтера
.venv/bin/python tools/serpent_results_test.py      # Проверка работы парсера выходных файлов
.venv/bin/python tools/rag_eval.py --top 5          # Проверка работоспособности RAG
```

Если что-то не так:

| Симптом | Причина | Решение |
|---|---|---|
| `env_info` вернул `NO_BINARY` | нет `bin/sss2` | `cp /путь/к/sss2 bin/sss2 && chmod +x bin/sss2` |
| `env_info` вернул `NO_XSDATA` | пусто в `libraries/` | `cp -R /путь/к/xsdata/* libraries/` |
| `env_info` вернул `ACELIB_PATHS_STALE` | пути в индексе старые | `./setup.sh` или `python3 tools/fix_library.py` |
| `docs_search` вернул `RAG_DEPS_MISSING` | не поставлен `--extra rag` | `uv sync --extra rag` |
| сервер не подключается | нет `.venv` | `./setup.sh` |
---