bugzilla-mcp

Bugzilla 티켓과 프로젝트를 관리하기 위한 MCP(Model Context Protocol) 서버로, Express 위에서 제공되며 예약된 시간에 Bugzilla를 핑(ping)하는 내장 cron 작업이 포함되어 있습니다.

Bugzilla 5.2 REST API를 대상으로 합니다.

기능

• Streamable HTTP 기반 MCP — POST /mcp에서 제공 (무상태(stateless)이며 모든 MCP 클라이언트와 호환)

• 버그, 댓글, 첨부 파일, 제품, 구성 요소, 필드 메타데이터를 다루는 15가지 도구

• 미리 구성된 시간에 Bugzilla를 핑하고 새 버그와 변경된 버그를 폴링하는 cron 작업

• 아웃고잉 웹훅 — cron 작업이 서명된 bug.created / bug.changed 이벤트를 구성 가능한 URL로 POST합니다.

• 브라우저에서 cron 일정과 웹훅을 구성할 수 있는 GET /settings의 설정 페이지

• 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 클라이언트는 Authorization: Bearer <MCP_AUTH_TOKEN> 헤더와 함께 http://<host>:3000/mcp에 연결합니다.

• 설정 페이지는 http://<host>:3000/settings에 있습니다 (동일한 토큰을 입력하세요).

• cron/웹훅 설정은 앱 옆의 .bugzilla-mcp-state.json에 저장됩니다 (STATE_FILE로 경로를 재정의할 수 있습니다).

프로덕션 환경에서는 API 키에 전용 최소 권한 Bugzilla 서비스 계정을 사용하고, 항상 MCP_AUTH_TOKEN을 설정하며(이 토큰이 없으면 설정 쓰기가 거부됨), 서버가 localhost 밖에서 접근 가능하다면 서버 앞단에서 TLS를 종료하세요.

MCP 도구

search_bugs, create_bug, update_bug는 Bugzilla 사용자 정의 필드를 위한 선택적 custom_fields 객체를 받습니다. 예를 들어 필터링하거나 필수 필드를 설정할 때 custom_fields: {"cf_severity_class": "Sev1-Critical"}처럼 사용합니다. Bugzilla REST 계약에 따라 다중 선택 사용자 정의 필드의 배열 값은 해당 필드의 전체 값을 대체합니다. keywords 및 cc와 달리 사용자 정의 필드에는 {add, remove} 형태의 증분 업데이트가 없습니다.

참고: Bugzilla에는 버그 삭제 API가 없습니다. 종료/해결은 update_bug를 통해 수행합니다 (예: status=RESOLVED, resolution=FIXED).

HTTP 엔드포인트

