MCP-сервер Telebugs

MCP-сервер (Model Context Protocol), позволяющий ИИ-агентам извлекать отчеты об ошибках из Telebugs, self-hosted альтернативы Sentry.

Архитектура

┌─────────────────┐                           ┌─────────────────────────────────────┐
│  Local Machine  │                           │              Remote VPS             │
│                 │         HTTPS             │                                     │
│  Claude Desktop │ ◄───────────────────────► │  Bun MCP Server   ───►  Telebugs    │
│                 │      (SSE transport)      │     :3100              SQLite DB    │
└─────────────────┘                           └─────────────────────────────────────┘

Related MCP server: otel-mcp

Возможности

• Прямой доступ к базе данных — чтение и запись в базу данных SQLite Telebugs

• Аутентификация MCP OAuth — OAuth-поток через браузер, поддерживаемый пользователями Telebugs

• Аутентификация по API-ключу — по-прежнему принимает существующие API-ключи пользователей Telebugs в качестве токенов носителя (bearer tokens)

• Контроль доступа — пользователи видят только те проекты, в которых они состоят

• Транспорт SSE — позволяет удаленные подключения через Claude Desktop

• Эффективность токенов — компактный JSON, по умолчанию отображаются только открытые ошибки

• Одиночный бинарный файл — кросс-компиляция для Linux, отсутствие зависимостей среды выполнения

Доступные инструменты

list_error_groups

Возвращает total_count для пагинации.

list_reports

Возвращает total_count для пагинации.

search_errors

resolve_error_group / unresolve_error_group / unmute_error_group

Эти инструменты требуют только group_id (number).

mute_error_group

add_note

delete_note

create_project (только для администратора)

update_project (только для администратора)

delete_project / regenerate_project_token (только для администратора)

Эти инструменты требуют только project_id (number).

add_project_member / remove_project_member (только для администратора)

get_project_token / list_project_members

Эти инструменты требуют только project_id (number).

list_platforms

Параметры отсутствуют. Возвращает все доступные названия платформ.

Установка

cd telebugs-mcp
bun install

Сборка

# Build for current platform
bun run build

# Build for Linux (for VPS deployment)
bun run build:linux

Конфигурация

Локальный запуск

TELEBUGS_DB_PATH=/path/to/telebugs/storage/db/development.sqlite3 bun run dev

Развертывание

Одиночный бинарный файл

# Copy to server
scp telebugs-mcp-linux root@your-server:~/telebugs-mcp-linux

# On server
chmod +x ~/telebugs-mcp-linux
./telebugs-mcp-linux

Служба systemd

Скопируйте telebugs-mcp.service в /etc/systemd/system/:

cp telebugs-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable telebugs-mcp
systemctl start telebugs-mcp

Проверьте статус:

systemctl status telebugs-mcp

Обратный прокси-сервер Nginx (опционально)

location /mcp {
    proxy_pass http://127.0.0.1:3100;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # SSE support
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
}

Конфигурация Claude Desktop

Для MCP-клиентов с поддержкой OAuth настройте только URL сервера. Клиент обнаружит метаданные OAuth, откроет страницу входа в браузере и повторит попытку с выданным токеном носителя:

{
  "mcpServers": {
    "telebugs": {
      "url": "https://your-server/mcp"
    }
  }
}

Когда MCP-сервер работает за обратным прокси-сервером, установите MCP_BASE_URL на публичный HTTPS-источник:

MCP_BASE_URL=https://your-server bun run start

Страница входа OAuth отображается с помощью React с CSS, сгенерированным Tailwind через плагин Bun. Она соответствует странице входа Telebugs, показывает запрашивающего клиента и источник перенаправления, а также требует явного подтверждения перед выдачей кода авторизации. Она принимает ваш email/пароль от Telebugs, проверяя их по тому же bcrypt users.password_digest, который использует Telebugs. Она также может принимать ссылку для входа в Telebugs из /session/transfers/..., когда задан TELEBUGS_SECRET_KEY_BASE, чтобы MCP-сервер мог получить ключ верификатора active_record/signed_id от Rails и проверить полезную нагрузку подписанного ID.

Если Telebugs настроен с использованием RAILS_MASTER_KEY вместо SECRET_KEY_BASE, прочитайте значение из приложения Telebugs с помощью bin/rails runner 'puts Rails.application.secret_key_base' и передайте его этому серверу как TELEBUGS_SECRET_KEY_BASE.

Для клиентов, которые еще не поддерживают MCP OAuth, статический токен носителя по-прежнему работает. Добавьте его в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "telebugs": {
      "url": "http://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer your_telebugs_api_key"
      }
    }
  }
}

Получение вашего API-ключа

1. Войдите в свой экземпляр Telebugs

2. Перейдите в Пользователь → Настройки аккаунта → Безопасность

3. Скопируйте свой API-ключ

Безопасность

• Операции только для администраторов принудительно ограничены для управления проектами (создание, обновление, удаление, пересоздание токена, членство)

• Операции записи ограничены изменением статуса ошибок, заметками и управлением проектами

• Все мутации ограничены членством пользователя в проектах

• API-ключи проверяются только по активным пользователям

• Токены доступа OAuth являются кратковременными и хранятся в памяти MCP-сервера

• Все запросы фильтруются по членству пользователя в проектах

• Параметризованные запросы (защита от SQL-инъекций)

Проверка работоспособности

curl http://localhost:3100/health
# {"status":"ok"}

Лицензия

MIT