# FASTMEAN MCP

Локальный stdio MCP-сервер **1.0.1** для схем FASTMEAN: создание родных `.scm` с проводами и узлами, просмотр, нативный частотный и переходный анализ, символьные выражения через CIRSYM.

Для расчётов и открытия окна нужны Windows и отдельно установленный FASTMEAN 6.1/6.0. Программа, её решатели, шрифты и готовые DLL/EXE в репозиторий не включены. Создание, чтение и preview поддержанных схем доступны без приложения; `fastmean_status` сообщает `installed: false`.

## Установка в Codex

Нужны существующий Python 3.12+ с `venv`, Codex CLI и доступ pip к зависимостям. Для установки с подключением нативного движка сначала установите FASTMEAN отдельно. Из проверенной копии репозитория выполните:

```text
py -3.12 distribution/install.py --dry-run
py -3.12 distribution/install.py
py -3.12 distribution/doctor.py
```

Можно использовать другой уже установленный Python 3.12+. Для нестандартной установки FASTMEAN передайте `--app-dir "C:\Apps\FASTMEAN"` командам установки. Для нативных скриптов нужна доступная для записи папка результатов с ASCII-путём: задайте `--output-dir`, если стандартный путь содержит кириллицу.

Установщик создаёт отдельную среду в `%LOCALAPPDATA%\FastmeanMCP`, подключает сервер `fastmean` через Codex CLI и сохраняет резервную копию конфигурации. Остальные записи MCP, комментарии и пользовательские настройки сохраняются. Doctor выполняет initialize, обнаружение инструментов и status через настоящий stdio; расчёт она не запускает. После установки перезапустите подключение или приложение Codex. Настройка stdio описана в [официальной документации OpenAI](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).

Основной установщик использует обычный Python. Менять ExecutionPolicy, защиту Windows, системную кодировку, реестр или PATH не требуется. Обновление и удаление описаны в [distribution/README.md](distribution/README.md).

Один запрос агенту из открытого репозитория:

> Установи этот FASTMEAN MCP через distribution/install.py, проверь dry-run и doctor. Используй уже установленный Python и мою FASTMEAN. Сохрани остальные настройки Codex и не меняй настройки Windows. Если не хватает обязательной программы или доступа, сообщи конкретную причину.

Инструкции агенту — в [AGENTS.md](AGENTS.md). Сам сервер не требует ключа OpenAI API; доступ к модели определяется вашим MCP-клиентом.

## Возможности и инструменты

Можно попросить: «Создай RC-фильтр с R=1 кОм и C=1 мкФ, проверь рисунок, построй АЧХ и ФЧХ от 1 Гц до 100 кГц и получи передаточную функцию. Затем открой схему в FASTMEAN».

Обычная последовательность: status → example → create → preview → inspect → AC / transient / symbolic. Открытие окна выполняется отдельно через `fastmean_open`.

Доступны 17 инструментов:

| Инструмент | Назначение |
|---|---|
| `fastmean_status` | Установка, возможности, лимиты и активные операции |
| `fastmean_example` | JSON-примеры RC, RLC и делителя напряжения |
| `fastmean_create_circuit` | Новая родная SCM из элементов и узлов |
| `fastmean_inspect` | Компоненты, соединения, порты и параметры SCM |
| `fastmean_edit_values` | Изменение номиналов в новой копии |
| `fastmean_relayout` | Перекомпоновка поддержанной цепи с физическими проводами |
| `fastmean_preview` | PNG и SVG схемы для визуальной проверки |
| `fastmean_ac` | Нативная АЧХ/ФЧХ, CSV и PNG графика |
| `fastmean_transient` | Нативный переходный процесс, CSV и PNG |
| `fastmean_symbolic` | Нативная символьная формула и передаточная функция |
| `fastmean_list_examples` | Поиск схем в установленной FASTMEAN |
| `fastmean_open` | Открытие рабочей копии штатной программой |
| `fastmean_search_manual` | Поиск по включённой справке возможностей |
| `fastmean_list_runs` | Сохранённые задания и результаты |
| `fastmean_get_result` | Результат по run_id, изображения и ссылки на файлы |
| `fastmean_read_data` | Страница числовых данных CSV |
| `fastmean_cancel` | Отмена принадлежащей серверу активной операции |

## Схемы и рисунки

Создание поддерживает R, C, L и независимый источник напряжения U/V с постоянным, синусоидальным или импульсным сигналом. Узлы источника задаются как `[плюс, минус]`; `0` — земля. Имена — ASCII-идентификаторы. Номиналы задаются в СИ или строками с суффиксами: `M` — мега, `m` — милли, `u` — микро.

```json
{
  "components": [
    {"kind": "U", "name": "U1", "nodes": ["in", "0"], "value": 1, "waveform": {"kind": "sine", "frequency": "1k"}},
    {"kind": "R", "name": "R1", "nodes": ["in", "out"], "value": "1k"},
    {"kind": "C", "name": "C1", "nodes": ["out", "0"], "value": "1u"}
  ],
  "ports": ["in", "out"],
  "analysis": {"input": "in", "output": "out"}
}
```

Новые схемы используют соседние элементы, ортогональные провода и родные соединительные узлы. Порты обозначают внешние входы и выходы. Для ручной компоновки есть `layout.placements`, `layout.nodes`, `layout.ports` и `layout.routes`: координаты кратны 20, повороты — 0–3. Preview поддерживает перечисленные элементы, землю, порты, соединения и текст; неизвестные модели отклоняются. Его PNG/SVG помечен `MCP schematic preview, not native screenshot`.

