mcp-super-app

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

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

Установка

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

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

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

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

Что умеет сервер целиком — девять инструментов, каталог скиллов, цены на генерацию картинок и типовые маршруты работы — в карте инструментов.

Требования

• Node.js ≥ 20.

• Ключ OpenRouter — только для create_image. Остальные инструменты работают без ключа. Ключ у каждого свой: https://openrouter.ai/keys.

Инструменты

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

Ключ OpenRouter

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

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

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

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

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

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

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

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

2. Нет команды claude? Так бывает, когда стоит десктопное приложение: оно не кладёт CLI в PATH. Тогда добавь сервер в корневой ключ mcpServers файла .claude.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.

Разработка

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.

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

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

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

• Нашёл баг — заведи issue. Это рабочий канал, читается.

• Pull request тоже можно — он полезен как баг-репорт с готовым патчем, и разбирать его так и будут. Но смержен он не будет: правка переносится в приватную копию, выходит релизом, а PR закрывается со ссылкой на версию, в которой она приехала. Это не отказ, просто иначе она не выживет.

• Ставить сервер форком не нужно — обновления приходят через update_server, ему нужен обычный клон.