# mcp-super-app

MCP-сервер для Claude Code: собирает рутинные setup-действия (каркас проекта, скиллы,
среда сборки лендинга, guard-хук, картинки, иконки) в одну точку входа. Подключил
сервер → все инструменты доступны из любого чата обычными tool-вызовами.

Стек: TypeScript + `@modelcontextprotocol/sdk`, транспорт **stdio** (локальный сервер,
никуда ничего не отправляет, кроме OpenRouter при генерации картинок).

---

## Установка

Пошаговая инструкция — в [INSTALL.md](INSTALL.md). Она из двух частей: сначала три
шага для человека (открыть новый чат в Claude Code — папку выбирать не нужно — и
включить режим «Bypass Permissions»), потом готовый текст, который копируется в чат
целиком. Дальше агент делает всё сам — определяет
систему (macOS или Windows), выбирает папку под сервер, проверяет окружение, скачивает и
собирает сервер, подключает его к Claude Code и чинит ошибки по дороге. Разбираться в
коде не нужно.

Если сервер уже стоял и нужно просто переустановить — можно короче, одной фразой:

```
Установи MCP-сервер по инструкции: https://github.com/AndreyTsibin/mcp-super-app-public/blob/main/INSTALL.md
```

Что делать, если что-то пошло не так, — там же, раздел «Что делать, если не заработало».

Что умеет сервер целиком — девять инструментов, каталог скиллов, цены на генерацию
картинок и типовые маршруты работы — в [карте инструментов](docs/TOOLS.md).

---

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

- **Node.js ≥ 20**.
- **Ключ OpenRouter** — только для `create_image`. Остальные инструменты работают без ключа.
  Ключ у каждого свой: <https://openrouter.ai/keys>.

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

| Инструмент | Что делает |
|---|---|
| `bootstrap_project` | Разворачивает каркас нового проекта одним вызовом: `.gitignore`, `.editorconfig`, `.claude/` (settings, хук, `CLAUDE.md`, `HANDOFF`), `docs/` по профилю **S/M/L** и Auto-memory. Идемпотентно — существующее не затирает. |
| `install_skill` | Ставит скилл в проект: bundled → копия в `.claude/skills/<id>/`; proxied → прогон официального CLI. Если скилл несёт слэш-команды (`diagram-design` — диаграммы), они кладутся в `.claude/commands/`. Артефакты авто-добавляются в `.gitignore` (команды — пофайлово, чтобы свои команды проекта остались под git). Каталог доступных скиллов (тип, назначение, команда установки для proxied) лежит прямо в описании параметра `skill`. |
| `create_website` | Единая точка входа для сайтов, режим выбирается параметром `kind`. **`landing`** — Astro-проект генератора: библиотека из 21 секции с вариантами, токен-контракт + тема, страницы `/kit` (полигон) и `/themes` (выбор темы), каркасы страниц с маркерами `[[…]]` вместо текста, стандарты `docs/`, шаблоны заявок `send.php` + `lead-form.js`, previewer и машинный валидатор `.claude/check-landing.mjs`. **`multipage`** — перенос существующего сайта на Astro: playbook метода (выбор режима — точная копия своего сайта/макета или редизайн по чужому донору, разведка донора, единственные источники правды, токены, редизайн-дельта против фильтров за дубли для режима B, роутинг, приёмка) + обкатанный код заявок; шаблон и каркас не разворачиваются намеренно — стек и структура зависят от донора. Оба режима ставят скиллы флоу, пишут `docs/_dev/tracker.md` (одна строка = одна сессия) и дописывают протокол «одна сессия = одна задача» в `.claude/CLAUDE.md` проекта. |
| `install_guard` | Ставит PreToolUse-хук защиты от деструктивных команд (`rm`, `find -delete`, `git reset --hard` и т.п.) — глобально (`target=user`) или в проект. Безопасный merge в `settings.json`. |
| `create_image` | Единая точка входа для картинок: генерация и редактирование через OpenRouter. Возвращает **картинку в чат** + сохраняет файл в проект (`./generated` по умолчанию) + отдаёт `usage.cost`. Выбор модели начинается с вопроса «кадр идёт в продакшен?». Да (лендинг, сайт клиента, всё, что увидит аудитория) — `google/gemini-3.1-flash-image` + `resolution:'2K'` ($0.101, 2752×1536), и вся серия на нём же. Это же модель по умолчанию. Нет (черновики, референсы, эксперименты) — `google/gemini-3.1-flash-lite-image` + `resolution:'1K'` ($0.034, самый быстрый кадр). Не понравился черновой кадр или впереди правки и серия — `bytedance-seed/seedream-5-0-lite` ($0.035 флэт, 7.5 МП, лучший редактор). Ещё есть `google/gemini-3-pro-image` для сложнейших сцен и `bytedance-seed/seedream-5-0-pro` — по прямой просьбе. Всего пять моделей, других инструмент не принимает. `reference_images` (пути/URL) — image-to-image, редактирование и консистентность серии. **Промпт обязателен через скилл `image`:** нет скилла в проекте или пустой `prompt_source` — тул отказывает и не тратит деньги. |
| `optimize_images` | Готовит картинки к продакшену (sharp): ресайз до `max_width` (без апскейла), конверт в webp/jpeg/avif, EXIF-поворот, опциональные srcset-варианты (`widths`). По умолчанию заменяет исходник оптимизированным файлом. Возвращает итоговые размеры (для `width`/`height` в `<img>`). |
| `search_icons` | Ищет иконку по английскому слову/концепту в двух наборах: **lucide** (~2000 generic UI-иконок — wrench, shield, clock…) и **simple-icons** (~3400 лого брендов — GitHub, HP, Telegram…). Возвращает точные `name`/`set` для `get_icon`. |
| `get_icon` | Отдаёт сырой SVG иконки по точному `name`/`set`. `size` — px (квадрат), `color` — CSS-цвет (lucide и так `currentColor`; simple-icons по умолчанию — официальный фирменный hex бренда). |
| `update_server` | Обновляет сам сервер: `git pull --ff-only` в его каталоге, при изменившемся манифесте — `npm install`, затем `npm run build`. Отказывается работать, если в каталоге есть незакоммиченные правки. После обновления требует перезапуска приложения — процесс продолжает крутить старый код. |


