Getting Started

Usage

Learn how to use the Bugzilla MCP Server tools.

Overview

Once configured, the Bugzilla MCP Server provides several tools that your AI assistant can use to interact with Bugzilla. This guide provides comprehensive examples, response formats, and real-world usage patterns for each tool.

Available Tools

`bug_info` - Get Bug Information

Retrieves complete information about a bug by ID, including all metadata, status, assignee, and more.

Parameters:

id (int, required) - The Bugzilla bug ID

Example Usage:

Get information about bug #12345
What are the details of bug 12345?
Show me everything about bug #12345

Response Format: The tool returns a dictionary containing all bug information:

{
  "id": 12345,
  "summary": "Bug title/summary",
  "status": "NEW",
  "resolution": "",
  "product": "Firefox",
  "component": "Core",
  "version": "120",
  "platform": "All",
  "op_sys": "All",
  "priority": "P1",
  "severity": "S1",
  "assigned_to": "developer@example.com",
  "reporter": "user@example.com",
  "creation_time": "2024-01-15T10:30:00Z",
  "last_change_time": "2024-01-20T14:22:00Z",
  "cc": ["reviewer@example.com"],
  "keywords": ["crash", "regression"],
  "whiteboard": "[needs-review]",
  "flags": [...],
  // ... and many more fields
}

Common Use Cases:

Check bug status and resolution
Get assignee information
Review bug metadata and tags
Check creation and update timestamps
Verify product and component

`bug_comments` - Get Bug Comments

Retrieves comments for a specific bug. By default, only public comments are returned, but you can request private comments if you have the necessary permissions.

Parameters:

id (int, required) - The Bugzilla bug ID
include_private_comments (bool, optional) - Include private comments (default: false)

Example Usage:

Get comments for bug #12345
Show me all comments for bug 12345 including private ones
What have people said about bug #12345?

Response Format: Returns a list of comment objects:

[
  {
    "id": 1,
    "author": "developer@example.com",
    "text": "I've identified the issue in the code...",
    "time": "2024-01-15T10:35:00Z",
    "is_private": false,
    "count": 0
  },
  {
    "id": 2,
    "author": "reviewer@example.com",
    "text": "Internal note: needs security review",
    "time": "2024-01-16T09:20:00Z",
    "is_private": true,
    "count": 1
  }
]

Important Notes:

Private comments are only returned if include_private_comments=true and your API key has permission to view them
Comments are typically returned in chronological order
Each comment includes author, timestamp, and text content

`add_comment` - Add Comment to Bug

Adds a comment to a bug. Comments can be public (visible to all) or private (visible only to users with appropriate permissions).

Parameters:

bug_id (int, required) - The Bugzilla bug ID
comment (string, required) - The comment text to add
is_private (bool, optional) - Make the comment private (default: false)

Example Usage:

Add a comment to bug #12345: "This issue has been fixed in the latest release"
Add a private comment to bug #12345: "Internal note: needs review before release"
Post a comment: "Fixed in commit abc123def" to bug 12345

Response Format: Returns the ID of the created comment:

{
  "id": 42
}

Common Use Cases:

Update bug status with progress notes
Add technical details or findings
Post internal notes for team members
Document fixes or workarounds
Request additional information

Private comments require appropriate permissions. Ensure your API key has the necessary access rights.

`bugs_quicksearch` - Search Bugs

Searches for bugs using Bugzilla's powerful quicksearch syntax. Returns a list of bugs matching your criteria with essential fields.

Parameters:

query (string, required) - Quicksearch query string
limit (int, optional) - Maximum number of results (default: 50, max: typically 1000)
offset (int, optional) - Offset for pagination (default: 0)

Example Usage:

Search for bugs assigned to john@example.com
Find all open bugs in the Firefox product
Search for bugs with status NEW or ASSIGNED
Show me high priority bugs in the Core component

Response Format: Returns a list of bugs with essential fields:

[
  {
    "bug_id": 12345,
    "product": "Firefox",
    "component": "Core",
    "assigned_to": "developer@example.com",
    "status": "NEW",
    "resolution": "",
    "summary": "Bug title/summary",
    "last_updated": "2024-01-20T14:22:00Z"
  },
  {
    "bug_id": 12346,
    "product": "Firefox",
    "component": "DOM",
    "assigned_to": "another@example.com",
    "status": "ASSIGNED",
    "resolution": "",
    "summary": "Another bug",
    "last_updated": "2024-01-19T09:15:00Z"
  }
]

Quicksearch Syntax Examples:

Basic Searches:

assignedto:john@example.com - Bugs assigned to a specific user
reporter:user@example.com - Bugs reported by a user
product:Firefox - Bugs in a specific product
component:Core - Bugs in a specific component
status:NEW - Bugs with a specific status
priority:P1 - Bugs with a specific priority
severity:S1 - Bugs with a specific severity

Combined Searches:

product:Firefox status:NEW - New bugs in Firefox
assignedto:john@example.com status:ASSIGNED - Assigned bugs for a user
component:Core priority:P1,P2 - High priority Core bugs
status:NEW,ASSIGNED product:Firefox - Open Firefox bugs

