@happ-ai/platform-mcp

中文文档
0.46.1发布于 2026/11/17TypeScriptESM + CJS近 30 天下载 6280

MCP server exposing the Happ platform API as tools (login, companies, assistants, channels, phones)

原始使用文档
文档目录7 节
  1. Подключение MCP
  2. Обновления
  3. Локальная разработка (из исходников)
  4. CLI
  5. Трасса сессии и отчёты о проблемах
  6. Что умеет MCP-сервер
  7. Разработка

@happ-ai/platform-mcp

MCP-сервер и CLI для платформы Happ: даёт Claude Code (и любому MCP-клиенту) доступ к API платформы — компании, ассистенты, каналы, чаты, звонки, аналитика. Один бинарник работает в двух режимах: без аргументов стартует как MCP-сервер (stdio), с командой (login, whoami, …) — как обычный CLI.

Подключение MCP

Пакет публичный на npmjs, токены и env-переменные не нужны — окружение выбирается именем бинарника:

БинарникAPIКлиент
happapi.happ.tools (прод)my.happ.tools
happ-devapi.dev.happ.tools (дев)dev.happ.tools
happ-mcplocalhost:3000 (локальный)localhost:4001
# прод
claude mcp add -s user happ -- npx -y @happ-ai/platform-mcp@latest

# дев
claude mcp add -s user happ-dev -- npx -y --package=@happ-ai/platform-mcp@latest happ-dev

Используй именно --package= (длинную форму): голый -p в аргументах после -- ломает парсинг claude mcp add.

Windows. npm-шимы (happ-dev.cmd) запускают dist/index.js напрямую, имя бинарника теряется и happ-dev уходит на прод. Задавай окружение явно: -e HAPP_ENV=dev (значения prod | dev | local, перебивает имя бинарника, но не явные HAPP_API_URL/HAPP_CLIENT_URL):

claude mcp add -s user happ-dev -e HAPP_ENV=dev -- npx -y @happ-ai/platform-mcp@latest

Если браузер не открылся автоматически (Windows без ассоциации, headless, SSH), happ login и happ_login сразу печатают ссылку /cli-auth?port=… — открой её вручную в течение 3 минут, слушатель ждёт на 127.0.0.1.

Обновления

  • MCP через @latest (команды выше) обновляется сам: npx сверяется с npm при каждом старте сервера, так что новая версия подхватывается при следующей сессии Claude Code. Ничего делать не нужно.
  • MCP без @latest (старая регистрация) застревает в кеше npx навсегда. Перерегистрируй один раз: claude mcp remove happ, затем команда подключения из раздела выше.
  • Глобальная установка CLI (npm install -g) сама не обновляется — обнови вручную: npm update -g @happ-ai/platform-mcp.

Сервер сам напоминает об устаревании: happ_login / happ_whoami (и happ login / happ whoami в терминале) сверяют текущую версию с последней опубликованной в npm и дописывают подсказку об обновлении, если вышла новая. Проверка тихая: без сети или при недоступном registry ничего не ломается и не тормозит (таймаут 2.5 с).

Локальная разработка (из исходников)

pnpm install && pnpm build
claude mcp add happ \
  -e HAPP_API_URL=http://localhost:3000/api \
  -e HAPP_CLIENT_URL=http://localhost:4001 \
  -- node /абсолютный/путь/до/platform-mcp/dist/index.js

Явные HAPP_API_URL / HAPP_CLIENT_URL всегда перебивают пресеты имени бинарника. После пересборки (pnpm build) уже запущенную сессию Claude Code нужно переподключить к серверу (/mcp → reconnect), иначе она держит старый процесс.

CLI

Те же три имени (happ, happ-dev, happ-mcp) работают как терминальный CLI:

happ login    # вход через браузер, сохраняет токен в ~/.happ/credentials.json
happ whoami   # текущий пользователь (GET /auth/me)
happ logout   # удалить сохранённый токен
happ help     # справка

happ login открывает страницу /cli-auth веб-клиента, где ты подтверждаешь вход; одноразовый код обменивается на персональный токен happ_… (живёт 90 дней, отзывается администратором в админке — раздел Access keys на карточке пользователя). Токены хранятся в ~/.happ/credentials.json раздельно по API-адресу, так что логины в прод/дев/локалку живут одновременно.

Если токен отозван или истёк, инструменты отвечают ошибкой 401 с просьбой перелогиниться через happ login — автоматически браузер не открывается.

