srcmap-mcp

MCP server for source map debugging. Fetch, inspect, look up, and extract original sources from any production website — directly from your AI assistant.

Add To Your Editor

Claude Code

claude mcp add srcmap-mcp -- npx srcmap-mcp

Codex CLI

codex --mcp-config '{"srcmap-mcp":{"command":"npx","args":["srcmap-mcp"]}}'

Gemini CLI

gemini --mcp-config '{"srcmap-mcp":{"command":"npx","args":["srcmap-mcp"]}}'

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "srcmap-mcp": {
      "command": "npx",
      "args": ["srcmap-mcp"]
    }
  }
}

{
  "mcpServers": {
    "srcmap-mcp": {
      "command": "npx",
      "args": ["srcmap-mcp"]
    }
  }
}

{
  "context_servers": {
    "srcmap-mcp": {
      "command": {
        "path": "npx",
        "args": ["srcmap-mcp"]
      }
    }
  }
}

docker run -i --rm ghcr.io/bartwaardenburg/srcmap-mcp

Prerequisites

This MCP server requires the srcmap CLI to be installed:

cargo install srcmap-cli

Verify it's available:

srcmap --version

Features

8 tools across 3 categories for complete source map debugging:

Inspection (4 tools)

Lookup (2 tools)

Fetch (2 tools)

Configuration

Toolset Filtering

Example: SRCMAP_TOOLSETS=lookup,fetch enables only lookup and fetch tools.

Example Usage

Debug a production error

Sentry is showing TypeError: Cannot read property 'items' of undefined at main-2f8a.js:1:34291 on https://app.example.com — what's the original source?

The assistant fetches the bundle and source map, looks up the position, and shows you the exact original file and line causing the error — with surrounding context.

Investigate what's deployed

What code is actually running on https://app.example.com? Extract the source tree so we can look around.

The assistant pulls the production bundles, extracts all original sources, and gives you the full project structure to explore.

Trace a bug from a stack trace

Users are reporting a crash on our checkout page. Here's the minified stack trace — can you trace each frame back to the original source?

at https://cdn.example.com/checkout-a3f2.js:1:48293
at https://cdn.example.com/checkout-a3f2.js:1:51007
at https://cdn.example.com/vendor-9b1e.js:1:12844

The assistant resolves each frame to the original file, function name, and line number — turning a wall of minified positions into a readable stack trace.

Development

pnpm install      # Install dependencies
pnpm dev          # Run in development mode
pnpm build        # Compile TypeScript
pnpm test         # Run tests
pnpm typecheck    # Type check without emitting

Project Structure

src/
  index.ts              Entry point (env, client, transport)
  server.ts             McpServer factory and toolset registry
  srcmap-client.ts      CLI process wrapper with caching
  cache.ts              TTL cache
  tool-result.ts        Result/error formatting helpers
  update-checker.ts     npm update checker
  types.ts              TypeScript interfaces
  tools/
    inspection.ts       Info, validate, sources, mappings tools
    lookup.ts           Lookup and resolve tools
    fetch.ts            Fetch and extract tools
    tools.test.ts       Tool handler tests

Requirements

• Node.js >= 20
• srcmap CLI installed (cargo install srcmap-cli)

License

MIT