observer-launch-mcp

Задавайте Клоду вопросы о ваших данных Observe — недавние ошибки, частые сбои, объем логов по подам — не написав OPAL вручную. Это MCP-сервер, который дает Клоду прямой живой доступ к вашему тенанту Observe.

Настройка (2 шага)

1. Запустите мастер настройки. Он запрашивает ваши учетные данные Observe и алиасы наборов данных, затем автоматически регистрирует себя в Claude Code:

npx @aryanbansal-launch/observer-launch-mcp init

Вас попросят указать:

• Observe customer ID — число, находится в вашем URL Observe.

• Observe API key — создайте его в Manage account → My API tokens. (Не токен ingest/datastream — они выглядят похоже, но здесь не работают.)

• Cluster — например, eu-1. Оставьте пустым, если вы на стандартном US-тенанте.

• Алиасы наборов данных (необязательно) — удобные имена для наборов данных, о которых вы часто спрашиваете, например, launch-management → 41249178. Найдите ID в интерфейсе Observe: откройте набор данных, он в URL. Можно пропустить это и использовать сырые ID наборов данных, или добавить алиасы позже.

2. Перезапустите Claude Code (или начните новую сессию), чтобы он подхватил новый сервер. Подтвердите, что всё работает:

Is the Observe connection working?

Вот и всё — остальные инструменты ниже теперь доступны в чате.

claude mcp add observe -s user \
  -e OBSERVE_CUSTOMER_ID=<your id> \
  -e OBSERVE_API_KEY=<your token> \
  -e OBSERVE_CLUSTER=eu-1 \
  -e OBSERVE_DATASETS='{"launch-management":"41249178"}' \
  -- node <path to installed server.js>

Сначала запустите npx @aryanbansal-launch/observer-launch-mcp init, если вам нужен абсолютный путь — он выводит точную команду, которую выполнит, прямо перед её запуском. Используйте прямую команду node <path>, а не npx <package> в качестве финальной записи — Claude Code запускает зарегистрированные серверы с пустым окружением (без PATH), и собственный shebang npx требует PATH для поиска node, поэтому npx-как-команда молча показывает "Failed to connect." Мастер уже избегает этого за вас.

Related MCP server: Fathom AI MCP Server

Что можно спросить

После настройки просто общайтесь с Клодом естественно:

• «Работает ли соединение с Observe?»

• «Какие алиасы сервисов/наборов данных у меня настроены?»

• «Покажи недавние ошибки из launch-management за последний час»

• «Какая у нас самая частая ошибка в launch-nginx на этой неделе?»

• «Какие поды сейчас больше всего логируют в launch-management-bg?»

• «Сколько вывода stderr генерирует launch-nginx за последние 6 часов?»

• «Подсчитай строки логов на под в launch-telemetry за последний час»

• «Получи последние 20 сырых строк логов из launch-logs-bg-exporter»

Для всего, что не покрыто конкретной формой вопроса, просто опишите, что вам нужно — Клод напишет OPAL-конвейер с помощью общего инструмента запросов.

Справочник инструментов

get_error_summary и get_log_stats агрегируют на стороне сервера, поэтому они остаются быстрыми независимо от временного окна. get_service_errors и run_opal_query добавят предупреждение, если вы запрашиваете окно 6 часов и более без агрегации, поскольку сырые выгрузки строк за широкое окно рискуют упереться в лимит Observe в 100k строк.

Форматы логов

Наборы данных в одном тенанте редко имеют общую схему логов, поэтому get_service_errors и get_error_summary определяют формат для каждого набора данных (один раз на процесс) и строят соответствующий запрос:

Каждый результат сообщает, какой формат был определен. Чтобы пропустить проверку, укажите его в конфигурации набора данных:

{ "launch-nginx": { "id": "41250854", "shape": "http" } }

Простые записи "alias": "id" по-прежнему работают и определяются автоматически.

Покрытие сообщается, а не скрывается. В наборах данных level некоторые строки не имеют разбираемого поля level (стек-трейс, голая строка, не-JSON вывод), и фильтр по серьезности не может их увидеть. Когда эта доля превышает 1%, инструменты сообщают об этом:

Note: 529 of 2136 rows (24.8%) have no parseable "level" field and were not
scanned. Pass includeUnparsed=true to keyword-match those too.

includeUnparsed=true выполняет поиск по ключевым словам в этих строках. Это опционально, потому что сопоставление по ключевым словам также помечает строки info, которые просто содержат слово "error".

Справочник конфигурации

ID наборов данных специфичны для тенанта и намеренно не включены в этот пакет. Если ничего не настроено, поиск по алиасам не сработает, и вы можете передавать сырые числовые ID наборов данных напрямую любому инструменту.

Устранение неполадок

• Проверка работоспособности не проходит → вероятно, ваш API-ключ — это токен ingest/datastream, а не из Manage account → My API tokens. Перегенерируйте его.

• claude mcp list показывает "Failed to connect" для вручную зарегистрированной записи → проверьте, что команда — node <path>, а не npx <package> (см. примечание выше).

• Инструмент возвращает "Unknown service/dataset" → запустите list_known_services, чтобы увидеть, что настроено, или передайте сырой числовой ID набора данных.

• get_service_errors/get_error_summary не возвращают ничего полезного → проверьте примечание "Detected log format" в результате. Если формат определен неверно, укажите его явно с помощью {"alias": {"id": "...", "shape": "http"}} (см. Форматы логов). Если указано text, в ваших логах нет поля серьезности, и сопоставление основано на ключевых словах.

• Ошибки, которые вы видите в интерфейсе Observe, отсутствуют в результатах → обратите внимание на примечание о покрытии. Строки без разбираемого level по умолчанию пропускаются; передайте includeUnparsed=true.

Вклад в проект

npm install
npm run build   # tsc, then chmod +x on the bin entry
npm publish      # only if you intend to ship a new version

Скопируйте шаблон get_error_summary/get_log_stats в src/run-server.ts для других повторяющихся OPAL-запросов (например, стоимость по сервисам, процентили задержки) — дайте инструменту описательное имя/описание, чтобы Клод выбирал его вместо run_opal_query, когда это уместно.