tracegist-mcp-bridge

Local-first MCP bridge for inspecting TraceGist package zips.

Usage

Run directly with npx:

npx tracegist-mcp-bridge

Or install globally:

npm install -g tracegist-mcp-bridge
tracegist-mcp-bridge

Configuration

Set TRACEGIST_DIR to change where the bridge looks for packages (defaults to ~/Downloads):

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "TRACEGIST_DIR": "~/Downloads/tracegist"
      }
    }
  }
}

MCP tools

| Tool | Description | | ------------------------------------------ | --------------------------------------------------------------- | | list_tracegist_packages | List package ZIPs in Downloads | | get_tracegist_package_overview | Manifest + truncated handoff preview | | get_tracegist_handoff_markdown | Full handoff markdown (with voice transcripts injected) | | read_tracegist_package_file | Read any file from the ZIP (e.g. network/api-requests.jsonl) | | extract_tracegist_package_file | Extract a file to disk | | transcribe_tracegist_package_voice_notes | Voice-note transcription (OpenRouter or local Whisper) | | get_tracegist_issue_draft | Tracker-agnostic JSON for filing a Linear / GitHub / Jira issue | | watch_live_session | Poll real-time session events while recording is active | | get_live_screenshot | Request and retrieve a screenshot of the current tab | | ask_tester_question | Send a question to the tester (shown as a browser toast) | | get_tester_response | Retrieve the tester's voice + screenshot answer | | get_live_session_summary | Complete interaction log and voice transcriptions after session |

Package contents

Each session ZIP may include:

| Path | Description | | ---------------------------- | -------------------------------------------------------------------------------------- | | *-coding-agent-handoff.md | Structured handoff for the coding agent | | *-manifest.json | Session metadata and file index | | *-playwright-repro.spec.ts | Auto-generated Playwright repro script skeleton | | network/api-requests.jsonl | API request/response bodies (opt-in, requires Deep Diagnostics + body capture enabled) | | markers/marker-NN-*/ | Per-marker screenshots, voice notes, highlight captures |

Voice-note transcription

Local Whisper is bundled — no Python, no system ffmpeg. The TraceGist extension records voice notes as 16 kHz mono wav, which whisper.cpp accepts directly.

Default — local Whisper (bundled, private, no external calls)

tracegist-mcp-bridge depends on nodejs-whisper, which compiles whisper.cpp at install time. The first transcription auto-downloads the model (~150 MB for the default base.en) into the package's cache.

Override the model via env var:

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "TRACEGIST_WHISPER_MODEL": "small.en"
      }
    }
  }
}

Common models: tiny.en, base.en (default), small.en, medium.en, large-v3. English-only *.en variants are smaller and faster for English voice notes. Drop the .en suffix for multilingual.

Install-time requirement: a C/C++ toolchain. Xcode CLI tools (macOS) and build-essential (Linux) are commonly already installed; on Windows you'll typically need to install Visual Studio Build Tools (the "Desktop development with C++" workload) explicitly.

Optional — OpenRouter (cloud, fastest first response)

Set OPENROUTER_API_KEY when launching the bridge. When set, OpenRouter is tried first and local Whisper acts as fallback:

{
  "mcpServers": {
    "tracegist": {
      "command": "npx",
      "args": ["-y", "tracegist-mcp-bridge"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-..."
      }
    }
  }
}

The bridge logs the active paths at startup (Voice transcription path(s): ...).