Skip to content
Back to search

bugzilla-mcp

Dual-mode MCP Server (Core 2026-07-28 + MCP Apps + MCP Events) for self-hosted Bugzilla 5.0/5.2+

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hhubb22--bugzilla-mcp/badge.svg)](/listings/hhubb22--bugzilla-mcp)

HTML

<a href="/listings/hhubb22--bugzilla-mcp"><img src="/api/listings/hhubb22--bugzilla-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

bun install
bun run build:ui

Add to your MCP client configuration (Antigravity, Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "bugzilla": {
      "command": "bun",
      "args": ["run", "/ABS/PATH/TO/bugzilla-mcp/packages/server/src/cli.ts", "--transport=stdio"],
      "env": {
        "BUGZILLA_BASE_URL": "https://bugzilla.example.internal",
        "BUGZILLA_API_KEY": "<your-bugzilla-api-key>",
        "BUGZILLA_DB_PATH": "/ABS/PATH/TO/bugzilla-mcp.sqlite"
      }
    }
  }
}

> **Stock Bugzilla 5.0 / 5.2 note**: Stock Bugzilla 5.0/5.2 without a reverse-proxy header rewrite or 5.3+ patch ignores `X-BUGZILLA-API-KEY`. Set `BUGZILLA_ALLOW_QUERY_FALLBACK=true` **only** if your Apache/Nginx access logs strip query strings (`%U` instead of `%r`). See [docs/security-and-operations.md](docs/security-and-operations.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 96 lines
  1. # `bugzilla-mcp`
  2. Production-hardened, dual-mode (**Cloud Autonomous Agent** + **Local IDE / Antigravity**) **Model Context Protocol (MCP) Server** for self-hosted **Bugzilla 5.0 / 5.2+**, built with TypeScript, **Bun**, and **VoidZero (`vite-plus`)**.
  3. ## Protocol & Spec Alignment
  4. - **MCP Core `2026-07-28`** (+ `2025-11-25` Dual-Era session compatibility with tenant-bound sessions)
  5. - **MCP Apps (`SEP-1865`)** single-file React workbench (`ui://bugzilla/triage-app.html`) & inline dossier card (`ui://bugzilla/dossier-card.html`)
  6. - **MCP Events (`SEP-3415` + ChatGPT Events dialect adapter)** with lag-windowed cursors & SSRF-hardened DNS-pinned Standard Webhooks
  7. ## Architecture Overview
  8. ```mermaid
  9. flowchart LR
  10. Host["MCP Host / IDE / Cloud Agent"] -->|"stdio or Streamable HTTP (/mcp)"| Server["@bugzilla-mcp/server\nDual-Era Auth · /bind · /approve"]
  11. Host -.->|"MCP App iframe (SEP-1865)"| AppUI["@bugzilla-mcp/app-ui\nSingle-File React Workbench"]
  12. Server --> Core["@bugzilla-mcp/core\nTiered Write Guard · Synthetic Events"]
  13. Core --> Storage["@bugzilla-mcp/storage\nSQLite WAL (issuer, principalId, instanceUrl)"]
  14. Core --> Client["@bugzilla-mcp/bugzilla-client\nHeader Auth · Per-Key Queue"]
  15. Client -->|"HTTPS REST"| BZ["Self-Hosted Bugzilla 5.0 / 5.2+"]
  16. ```
  17. ## Key Safety Properties
  18. - **Zero API Key in LLM Context**: Bugzilla API keys are collected via out-of-band `/bind` HTTPS forms (cloud) or environment variables (local), stored with AES-256-GCM AAD bound to `(issuer, principalId, instanceUrl)`, and never emitted into prompts, logs, or URLs by default.
  19. - **Tiered Write Guard**:
  20. - **Safe-Auto (`bugzilla_post_analysis`)**: Strictly `isPrivate: true`; fails closed to a server-local internal note (`SavedAsInternalNote`) when the user is not an insider or upstream rejects private comments—never degrades to a public comment.
  21. - **Guarded-Write (`bugzilla_propose_update` / `app_resolve_proposal`)**: Optimistic `last_change_time` freshness verification (`StaleBugConflict` requires a new immutable revision), single-use issuer-bound cloud `/approve` tokens, and immutable write audits.
  22. - **Multi-Issuer Tenant Isolation (`[R-970164]`)**: Every tenant-scoped SQLite table, event cursor, approval token, legacy HTTP session, and MCP App draft cache is partitioned by `(issuer, principalId, instanceUrl)`.
  23. ## 5-Minute Quick Start (Local IDE `stdio`)
  24. ```bash
  25. bun install
  26. bun run build:ui
  27. ```
  28. Add to your MCP client configuration (Antigravity, Claude Desktop, Cursor, etc.):
  29. ```json
  30. {
  31. "mcpServers": {
  32. "bugzilla": {
  33. "command": "bun",
  34. "args": ["run", "/ABS/PATH/TO/bugzilla-mcp/packages/server/src/cli.ts", "--transport=stdio"],
  35. "env": {
  36. "BUGZILLA_BASE_URL": "https://bugzilla.example.internal",
  37. "BUGZILLA_API_KEY": "<your-bugzilla-api-key>",
  38. "BUGZILLA_DB_PATH": "/ABS/PATH/TO/bugzilla-mcp.sqlite"
  39. }
  40. }
  41. }
  42. }
  43. ```
  44. > **Stock Bugzilla 5.0 / 5.2 note**: Stock Bugzilla 5.0/5.2 without a reverse-proxy header rewrite or 5.3+ patch ignores `X-BUGZILLA-API-KEY`. Set `BUGZILLA_ALLOW_QUERY_FALLBACK=true` **only** if your Apache/Nginx access logs strip query strings (`%U` instead of `%r`). See [docs/security-and-operations.md](docs/security-and-operations.md).
  45. ## Documentation Map
  46. | Guide | Purpose |
  47. | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ |
  48. | [docs/quickstart-and-clients.md](docs/quickstart-and-clients.md) | Local `stdio`, Loopback HTTP, and programmatic Cloud Multi-User embedding (`startMcpHttpServer`) |
  49. | [docs/reference.md](docs/reference.md) | Environment variables, CLI flags, all 11 MCP tools, resources, events, webhooks, and HTTP routes |
  50. | [docs/security-and-operations.md](docs/security-and-operations.md) | Threat model, Bugzilla 5.0/5.2 quirks & proxy checklist, SQLite pre-v3 migration runbook, and troubleshooting |
  51. | [specs/](specs/) | Frozen contract-driven specifications (`25` stamped `[R-xxxxxx]` EARS clauses) & Quint formal models |
  52. ## Workspace Packages
  53. | Package | Responsibility |
  54. | :----------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  55. | [`packages/contracts`](packages/contracts) | Strict Zod schemas, `RESERVED_LEGACY_ISSUER`, and TypeScript contracts (`C0 v3`) |
  56. | [`packages/storage`](packages/storage) | `StoragePorts` + SQLite (`node:sqlite` WAL) with `(issuer, principalId, instanceUrl)` partitioning & atomic pre-v3 migration |
  57. | [`packages/bugzilla-client`](packages/bugzilla-client) | Self-hosted Bugzilla REST client (header auth default, explicit `allowQueryFallback`, per-key serial queue avoiding MariaDB `user_api_keys.last_used` deadlocks, error classification) |
  58. | [`packages/core`](packages/core) | Tiered Write Guard, issuer-bound single-use cloud approval tokens, SSRF-hardened DNS-pinned Standard Webhooks, and Synthetic Events engine |
  59. | [`packages/app-ui`](packages/app-ui) | Sanitization & host controller + single-file React/Vite+ MCP App UI (`tenantKey` isolation, `<= 4` unified concurrency gate, native `<dialog>` confirmations) |
  60. | [`packages/server`](packages/server) | Dual-Era Streamable HTTP handler, `/bind` & `/approve` pages, AES-256-GCM credential vault, loopback-guarded HTTP runtime, and `stdio` transport |
  61. ## Verification & Quality Gates
  62. ```bash
  63. bun run build:ui # Build single-file MCP App HTML (packages/app-ui/dist-web/triage-app.html)
  64. bun run check # Format + Oxlint (vite-plus)
  65. bun run typecheck # Type-check all 6 packages + React web bundle
  66. bun run typecheck:tests # Type-check test suite
  67. bun run test # Contract & multi-issuer isolation suite (82 tests, 25/25 clauses)
  68. bun run verify:quint # Quint formal safety invariants (write_guard + events_ingestion)
  69. ```
  70. ### Live Bugzilla 5.2 Zero-Mock E2E (Docker / OrbStack)
  71. ```bash
  72. cd docker/bugzilla && docker compose up -d --build --wait
  73. cd ../.. && bun run test:e2e
  74. # Tear down temporary Bugzilla when done:
  75. cd docker/bugzilla && docker compose down -v
  76. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.