Bugsby

The MCP visualizer. Point Bugsby at any package that registers MCP tools via @modelcontextprotocol/sdk and it turns each tool into an interactive flowchart — every function, branch, and I/O call — narrated in plain English, without opening a single file.

Built for developers supervising AI coding agents who need to keep ground truth of what's actually in their repo.

Install + run

npm i -g @bugsby/cli

Bugsby needs a license — grab one at bugsby.dev and activate it once:

bugsby activate <your-license-key>

Then point Bugsby at any MCP package:

bugsby start

Bugsby boots a local server, opens your browser, and draws a flowchart for every MCP tool in whatever directory you ran it in. To analyze a different directory:

bugsby start --target /path/to/some/mcp/package

Prefer not to install globally? npx @bugsby/cli start works too (activate with npx @bugsby/cli activate <key>).

Requirements

• Node 24+
• A TypeScript or JavaScript MCP package to inspect (built on @modelcontextprotocol/sdk). Other languages aren't supported yet.
• A Bugsby license — one-time purchase at bugsby.dev, then bugsby activate <key>
• One of:
  • Ollama running locally (default fallback — pull qwen2.5-coder:7b first)
  • GROQ_API_KEY (free tier at console.groq.com)
  • ANTHROPIC_API_KEY or an existing Claude Code subscription

CLI

bugsby start [options]        Boot the viewer for a project (default command)
bugsby activate <key>         Save a license key to ~/.bugsby/.env
bugsby license                Show your current license status

start options:
  -t, --target <dir>      Directory to analyze (default: cwd)
  -p, --port <number>     Port to listen on (default: 3737, falls back to next free)
  --no-open               Don't open the browser automatically
  --provider <name>       Force provider: ollama | groq | claude-code
  -h, --help              Show help
  -v, --version           Show version

bugsby with no subcommand is equivalent to bugsby start.

bugsby start requires a valid license. It reads BUGSBY_LICENSE_KEY from your shell environment or from ~/.bugsby/.env (where bugsby activate writes it). The key is verified locally with an embedded public key — no network call, no account.

Configuration

Bugsby reads env vars from (highest precedence first):

1. CLI flags
2. Shell process.env (e.g. GROQ_API_KEY=… npx bugsby start)
3. <target>/.bugsby/.env — per-project overrides
4. ~/.bugsby/.env — global per-user config

Available env vars:

• BUGSBY_LICENSE_KEY — your license key (usually set via bugsby activate)
• BUGSBY_TARGET — directory to analyze (default: cwd)
• BUGSBY_PROVIDER — ollama | groq | claude-code (default: auto-detect)
• GROQ_API_KEY, ANTHROPIC_API_KEY — provider auth
• OLLAMA_HOST, OLLAMA_MODEL — local provider overrides
• CLAUDE_CODE_MODEL, GROQ_MODEL — model overrides

BUGSBY_TARGET must point at a package whose source registers MCP tools via setRequestHandler(CallToolRequestSchema, ...) from @modelcontextprotocol/sdk. Bugsby walks the package for source files, finds the call-tool handler, and treats each case clause inside its switch as one flow.

Providers

Bugsby uses Groq + Llama 3.3 70B by default when a GROQ_API_KEY env var is present. The 70B-parameter model produces noticeably sharper narrations and request-mode filter classifications than the local 7B fallback, runs at ~500 tok/s cloud-side, and keeps your laptop cool on cache misses.

Without a key, Bugsby falls back to local Ollama with qwen2.5-coder:7b. The fallback also kicks in automatically when Groq is rate-limited, quota-exhausted, unreachable, or returns 5xx — so a missing API key, a hiccup at Groq, or working offline never breaks the viewer. Existing cached narrations (regardless of which provider generated them) are reused; only new uncached narrations go to whichever provider is currently selected.

The request-mode filter routes through the Claude Agent SDK when an Anthropic API key is set or an existing Claude Code subscription is detected (macOS Keychain on Mac, ~/.claude/.credentials.json on Linux/Windows). Claude is allowed Read, Grep, and Glob inside BUGSBY_TARGET — it can inspect the actual codebase and ground classifications in source instead of guessing from cached summaries. Narrations stay on Groq/Ollama (cheap summarization work doesn't need a codebase-aware agent). Cascade if Claude Code is rate-limited, quota-exhausted, or unreachable: Claude Code → Groq → Ollama.

Override the selection with --provider ollama, --provider groq, or --provider claude-code to pin the primary regardless of which keys are present.

Usage

The left pane lists every flow (MCP tool) in your target. Click one to see its description, a natural-language narration of what an AI agent does by invoking it, and a structural call tree of every function reached from the tool's case body.

Caching

Narrations are cached at $BUGSBY_TARGET/.bugsby/cache.json, keyed by the sha256 of the handler body plus the file contents of the local imports it actually references. Edit a tool and its narration regenerates; leave it alone and the cached narration loads instantly.

Scope

• MCP entry points only (@modelcontextprotocol/sdk's setRequestHandler(CallToolRequestSchema, ...) with a switch on request.params.name)
• One flow per case clause whose test is a string literal
• Call tree depth capped at 3
• No filesystem watching, no editing

Development

For contributors working on Bugsby itself:

git clone …
cd bugsby
pnpm install
cp .env.example .env.local       # set BUGSBY_TARGET and optional API keys
pnpm dev                          # Next.js dev server at http://localhost:3000

To verify the packaged CLI locally without publishing:

pnpm build                        # builds Next standalone + compiles bin/cli.ts
BUGSBY_LICENSE_KEY=<a valid license key> node dist/bin/cli.js start   # exercises `bugsby start`
pnpm pack --pack-destination /tmp # produces /tmp/bugsby-<version>.tgz