Archicad MCP
README.md
# Archicad MCP
MCP-сервер для Archicad через аддон [Tapir](https://github.com/ENZYME-APD/tapir-archicad-automation).
Даёт модели проектные данные (стены, плиты, зоны, свойства, этажи) и умеет строить и править модель,
не заваливая её контекст семьюстами схемами.
## Что нужно
- Archicad 25–30 (поддерживается установленным Tapir).
- Аддон Tapir **2.0** внутри Archicad: ставится инсталлятором с
[релиз-страницы](https://github.com/ENZYME-APD/tapir-archicad-automation/releases/tag/2.0.0),
после установки аддон нужно один раз включить в `Options → Add-On Manager`: строка
«Tapir Additional JSON Commands», галочка слева. Сам файл лежит в
`Program Files\Graphisoft\Archicad NN\Add-Ons\Tapir\TapirAddOn_ACNN_Win.apx`.
- Python 3.11+ для самого сервера.
Tapir слушает `127.0.0.1:19723–19743` — первый запущенный Archicad занимает 19723, следующий
свободный. Сервер сам находит живой порт при первом вызове.
## Установка
```powershell
python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .
```
Проверка, что пакет жив (Archicad не нужен):
```powershell
.venv\Scripts\archicad-mcp.exe --list-tools
```
## Подключение
```json
{
"mcpServers": {
"archicad": {
"command": "D:\\path\\to\\Archicad MCP\\.venv\\Scripts\\archicad-mcp.exe",
"env": { "ARCHICAD_MCP_MODE": "safe" }
}
}
}
```
Переменные окружения:
| Переменная | По умолчанию | Что делает |
| --- | --- | --- |
| `ARCHICAD_MCP_MODE` | `safe` | `readonly` / `safe` / `full` — см. ниже |
| `ARCHICAD_MCP_PORT` | — | прибить один порт вместо перебора |
| `ARCHICAD_MCP_HOST` | `127.0.0.1` | адрес |
| `ARCHICAD_MCP_TIMEOUT` | `60` | таймаут одного вызова, секунды |
| `ARCHICAD_MCP_RESULT_BUDGET` | `12000` | сколько символов ответа отдавать целиком |
## Режимы
| Режим | Чтение | Изменения | Разрушающее (Delete*, Quit, Close) |
| --- | --- | --- | --- |
| `readonly` | да | отказ | отказ |
| `safe` | да | да | только dry-run, применение — по `confirm=true` |
| `full` | да | да | как есть |
Интерактивные команды (`GetPointFromUser`, диалоги, ScriptUI) блокируются везде, кроме `full`:
они останавливаются и ждут клика в Archicad, то есть подвешивают вызов.
## Инструменты
Чтение и состояние: `archicad_status`, `project_info`, `stories`, `find_elements`,
`selected_elements`, `element_details`.
Свойства: `search_properties`, `get_property_values`, `set_property_values`, `resolve_names`.
Свойства задаются **именами** — сервер сам достаёт id через `SearchProperties`.
Имена свойств Tapir отдаёт внутренние, без пробелов: `ElementID`, `Home Story`, `Type`, группа
`GeneralElemProperties`. С пробелом тоже можно: `Element ID` найдётся, сервер сравнивает имена
без пробелов и знаков.
Создание и правка: `create_walls`, `create_slabs`, `create_zones`, `select_elements`,
`delete_elements`.
Остальные ~770 команд Tapir (публикация, IFC, сметы, навигатор, MEP, отделки):
1. `search_commands("publish pdf")` — найти (у каждой находки есть `kind`: read / write /
destructive / interactive);
2. `describe_command("PublishPublisherSet")` — прочитать аргументы, форму ответа и строку
`Policy:` о том, что текущий режим сделает с этой командой;
3. `run_command("PublishPublisherSet", {...})` — вызвать.
Большие ответы обрезаются до бюджета, в них остаётся блок `_truncated` с `resultId`, `total` и
`showing`. Дальше `read_result(result_id, offset, limit)` — постраничное чтение.
Аргументы проверяются до отправки: если у команды нет такого аргумента, ответ будет
`CreateWalls does not take dryRun. Accepted arguments: wallsData.` вместо ответа Archicad
о нарушении правила JSON-схемы. Важная деталь: `dryRun` поддерживают не все команды — у
`CreateWalls` его нет, у `DeleteElements` и `SetPropertyValuesOfElements` есть.
`find_elements` и `selected_elements` отдают готовые guid-строки, их можно сразу передавать в
`element_details`, `get_property_values`, `select_elements`, `delete_elements`.
## Как это устроено
- `defs.py` — читает вендоренные определения Tapir (`src/archicad_mcp/tapir/*.js`, 789 команд),
разворачивает `$ref`, печатает сигнатуры.
- `client.py` — HTTP к Archicad: обёртка `API.ExecuteAddOnCommand`, поиск порта, человеческие
ошибки (`NotRunning`, `AddOnMissing`, `TimedOut`, `PortNotTapir`, `CommandFailed`).
- `classify.py` — политика режимов.
- `compact.py` — обрезка ответов и хранилище полных версий.
- `search.py` — BM25 по именам и описаниям команд.
- `tools.py` — сами инструменты, `server.py` — регистрация в MCP.
## Тесты
```powershell
.venv\Scripts\python.exe -m pytest -q
```
Архикада в тестах нет: `FakeTransport` из `tests/conftest.py` отвечает вместо него, поэтому
проверяется логика сервера, а не живой Archicad. Живой прогон — первый запуск через MCP-клиент.
## Проверено на живом Archicad
Archicad 26.0.0 R1 (build 5002) + Tapir 2.0.0, на настоящем рабочем проекте:
```powershell
python scripts\live_check.py
```
```json
{"port": 19723, "tapirAddOn": "2.0.0", "archicad": 26, "archicadBuild": 5002,
"language": "RUS", "mode": "safe", "connected": true, "commandsAvailable": 789}
```
Что это дало по фактам, а не по документации:
- Язык приходит полем `languageCode`, а не `language`.
- `GetElementsByType` в пустом проекте честно отдаёт пусто; в реальном — столько, сколько есть
объектов нужного типа.
- `GetPropertyValuesOfElements` отвечает **без id свойств**, значения идут в том же порядке, в
котором их спросили, — сервер раскладывает их по именам сам.
- Имена свойств внутренние: `ElementID`, `Type`, группа `GeneralElemProperties`.
- `CreateWalls` не принимает `dryRun`, поэтому превью создания стены невозможно: проверка только
через аргументы и ответ Archicad.
- `ChangeSelectionOfElements` и `GetSelectedElements` работают: `{"action":"added","requested":3,"done":3}`,
затем `{"count":4,...}` — четвёртый элемент уже был выделен до вызова.
- `DeleteElements` с `dryRun` отвечает `{"requested":1,"done":1}` и строкой
`Note: … was previewed only: dryRun was switched on. Nothing changed.`
- `CreateWalls` работает: две стены (0,0)→(5,0) и (0,0)→(0,5) с `floorIndex: 0`, `height: 3`,
`thickness: 0.2`, `structureType: "Basic"` появились в проекте, получили id `СТН-003` и `СТН-004`
и читаются обратно через `element_details(..., ["details"])` теми же координатами.
- Геометрия лежит не в отдельном поле, а внутри `details`: `fields` принимает только
`elementId`, `type`, `id`, `floorIndex`, `layerIndex`, `drawIndex`, `details`,
`floorPlanPolygons`, `hotlinkId`. Просьба `fields: ["begCoordinate"]` теперь ловится до отправки
и перечисляет допустимые значения.
## Когда Archicad занят
Пока в Archicad открыт модальный диалог, аддон отвечает на всё одной и той же ошибкой:
```json
{"succeeded": false, "error": {"code": 4001,
"message": "Invalid program status (there is an open modal dialog: Параметры Объекта по Умолчанию)"}}
```
Падает даже проба `GetAddOnVersion`, поэтому раньше сервер честно врал «аддон не установлен».
Теперь он различает эти случаи и пишет:
```json
{"error": "Archicad has a dialog open (Параметры Объекта по Умолчанию), so it cannot run commands.",
"hint": "Close the dialog in Archicad, then call again. Nothing was changed."}
```
Повтора нет: пока диалог открыт, любой вызов упрётся в то же самое. Для чтения сервер делает один
тихий повтор на случай, когда Archicad занят предыдущей командой; для изменения — никогда, потому
что повторный `DeleteElements` может удалить уже другое.
## Ограничения
- Tapir 1.x не поддерживается: используются команды, появившиеся в 2.0.
- На живом Archicad 26 проверены состояние, проект, этажи, поиск элементов, выделение, детали,
свойства, `resolve_names`, превью удаления, создание стен и люк `run_command`.
- `create_slabs` и `create_zones` проверены только схемой и фейком: для плиты нужен полигон с
уровнем, для зоны — категория и геометрия, и проверять их лучше на черновом проекте.
- `create_walls` принимает данные Tapir как есть (метры, `begCoordinate`/`endCoordinate`), без
разбора PDF или DWG.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues