Bugoon
← Back to articles
チュートリアル

Scale Bugoon MCP Across Your Team: Standardize Bug Handling with .claude/commands

Scale Bugoon MCP Across Your Team: Standardize Bug Handling with .claude/commands

The Problem: Bug Triage That Lives in One Person's Head

You've set up the Bugoon MCP server, connected it to Claude Code, and started resolving bugs faster than ever. But then a new engineer joins your team — or you switch machines — and suddenly all that workflow knowledge evaporates. The commands you memorized, the order you run tools in, the way you update statuses after fixing a bug: none of it is written down anywhere.

That's the gap this article closes. We'll show you how to encode your Bugoon workflow into .claude/commands/ files that every teammate can run identically, how to document MCP tool usage in CLAUDE.md, and how to manage .mcp.json cleanly across multiple projects.

How .claude/commands/ Works with Bugoon MCP Tools

Claude Code supports project-level custom slash commands stored in .claude/commands/. Each .md file in that directory becomes a /command-name your whole team can invoke inside Claude Code sessions. The file contains a natural-language prompt — and that prompt can explicitly instruct Claude to call Bugoon MCP tools in a specific sequence.

The Bugoon MCP server exposes these primary tools:

  • list_bug_reports — fetch a filtered list of bug reports for a project
  • get_bug_report — retrieve full details for a single report by ID
  • get_screenshot — fetch the screenshot attached to a report
  • update_bug_report_status — change a report's status (open / in_progress / resolved)
  • get_project — retrieve project metadata

Two built-in MCP prompts are also available — fix_bug and triage_bug — which wrap common sequences into a single invocation. Your custom commands can call either the raw tools or these prompts, depending on how much control you need.

Before anything else, make sure your .mcp.json is present in the project root:

{
  "mcpServers": {
    "bugoon": {
      "command": "npx",
      "args": ["-y", "@rubyjobs-jp/bugoon-mcp-server"],
      "env": {
        "BUGOON_SECRET_KEY": "YOUR_SECRET_KEY",
        "BUGOON_API_URL": "https://bugoon.com"
      }
    }
  }
}

With that in place, every MCP tool listed above is available in your Claude Code session. Now let's build the commands.

Sample Command: /triage-today

Create the file .claude/commands/triage-today.md:

Fetch all open bug reports submitted today using the `list_bug_reports` MCP tool
(filter: status=open, created_today=true).

For each report returned:
1. Call `get_bug_report` to retrieve full details.
2. Call `get_screenshot` to inspect the visual evidence.
3. Assign a severity label: critical / high / medium / low.
4. Write one sentence explaining why you chose that severity.

Output a markdown table with columns: ID | Title | Severity | Reasoning.
Sort by severity descending (critical first).
Do not update any statuses — this is read-only triage.

Teammates run it with:

/triage-today

Claude fetches today's open reports, inspects each screenshot, and produces a prioritized triage table — all in one shot. Because the prompt explicitly says "do not update any statuses," there's no risk of accidentally closing a bug during the read pass. Keeping triage and resolution as separate commands reduces mistakes and makes the audit trail cleaner.

Sample Command: /fix-bug

Create the file .claude/commands/fix-bug.md:

Arguments: $ARGUMENTS (expected: a bug report ID, e.g. "42")

1. Call `get_bug_report` with the provided ID to load the full report,
   including reproduction steps, environment info, and annotation data.
2. Call `get_screenshot` to view the visual evidence attached to the report.
3. Locate the relevant source file(s) based on the URL and component info in the report.
4. Implement the minimal fix. Do not refactor unrelated code.
5. Run the project's test suite to confirm nothing is broken.
6. Call `update_bug_report_status` to set the status to "resolved".
7. Summarize what you changed and why in one short paragraph.

Usage:

/fix-bug 42

The $ARGUMENTS placeholder is replaced by whatever text follows the command name. Claude will load bug #42, read the screenshot, apply a targeted fix, run tests, mark the bug resolved, and write a summary — the full lifecycle in a single command. No copy-pasting IDs between tools, no forgetting to update the status afterward.

You can also wire this to the built-in fix_bug MCP prompt if you prefer to delegate the sequencing entirely to the server:

Use the `fix_bug` MCP prompt with bug_report_id=$ARGUMENTS.
After the prompt completes, confirm the status was updated to "resolved".

