trace-mcp

Framework-aware code intelligence MCP server — 48+ framework integrations across 68 languages.

Your AI agent reads UserController.php and sees a class. trace-mcp reads it and sees a route → controller → FormRequest → Eloquent model → Inertia render → Vue page → child components — in one graph.

The problem

AI coding agents are language-aware but framework-blind.

They don't know that Inertia::render('Users/Show', $data) connects a Laravel controller to resources/js/Pages/Users/Show.vue. They don't know that $user->posts() means the posts table defined three migrations ago. They can't trace a request from URL to rendered pixel.

So they brute-read files, guess at relationships, and miss cross-language edges entirely. The bigger the project, the worse it gets.

The solution

trace-mcp builds a cross-language dependency graph from your source code and exposes it through the Model Context Protocol. Any MCP-compatible agent (Claude Code, Cursor, Windsurf, etc.) gets framework-level understanding out of the box.

| Without trace-mcp | With trace-mcp | |---|---| | Agent reads 15 files to understand a feature | get_task_context — optimal code subgraph in one shot | | Agent doesn't know which Vue page a controller renders | routes_to → renders_component → uses_prop edges | | "What breaks if I change this model?" — agent guesses | get_change_impact traverses reverse dependencies across languages | | Schema? Agent needs a running database | Migrations parsed — schema reconstructed from code | | Prop mismatch between PHP and Vue? Discovered in production | Detected at index time — PHP data vs. defineProps |

Key capabilities

• Request flow tracing — URL → Route → Middleware → Controller → Service, across 18 backend frameworks
• Component trees — render hierarchy with props / emits / slots (Vue, React, Blade)
• Schema from migrations — no DB connection needed
• Event chains — Event → Listener → Job fan-out (Laravel, Django, NestJS, Celery, Socket.io)
• Change impact analysis — reverse dependency traversal across languages
• Graph-aware task context — describe a dev task → get the optimal code subgraph (execution paths, tests, types), adapted to bugfix/feature/refactor intent
• CI/PR change impact reports — automated blast radius, risk scoring, test gap detection, architecture violation checks on every PR
• Call graph & DI tree — bidirectional call graphs, NestJS dependency injection
• ORM model context — relationships, schema, metadata for 7 ORMs
• Dead code & test gap detection — find untested exports, dead code, coverage gaps
• Multi-repo federation — link graphs across separate repos via API contracts; cross-repo impact analysis
• AI-powered analysis — symbol explanation, test suggestions, change review, semantic search (optional)

Supported stack

Languages (68): PHP, TypeScript/JavaScript, Python, Go, Java, Kotlin, Ruby, Rust, C, C++, C#, Swift, Objective-C, Dart, Scala, Groovy, Elixir, Erlang, Haskell, Gleam, Bash, Lua, Perl, GDScript, R, Julia, Nix, SQL, HCL/Terraform, Protocol Buffers, Vue SFC, HTML, CSS/SCSS/SASS/LESS, XML/XUL/XSD, YAML, JSON, TOML, Assembly, Fortran, AutoHotkey, Verse, AL, Blade, EJS, Zig, OCaml, Clojure, F#, Elm, CUDA, COBOL, Verilog/SystemVerilog, GLSL, Meson, Vim Script, Common Lisp, Emacs Lisp, Dockerfile, Makefile, CMake, INI, Svelte, Markdown, MATLAB, Lean 4, FORM, Magma, Wolfram/Mathematica

Frameworks: Laravel (+ Livewire, Nova, Filament, Pennant), Django (+ DRF), FastAPI, Flask, Express, NestJS, Fastify, Hono, Next.js, Nuxt, Rails, Spring, tRPC

ORMs: Eloquent, Prisma, TypeORM, Drizzle, Sequelize, Mongoose, SQLAlchemy

Frontend: Vue, React, React Native, Blade, Inertia, shadcn/ui, Nuxt UI, MUI, Ant Design, Headless UI

Other: GraphQL, Socket.io, Celery, Zustand, Pydantic, Zod, n8n, React Query/SWR, Playwright/Cypress/Jest/Vitest/Mocha

Full details: Supported frameworks · All tools

Quick start

npm install -g trace-mcp
trace-mcp init        # one-time global setup (MCP clients, hooks, CLAUDE.md)
trace-mcp add         # register current project for indexing

Step 1: init — one-time global setup. Configures your MCP client (Claude Code, Cursor, Windsurf, or Claude Desktop), installs the guard hook, and adds a tool routing guide to ~/.claude/CLAUDE.md.

Step 2: add — registers a project. Detects frameworks and languages, creates the index database, and adds the project to the global registry. Run this in each project you want trace-mcp to understand.

All state lives in ~/.trace-mcp/ — nothing is stored in your project directory.

Start your MCP client and use:

> get_project_map to see what frameworks are detected
> get_task_context("fix the login bug") to get full execution context for a task
> get_change_impact on app/Models/User.php to see what depends on it