Меню точек входа живёт в глобальном скилле `mcp-super-app` — сервер **ставит и обновляет
его сам**, при каждом старте и после `update_server`. Вписывать правило в личный `CLAUDE.md`
не нужно: скилл едет вместе с сервером и одинаков у всех. `MCP instructions` при этом ужаты
до указателя на скилл плюс короткий фолбэк на случай, когда клиент скилл ещё не подхватил.
Туда же при старте попадают самопроверки: **сборка устарела** (`src/` новее запущенного
`dist/` — правки не применились), **доступно обновление** (в репозитории вышла версия свежее
установленной; проверка через `git ls-remote`, кэш на сутки, при отсутствии сети молча
пропускается) и **не хватает обязательных ключей в `.env`**. Когда обновление есть, оно
становится дополнительным пунктом того же меню точек входа.

## Ключ OpenRouter

Нужен, только если будешь генерировать картинки.

```bash
cp .env.example .env
# впиши свой ключ: OPENROUTER_API_KEY=sk-or-v1-...
```

`.env` игнорируется git (см. `.gitignore`). Ключ берётся из `.env` в корне пакета —
сервер грузит его сам при старте, передавать через конфиг не нужно.

## Подключение к Claude Code вручную

Если по какой-то причине не сработал автоматический путь из [INSTALL.md](INSTALL.md).

Сервер подключается **глобально**, для всех проектов сразу. Регистрация на одну папку —
самая частая причина «инструменты были и пропали».

**1. CLI** (`-s user` = во всех проектах):

```bash
claude mcp add mcp-super-app -s user -- node /абсолютный/путь/к/mcp-super-app/dist/index.js
```

**2. Нет команды `claude`?** Так бывает, когда стоит десктопное приложение: оно не кладёт
CLI в PATH. Тогда добавь сервер в **корневой** ключ `mcpServers` файла `.claude.json` в
домашней папке. Этот файл хранит состояние клиента — не перезаписывай его целиком, сними
копию и допиши:

