OpenTrace

Index any codebase into a knowledge graph — then query it with AI via MCP.

OpenTrace parses source code with tree-sitter, extracts classes, functions, imports, and call relationships, and stores the result in an embedded graph database. The graph is queryable through a built-in MCP server, so tools like Claude Code can search, traverse, and understand your codebase structure.

Install

pip install opentraceai

Or run directly with uv:

uvx opentraceai index .

Requires Python 3.12+.

Quick Start

1. Index a codebase

opentraceai index /path/to/repo

This parses every supported file, extracts symbols and relationships, and writes the graph to .opentrace/index.db.

$ opentraceai index ~/projects/myapp
Opening database at .opentrace/index.db ...
Indexing /home/user/projects/myapp ...
  1284 nodes, 3421 relationships, 187 files, 95 classes, 412 functions
Done in 4.2s.

2. Query via MCP

Start a stdio MCP server against the indexed database:

opentraceai mcp

The database is auto-discovered by walking up from the current directory to the git root, looking for .opentrace/index.db. You can override with --db <path>.

Claude Code

Add OpenTrace to Claude Code as a plugin, or configure it manually in your project's .mcp.json:

{
  "mcpServers": {
    "opentrace": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opentraceai", "mcp"]
    }
  }
}

MCP Tools

Supported Languages

Config and data files (JSON, YAML, TOML, Protobuf, SQL, GraphQL, Bash) are indexed as file nodes.

CLI Reference

opentraceai index [PATH]

Index a local codebase into a LadybugDB knowledge graph.

opentraceai mcp

Start a stdio MCP server exposing graph query tools.

opentraceai stats

Display graph statistics (node/edge counts by type).

opentraceai serve

Start an HTTP server exposing the graph database as a REST API.

opentraceai query QUERY_STRING

Run a Cypher or full-text search query against the graph database.

opentraceai export [OUTPUT]

Export the graph database as a .parquet.zip archive.

opentraceai import ARCHIVE

Import a .parquet.zip archive into the graph database.

opentraceai impact FILE_PATH

Analyze the blast radius of changes to a file.

opentraceai config

Read or write project configuration (.opentrace/config.yaml). Subcommands: set, get, show, path.

opentraceai login / logout / whoami / refresh

Authenticate with api.opentrace.ai.

Development

uv sync          # Install dependencies
uv run pytest    # Run tests
uv run ruff check src/ tests/   # Lint
uv run ruff format src/ tests/  # Format

Part of OpenTrace

This package is the CLI/MCP component of OpenTrace, an open-source platform for mapping system architecture into knowledge graphs. The full project also includes a browser-based graph explorer at app.opentrace.ai.

License

Apache License 2.0