# mathcad-prime-mcp

MCP-сервер поверх штатного Automation API PTC Mathcad Prime 12
(`Ptc.MathcadPrime.Automation.dll`, COM ProgID `MathcadPrime.Application`).
Даёт Claude открывать `.mcdx`-документы, читать/писать переменные, помеченные
как Input/Output, и сохранять файл.

## Важное ограничение

Automation API видит **только те переменные, которые в самом документе
Prime явно помечены** как Input или Output variable (ПКМ на переменной ->
"Set as Input/Output Variable" на ленте Automation). Обычные переменные без
такой метки через `mathcad_get_variables` не появятся и не читаются/пишутся.

## Особенность процесса

`MathcadPrime.exe` - синглтон на сессию Windows: повторные подключения COM
попадают в один и тот же процесс, включая уже открытый пользователем вручную.
`mathcad_quit` убивает процесс только если сервер сам его запустил (было
подтверждено тестом - если Prime уже был открыт до первого вызова, `quit`
ничего не закрывает).

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

- `mathcad_open(path)` - открыть/переиспользовать документ, список Input/Output
- `mathcad_list_worksheets()` - все открытые в текущем инстансе Prime документы
- `mathcad_get_variables(path)` - обновить список алиасов Input/Output
- `mathcad_set_value(path, name, value, units="")` - задать скаляр
- `mathcad_set_string(path, name, value)` - задать строку
- `mathcad_set_batch(path, values, timeout_ms=30000)` - пакетно задать несколько
  значений и пересчитать разом
- `mathcad_get_value(path, name, source="output"|"input")` - универсальное чтение
  (число/строка/матрица)
- `mathcad_get_value_as(path, name, units)` - чтение output с конвертацией единиц
- `mathcad_get_matrix` / `mathcad_set_matrix` - матрицы
- `mathcad_recalculate(path)` - форсировать пересчёт (Synchronize)
- `mathcad_save(path)` / `mathcad_save_as(path, new_path)`
- `mathcad_quit()` - безопасно закрыть только свой процесс

## Установка

```
uv sync
```

При ошибке uv `Failed to write to the client cache` - сломан junction
`AppData\Local\uv`, обходить через `UV_CACHE_DIR=<своя папка> uv sync`.

Зарегистрирован в `~/.claude.json` -> `mcpServers.mathcad-prime`
(`.venv\Scripts\python.exe -m mathcad_prime_mcp.server`). Нужен перезапуск
Claude Code, чтобы сервер подхватился.

## Что проверено вживую

Открытие реального документа (`lab1.mcdx`), чтение метаданных/списка
Input-Output, безопасность `mathcad_quit` (не трогает чужой уже открытый
процесс), корректность кириллических путей через COM. `set_value` /
`get_value` / batch / матрицы протестированы только по сигнатурам API (нет
под рукой документа с размеченными Input/Output переменными) - если что-то
пойдёт не так на реальном расчёте, смотреть сюда первым делом.

---

# Авторские инструменты: лист целиком из текста

Второй слой сервера (`tools_ws.py` + пакет `ws/`) обходит ограничение выше.
Он не пользуется Automation API для чтения значений, а работает с самим
файлом: `.mcdx` это zip, формулы лежат в `mathcad/worksheet.xml`, а все
посчитанные значения и ошибки Prime складывает в `mathcad/result.xml`.
Поэтому лист можно **собрать из текста и проверить, ни разу не взглянув на
экран**.

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

| Инструмент | Что делает |
|---|---|
| `mathcad_source_help` | синтаксис компактного исходника |
| `mathcad_write` | исходник -> `.mcdx`, пересчёт, проверка, выравнивание в два прохода |
| `mathcad_verify` | пересчитать и вернуть весь лист текстом: формулы, значения, ошибки |
| `mathcad_trace_data` | числовые данные кривых графика (для расчёта выводов) |
| `mathcad_figures` | png расчётной части и каждого графика, обрезанные по содержимому |
| `mathcad_cheatsheet` | памятка к защите: формулы + значения + пояснения `@note` |

## Формат исходника

```
# комментарий
@text 1. Чтение файла и параметры помехи      # подпись прямо в листе
S := READWAV("lab4.wav") ; m := floor(max(S)*0.1) ; L := length(S)
@note m - амплитуда шума, 10 процентов от максимума   # только в шпаргалку
n := 0..L-1 ; D[n] := rnd(m)-m/2 ; V[n] := S[n]+D[n]
WRITEWAV("out.wav",44100,16,V)=               # вычисление, показывает значение
L= ; sk=                                      # вывод значений
@plot x=n y=S[n]:red:2,V[n]:navy:1 xlim=0..200 ylim=0..5 size=620x260
@gap 40
```

Строка это ряд регионов, `;` разделяет регионы в ряду. Выражения: `+ - * / ^`,
`|x|` модуль, `f(a,b)` вызов, `X[i]` индекс, `a..b` диапазон. Греческие имена
по ASCII-псевдонимам: `Phi` (Хевисайд), `pi`, `sigma`, `omega`, `Delta`.
Слева от `:=` допустимо имя, `X[i]` или `f(x)`.

## Почему проверка не требует скриншотов

`mathcad_verify` печатает по строке на регион:

```
  6  sk := stdev(D)
 22  sk =  ->  183.909
 28  график  x=n,n  y=S[n],V[n]   x[0..44099] y[-6368..6368]; y[-6684..6683]
  2  b := a+zzz   ### ОШИБКА: Эта переменная не определена.
```

Текст ошибки тот же, что показывает Prime. У графиков видны диапазоны данных
каждой кривой, то есть корректность кривой проверяется числами.

## Как получается ровная вёрстка

Ширину формулы вместе с показанным результатом знает только Prime. Поэтому
`mathcad_write` собирает лист дважды: после первого пересчёта читает из файла
проставленные Prime `actualWidth`/`actualHeight` и раскладывает по ним ровными
колонками. Учитывается и то, что Prime привязывает формулу по базовой линии:
дроби и степени выступают вверх, под них резервируется место.

## Подписи в листе

Текстовый блок в Prime 12 это не просто тег: содержимое лежит в отдельной
части-архиве `mathcad/xaml/FlowDocumentN.XamlPackage` (WPF FlowDocument),
на которую ссылается `mathcad/_rels/worksheet.xml.rels`, а `item-idref`
элемента `<text>` совпадает с Id этой связи. Всё это собирает `ws/textblock.py`.

## Ограничения

- `rnd` даёт новую реализацию при каждом пересчёте: числа в отчёте и в файле
  совпадут, только если после последнего пересчёта не пересчитывать снова.
- Если формулы читают файлы по относительному имени (`READWAV`, `READPRN`),
  `.mcdx` должен лежать рядом с ними; для `mathcad_figures` это `work_dir`.
- `mathcad_figures` пересчитывает лист, поэтому `WRITEWAV`/`WRITEPRN` в
  исходнике перезапишут свои файлы новой реализацией шума.
- Картинки снимаются в масштабе Prime: при 100 % график шириной 610 единиц
  даёт ~610 px. Для более крупных картинок есть `zoom_clicks`.

## Схемы Prime

Полезно при расширении: `<установка Prime>\Mathcad Converter\schema\*.xsd`
описывают worksheet/math (версии 10-30, текущая в файлах 50, но структура
близка). Оттуда взята структура текстового региона.