[Point75A](examples/point75a/README.md) сохраняет расположение и все **25** R/L/C опубликованного кроссовера Troels Gravesen, Fig.31: [оригинальный PDF](http://www.troelsgravesen.dk/download/Point75A%26B.pdf). Четыре отдельно обозначенных компонента стенда — источник и три резистивные нагрузки — дают 29 элементов. Это электрическая модель фильтров: нагрузки 8 Ом не воспроизводят акустику динамиков. Оригинальные PDF и изображения не распространяются.

![Схема Point75A: MCP preview с проводниками](examples/point75a/preview.png)

Это рисунок, построенный MCP по SCM, с читаемыми обозначениями; не снимок окна FASTMEAN. [Готовая схема](examples/point75a/Point75A.scm) открывается в программе.

## Расчёты и результаты

FASTMEAN выполняет числовой расчёт через документированные скрипты. Matplotlib строит PNG по экспортированным нативным данным. Символьную формулу возвращает установленный `cirsymw.exe`; другим решателем она не подменяется. Preview схемы и график по данным имеют указанное происхождение и не являются снимками окна программы.

Исходные SCM сохраняются. Создание, редактирование, preview и расчёт получают отдельные папки. Нативная рабочая копия отключает окна графиков, развёртки и чтение сохранённого состояния; небезопасные файловые директивы отклоняются. `fastmean_open` явно открывает отдельную копию в GUI. Существующие пользовательские окна сервером не управляются.

JSON-ответы ограничены по размеру; полный результат сохраняется отдельным файлом. PNG передаётся также как MCP ImageContent, файлы — как ResourceLink. Ресурсы:

- `fastmean://guide` — справка возможностей и нативных команд;
- `fastmean://runs/{run_id}` — сохранённый результат и каталог файлов;
- `fastmean://artifacts/{run_id}/{name}` — опубликованный файл задания.

Читать можно только опубликованные файлы соответствующего задания. Отдельное чтение ограничено 8 МиБ; большие CSV читаются через `fastmean_read_data` страницами по 200 строк, максимум 500 за запрос. Активные operation_id доступны в status; отмена относится только к созданным сервером процессам.

| Переменная | Назначение |
|---|---|
| `FASTMEAN_APP_DIR` | Папка отдельно установленной FASTMEAN с Fastmean.exe |
| `FASTMEAN_OUTPUT_DIR` | Папка новых схем и результатов, вне установки приложения |

Приложение ищется в `%LOCALAPPDATA%\FASTMEAN 6.1`, затем 6.0. Установщик задаёт собственную папку `results`; при прямом запуске сервера используется `Documents\Codex\FASTMEAN-runs` текущего пользователя. MCP-клиент сам запускает stdio-сервер. Для разработки доступны `python -m fastmean_mcp` и console entry point `fastmean-mcp`.

## Ограничения и русский интерфейс

Символьный адаптер поддерживает линейные R/C/L, один независимый источник напряжения, выходной пробник и нулевые начальные условия. Для H(p) отрицательный вывод источника должен быть заземлён, а вход соответствовать положительному. Это не универсальный решатель произвольных уравнений. Старые бинарные SCM, создание нелинейных моделей и источников тока не поддержаны. Существующие схемы могут содержать модели, доступные числовому движку, но недоступные preview или символьному адаптеру. Ограничения DEMO задаёт установленная FASTMEAN.

Искажённые русские подписи старой ANSI-программы могут сохраняться в GUI. Необязательный [исходный помощник русского интерфейса](font-fix/README.md) меняет кодировку внутри процесса; он не устанавливает шрифты. Готовые EXE/DLL не включены. Windows Application Control / Smart App Control может блокировать этот загрузчик или локальную сборку; MCP работает без него. Обход защиты и изменение системной локали не выполняются.

## Разработка и проверки

[Результаты проверок](docs/validation.md). Большая схема проверена в родном окне FASTMEAN и независимым расчётом. В 1.0.1 исправлена публикация вложенных файлов через короткие Windows-пути DOS 8.3; проверки ссылок и выхода за папку задания сохранены.

```text
python -m pip install -r requirements-dev.txt
python -m pip install -e .
python -m pytest -q
```

CI настроен для Python 3.12 на Ubuntu и Windows без FASTMEAN. Нативные тесты там пропускаются: это проверка адаптера, а не сертификация движка. На Windows при наличии FASTMEAN тесты `test_engine` обнаруживают её автоматически. Для дополнительных настоящих stdio/relayout расчётов включите `FASTMEAN_MCP_NATIVE_TEST=1` и `FASTMEAN_RELAYOUT_NATIVE=1`. Они запускают установленную программу в отдельных рабочих процессах и сохраняют входные SCM.

Основные модули: `server.py` — MCP; `schematic.py` / `layout.py` — SCM и провода; `preview.py` — рисунок; `engine.py` — числовой CLI; `symbolic.py` — CIRSYM; `artifacts.py` — результаты и ресурсы. [Заметка о других инженерных MCP](docs/polish-review.md) объясняет принятые решения. Прохождение ещё не запущенного CI и совместимость со всеми установками не предполагаются: смотрите фактический журнал своего запуска.

Оригинальный код адаптера — [MIT](LICENSE). Исходный locale helper — LGPL-3.0-only; зависимости и внешние материалы перечислены в [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). FASTMEAN остаётся отдельным приложением со своей лицензией. Официальные возможности: [символьный анализ FASTMEAN](http://www.fastmean.ru/rus/index.php?page=symbolic.php).