@moabpro/recap-mcp

MCP-сервер MoabRecap для Claude Code: разработчик одной командой отправляет recap о сделанной работе, руководство видит сводку в портале. Авторизация — через портал (Keycloak device-flow), доступ строго по роли crew.

Требования: Node ≥ 20, Claude Code, учётка moab.tools с ролью crew.

Транспорт: почему плагин с http-демоном

У stdio есть неустранимая особенность: если процесс сервера умер (упал npx, не достучался до реестра, процесс убили), Claude Code не поднимает его заново — до перезапуска сессии тулы недоступны, recap отправить нельзя. Это цитата из документации CC:

If an HTTP or SSE server disconnects mid-session, Claude Code automatically reconnects with exponential backoff: up to five attempts… Stdio servers are local processes and are not reconnected automatically.

Поэтому основной способ установки — плагин Claude Code, который цепляется к локальному http-демону на 127.0.0.1:47823:

• соединение рвётся → Claude Code сам реконнектится (5 попыток с бэкоффом), а на старте — 3 попытки на connection refused;
• демон один на машину, живёт между сессиями и гаснет после 180 минут простоя;
• поднимается лениво: headersHelper плагина дёргает ensure-daemon перед подключением (CC ждёт его до 10 с) и он же перезапускает демона после обновления плагина;
• npm-реестр в горячем пути не участвует вообще — плагин везёт сервер одним бандлом.

Папку проекта демон узнаёт из заголовка X-Project-Dir, который Claude Code подставляет из ${CLAUDE_PROJECT_DIR} (подстановка работает только для конфигов, поставляемых плагином, — поэтому http-путь и оформлен плагином). Если заголовка нет, инструменты возвращают ошибку и не подставляют cwd демона: он общий на машину, и такая подстановка увела бы recap в чужой проект.

Stdio-режим никуда не делся — он остаётся запасным (npx -y @moabpro/recap-mcp, установка через init).

Установка (рекомендуемая: плагин из npm)

npx -y @moabpro/recap-mcp@latest install-plugin

Одна команда делает всё: кладёт плагин из пакета в ~/.moab/recap-marketplace, регистрирует маркетплейс moab (claude plugin marketplace add), ставит плагин, снимает старую stdio-установку и раскладывает команды. Затем перезапусти Claude Code и войди: /moab-login (нужна роль crew).

Плагин лежит внутри npm-пакета (plugin/ в тарболе) намеренно: репозиторий приватный, и /plugin marketplace add <git-url> у сотрудника без прав падает с not found (GitLab так отвечает и на «нет доступа»), а пакет — публичный. Кому доступ к репозиторию есть, git-маркетплейс тоже работает:

/plugin marketplace add https://gitlab.moab.tools/moab-org/Recap.git
/plugin install moab-recap@moab
npx -y @moabpro/recap-mcp init --remove-stdio

Команда снимает mcpServers.moab-recap и наш SessionStart-хук, добавляет авторазрешение тулов плагина и обновляет файлы команд в ~/.claude/commands/.

Команды живут не в плагине, а в ~/.claude/commands/ — намеренно: плагинные команды Claude Code всегда неймспейсит (/moab-recap:moab-switch-project), и привычное «/sw + Tab» перестаёт подставлять /moab-switch-project. Файлы кладёт init и, дальше сам, SessionStart-хук плагина — так что они обновляются вместе с плагином, а имена остаются короткими. У свежей установки без init команды появятся со второй сессии (первый раз их пишет хук).

Обновление — та же команда (npx -y @moabpro/recap-mcp@latest install-plugin); для git-маркетплейса — /plugin marketplace update moab. Демон старой версии гасится и заменяется автоматически при следующем подключении.

Установка (запасная: stdio)

npx -y @moabpro/recap-mcp init

Что делает init (глобально, для всех сессий):

• ~/.claude.json → mcpServers.moab-recap (запуск через npx -y @moabpro/recap-mcp);
• ~/.claude/settings.json → SessionStart-хук + авторазрешение тулов сервера (permissions.allow);
• ~/.claude/commands/ → команды moab-recap, moab-switch-project, moab-login, moab-logout, moab-status;
• подчищает хуки и команды старого PowerShell-клиента (recap-*.ps1, moabrecap.md, switch-project.md, moabupdate.md → ~/.claude/commands/_pre-recap-mcp-bak/);
• перед записью делает бэкапы *.recap-bak.

Команды

| Команда | Что делает | | --- | --- | | /moab-switch-project [имя\|0\|N\|*] | Закрепить проект за текущей папкой. Без аргумента подставляется имя текущей папки: проект с таким именем закрепляется сразу, а если его нет — показывается полная таблица, чтобы выбрать существующий или создать новый. 0 — research-режим (без рекапов); N — создать новый; * — полный список без подстановки. Если с прошлого рекапа осталась работа сложности ≥ 4 — сначала предложит /moab-recap; мелочь (≤ 3) пропускает молча. | | /moab-recap [подсказка] | Собрать и отправить recap за окно «с прошлого рекапа»: summary для руководства, теги, сложность и трудозатраты. Аргумент передаётся как userHint. | | /moab-login | Вход (device-flow). | | /moab-status | Статус входа; дотягивает подтверждённый в браузере вход. | | /moab-logout | Сбросить сохранённые токены. |