Трасса сессии и отчёты о проблемах

Сервер ведёт журнал вызовов happ_* инструментов текущей сессии (аргументы, укороченный ответ, ошибка целиком, длительность) и в фоне отправляет его батчами в POST /mcp-telemetry/events платформы — команда Happ видит сессии в админке (/mcp). Отправка best-effort: недоступный эндпоинт не тормозит и не ломает инструменты, недоставленные батчи копятся в ~/.happ/mcp-trace/ и досылаются при следующем старте.

Приватность. Всё маскируется ещё на машине интегратора (src/telemetry/redact.ts): поля вроде password/token/apiKey/secret на любой глубине → отпечаток (длина + последние 4 символа), секреты по формату (JWT, happ_…, sk-…, Bearer, токены Telegram/Slack) вырезаются из любого текста, строки длиннее 1000 символов (промпты, тексты сообщений) заменяются на <text N chars sha256:…>. Ответы обрезаются до 4 КБ, аргументы до 8 КБ. Второй такой же проход делает сервер.

Отключить автоотправку: HAPP_MCP_TELEMETRY=off в env MCP-сервера. Журнал в памяти при этом остаётся — happ_store_logs продолжает работать.

Заголовки корреляции. Каждый запрос к API из инструмента несёт X-Happ-Mcp-Session / X-Happ-Mcp-Tool / X-Happ-Mcp-Seq и User-Agent: happ-mcp/<версия>; бэкенд кладёт их в audit_log.metadata. Запрос с личным токеном без этих заголовков в окне сессии админка показывает как «обход MCP» (агент достал токен и пошёл в API напрямую).

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

  • happ_store_logs(summary, category?, anchorTool?, lastCalls?) — по просьбе человека («сохрани/отправь логи») отправляет описание проблемы от агента плюс срез трассы: с первого вызова anchorTool (например happ_integration_sync) или последние N вызовов; без параметров — вся сессия. Возвращает id отчёта, который агент называет человеку.
  • happ_trace_recent() — компактный список вызовов сессии (номер, инструмент, статус, время) без payload'ов, чтобы выбрать якорь.

Что умеет MCP-сервер