```json
{
  "mcpServers": {
    "mcp-super-app": {
      "command": "node",
      "args": ["/абсолютный/путь/к/mcp-super-app/dist/index.js"]
    }
  }
}
```

Путь обязательно абсолютный — `~` и относительные не разворачиваются, конфиг
глобальный. На Windows это `C:\\Users\\Имя\\mcp-super-app\\dist\\index.js`
(в JSON обратные слэши экранируются, как здесь).

Домашнюю папку узнавай командой `node -e "console.log(require('os').homedir())"`, а не по
`~`: на Windows с рабочим или доменным профилем домашняя папка часто лежит на сетевом
диске, и конфиг, записанный по `~`, ложится мимо приложения. Ту же запись внутри ключа
`projects` клиент применит только к одной папке — как и файл `.mcp.json` в корне проекта.

Проверить, что получилось: `claude mcp list` — сервер должен быть в списке и подключён.

**Обновления — через агента, в консоль лезть не нужно.** Сервер при старте сам смотрит,
не ушла ли ветка в origin вперёд, и если ушла — говорит об этом в начале сессии. Дальше
достаточно сказать Claude Code «обнови сервер»: тул `update_server` сделает `git pull`,
при необходимости переустановит зависимости, пересоберёт и попросит перезапустить
приложение. Руками то же самое: `git pull && npm install && npm run build` в папке
репозитория + перезапуск.

**Что сервер проверяет при старте.** Три вещи, и о каждой он молчит, пока всё в порядке:

- **вышло ли обновление** — сравнивает твою копию с origin по свежему тегу версии;
- **собран ли он из текущих исходников** — если обновиться руками (`git pull`) и забыть
  `npm run build`, сервер продолжит работать по старому коду, а правки будут выглядеть
  как «не применились»;
- **заданы ли в `.env` обязательные ключи** — обновление может добавить новый ключ, и без
  этой проверки ты бы упёрся в ошибку инструмента, которая выглядит как его поломка.
  Какие ключи обязательны, написано в `.env.example`: обязателен каждый, у которого нет
  пометки `# optional`.

Проверки безопасны и результат обновления кэшируется на сутки: нет сети, git или файлов —
сервер просто стартует молча. `update_server` отказывается работать, если в папке сервера
есть незакоммиченные правки — чужую работу он не трогает.

После подключения перезапусти Claude Code.

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

```bash
npm install
npm run build      # компиляция TS → dist/
npm run dev        # tsx watch — запуск из src/ без сборки
npm run typecheck  # tsc --noEmit
npx @modelcontextprotocol/inspector node dist/index.js   # ручная проверка тулов
```

Точка запуска сервера — `dist/index.js` (stdio).

## Структура

```
src/
├── index.ts          # точка входа: регистрация tools + stdio transport, загрузка .env
├── lib/              # общая инфра: openrouter, scaffold, project-slug, errors, settings-merge, …
└── tools/            # по модулю на инструмент
assets/               # статические шаблоны: skills/, bootstrap/, landing/, guard/
docs/                 # спеки и стандарты (архитектура, API)
```

Договорённости и рабочий метод — в [`.claude/CLAUDE.md`](.claude/CLAUDE.md).

## Правки и баг-репорты

**Этот репозиторий — зеркало.** Разработка идёт в приватной копии, а сюда `src/`, `assets/`
и `docs/` приезжают побайтово при каждом релизе, вместе с удалением лишнего. Поэтому
любая правка, сделанная здесь напрямую — коммитом в `main` или мержем pull request, —
живёт до следующего релиза и затем молча исчезает.

Что это значит на практике:

- **Нашёл баг — заведи [issue](https://github.com/AndreyTsibin/mcp-super-app-public/issues).**
  Это рабочий канал, читается.
- **Pull request тоже можно** — он полезен как баг-репорт с готовым патчем, и разбирать
  его так и будут. Но смержен он не будет: правка переносится в приватную копию, выходит
  релизом, а PR закрывается со ссылкой на версию, в которой она приехала. Это не отказ,
  просто иначе она не выживет.
- **Ставить сервер форком не нужно** — обновления приходят через `update_server`, ему нужен
  обычный клон.