Skip to main content
Glama
Archicad MCP

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.