116 инструментов happ_* поверх REST API платформы:

  • Авторизация — happ_login, happ_logout, happ_whoami.
  • Компании — CRUD, приглашение/удаление участников, отзыв приглашений, права пользователей (happ_permissions_*), персональные ключи доступа (happ_access_token*).
  • Ассистенты — CRUD, копирование, перенос между компаниями, папки, привязка интеграций; каталоги провайдеров, голосов и LLM-моделей (happ_voices_list, happ_llm_models_list).
  • Инструменты ассистента — CRUD (happ_tool_*).
  • База знаний — CRUD текстовых записей (happ_knowledge_*).
  • Телефония и номера — CRUD номеров, привязка/отвязка к ассистенту, подключение провайдеров телефонии (happ_telephony_connect).
  • Каналы — подключение виджета, Telegram-бота (по токену), WhatsApp; список/настройка/удаление интеграций компании.
  • Уведомления в Telegram — happ_telegram_push_*: код подключения, адресаты (личка и группы, куда добавлен бот) с раздельной маршрутизацией по видам событий, входящие ссылки. Ссылка — это URL, POST на который доставляет сообщение в выбранные чаты: её вставляют в HTTP-инструмент ассистента, чтобы он сам слал уведомление о заказе. url и token возвращаются один раз при создании и при ротации — платформа хранит только хэш.
  • Уведомления в Slack — happ_slack_push_*: ссылка авторизации, каналы, маршрутизация и входящие ссылки — всё как в Telegram, с одной разницей: канал выбирают внутри Slack во время авторизации, платформа получает готовый incoming-webhook и постить куда-то ещё физически не может. Поэтому «сменить канал» и «добавить второй» — это повторный проход по happ_slack_push_connect_url.
  • Чаты — список, сообщения, отправка от оператора, назначение менеджера/ассистента, вкл/выкл ИИ, сессии, плейграунд (happ_playground_*).
  • Звонки — список, детали, повторная транскрибация, правка транскрипта (редактирование/разбиение реплик, смена спикеров), назначение менеджера.
  • Текстовые рассылки — happ_text_campaign_*: массовая отправка первых Viber-сообщений через DirectHub-интеграцию ассистента. Создание с шаблоном текста ({{плейсхолдеры}} из variables получателя), загрузка получателей (до 10 000 за запрос, дубли отбрасываются), опциональное расписание (дата старта + дневные окна в таймзоне кампании), запуск/пауза/возобновление/отмена, прогресс и разбор сбоев (status=failed + lastError). Ответ клиента на рассылку подхватывает AI ассистента. Первое сообщение новому номеру платное по тарифу DirectHub — запуск только по явной просьбе человека.
  • Аналитика и мониторинг — сводная аналитика, мониторы (CRUD + разговоры), анализы (happ_analyses_list, happ_analysis_run), журнал действий (happ_activity_list).
  • Happ Functions — интеграционный код агента в закрытом рантайме Happ (happ_function_*, happ_functions_list): создание из кода и манифеста (хосты egress, секреты, доступ к API Happ), деплой версии на превью, тест превью/живой версии, выпуск, откат, вкл/выкл, привязка к ассистенту как вебхук-инструмент (в т.ч. несколько инструментов на подпутях одной функции), удаление. happ_functions_guide — контракт для агента, который пишет код (вход webhook_action / webhook_init / webhook_postcall, формат ответа, секреты-заглушки happ-secret://NAME, лимиты, пример Новой Почты). Манифест, расширяющий доступ, подтверждает только человек в кабинете: инструменты отдают approvalUrl и велят агенту остановиться, инструмента подтверждения нет. Значения секретов через модель не проходят — happ_function_secrets даёт только имена/статус и ссылку на страницу функции. Инструменты только в MCP, в копилоте их нет.
  • Тесты ассистента — тест-кейсы (CRUD + AI-генерация), прогоны с LLM-судьёй, оценка стоимости, советы по правке промпта (happ_test_*). Кейсы поддерживают фото от клиента: happ_test_media_upload грузит изображение с диска (filePath), из буфера обмена macOS (clipboard: true) или по ссылке (url); платформа распознаёт его VLM-ом, симулятор отправляет в нужный момент диалога, судья проверяет реакцию ассистента. Прогоны списывают LLM-баланс компании, tool-вызовы в тестах реальные. Кейс может нести переписку до теста (seedMessages): она пишется в чат перед диалогом с проставленной датой (daysAgo), и ассистент читает её как настоящую историю — так проверяется постоянный клиент, который пишет «на завтра 10 кг», а товар и адрес должны подтянуться из прошлых заказов. Промпт happ_fix_flow задаёт интеграторский флоу «жалоба → тест-кейс (красный) → правка → тест (зелёный) → отчёт».

Чего сервер не умеет: загрузка файлов и медиа в базу знаний и чаты (фото для тест-кейсов — умеет, см. выше), биллинг, интерактивные подключения через OAuth/QR (личный Telegram, Instagram, Messenger).

Разработка

pnpm install
pnpm dev        # запуск из исходников (tsx)
pnpm typecheck
pnpm build      # tsc → dist/

Публикация в npm — через GitHub Actions (release-workflow): пуш в main с новой версией в package.json собирает и публикует пакет.

版本与发布记录

@happ-ai/platform-mcp 共发布 91 个版本,首次发布于 2026/07/06;过去 12 个月发布了 91 个版本。

版本发布日期距今
0.46.1latest2026/11/17今天
0.46.02026/11/16今天
0.45.02026/11/115 天前
0.44.02026/11/115 天前
0.43.02026/11/106 天前
0.42.02026/11/0511 天前

关于 @happ-ai/platform-mcp 的常见问题

@happ-ai/platform-mcp 是什么?

MCP server exposing the Happ platform API as tools (login, companies, assistants, channels, phones)

如何安装 @happ-ai/platform-mcp?

在项目目录运行 npm install @happ-ai/platform-mcp,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 happ、happ-dev、happ-mcp,可以用 npx happ 直接运行。

@happ-ai/platform-mcp 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happ-ai/platform-mcp 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@happ-ai/platform-mcp 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=20。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@happ-ai/platform-mcp 可以商用吗?

@happ-ai/platform-mcp 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@happ-ai/platform-mcp 的下载量有多少?

根据 npm 官方下载统计,@happ-ai/platform-mcp 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,280 次,日均约 209 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happ-ai/platform-mcp 还在维护吗?

最新版本 0.46.1 发布于 2026/11/17(今天);至今共发布 91 个版本,其中过去 12 个月发布了 91 个;首次发布于 2026/07/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。