Adding more projects

cd /path/to/another/project
trace-mcp add

Or specify a path directly:

trace-mcp add /path/to/project

List all registered projects:

trace-mcp list

Upgrading

After updating trace-mcp (npm update -g trace-mcp), run:

trace-mcp upgrade

This runs database migrations and reindexes all registered projects with the latest plugins. To upgrade a specific project:

trace-mcp upgrade /path/to/project

Manual setup

If you prefer manual control, see Configuration for all options. You can skip specific init steps:

trace-mcp init --skip-hooks --skip-claude-md --skip-mcp-client

Indexing details

Automatic: trace-mcp serve starts background indexing immediately and launches a file watcher. The server is ready for tool calls right away — results improve as indexing progresses. If the project isn't registered yet, serve auto-registers it.

Manual: index a project without starting the server:

trace-mcp index /path/to/project          # incremental (skips unchanged files)
trace-mcp index /path/to/project --force   # full reindex

Files are content-hashed (MD5). On re-index, unchanged files are skipped. Both serve and serve-http start a file watcher that debounces rapid changes (300ms) and processes deletions immediately.

Global directory structure

All trace-mcp state is centralized:

~/.trace-mcp/
  .config.json              # global config + per-project settings
  registry.json             # registered projects
  topology.db               # cross-service topology + federation graph
  index/
    my-app-a1b2c3d4e5f6.db  # per-project databases (named by project + hash)

Getting the most out of trace-mcp

trace-mcp works on three levels to make AI agents use its tools instead of raw file reading:

Level 1: Automatic (works out of the box)

The MCP server provides instructions and tool descriptions with routing hints that tell AI agents when to prefer trace-mcp over native Read/Grep/Glob. This works with any MCP-compatible client — no configuration needed.

Level 2: CLAUDE.md (recommended)

Add this block to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global use) to reinforce tool routing:

## Code Navigation Policy

Use trace-mcp tools for code intelligence — they understand framework relationships, not just text.

| Task | trace-mcp tool | Instead of |
|------|---------------|------------|
| Find a function/class/method | `search` | Grep |
| Understand a file before editing | `get_outline` | Read (full file) |
| Read one symbol's source | `get_symbol` | Read (full file) |
| What breaks if I change X | `get_change_impact` | guessing |
| All usages of a symbol | `find_usages` | Grep |
| Starting work on a task | `get_task_context` | reading 15 files |
| Quick keyword context | `get_feature_context` | reading 15 files |
| Tests for a symbol | `get_tests_for` | Glob + Grep |
| HTTP request flow | `get_request_flow` | reading route files |
| DB model relationships | `get_model_context` | reading model + migrations |

Use Read/Grep/Glob for non-code files (.md, .json, .yaml, config).
Start sessions with `get_project_map` (summary_only=true).

Level 3: Hook enforcement (Claude Code only)

For hard enforcement, install the PreToolUse guard hook that blocks Read/Grep/Glob on source code files and redirects the agent to trace-mcp tools with specific suggestions. The hook is installed globally by trace-mcp init, or manually:

trace-mcp setup-hooks --global    # install
trace-mcp setup-hooks --uninstall # remove

This copies the guard script to ~/.claude/hooks/ and adds the hook to your Claude Code settings.

What the hook does:

• Blocks Read/Grep/Glob/Bash on source code files (.ts, .py, .php, .go, .java, .rb, etc.)
• Allows non-code files (.md, .json, .yaml, .env, config)
• Allows Read before Edit — first Read is blocked with a suggestion, retry on the same file is allowed (the agent needs full content for editing)
• Allows safe Bash commands (git, npm, build, test, docker, etc.)
• Redirects with specific trace-mcp tool suggestions in the denial message

How it works

Source files (PHP, TS, Vue, Python, Go, Java, Kotlin, Ruby, HTML, CSS, Blade)
    │
    ▼
┌──────────────────────────────────────────┐
│  Pass 1 — Per-file extraction            │
│  tree-sitter → symbols                   │
│  integration plugins → routes,           │
│    components, migrations, events,       │
│    models, schemas, variants, tests      │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  Pass 2 — Cross-file resolution          │
│  PSR-4 · ES modules · Python modules    │
│  Vue components · Inertia bridge         │
│  Blade inheritance · ORM relations       │
│  → unified directed edge graph           │
└────────────────────┬─────────────────────┘
                     │
                     ▼
┌──────────────────────────────────────────┐
│  SQLite (WAL mode) + FTS5               │
│  nodes · edges · symbols · routes       │
│  + optional: embeddings · summaries     │
└────────────────────┬─────────────────────┘
                     │
                     ▼
         MCP server (stdio or HTTP/SSE)
         44+ tools · 2 resources

Incremental by default — files are content-hashed; unchanged files are skipped on re-index.

Plugin architecture — language plugins (symbol extraction) and integration plugins (semantic edges) are loaded based on project detection, organized into categories: framework, ORM, view, API, validation, state, realtime, testing, tooling.

