Skip to main content
Glama
remplanner-mcp

remplanner-mcp

by pom6ac
README.md
# remplanner-mcp

MCP-сервер (stdio) для рисования планировок в [remplanner.ru](https://remplanner.ru): создание и открытие
проектов, комнаты и стены точными размерами, проёмы, двери и окна, мебель и сантехника из каталога,
валидация модели, рендер плана картинкой, сохранение с бэкапом и сверкой. 36 инструментов; все размеры
в миллиметрах.

Документация: `docs/design.md` (архитектура и факты о сайте), `docs/tasks.md` (план),
`docs/remplanner-features.md` (функции сайта), `CONTRIBUTING.md` (процесс разработки), `AGENTS.md`
(правила для агентов).

## Требования

- Node.js **≥ 22.18** (код на TypeScript исполняется напрямую, без сборки).
- **Chrome** (сервер запускает headless-браузер через `playwright-core`).
- Доступ к `remplanner.ru`.

Если корпоративная сеть подменяет TLS-сертификаты, добавьте свой корневой сертификат — **это опция,
обычно не нужна**:

```sh
export NODE_EXTRA_CA_CERTS=/путь/к/corp-root.pem   # при необходимости
```

## Установка

```sh
git clone https://github.com/pom6ac/remplanner-mcp.git
cd remplanner-mcp
npm install
npm run typecheck && npm test
```

## Учётные данные и вход

Учётные данные лежат в `~/.remplanner-mcp/credentials.env` (каталог 0700, файл 0600, создаётся вручную):

```
REMPLANNER_LOGIN=...
REMPLANNER_PASSWORD=...
```

Вход и проверка:

```sh
npm run login   # вход, сессия -> ~/.remplanner-mcp/state.json (0600)
npm run check   # статус: logged_in, тариф, число проектов
```

Можно работать и без аккаунта: анонимный проект создаётся инструментом `project_create` и живёт
в cookie-сессии сервера (`~/.remplanner-mcp/state.anon.json`), квоту аккаунта не занимает.

## Подключение к агентам

Замените `<путь-к-репозиторию>` на путь, куда склонировали репозиторий.

### Claude Code

```sh
claude mcp add -s user remplanner -- node <путь-к-репозиторию>/src/cli.ts serve
```

### OpenCode (`~/.config/opencode/opencode.json`)

```json
{
  "mcp": {
    "remplanner": {
      "type": "local",
      "command": ["node", "<путь-к-репозиторию>/src/cli.ts", "serve"],
      "enabled": true
    }
  }
}
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.remplanner]
command = "node"
args = ["<путь-к-репозиторию>/src/cli.ts", "serve"]
startup_timeout_sec = 60
tool_timeout_sec = 120
```

Проверка: в клиенте должен появиться список из 36 инструментов `remplanner` (от `auth_status`
до `render_plan`). Полезные переменные окружения: `REMPLANNER_HEADED=1` (видимый браузер),
`REMPLANNER_ANON=1` (работать только анонимно), `REMPLANNER_BROWSER=<путь>` (свой Chrome).

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

- **Одна сессия на аккаунт.** Вход из MCP выбивает открытую вкладку сайта и наоборот. Пока агент
  работает, не открывайте ЛК и редактор remplanner.ru в браузере.
- **Бесплатный тариф — один проект** в аккаунте; второй создать нельзя (`PLAN_LIMIT`), копирование
  и этажи — PRO. Анонимные проекты квоту не занимают.
- **X-пересечения стен не поддержаны** (`UNSUPPORTED_JUNCTION`): стену в точке примыкания нужно
  разрезать `wall_split`.
- **Бэкап перед сохранением:** перед каждой записью снимок модели пишется в `~/.remplanner-mcp/backups/`,
  после сохранения модель на сервере сверяется повторным чтением.
- Известные дефекты (отчёт пользовательского испытания, см. также `model_validate` и таблицу ошибок):
  - `render_plan` может отрисовать не текущую ревизию модели: мутации стен синхронизируются
    с редактором, предметные (`item_add`/`item_update`) перед рендером в редактор не проталкиваются,
    ревизия модели в ответе не возвращается — после правок предметов сверяйтесь с `model_validate`;
  - `model_validate` проверяет попадание в комнату только центра предмета, частичный выход
    габарита (bbox) за комнату не ловится;
  - `project_open` при неожиданном ответе сервера может вернуть пустую модель без предупреждения —
    сравнивайте с ожиданиями перед сохранением.

## Как пользоваться

Пример запроса агенту (в Claude Code / OpenCode / Codex с подключённым сервером):

> «Открой анонимный проект и нарисуй комнату 4000×3000 мм, сделай дверь на южной стене по центру
> и окно на северной, поставь диван вдоль западной стены. Покажи план и сохрани».

Типовой сценарий инструментов:

```
project_create            # анонимный проект (или project_open для проекта аккаунта)
room_add_rect             # комната 4000×3000
opening_add               # дверь, окно
catalog_search + item_add # мебель из каталога
model_validate            # проверка геометрии перед сохранением
render_plan               # PNG плана
project_save              # сохранение с бэкапом и сверкой
```

Типовые ошибки и их расшифровка — в таблице ниже.

| Код | Что означает | Что делать |
|---|---|---|
| `AUTH_REQUIRED` | нет `credentials.env` или `state.json` | выполните `npm run login` |
| `SESSION_TAKEN_OVER` | сессию выбил вход в другом месте | закройте вкладку сайта или подождите 10 минут, затем `npm run check` |
| `SAVE_CONFLICT` | `save_id` на сервере новее рабочей копии | `project_open` (перечитать) или `project_save` с `force: true` только по явному решению |
| `GEOMETRY_CONFLICT` | пересечение стен, проём вне стены | проверьте `model_validate`, разделите стену `wall_split` |
| `UNSUPPORTED_JUNCTION` | T/X-примыкание стен | разрежьте стену `wall_split` в точке примыкания |
| `OUTSIDE_ROOM` | предмет/точка вне помещений | задайте позицию внутри комнаты (метки `R1…` из `model_get`) |
| `NORMALIZATION_DROPPED` | редактор удалил элементы модели | проверьте `model_validate`: короткие стены, проёмы без опоры |
| `EDITOR_INCOMPATIBLE` | сайт обновился, контракт адаптера не прошёл | прогоните `npm run test:contract`, сверьте `src/editor/inject.js` |
| `EDITOR_PROJECT_MISMATCH` | редактор открыл другой проект | сохранение в чужой проект запрещено; перечитайте `project_open` |
| `CAPTCHA_REQUIRED` | сайт требует капчу | ручной `npm run login --headed` |
| `RATE_LIMITED` / `TIMEOUT` | лимит частоты (30 запросов/мин, сохранение ≤ 1 в 5 с) | повторите позже — лимитер встроен |

## Дорожная карта

Фаза 2 (`docs/phase2-design.md`) — поддержка правок существующей геометрии и richer-редактирование:
демонтаж и перенос стен с пересчётом примыканий, перегородки, электрика и вода (розетки, выводы),
отделка поверхностей; покрытие редактора сверяется с эталонными пробами, задачи F2-01…F2-12
в `docs/phase2-tasks.md`.

## Разработка

```sh
npm test               # юнит-тесты (node --test, без сети)
npm run test:contract  # контракт адаптера редактора (анонимно, сеть)
npm run test:live      # живой сценарий (только REMPLANNER_LIVE=1, анонимно)
```

Процесс разработки и роли — в [CONTRIBUTING.md](CONTRIBUTING.md), правила для агентов —
в [AGENTS.md](AGENTS.md).

## Лицензия

[MIT](LICENSE)