bugzilla-mcp

MCP-сервер (Model Context Protocol) для управления тикетами и проектами Bugzilla, работающий поверх Express со встроенной cron-задачей, которая периодически обращается к Bugzilla по расписанию.

Ориентирован на Bugzilla 5.2 REST API.

Возможности

• MCP через Streamable HTTP на POST /mcp (без состояния; работает с любым MCP-клиентом)

• 15 инструментов для работы с багами, комментариями, вложениями, продуктами, компонентами и метаданными полей

• Cron-задача, которая обращается к Bugzilla в заданное время и опрашивает новые и изменённые баги

• Исходящий вебхук — cron-задача отправляет POST-запросы с подписанными событиями bug.created / bug.changed на настраиваемый URL

• Страница настроек по адресу GET /settings для настройки расписания cron и вебхука из браузера

• Поддержка Docker (многоступенчатая сборка, непривилегированный пользователь, docker-compose)

Related MCP server: kanban-mcp

Быстрый старт

Требуются Node.js 20+ и сетевой доступ к вашему экземпляру Bugzilla.

git clone https://github.com/COG-GTM/bugzilla-mcp
cd bugzilla-mcp
npm install
npm run build
cp .env.example .env

Отредактируйте .env:

BUGZILLA_BASE_URL=https://your-bugzilla.example.com/
BUGZILLA_API_KEY=<key from Bugzilla Preferences -> API Keys>
# Only for Bugzilla 5.0.x, which ignores the auth header (default: header):
BUGZILLA_AUTH_STYLE=query
# Any random string of your choosing, e.g. `openssl rand -hex 32`:
MCP_AUTH_TOKEN=<random token>

Затем запустите:

npm run start:local

• MCP-клиенты подключаются к http://<host>:3000/mcp с заголовком Authorization: Bearer <MCP_AUTH_TOKEN>.

• Страница настроек доступна по адресу http://<host>:3000/settings (введите тот же токен).

• Настройки cron/вебхука сохраняются в файле .bugzilla-mcp-state.json рядом с приложением (путь можно переопределить через STATE_FILE).

Для продакшена: используйте выделенную сервисную учётную запись Bugzilla с минимальными правами для API-ключа, всегда задавайте MCP_AUTH_TOKEN (без него запись настроек запрещена) и завершайте TLS перед сервером, если он доступен за пределами localhost.

MCP-инструменты

search_bugs, create_bug и update_bug принимают необязательный объект custom_fields для пользовательских полей Bugzilla, например custom_fields: {"cf_severity_class": "Sev1-Critical"} при фильтрации или установке обязательного поля. Согласно контракту REST Bugzilla, значение массива для поля с множественным выбором заменяет всё значение поля — в отличие от keywords и cc, у пользовательских полей нет инкрементальной формы {add, remove}.

Примечание: у Bugzilla нет API для удаления багов; закрытие/резолюция выполняется через update_bug (например, status=RESOLVED, resolution=FIXED).

HTTP-эндпоинты