Advanced Searches:

keywords:crash - Bugs with specific keywords
whiteboard:[needs-review] - Bugs with whiteboard tags
cc:reviewer@example.com - Bugs CC'd to a user
resolution:FIXED - Fixed bugs
resolution:--- - Unresolved bugs

Pagination:

# First page (default)
bugs_quicksearch(query="product:Firefox", limit=50, offset=0)

# Second page
bugs_quicksearch(query="product:Firefox", limit=50, offset=50)

# Third page
bugs_quicksearch(query="product:Firefox", limit=50, offset=100)

Use the learn_quicksearch_syntax tool to get the complete documentation for your Bugzilla instance's quicksearch syntax.

`learn_quicksearch_syntax` - Get Quicksearch Documentation

Retrieves Bugzilla's quicksearch syntax documentation directly from your Bugzilla instance. This helps AI assistants learn the available search options.

Parameters: None

Example Usage:

Show me the quicksearch syntax documentation
How do I search for bugs?
What search options are available?

Response Format: Returns HTML documentation from your Bugzilla instance containing:

Available search fields
Syntax examples
Field combinations
Special operators

When to Use:

Learning available search fields
Understanding complex search syntax
Discovering advanced search capabilities
Getting instance-specific documentation

`server_url` - Get Server URL

Returns the base URL of your configured Bugzilla instance.

Parameters: None

Example Usage:

What's the Bugzilla server URL?
Get the server URL

Response Format: Returns a string with the base URL:

"https://bugzilla.example.com"

Use Cases:

Verify configuration
Generate links to Bugzilla
Check which instance you're connected to

`bug_url` - Get Bug URL

Generates a direct link to view a specific bug in your Bugzilla instance.

Parameters:

bug_id (int, required) - The Bugzilla bug ID

Example Usage:

Get the URL for bug #12345
Give me a link to bug 12345
What's the web URL for bug #12345?

Response Format: Returns a complete URL string:

"https://bugzilla.example.com/show_bug.cgi?id=12345"

Use Cases:

Share bug links with team members
Open bugs in a web browser
Create references in documentation
Generate clickable links in responses

Common Workflows

Workflow 1: Investigating a Bug Report

Scenario: A user reports a bug and you need to investigate it.

1. Get bug information: "Get details about bug #12345"
2. Read comments: "Show me all comments for bug #12345"
3. Check related bugs: "Search for bugs in the same component as bug #12345"
4. Add investigation note: "Add comment to bug #12345: 'Investigating the root cause...'"

Workflow 2: Managing Your Bug Queue

Scenario: Review and manage bugs assigned to you.

1. Find your bugs: "Search for bugs assigned to me with status NEW or ASSIGNED"
2. Review each bug: "Get information about bug #12345"
3. Check comments: "Get comments for bug #12345"
4. Update status: "Add comment to bug #12345: 'Working on this, ETA: tomorrow'"

Workflow 3: Bug Triage

Scenario: Triage new bugs in a product.

1. Find new bugs: "Search for bugs in product Firefox with status NEW"
2. Review each bug: Get bug information for each result
3. Check duplicates: "Search for bugs with similar summary"
4. Assign or update: "Add comment to bug #12345: 'Triaged: assigned to team X'"

Workflow 4: Release Preparation

Scenario: Find and verify bugs fixed in a release.

1. Find fixed bugs: "Search for bugs with resolution FIXED in product Firefox"
2. Verify fixes: "Get information about bug #12345"
3. Check comments: "Get comments for bug #12345 to see fix details"
4. Generate report: Use bug URLs to create a release notes document

Advanced Usage Patterns

Combining Multiple Tools

Example: Get comprehensive bug information

1. Search: "Find bugs assigned to me"
2. For each result:
   - Get full details: bug_info(id)
   - Get comments: bug_comments(id)
   - Get URL: bug_url(id)

Efficient Searching

Best Practices:

Start with broad searches, then narrow down
Use specific fields to reduce result sets
Combine multiple criteria for precise results
Use pagination for large result sets

Example:

# Too broad (may return too many results)
"Search for all bugs"

# Better (more specific)
"Search for bugs in product Firefox with status NEW"

# Best (very specific)
"Search for bugs in product Firefox, component Core, status NEW, priority P1"

Error Handling

The tools provide clear error messages:

Invalid bug ID: "Failed to fetch bug info\nReason: Bug not found"
Permission denied: "Failed to fetch bug comments\nReason: Access denied"
Invalid search: "Search failed with status code 400"

Tips for Best Results

Be Specific: Use specific criteria when searching to get relevant results
Use Quicksearch Effectively: Learn the quicksearch syntax for powerful searches
Check Permissions: Ensure your API key has permissions for the operations you need
Private Comments: Remember that private comments require appropriate permissions
Pagination: Use offset and limit for large result sets
Combine Tools: Use multiple tools together for comprehensive information
Verify Before Acting: Get bug information before adding comments
Use URLs: Generate bug URLs for easy sharing and reference