BugTracker MCP server

@orbit360.lk/bugtracker-mcp

Gives an AI coding agent direct access to captured bug reports and to your local server logs — without your application exposing anything.

This runs on your own machine. It is not deployed, not imported by the application under test, and not reachable from the network.

Chrome extension ──push──▶ bridge (127.0.0.1) ──▶ local store
                                                     │
your app's log files ────────read───────────────────▶│
                                                     ▼
                                          MCP ◀── Antigravity / Claude Code / Copilot / Cursor

Why this instead of an endpoint in your app

The alternative is a route in your application that returns exceptions over HTTP. That works, but it means shipping code, a token, and a CORS allowlist into a project you may not want to touch.

This server reads storage/logs/laravel.log — or any log you point it at — straight off the disk. No route, no token in your app, no CORS, nothing to review, nothing to accidentally leave enabled in production.

Install

Nothing to install. Your MCP client runs it on demand:

npx -y @orbit360.lk/bugtracker-mcp

Check it resolves:

npx -y @orbit360.lk/bugtracker-mcp --help

PowerShell: quote the package name — a bare leading @ is the splatting operator and PowerShell refuses to parse the line.

npx -y "@orbit360.lk/bugtracker-mcp" --help

Requires Node 20 or newer.

Use this when you want to modify the server, or when the machine cannot reach the npm registry.

cd mcp-server
npm install
npm run build

Your agent then runs node /absolute/path/to/mcp-server/dist/index.js.

Configure

Everything comes from the environment. Nothing is hardcoded, so the same binary serves whichever project you are working on.

| Variable | Required | Purpose | |---|---|---| | BUGTRACKER_BRIDGE_TOKEN | yes | Shared secret. Generate it in the extension under Integration → Local agent bridge. | | BUGTRACKER_LOG_PATHS | for find_logs | Comma-separated files or directories the agent may read. An allowlist — nothing outside it is searchable. | | BUGTRACKER_BRIDGE_PORT | no | Loopback port. Default 4319. | | BUGTRACKER_DATA_DIR | no | Where mirrored records are kept. Default ~/.bugtracker. |

The server refuses to start without a token rather than opening an unauthenticated port.

| Flag | | |---|---| | --help, -h | Usage and every environment variable. | | --version, -v | Print the version. |

Register it with your agent

The extension generates these blocks with your token and paths already filled in — Integration → Local agent bridge → step 4. Copy from there rather than editing by hand.

Google Antigravity IDE — .gemini/mcp_config.json in your project root, or ~/.gemini/config/mcp_config.json globally:

{
  "mcpServers": {
    "bugtracker": {
      "command": "npx",
      "args": ["-y", "@orbit360.lk/bugtracker-mcp"],
      "env": {
        "BUGTRACKER_BRIDGE_TOKEN": "paste-the-token-here",
        "BUGTRACKER_BRIDGE_PORT": "4319",
        "BUGTRACKER_LOG_PATHS": "/path/to/your-app/storage/logs"
      }
    }
  }
}

In Antigravity IDE, connected tools are listed in the chat panel under Additional Options (…) > MCP Servers.

Claude Code — .mcp.json in your project, or ~/.claude.json:

{
  "mcpServers": {
    "bugtracker": {
      "command": "npx",
      "args": ["-y", "@orbit360.lk/bugtracker-mcp"],
      "env": {
        "BUGTRACKER_BRIDGE_TOKEN": "paste-the-token-here",
        "BUGTRACKER_BRIDGE_PORT": "4319",
        "BUGTRACKER_LOG_PATHS": "/path/to/your-app/storage/logs"
      }
    }
  }
}

VS Code / Copilot — the same block in .vscode/mcp.json under servers.

Cursor — the same block in ~/.cursor/mcp.json.

Then in the extension: Integration → Local agent bridge, enable it, paste the same token, and press Test connection.

Tools

| Tool | What it does | |---|---| | list_projects | Applications with captures, their record counts and modules. Start here. | | list_bugs | Records, newest first. Filter by project, module, status, type or free text. | | get_bug | The full AI-ready report for one record. | | get_evidence | Raw diagnostics — console, exceptions, every network request with bodies. | | get_module_backlog | Every open item in a module, ordered by priority, in one document. | | find_logs | Searches your local logs for a literal string. | | find_logs_for_bug | Takes a record id, pulls the correlation ids the browser saw, searches the logs for each. | | mark_fixed | Queues a status change the extension applies on its next sync. |

find_logs_for_bug is the one that replaces the backend endpoint: it goes from a browser symptom to the server stack trace in a single call.

Try it

List the open bugs in the Orders module, then find the server logs for the highest-priority one and tell me the root cause.

What gets mirrored

Record metadata, the rendered Markdown report, and the raw diagnostics.

Screenshots are not pushed — they stay in the browser. Records are mirrored on save, edit and delete; use Push all records in the extension to backfill after enabling the bridge.

Security

• The bridge binds 127.0.0.1 explicitly. It is not reachable from your network.
• Every endpoint except /health requires the bearer token, compared in constant time.
• find_logs is confined to BUGTRACKER_LOG_PATHS. A path outside it is rejected, including via .. — the check resolves before comparing.
• Files over 256 MB are skipped so a rotated log cannot hang the agent.
• The token lives in your agent's config and the extension's settings. Treat that config file the way you would an .env.

Your captured records include URLs, request and response bodies, and console output from the applications you test. Redaction runs in the extension before anything is stored, but review Settings → Redaction before pointing an agent at production captures.

Verify the install

node scripts/smoke.mjs

Starts the server on a scratch port, pushes a record through the bridge, exercises every tool over stdio, and checks that a path outside the allowlist is refused. All checks should pass.