/mcp, /cron/* и JSON API /settings требуют заголовок Authorization: Bearer <MCP_AUTH_TOKEN>, если задан MCP_AUTH_TOKEN. Сама страница настроек — статический HTML; она запрашивает токен и отправляет его как Bearer-заголовок при каждом вызове API.

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

Скопируйте .env.example в .env и заполните:

Значения, изменённые через страницу настроек, сохраняются в STATE_FILE и переопределяют соответствующие переменные окружения после перезапуска.

API-ключ отправляется в каждом запросе к Bugzilla в заголовке X-BUGZILLA-API-KEY или как query-параметр api_key, если задано BUGZILLA_AUTH_STYLE=query.

BUGZILLA_AUTH_STYLE=query помещает ключ в URL запроса, где его могут зафиксировать промежуточные прокси и журналы доступа. Bugzilla 5.0.x игнорирует заголовок и не принимает других способов аутентификации, поэтому используйте query только для таких экземпляров, с выделенной сервисной учётной записью с минимальными правами и периодической ротацией ключа.

Запуск

Docker (рекомендуется)

cp .env.example .env   # then edit
docker compose up --build

Локально

npm install
npm run build
npm run start:local   # loads .env via node --env-file; or: npm run dev

npm start читает конфигурацию только из окружения процесса (используется в Docker-образе); используйте start:local или dev, чтобы загрузить локальный файл .env.

Cron-задача

При каждом запланированном срабатывании задача:

1. Вызывает GET /rest/version как проверку работоспособности.

2. Опрашивает GET /rest/bug?last_change_time=<lastRun> для багов, изменённых с прошлого запуска (при первом запуске пропускается, так как нет базовой отметки), и разделяет их на новые баги (creation_time ≥ время последнего запуска) и изменённые баги.

3. Доставляет события вебхука (см. ниже), если настроен URL вебхука.

4. Логирует результаты и сохраняет последний результат в памяти; он доступен по адресу GET /cron/status.

Отметка последнего запуска сохраняется в STATE_FILE, поэтому после перезапуска не пропускаются баги, созданные, пока сервер был недоступен. Отметка продвигается только после успешной доставки вебхука (или если вебхук не настроен), поэтому неудачные доставки повторяются при следующем запуске (семантика at-least-once — получатели должны дедуплицировать по id бага).

Вебхук

Когда задан WEBHOOK_URL (или он настроен через страницу настроек), каждый запуск cron отправляет одну пакетную JSON-полезную нагрузку на каждый тип события:

{
  "event": "bug.created",
  "instance": "https://bugzilla.example.com",
  "firedAt": "2026-01-01T09:00:00.000Z",
  "bugs": [
    { "id": 17, "summary": "...", "status": "CONFIRMED",
      "creation_time": "...", "last_change_time": "..." }
  ]
}

bug.changed использует ту же структуру. Неудачные доставки повторяются 3 раза с экспоненциальной задержкой (1с/5с/25с); статус последней доставки виден на GET /cron/status и на странице настроек.

Если задан WEBHOOK_SECRET, каждый запрос содержит заголовок X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>. Проверяйте его на стороне получателя, например в Node:

const expected = "sha256=" +
  crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));

Вебхук видит только те баги, которые доступны учётной записи с настроенным BUGZILLA_API_KEY — баги, ограниченные группами и недоступные для чтения этой учётной записи, никогда не доставляются.

Страница настроек

GET /settings отдаёт страницу на простом HTML (без шага сборки и без фреймворков), которая позволяет:

• просматривать и изменять интервал опроса в минутах (преобразуется в cron-выражение и применяется на лету),

• задавать URL вебхука, секрет (только для записи — повторно не отображается) и флаг включения,

• запускать Run now и Send test event,

• просматривать статус последнего запуска и последней доставки вебхука.

Введите MCP_AUTH_TOKEN в верхней части страницы; без него JSON API отклоняет все вызовы. Изменения сохраняются в STATE_FILE (файл записывается с правами 0600).

Подключение MCP-клиента

Направьте любой MCP-клиент, поддерживающий Streamable HTTP, на http://<host>:3000/mcp, передав заголовок Authorization: Bearer <MCP_AUTH_TOKEN>, если он настроен.

Настройка с Devin

Чтобы Devin мог использовать этот сервер как MCP-интеграцию:

1. Разверните сервер там, где Devin сможет до него добраться. Devin работает в облаке, поэтому localhost на вашем ноутбуке не подойдёт — разместите его на сервере с публичным (или доступным через VPN/по белому списку) HTTPS URL. Используйте Docker-настройку выше или npm run start:local за TLS-терминирующим обратным прокси.

2. Настройте сервер, указав учётные данные Bugzilla:

   • BUGZILLA_BASE_URL — URL вашего экземпляра Bugzilla.

   • BUGZILLA_API_KEY — API-ключ для выделенной сервисной учётной записи с минимальными правами (Bugzilla → Preferences → API Keys). Devin будет действовать от имени этой учётной записи при каждом чтении и записи, а история багов будет относить изменения к ней.

   • BUGZILLA_AUTH_STYLE=query, если экземпляр работает на Bugzilla 5.0.x.

   • MCP_AUTH_TOKEN — случайный секрет (например, openssl rand -hex 32); обязателен, чтобы до сервера мог добраться только Devin.

3. Добавьте MCP-сервер в Devin. Администраторы организаций могут добавить его через Settings → MCP Marketplace → Add a custom MCP (см. документацию Devin MCP); администраторы enterprise могут вместо этого настроить его один раз для нескольких организаций через Settings → Enterprise → Connections → Server catalog, как показано ниже. В любом случае укажите:

   • Transport: HTTP (Streamable HTTP; этот сервер не поддерживает stdio)

   • URL: https://<your-host>/mcp

   • Authentication / custom headers: Authorization: Bearer <MCP_AUTH_TOKEN> (значения только для записи — при изменении вводите каждый заголовок заново)

   • Оставьте Enable in sessions включённым и (только для enterprise-каталога) выберите, какие организации получат сервер, в разделе Targeting.

   

4. Проверьте. Попросите Devin перечислить инструменты Bugzilla или выполнить быстрый вызов search_bugs. Все 15 инструментов (поиск/создание/обновление багов, комментарии, вложения, история, пользовательские поля) должны быть доступны.

5. Опционально — вебхуки. Откройте https://<your-host>/settings, введите тот же MCP_AUTH_TOKEN, задайте интервал опроса и URL вебхука, чтобы сервер отправлял события bug.created / bug.changed (например, на эндпоинт, который запускает сессию Devin для каждого нового бага).

Примечания:

• Один экземпляр сервера = одна учётная запись Bugzilla. Если разным вызывающим сторонам нужны разные права, запускайте по одному экземпляру на каждый API-ключ.

• Никогда не коммитьте .env; храните API-ключ и токен как секреты.