GrowthBook

GrowthBook MCP Thin

Тонкий MCP-сервер для GrowthBook с четырьмя инструментами:

Инструмент	Назначение
growthbook_list_skills	Список точек входа верхнего уровня для навыков (имя + описание)
growthbook_read_skill	Возврат указанного навыка или квалифицированного дочернего рабочего процесса (feature-flags или feature-flags/references/flag-create)
growthbook_api_read	Аутентифицированный GET-прокси к API GrowthBook
growthbook_api_write	Аутентифицированный POST/PUT/PATCH/DELETE-прокси

Компетенции находятся в репозитории навыков и встраиваются во время сборки. Возможности разделены на инструменты чтения и записи API (без форматтеров для отдельных конечных точек), чтобы клиенты могли корректно обрабатывать readOnlyHint / destructiveHint.

Инструменты имеют префикс growthbook_, чтобы оставаться однозначными, когда у клиента загружено несколько MCP-серверов.

Установка / запуск

npm install
npm run build

Укажите вашему MCP-клиенту скомпилированную точку входа:

{
  "mcpServers": {
    "growthbook": {
      "command": "node",
      "args": ["/absolute/path/to/growthbook-mcp/server/index.js"],
      "env": {
        "GB_API_KEY": "your_api_key_or_pat",
        "GB_API_URL": "https://api.growthbook.io"
      }
    }
  }
}

Или запустите опубликованный пакет:

npx @growthbook/mcp

Переменные окружения