Как это работает

• Проект закреплён за ПАПКОЙ, а не за сессией. Ключ — корень проекта (CLAUDE_PROJECT_DIR у stdio, заголовок X-Project-Dir у http), пины лежат в ~/.claude-recap-pins.json. Session-id не используется: он наследовался между терминалами и уводил рекапы в чужой проект.
• SessionStart-хук подставляет в контекст, какой проект закреплён (и ставит заголовок сессии). Если папка не закреплена — просит сначала выполнить /moab-switch-project.
• Окно «с прошлого рекапа» считается по якорю в таком порядке: локальный ~/.claude-recap-last.json → время последнего рекапа проекта с сервера → старт сессии → последние 12 часов. Локальный якорь переживает /clear, компакт и перезапуск.
• Git-статистика (файлы, коммиты, +/−) собирается сервером инструмента сама — вручную ничего считать не нужно.
• Транскрипт берётся из папки своего проекта (~/.claude/projects/<путь-через-дефисы>): один демон обслуживает все терминалы сразу, и «самый свежий транскрипт по машине» мог оказаться чужим.
• Порог «мелочи» одинаков везде. /moab-recap при сложности ≤ 3 спрашивает «может, ещё поработаем?», и /moab-switch-project при той же сложности молча не предлагает рекап — чтобы доделанная после рекапа мелочь не превращалась в вопрос на каждом старте сессии.
• research-режим (/moab-switch-project 0) — папка помечается как исследовательская, рекапы по ней не отправляются.

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

| Инструмент | Назначение | | --- | --- | | moab_login / moab_auth_status / moab_auth_logout | Вход, статус, выход. | | list_projects | Список проектов пользователя. Без search подставляет имя текущей папки, search="*" — весь список, точное совпадение → AUTO_SELECT. | | pin_project | Закрепить проект (или __research__) за папкой. | | recap_status | Read-only, без сети: есть ли работа с прошлого рекапа (HAS_WORK … + окно и срез git-выхлопа для оценки сложности / NO_WORK …). | | get_project_brief / set_project_brief | Бриф проекта «что это и зачем» — общий на проект, идёт в отчёт руководству. | | send_recap | Отправка рекапа (summary, tags, complexityRating, effortRating, опц. userHint). |

Вызывать инструменты напрямую не нужно — их дёргают slash-команды.

CLI

| Команда | Что делает | | --- | --- | | recap-mcp | stdio-сервер (так его запускает Claude Code при stdio-установке). | | recap-mcp serve --http [--port N] | Поднять http-демон (обычно его запускает ensure-daemon, вручную нужен для отладки). | | recap-mcp ensure-daemon [--wait ms] | Проверить/поднять демона; печатает {} — это контракт headersHelper Claude Code. | | recap-mcp daemon-status / daemon-stop | Статус и остановка демона. | | recap-mcp install-plugin (= init --plugin) | Поставить плагин из пакета: копия в ~/.moab/recap-marketplace → claude plugin marketplace add + install → снять stdio → команды. | | recap-mcp init [--remove-stdio] | Поставить stdio-установку / снять её при переезде на плагин. | | recap-mcp session-start [--ensure] | Тело SessionStart-хука (--ensure — попутно будит демона; так его зовёт плагин). |

Конфигурация (опц., env)

| Переменная | По умолчанию | | --- | --- | | RECAP_URL | https://recap.moab.tools | | KEYCLOAK_AUTHORITY | https://auth.moab.tools/realms/moab | | KEYCLOAK_CLIENT | recap-cli | | MOAB_CONFIG_DIR | ~/.moab (токены — в ~/.moab/recap-mcp) | | RECAP_MCP_PORT | 47823 (порт демона; менять — только вместе с url в plugin/.mcp.json) | | RECAP_MCP_IDLE_MIN | 180 (простой до самовыключения демона; 0 — не гасить) |

Файлы на диске

• ~/.claude-recap-pins.json — какой проект закреплён за какой папкой;
• ~/.claude-recap-last.json — якорь «прошлый рекап»;
• ~/.moab/recap-mcp/ — сохранённые токены входа;
• ~/.moab/recap-mcp/daemon.log — лог демона (обрезается на 512 КБ).

Разработка

npm run build     # tsc → sync-plugin (команды + версии плагина) → esbuild-бандл в ../plugin/server
npm test          # vitest

npm run build — единственный способ обновить плагин: версия в src/version.ts должна совпадать с package.json (иначе сборка падает), а plugin/commands/ сборка сносит, если он вдруг появился (команды ставятся в ~/.claude/commands, см. init.ts:ensureCommandFiles). Тексты команд — в src/commands.ts, единый источник для init и хука. Бандл plugin/server/moab-recap.mjs коммитится: плагин раздаётся гитом, а не npm.

Лицензия: UNLICENSED (внутренний инструмент moab.tools).