MCP_AUTH_TOKEN이 설정된 경우 /mcp, /cron/*, /settings JSON API는 Authorization: Bearer <MCP_AUTH_TOKEN>을 요구합니다. 설정 페이지 자체는 정적 HTML이며, 토큰을 입력받아 모든 API 호출에서 Bearer 헤더로 전송합니다.

구성

.env.example을 .env로 복사하고 다음을 입력하세요:

설정 페이지에서 변경한 값은 STATE_FILE에 저장되며, 재시작 시 해당 환경 변수를 재정의합니다.

API 키는 모든 Bugzilla 요청에서 X-BUGZILLA-API-KEY 헤더로 전송되며, BUGZILLA_AUTH_STYLE=query인 경우 api_key 쿼리 매개변수로 전송됩니다.

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 이미지에서 사용). 로컬 .env 파일을 로드하려면 start:local 또는 dev를 사용하세요.

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 페이로드를 POST합니다:

{
  "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도 동일한 형태를 사용합니다. 실패한 전달은 지수 백오프(1초/5초/25초)로 3회 재시도되며, 마지막 전달 상태는 GET /cron/status와 설정 페이지에서 확인할 수 있습니다.

WEBHOOK_SECRET이 설정된 경우 각 요청에는 X-Webhook-Signature: sha256=<원본 본문의 16진수 HMAC-SHA256>이 포함됩니다. 수신 측에서 검증하세요. 예를 들어 Node에서는 다음과 같습니다:

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

웹훅은 구성된 BUGZILLA_API_KEY ID에 보이는 버그만 볼 수 있습니다. 계정이 읽을 수 없는 그룹 제한 버그는 절대 전달되지 않습니다.

설정 페이지

GET /settings는 다음을 위한 순수 HTML 페이지(빌드 단계 없음, 프레임워크 없음)를 제공합니다:

• 폴링 간격을 분 단위로 확인하고 편집 (cron 표현식으로 변환되어 즉시 적용),

• 웹훅 URL, 시크릿(쓰기 전용 — 다시 표시되지 않음), 활성화 플래그 설정,

• 지금 실행 및 테스트 이벤트 보내기 트리거,

• 마지막 실행 및 마지막 웹훅 전달 상태 확인.

페이지 상단에 MCP_AUTH_TOKEN을 입력하세요. 이 토큰이 없으면 JSON API가 모든 호출을 거부합니다. 변경 사항은 STATE_FILE에 저장됩니다(모드 0600으로 기록).

MCP 클라이언트 연결

Streamable HTTP를 지원하는 모든 MCP 클라이언트를 http://<host>:3000/mcp로 연결하세요. 구성된 경우 Authorization: Bearer <MCP_AUTH_TOKEN> 헤더를 포함하세요.

Devin으로 설정

Devin이 이 서버를 MCP 통합으로 사용하도록 하려면:

1. Devin이 접근할 수 있는 곳에 서버를 배포하세요. Devin은 클라우드에서 실행되므로 노트북의 localhost로는 작동하지 않습니다. 공개(또는 VPN/허용 목록) HTTPS URL이 있는 서버에 호스팅하세요. 위의 Docker 설정이나 TLS를 종료하는 리버스 프록시 뒤에서 npm run start:local을 사용하세요.

2. 서버를 Bugzilla 자격 증명으로 구성하세요:

   • BUGZILLA_BASE_URL — Bugzilla 인스턴스 URL.

   • BUGZILLA_API_KEY — 전용 최소 권한 서비스 계정의 API 키 (Bugzilla → 환경 설정 → API 키). Devin은 모든 읽기/쓰기에서 이 계정으로 동작하며, 버그 기록에는 이 계정으로 변경 사항이 기록됩니다.

   • 인스턴스가 Bugzilla 5.0.x인 경우 BUGZILLA_AUTH_STYLE=query.

   • MCP_AUTH_TOKEN — 무작위 시크릿 (예: openssl rand -hex 32). Devin만 서버에 접근할 수 있도록 필수입니다.

3. Devin에 MCP 서버를 추가하세요. 조직 관리자는 설정 → MCP Marketplace → 사용자 지정 MCP 추가를 통해 추가할 수 있습니다 (Devin MCP 문서 참조). 엔터프라이즈 관리자는 대신 설정 → 엔터프라이즈 → 연결 → 서버 카탈로그를 통해 여러 조직에 대해 한 번에 구성할 수 있습니다(아래 참조). 어느 쪽이든 다음을 입력하세요:

   • 전송: HTTP (Streamable HTTP; 이 서버는 stdio를 지원하지 않음)

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

   • 인증 / 사용자 지정 헤더: Authorization: Bearer <MCP_AUTH_TOKEN> (값은 쓰기 전용 — 변경 시 모든 헤더를 다시 입력해야 함)

   • 세션에서 사용을 켜두고, (엔터프라이즈 카탈로그 전용) 타기팅에서 서버를 받을 조직을 선택하세요.

   

4. 확인. Devin에게 Bugzilla 도구를 나열하거나 간단한 search_bugs 호출을 실행하도록 요청하세요. 15개 도구 모두(버그 검색/생성/업데이트, 댓글, 첨부 파일, 기록, 사용자 정의 필드) 사용할 수 있어야 합니다.

5. 선택 사항 — 웹훅. https://<your-host>/settings를 열고 동일한 MCP_AUTH_TOKEN을 입력한 다음, 폴링 간격과 웹훅 URL을 설정하여 서버가 bug.created / bug.changed 이벤트를 푸시하도록 하세요 (예: 새 버그마다 Devin 세션을 트리거하는 엔드포인트).

참고:

• 서버 인스턴스 하나 = Bugzilla ID 하나. 호출자마다 다른 권한이 필요하면 API 키별로 인스턴스를 하나씩 실행하세요.

• .env를 커밋하지 마세요. API 키와 토큰은 시크릿으로 저장하세요.