Переменная	Обязательная	По умолчанию	Назначение
GB_API_KEY	Да для stdio; необязательно для HTTP OAuth	—	API-ключ GrowthBook или персональный токен доступа
GB_API_URL	Нет	https://api.growthbook.io	Базовый URL API (self-hosted) и издатель OAuth AS по умолчанию
GB_MCP_TRANSPORT	Нет	stdio	stdio или http
GB_MCP_PORT	Нет	3333	Порт прослушивания HTTP (когда transport=http)
GB_MCP_HOST	Нет	127.0.0.1	Хост привязки HTTP
GB_MCP_URL	Да для HTTP	—	Публичный базовый URL MCP, встраиваемый в метаданные ресурса OAuth (сервер отказывается запускаться в HTTP-режиме без него)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	Нет	90000	Таймаут простоя keep-alive в HTTP-режиме. Должен превышать таймаут простоя любого балансировщика нагрузки перед сервером, иначе LB может повторно использовать соединение, которое сервер уже закрыл, и запрос завершится ошибкой 502
GB_OAUTH_ISSUER	Нет	GB_API_URL	URL издателя OAuth AS GrowthBook
GB_HTTP_HEADER_*	Нет	—	Дополнительные заголовки запросов (например, GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Нет	true	Установите в false / 0, чтобы отключить инструменты навыков

Режим HTTP + OAuth

OAUTH_AS_ENABLED=1  # on the GrowthBook API
GB_MCP_TRANSPORT=http GB_API_URL=http://localhost:3100 GB_MCP_PORT=3333 npm start

Клиенты подключаются к:

• http://127.0.0.1:3333/mcp — полный (навыки + чтение/запись API)
• http://127.0.0.1:3333/mcp/api — только возможности (growthbook_api_read + growthbook_api_write)

Неаутентифицированные запросы получают 401 с WWW-Authenticate, указывающим на /.well-known/oauth-protected-resource, который рекламирует сервер авторизации GrowthBook.

Перед обработкой MCP сервер проверяет REST GrowthBook (GET /api/v1/) с bearer-токеном. 401 от этой проверки (или позже от инструмента API) приводит к HTTP 401 с error="invalid_token", чтобы MCP-клиент мог обновить токен — вместо отображения "This API key has expired" как ошибки инструмента. 403 рассматривается как принятый bearer (отказ в разрешении ≠ недействительный токен), чтобы клиенты не попадали в цикл обновления.

Режим только возможностей

HTTP (рекомендуется для удаленного доступа): укажите клиенту /mcp/api вместо /mcp:

{
  "mcpServers": {
    "growthbook": {
      "url": "http://127.0.0.1:3333/mcp/api"
    }
  }
}

Путь	Инструменты
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (если не GB_SKILLS_ENABLED=false)
/mcp/api	только growthbook_api_read, growthbook_api_write

stdio / для всего процесса: установите переменные окружения, чтобы навыки никогда не регистрировались:

"env": {
  "GB_API_KEY": "...",
  "GB_SKILLS_ENABLED": "false"
}

Когда навыки отключены, регистрируются только инструменты чтения/записи API. growthbook_list_skills и growthbook_read_skill не предоставляются.

Как встраиваются навыки

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs копирует дерево навыков верхнего уровня из канонического репозитория навыков, сохраняя структуру:

skills/<skill>/SKILL.md                   → server/skills/<skill>/SKILL.md
skills/<skill>/references/<workflow>.md   → server/skills/<skill>/references/<workflow>.md

Разрешение пути источника:

1. Переменная окружения SKILLS_SRC (путь к корню репозитория навыков)
2. agent-skills.local.json — { "path": "../skills" }, относительно корня репозитория. В gitignore; скопируйте agent-skills.local.json.example
3. skills-src/ — то, что CI и Docker-сборка используют как поставщика

Неявного поиска соседних каталогов нет. ../skills разрешается в то, что находится по этому пути, что заставляет локальную сборку молча расходиться с коммитом, из которого собирает CI.

CI, облачные развертывания и релизы читают agent-skills.lock.json и проверяют именно этот коммит навыков. Чтобы опубликовать изменения навыков вышестоящего уровня, обновите коммит в файле блокировки. Локальная разработка может указывать на любой checkout с помощью agent-skills.local.json или SKILLS_SRC.

Репозиторий навыков остается источником истины — этот пакет не поддерживает форк содержимого навыков. Новые навыки проходят автоматически, кроме тех, что указаны в небольшом блок-листе в bundle-skills.mjs. В настоящее время заблокирован только gb-setup, потому что он настраивает адаптер оболочки gb-call, а не сам GrowthBook.

Каталоги scripts/ для отдельных навыков не копируются. Относительные ссылки `references/foo.md` переписываются в квалифицированные `feature-flags/references/foo` paths so growthbook_read_skill может их разрешать.

Использование навыков с инструментами API

Встроенные навыки по-прежнему показывают рабочие процессы как:

gb-call GET /api/v1/projects
gb-call POST /api/v2/features ./payload.json

Этот MCP-сервер не вызывает gb-call через оболочку. Сопоставьте GET → growthbook_api_read и POST/PUT/PATCH/DELETE → growthbook_api_write с тем же путем и необязательной строкой JSON-тела. Инструкции сервера и вывод growthbook_read_skill включают это примечание о мосте.

Детали инструментов

growthbook_api_read / growthbook_api_write

{ "path": "/api/v1/projects" }
{ "method": "POST", "path": "/api/v2/features", "body": "{\"id\":\"my-flag\",...}" }

• Чтение: только GET (readOnlyHint: true)
• Запись: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Возвращает необработанное тело ответа при 2xx
• При не-2xx возвращает действенную ошибку (isError: true), покрывающую сбои аутентификации, подсказки 404 для self-hosted и ограничения скорости
• Свободные пути нацелены на REST API GrowthBook

growthbook_list_skills / growthbook_read_skill

Регистрируются только когда GB_SKILLS_ENABLED не отключен.

• growthbook_list_skills возвращает точки входа навыков верхнего уровня. Запись может содержать полный рабочий процесс или вести к дочерним рабочим процессам.
• growthbook_read_skill принимает указанное имя верхнего уровня или квалифицированный дочерний путь, названный загруженным навыком (feature-flags/references/flag-create), и возвращает полный markdown (рабочий процесс + ограничения).

Разработка

git clone git@github.com:growthbook/skills.git ../skills
cp agent-skills.local.json.example agent-skills.local.json  # edit if not at ../skills

npm install
npm run build
npm start

Автономный HTTP-режим

По умолчанию сервер работает через stdio. Установите GB_MCP_TRANSPORT=http, чтобы запустить его как автономный HTTP-сервер, который предоставляет MCP на /mcp (навыки + инструменты API) и /mcp/api (только возможности), за поверхностью защищенного ресурса OAuth 2.0 (метаданные RFC 9728 + WWW-Authenticate RFC 6750).

• GB_MCP_URL (обязательно в HTTP-режиме) — публичный базовый URL сервера. Он встраивается в ресурс OAuth (аудиторию) и метаданные защищенного ресурса, поэтому никогда не выводится из заголовков запросов. Сервер отказывается запускаться без него.
• GB_MCP_PORT (по умолчанию 3333) и GB_MCP_HOST (по умолчанию 127.0.0.1).
• Входящие bearer-токены проверяются через запрос к REST API GrowthBook; отклоненный токен получает HTTP 401 + WWW-Authenticate, чтобы клиент мог обновить.

Запускайте его в доверенной сети или привязанным к loopback. Для мультитенантного или публичного развертывания разместите перед ним собственный шлюз/аутентификацию.

Релизы

Выпуск релиза — осознанное действие: увеличьте версию в package.json, затем отправьте соответствующий тег v*:

git tag v2.0.0
git push origin v2.0.0

Этот тегированный коммит (с навыками, зафиксированными на момент выпуска) публикует:

• @growthbook/mcp в npm — предрелизы (версии с -, например 2.0.0-beta.1) попадают под dist-tag beta; стабильные версии становятся latest
• мультиархитектурный (amd64 + arm64) образ в ghcr.io/growthbook/growthbook-mcp (:<version>, плюс :<major>, :<major>.<minor> и :latest для стабильных релизов)
• запись в реестре MCP
• релиз на GitHub

Установите релиз с помощью npx @growthbook/mcp@<version> или получите ghcr.io/growthbook/growthbook-mcp:<version>.