BugmoleDocs bugmole.com →

Bugmole MCP

To use Bugmole from ChatGPT, claude.ai or Claude Desktop without running anything yourself, connect the hosted server instead. See Use Bugmole from your AI assistant. This page covers the local server that runs next to your project.

Bugmole exposes repository exploration, planning, execution, diff proposal, review, and reporting through MCP tools. The MCP server is intended for an agent that needs an explicit QA workflow rather than a generic one-step login or test command.

Start the server

The default local endpoint is 127.0.0.1:3187:

bugmole --mcp

Or run the project worker, which keeps the MCP service available while it executes dashboard-created runs:

bugmole serve

Workflow

The recommended sequence is:

  1. bugmole_explore — inspect project structure, specifications, entrypoints, and available journeys. Follow up with bugmole_record_discovery and bugmole_journey_next until the journey is fully explored.
  2. bugmole_plan — produce a concrete plan with an actor, preconditions, actions, assertions, and evidence. The actor must be a confirmed role.
  3. bugmole_run — execute the approved plan in the configured environment.
  4. bugmole_report — summarize outcomes and evidence.

The server's bugmole://guidance/agent-testing resource describes each step in detail. The Bugmole skill teaches Claude this workflow.

Roles

Plans and test case sets are written for confirmed roles only. bugmole_roles_list returns the confirmed roles and the ones still waiting for a person. bugmole_role_propose suggests a role with the evidence that points at it (sign_in_wall, role_gated_route, role_gated_menu, spec, persona or agent), or, with fromEvidence: true, every role the journey graph, blockers and roles.yaml imply. bugmole_explore suggests roles by itself when it finds a sign-in wall or a role-gated route.

A suggestion waits on the dashboard's Roles page for a person to confirm, rename or reject it; an agent can't confirm one. Writing roles.yaml with bugmole_write_spec marks any role the agent adds as status: suggested. bugmole_plan and bugmole_write_test_cases refuse a suggested or rejected role and list the confirmed ones. See Roles.

Agent tasks and review

bugmole_task_next claims the next task and bugmole_task_update reports on it. When you report completed, the project's approval mode may hold the task for a person: Manual reviews every task, Auto reviews code and UI tasks, Extreme none. The response then has inReview: true and the task's status is in_review; don't treat the work as accepted. A person accepts it or sends it back. A task sent back comes through bugmole_task_next again with the reviewer's note in reviewNote and in the response's message. See Reviewing finished tasks.

Changing test cases

Write a new case set with bugmole_write_test_cases. To change one that exists, propose it with bugmole_propose_test_case: add, change or retire a case, with a summary saying why. The tool reads which revision you're changing from the project's storage and checks the case against the journey.

An accepted proposal never edits a case in place. It becomes the next revision, the one it replaces is marked obsolete, and past results stay with the revision they judged. The project's approval mode decides whether a manager must accept it (Manual, Auto) or it's accepted on arrival (Extreme). Results written with bugmole_write_test_case_results record which revision they judged.

Test case results and history

Each call to bugmole_write_test_case_results, and each run that judges a case set, replaces the case set's latest results and also keeps a copy of its own. The tool returns both keys:

Both live in the project's storage, on your machine or in Bugmole storage. The dashboard reads the last ten history files per case set to show each case's recent results.

Safety and evidence

Plans must preserve explicit proof requirements and should include negative or blocked cases where the business rules require them. Destructive operations remain project-scoped and subject to environment and watermark gates. If verification is blocked, the report should say why and identify the missing evidence.