Both approaches work — the explicit version gives you more control over each step; the prompt version is more concise.

Documenting MCP Tool Usage in CLAUDE.md

Custom commands solve the "how do I run this?" problem. CLAUDE.md solves the "why do we do it this way?" problem. Add a dedicated section so every Claude Code session — and every teammate opening one — understands the team's conventions:

## Bugoon MCP Usage Guidelines

All bug management goes through the Bugoon MCP server configured in `.mcp.json`.
Never update bug statuses manually via the dashboard while a fix is in progress.

### Available Custom Commands
- `/triage-today` — read-only triage of today's open reports (severity table)
- `/fix-bug <id>` — full fix lifecycle: fetch → inspect → fix → test → resolve

### Tool Usage Rules
- Always call `get_screenshot` before diagnosing a bug. Visual context matters.
- Use `update_bug_report_status` only after tests pass, not before.
- Do not set status to "resolved" if tests fail — set it to "in_progress" instead.
- `list_bug_reports` supports filtering by status and date. Use filters; do not load all reports and filter client-side.

### Workflow
Triage first with `/triage-today`, then fix in priority order with `/fix-bug`.
One bug per commit. Commit message format: `fix(B-<id>): <short description>`.

When this is in CLAUDE.md, Claude Code reads it at session start. New teammates get the conventions automatically — they don't need to ask which tool to call first, or when it's safe to mark a bug resolved.

Managing .mcp.json Across Multiple Projects

If your team maintains more than one Bugoon project — say, a main SaaS product and a separate internal tool — each project has its own BUGOON_SECRET_KEY. Hardcoding the key directly in .mcp.json means either committing secrets to the repo or manually editing the file every time you switch projects. Neither is acceptable.

The cleaner pattern: reference an environment variable inside .mcp.json, and set that variable per-project using a tool like direnv.

In each project root, create a .envrc file (and add it to .gitignore):

# .envrc  (project A)
export BUGOON_SECRET_KEY=sk_live_projectA_xxxxx
# .envrc  (project B)
export BUGOON_SECRET_KEY=sk_live_projectB_yyyyy

Your shared .mcp.json — which can be committed — reads the variable at runtime:

{
  "mcpServers": {
    "bugoon": {
      "command": "npx",
      "args": ["-y", "@rubyjobs-jp/bugoon-mcp-server"],
      "env": {
        "BUGOON_SECRET_KEY": "${BUGOON_SECRET_KEY}",
        "BUGOON_API_URL": "https://bugoon.com"
      }
    }
  }
}

Run direnv allow once per project after creating .envrc. From that point on, opening a terminal in project A automatically exports the correct key, and Claude Code picks it up when starting the MCP server. Switching to project B is just a directory change — no manual edits, no risk of leaking the wrong key into the wrong repo.

If your team doesn't use direnv, a shell alias per project works equally well:

alias cdA='cd ~/projects/projectA && export BUGOON_SECRET_KEY=sk_live_projectA_xxxxx'
alias cdB='cd ~/projects/projectB && export BUGOON_SECRET_KEY=sk_live_projectB_yyyyy'

The key principle: .mcp.json is safe to commit as long as it contains only variable references, not actual secret values.

Wrapping Up the Series

Across this series we've covered the full arc of the Bugoon MCP integration:

  • Installing @rubyjobs-jp/bugoon-mcp-server and connecting it to Claude Code
  • Using individual MCP tools to fetch, inspect, and resolve bug reports
  • Building reusable .claude/commands/ that encode your team's workflow
  • Standardizing conventions in CLAUDE.md so every session starts from the same baseline
  • Managing secrets safely across multiple projects with environment variable substitution

The end result is a bug-handling pipeline that any engineer on your team can run consistently — whether they're on day one or year three. Bug reports come in through the Bugoon widget, surface in Claude Code via MCP, get fixed with a single command, and are marked resolved automatically. No dashboard-switching, no copy-pasting IDs, no forgotten status updates.

If you haven't set up Bugoon yet, it takes about five minutes: embed one script tag on your site, create a project, and your users can start filing visual bug reports immediately.

Try Bugoon for free

Streamline bug reporting for your team.

Bugoon is free to get started. Add one line of code to your site and transform how your team handles bugs.

Get Started
← Back to articlesBugoon Blog