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)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues