ghl-context-mcp

Сознательно маленький MCP-сервер GoHighLevel. Шесть инструментов, ограниченных одной задачей: понимать, с кем вы собираетесь говорить.

Зачем он нужен

Типичный сценарий отказа, когда агента ставят поверх CRM, — это широкая обобщённая инструментальная поверхность, которая сбрасывает сырой JSON из API: модель выбирает не тот инструмент, сжигает своё окно контекста на полях, которые никто никогда не произнесёт вслух, и иногда выдумывает или перезаписывает запись. Этот сервер делает противоположную ставку. Он поставляет шесть инструментов, каждый из которых привязан к моменту, когда агент собирается поговорить с контактом. Каждое возвращаемое поле — это то, что человек мог бы сказать, или то, что агент передаёт дальше при следующем вызове. Сервер сам занимается вычислением дат и не выполняет записи, пока вы их не включите. Утверждение, что узкая поверхность лучше широкой, измеримо, и сопутствующий бенчмарк (mcp-tool-surface-bench) создаётся для того, чтобы это измерить.

Related MCP server: GHL MCP Server

Инструменты

Потолки — это бюджеты токенов на ответ, контролируемые тестом, который валит сборку, когда ответ вырастает за их пределы. См. DESIGN.md о том, что здесь означает «токен».

Использование

Это MCP-сервер, и его целевой пользователь — агент ИИ, а не человек за терминалом. Вы подключаете сервер к своему агенту (Claude Code, Claude Desktop или любой среде, поддерживающей MCP), а затем общаетесь с агентом на обычном языке. Именно агент решает найти контакт и подтянуть его контекст.

Быстрый старт для команды с Claude Code

1. Склонируйте репозиторий, затем установите и соберите:

   npm install && npm run build

2. Добавьте свои учётные данные:

   cp .env.example .env
   # then edit .env and fill in GHL_PIT and GHL_LOCATION_ID

3. Откройте папку в Claude Code. Он прочитает закоммиченный .mcp.json, предложит сервер ghl-context, и вы одобрите его один раз. Сервер загружает .env при запуске, поэтому токен никогда не лежит в конфигурационном файле.

4. Общайтесь со своим агентом так, как представитель начал бы свой день:

   Сегодня я звоню Маркусу Харлоуэю и Прие Найр. Дай мне краткую справку перед каждым звонком.

   Агент находит каждый контакт, подтягивает таймлайн, положение в воронке и предстоящие встречи и возвращает справку.

Другие MCP-клиенты

Направьте любой MCP-клиент на сервер через stdio. Опубликованный пакет не требует ни клонирования, ни сборки. Для Claude Desktop добавьте это в claude_desktop_config.json:

{
  "mcpServers": {
    "ghl-context": {
      "command": "npx",
      "args": ["-y", "ghl-context-mcp"],
      "env": {
        "GHL_PIT": "pit-...",
        "GHL_LOCATION_ID": "your-sub-account-id"
      }
    }
  }
}

Чтобы запустить локальную копию кода вместо опубликованного пакета, установите command в node, а args — в ваш собранный dist/index.js.

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

Создайте токен в разделе Settings, Integrations, Private Integrations с областями contacts.readonly, contacts.write, opportunities.readonly, opportunities.write и calendars.readonly.

Посмотреть без клиента

Если у вас нет под рукой MCP-клиента, в репозитории есть терминальная демонстрация, которая выполняет ту же последовательность, что и агент, и печатает справку:

npm run brief -- "Marcus Halloway"

Это демонстрация ценности, а не продукт. Продукт — это подключение агента, описанное выше.

Из исходников

npm install
npm run build
npm test

npm test проходит успешно без учётных данных. Живые проверки, npm run live-check и npm run live-write-check, требуют настоящего .env.

Формы ответов

Найденный контакт:

{
  "resolution": "exact",
  "contact": {
    "contact_id": "NnAyKFnTSAVKg1amAArO",
    "name": "Marcus Halloway",
    "primary_phone": "+15551230010",
    "primary_email": "marcus.halloway@example.com",
    "tags": ["synthetic-seed"],
    "owner": null,
    "last_activity_at": null,
    "last_activity_summary": null
  }
}

Неоднозначное совпадение возвращает кандидатов, а не угадывание:

{
  "resolution": "ambiguous",
  "candidates": [
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230012",
      "primary_email": "jordan.wells@example.com",
      "last_activity_at": null
    },
    {
      "contact_id": "...",
      "name": "Jordan Wells",
      "primary_phone": "+15551230013",
      "primary_email": "jordan.wells.cpa@example.com",
      "last_activity_at": null
    }
  ],
  "disambiguate_by": ["email", "primary_phone"],
  "instruction": "Ask the user which one, or call again with the exact email or phone."
}

Неоднозначность считается успехом. Агент, получивший ошибку, останавливается, а тот, кому вручили список кандидатов, продолжает работать и спрашивает пользователя, какой контакт он имел в виду.

Ошибки

Все ошибки имеют одну форму. Никакой сырой HTTP-статус не достигает модели.

Дизайн-заметки

Восемь правил, на которых построен сервер, по одной строке. Полная версия с обоснованием, которое спросил бы интервьюер, — в DESIGN.md.

1. Одна задача на инструмент. Если в описании появляется «и», это два инструмента.

2. Описания написаны для модели: когда использовать, когда не стоит и с каким смежным инструментом его пугают.

3. Никакие сырые API-формы не пересекают границу — за этим следит тест.

4. Ошибки — это инструкции в повелительном наклонении с перечислением допустимых вариантов.

5. Каждый ответ имеет потолок токенов, который контролирует тест, валящий сборку.

6. Сервер выполнит математику: сроки, длительности, относительное время, количество.

7. Записи утверждают состояние, от которого зависят, и громко падают при несоответствии.

8. Записи выключены, если не задано GHL_ALLOW_WRITES=true.

Чего этот сервер не делает

Каждое ограничение — намеренное.

Ограничения

Только один субъект, только авторизация по Private Integration Token, без OAuth. Пагинация ограничена максимумами по каждому инструменту. Обнаружение зависаний требует объёма данных, чтобы быть значимым, и сейчас использует фиксированную замену, потому что GoHighLevel не раскрывает историю этапов. Соотнесение телефонных номеров заточено под США. Потолки токенов — это прокси-токены, а не точные токены Claude. Чтения GoHighLevel отстают от записей примерно на секунду. Протестировано только на одной форме аккаунта.

Лицензия

MIT