TracePulse

Runtime feedback MCP server for AI coding agents.

ViewGraph sees the UI. TracePulse feels the backend.

"LLMs can't see what happens when their code actually runs. They're throwing darts in the dark." - Sentry Engineering

TracePulse closes this loop at dev time - seconds after the code change, not minutes after deployment.

TracePulse watches your dev server's stdout/stderr, parses errors into structured events with signal scoring, and exposes them as MCP tools that any AI coding agent can call. The agent edits code, calls get_errors, and instantly knows if the fix worked - no manual log reading, no copy-paste.

Status

🟡 Alpha v0.8.1 - Phases 1-5 complete. Core pipeline, watch mode, multi-process support, frontend-backend correlation, proactive monitoring. 18 error parsers, 19 MCP tools, 630 tests passing.

Quick Start

Add TracePulse to your MCP client's config file. The file location depends on which tool you use:

Config File Locations

⚠️ Common mistake: Kiro CLI uses .kiro/settings/mcp.json, not .kiro/mcp.json. If TracePulse tools don't appear, check you're editing the right file.

Start mode - spawn and monitor your dev server

{
  "mcpServers": {
    "tracepulse": {
      "command": "npx",
      "args": ["tracepulse", "start", "npm run dev"]
    }
  }
}

Attach mode - tail an existing log file

Use this when your servers are already running (managed by scripts, Docker, process managers, etc.):

{
  "mcpServers": {
    "tracepulse": {
      "command": "npx",
      "args": ["tracepulse", "attach", "--log-file", "./logs/server.log"]
    }
  }
}

Local development (without npm publish)

Point directly to the built CLI:

{
  "mcpServers": {
    "tracepulse": {
      "command": "node",
      "args": ["/path/to/tracepulse/dist/cli.js", "start", "npm run dev"]
    }
  }
}

Which mode should I use?

MCP Tools

Core (Phase 1)

Watch Mode (Phase 2)

Multi-Process (Phase 3)

Correlation (Phase 4)

Proactive (Phase 5)

Execution & Health

Error Parsers

TracePulse parses errors from 18 sources out of the box:

Runtime errors:

• Node.js - TypeError, ReferenceError, SyntaxError, etc. with V8 stack traces
• Python - Tracebacks with file:line extraction
• Go - Panics with goroutine stack traces
• Java - Exceptions with at frames and Caused by: chains
• Rust - Panics with RUST_BACKTRACE output
• JSON - Structured logs (pino, structlog JSON, logback) with level/message fields
• Structlog - Python structlog key-value format ([info], [warning], [error] brackets)

Build errors:

• TypeScript - tsc compiler errors (TS####)
• ESLint - Lint errors with rule names
• Vite/webpack - Build tool errors (module not found, transform failures)
• Build Stats - Module count, build time from Vite/webpack

Test runners:

• pytest - FAILED, ERROR, summary lines
• Jest - FAIL header, assertion details
• vitest - FAIL file, Expected/Received
• Go test - --- FAIL, error with file:line

Infrastructure:

• HTTP Access Log - uvicorn, express/morgan, nginx with status and duration
• Migration - alembic and Django migration output

Signal Scoring

Every event gets a signal_score (0–100) and signal_strength (high/medium/low):

CLI Usage

# Single process - spawn and monitor
tracepulse start "npm run dev"

# Attach to existing log file
tracepulse attach --log-file ./server.log

# Multi-process - monitor multiple services
tracepulse start --service api="npm run dev:api" --service worker="npm run worker"

# Config file
tracepulse start --config tracepulse.config.json

# Docker Compose
tracepulse compose --file docker-compose.yml

# With persistence (saves fingerprints across sessions)
tracepulse start --persist "npm run dev"

# With HTTP transport (for multi-client scenarios)
tracepulse start --http "npm run dev"

Hot-Reload Detection

TracePulse detects hot-reload events from 8 dev tools:

• Vite - compilation success, HMR updates
• webpack - compilation completed
• nodemon - restart/starting events
• Next.js - compilation, route compiling
• ts-node-dev - restart, compilation complete
• uvicorn - file change detection, reloader process
• Django - file change watching, system checks
• Flask - restart with stat/watchdog, change detection

When watch_for_errors detects a hot-reload, it sets hot_reload_detected: true in the response so the agent knows the server actually reloaded.

Security

• All log output is redacted for secrets (12 patterns: API keys, Bearer/JWT tokens, connection strings, PEM keys, GitHub/GitLab/Slack tokens) before entering the pipeline
• No secrets in MCP responses, ring buffer, or diagnostic output
• HTTP endpoints bind to 127.0.0.1 only - no external access
• Fingerprint persistence stores only hashes, not raw error messages
• No file system writes except optional fingerprint persistence

Companion Tools

TracePulse is designed to work alongside:

• ViewGraph - UI context layer (DOM, a11y, layout, annotations)
• Chrome DevTools MCP - Browser debugging (console, network, performance)

Together: backend verification (TracePulse) → browser verification (Chrome DevTools MCP) → visual verification (ViewGraph).

Architecture

See docs/architecture/architecture-guide.md for the full architecture guide with diagrams.

License

MIT