kompa-mcp-server

MCP (Model Context Protocol) сервер, который предоставляет данные социального прослушивания Kompa — buzz-записи, разбивку по тональности, трендовую линию, горячие темы, уникальных авторов — в виде инструментов, которые может вызывать любой MCP-клиент. Создан, чтобы вы могли общаться с данными Kompa прямо внутри Claude (Desktop или Code) вместо отдельного чат-интерфейса.

Этот пакет не зависит от Next.js-приложения kompa-chat — он лишь использует тот же Kompa GraphQL API и тот же процесс входа, перенесённые в обычный MCP-сервер. Он предоставляет две точки входа:

• build/index.js — stdio-транспорт для локальных MCP-клиентов, которые запускают дочерний процесс (Claude Desktop/Code через локальную конфигурацию).

• build/http.js — потоковый HTTP-транспорт, мультитенантный: один размещённый URL коннектора может обслуживать множество клиентов. Полное руководство по развёртыванию на VPS см. в DEPLOY.md (systemd + Caddy + подключение клиента).

Конфигурация аккаунта и тем

Отдельной системы API-ключей нет. У каждого клиента уже есть имя пользователя и пароль Kompa — они используются и здесь, через вызов инструмента:

configure_account({ username, password, topicIds: ["topic-id-1", ...] })

Вызовите его один раз в начале разговора (Claude сделает это автоматически, как только вы упомянете свои учётные данные/темы, или вы можете попросить его явно). После этого все остальные инструменты используют этот аккаунт и topic_ids, пока вы снова не вызовете configure_account — не нужно повторять их при каждом вызове, хотя вы по-прежнему можете передать topicIds в конкретном вызове, чтобы переопределить.

Такой подход используется вместо аутентификации через заголовки, потому что поддержка пользовательских заголовков запросов Claude для коннекторов сейчас находится в ограниченном бета-доступе — см. примечание «Auth model» в DEPLOY.md.

Для stdio-точки входа можно вообще пропустить вызов инструмента, задав переменные окружения KOMPA_USERNAME/KOMPA_PASSWORD/KOMPA_DEFAULT_INDEXES — в этом случае аккаунт будет предварительно настроен при запуске.

Инструменты

Все инструменты работы с данными принимают fromDate/toDate ("YYYY-MM-DD HH:mm:ss"), необязательные types, query, sentiments и необязательный topicIds (если он не задан, используется topicIds, установленный через configure_account).

Установка

npm install
npm run build

Скопируйте .env.example для справки (это актуально только для stdio-точки входа — см. выше).

Использование в автономном режиме (до публикации)

Направьте любой MCP-клиент непосредственно на собранный входной файл:

{
  "mcpServers": {
    "kompa": {
      "command": "node",
      "args": ["/absolute/path/to/kompa-mcp-server/build/index.js"]
    }
  }
}

• Claude Desktop: поместите этот блок в claude_desktop_config.json (Settings → Developer → Edit Config).

• Claude Code: поместите тот же блок mcpServers в .mcp.json в корне проекта или выполните:

  claude mcp add kompa -- node /absolute/path/to/kompa-mcp-server/build/index.js

После изменения конфигурации перезапустите клиент, а затем в чате напишите, например: "Мой аккаунт Kompa — X/Y, ID темы Z — какова разбивка по тональности для запроса 'foo' с 2026-08-01 по 2026-08-21?" — Claude вызовет configure_account, а затем инструмент работы с данными.

Публикация в npm

Чтобы пользователи могли устанавливать пакет через npx kompa-mcp-server вместо локального пути:

npm login
npm publish --access public

Тогда конфигурация MCP становится такой:

{
  "mcpServers": {
    "kompa": {
      "command": "npx",
      "args": ["-y", "kompa-mcp-server"]
    }
  }
}

Публикация в маркетплейсе плагинов Claude Code

И Claude Code, и — для организаций Team/Enterprise — сам claude.ai могут добавлять маркетплейс плагинов прямо из git-репозитория — публикация в npm здесь не нужна, поскольку marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json указывает на ваш размещённый HTTP-коннектор (см. DEPLOY.md), а не на локальный пакет. Структура:

marketplace-example/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── kompa-mcp/
        └── .claude-plugin/
            └── plugin.json      # edit the connector URL in here first

Для сопровождающего (мейнтейнера):

1. Измените url в marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json на ваш реальный развёрнутый домен (https://mcp.yourdomain.com/mcp).

2. Запушьте в GitHub репозиторий, содержащий структуру marketplace-example/ (переименуйте папку в то, чем должен быть корень репозитория) — публичный или приватный, если он нужен только вашей организации (для приватного требуется, чтобы у всех устанавливающих был доступ к репозиторию через их GitHub/git учётные данные).

3. Поделитесь URL репозитория.

Для пользователя Claude Code, который устанавливает плагин:

/plugin marketplace add https://github.com/<you>/<marketplace-repo>
/plugin install kompa-mcp-plugin@<marketplace-name>

Для организации claude.ai Team/Enterprise (без CLI, только графический интерфейс):

1. Владелец организации: Organization settings → Connectors/Plugins → Add plugin marketplace → "Add from a repository" → вставьте тот же URL GitHub.

2. Участники: Customize → Plugins, найдите kompa-mcp-plugin из вашего маркетплейса, нажмите install/connect.

Для отдельных аккаунтов Free/Pro/Max без организации этот способ через репозиторий недоступен — вместо него используйте процедуру загрузки zip-архива из PLUGIN.md.

Примечания и ограничения

• Вход использует тот же процесс с именем пользователя и паролем, что и auth.ts из kompa-chat — ни OAuth, ни автоматизации браузера.

• Токен доступа кэшируется в рамках процесса для каждого имени пользователя и обновляется за 5 минут до истечения срока действия.

• topicIds должны быть допустимыми ID индексов проектов Kompa, к которым у аккаунта есть доступ — этот сервер не обнаруживает и не перечисляет их за вас.

• В HTTP-режиме конфигурация аккаунта/тем хранится только в памяти этой MCP-сессии — при закрытии разговора/сессии она теряется, и следующая сессия должна снова вызвать configure_account.