Details: Architecture & plugin system

Documentation

| Document | Description | |---|---| | Supported frameworks | Complete list of languages, frameworks, ORMs, UI libraries, and what each extracts | | Tools reference | All 38 MCP tools with descriptions and usage examples | | Configuration | Config options, AI setup, environment variables, security settings | | Architecture | How indexing works, plugin system, project structure, tech stack | | Development | Building, testing, contributing, adding new plugins |

Multi-repo federation

Real projects are not a single repository. trace-mcp can link dependency graphs across separate repos — if microservice A calls an API endpoint in microservice B, trace-mcp knows that changing that endpoint in B breaks clients in A.

How it works

Federation is automatic by default. Every time a project is indexed (serve, serve-http, or index), trace-mcp:

1. Registers the project in the global federation (~/.trace-mcp/topology.db)
2. Discovers services (Docker Compose, workspace detection)
3. Parses API contracts — OpenAPI/Swagger, GraphQL SDL, Protobuf/gRPC
4. Scans code for HTTP client calls (fetch, axios, Http::, requests, http.Get, gRPC stubs, GraphQL operations)
5. Links discovered calls to known endpoints from previously indexed repos
6. Creates cross-repo dependency edges

Example

# Index two separate repos
cd ~/projects/user-service && trace-mcp add
cd ~/projects/order-service && trace-mcp add

# order-service has: axios.get('/api/users/{id}')
# user-service has: openapi.yaml with GET /api/users/{id}
# → trace-mcp automatically links them

# Check cross-repo impact
trace-mcp federation impact --endpoint=/api/users
# → "GET /api/users/{id} is called by 2 client(s) in 1 repo(s)"
#   [order-service] src/services/user-client.ts:42 (axios, confidence: 85%)

Federation CLI

trace-mcp federation add --repo=../service-b [--contract=openapi.yaml]
trace-mcp federation remove <name-or-path>
trace-mcp federation list [--json]
trace-mcp federation sync           # re-scan all repos
trace-mcp federation impact --endpoint=/api/users [--method=GET] [--service=user-svc]

MCP tools

| Tool | What it does | |---|---| | get_federation_graph | All federated repos, their connections, and stats | | get_federation_impact | Cross-repo impact: what breaks if endpoint X changes (resolves to symbol level) | | get_federation_clients | Find all client calls across repos that call a specific endpoint | | federation_add_repo | Add a repo to the federation via MCP | | federation_sync | Re-scan all federated repos |

Federation builds on top of the topology system. See Configuration for options.

CI/PR change impact reports

trace-mcp can generate automated change impact reports for pull requests — blast radius, risk scoring, test coverage gaps, architecture violations, and dead code detection.

CLI usage

# Generate a markdown report for changes between main and HEAD
trace-mcp ci-report --base main --head HEAD

# Output to file
trace-mcp ci-report --base main --head HEAD --format markdown --output report.md

# JSON output
trace-mcp ci-report --base main --head HEAD --format json

# Fail CI if risk level >= high
trace-mcp ci-report --base main --head HEAD --fail-on high

# Index before generating (for CI environments without pre-built index)
trace-mcp ci-report --base main --head HEAD --index

GitHub Action

Add this workflow to get automatic impact reports on every PR:

# .github/workflows/ci.yml (impact-report job runs after build-and-test)
- name: Index project
  run: node dist/cli.js index . --force

- name: Generate impact report
  run: |
    node dist/cli.js ci-report \
      --base ${{ github.event.pull_request.base.sha }} \
      --head ${{ github.event.pull_request.head.sha }} \
      --format markdown \
      --output report.md

- name: Post PR comment
  uses: marocchino/sticky-pull-request-comment@v2
  with:
    path: report.md

The full workflow is in .github/workflows/ci.yml — it runs build → test → impact-report on every PR.

Report sections

| Section | What it shows | |---|---| | Summary | Changed files, affected files count, risk level, gap counts | | Blast Radius | Files transitively affected by changes (depth-2 reverse dependency traversal) | | Test Coverage Gaps | Affected symbols with no matching test file | | Risk Analysis | Per-file composite score: 30% complexity + 25% churn + 25% coupling + 20% blast radius | | Architecture Violations | Layer rule violations involving changed files (auto-detects clean architecture / hexagonal presets) | | Dead Code | New exports in changed files that nothing imports |

Best for

• Full-stack projects in any supported framework combination
• Teams using AI agents (Claude, Cursor, Windsurf) for day-to-day development
• Multi-language codebases where PHP ↔ JavaScript ↔ Python boundaries create blind spots
• Monorepos with multiple services and shared libraries
• Microservice architectures where API changes ripple across repos
• Large codebases where agents waste tokens re-reading files

License

Elastic License 2.0 + Ethical Use Addendum — free for personal and internal use. See LICENSE for full terms.

Built by Nikolai Vysotskyi