This release is a pre-release and may not be stable for production use.
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
| Tool | Description |
|---|---|
search_graph |
Full-text search across nodes by name or properties |
list_nodes |
List nodes by type (Class, Function, File, etc.) |
get_node |
Get a node's full details and immediate neighbors |
traverse_graph |
Walk relationships from a node (outgoing, incoming, or both) |
get_stats |
Graph statistics — node/edge counts broken down by type |
Supported Languages
| Full extraction (symbols + calls + imports) | Structural extraction (symbols only) |
|---|---|
| Python, TypeScript/JavaScript, Go | Rust, Java, Kotlin, C#, C/C++, Ruby, Swift |
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.
| Option | Default | Description |
|---|---|---|
PATH |
. |
Directory to index |
--db |
.opentrace/index.db |
Database path |
--repo-id |
directory name | Repository identifier |
--batch-size |
200 |
Items per write batch |
-v, --verbose |
off | Debug logging |
opentraceai mcp
Start a stdio MCP server exposing graph query tools.
| Option | Default | Description |
|---|---|---|
--db |
auto-discovered | Database path |
-v, --verbose |
off | Debug logging |
opentraceai stats
Display graph statistics (node/edge counts by type).
| Option | Default | Description |
|---|---|---|
--db |
auto-discovered | Database path |
--output |
text |
Output format (text or json) |
opentraceai serve
Start an HTTP server exposing the graph database as a REST API.
| Option | Default | Description |
|---|---|---|
--db |
auto-discovered | Database path |
--host |
127.0.0.1 |
Bind address |
--port |
8787 |
Bind port |
-v, --verbose |
off | Debug logging |
opentraceai query QUERY_STRING
Run a Cypher or full-text search query against the graph database.
| Option | Default | Description |
|---|---|---|
--db |
auto-discovered | Database path |
-t, --type |
cypher |
Query language (cypher or fts) |
--limit |
100 |
Max rows (FTS only) |
--output |
table |
Output format (table, json, or jsonl) |
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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file opentraceai-0.5.0rc46.tar.gz.
File metadata
- Download URL: opentraceai-0.5.0rc46.tar.gz
- Upload date:
- Size: 638.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
853c34cbf578ef38d098f54aa761b2e7842b04c6121635a63182881639b0715b
|
|
| MD5 |
e321041fc5971dfe32a1cee572235407
|
|
| BLAKE2b-256 |
290c137d37c49d7aeb246b3afb23012b29d590fbe5aa5da00f8f4bbe6ed1a28c
|
Provenance
The following attestation bundles were made for opentraceai-0.5.0rc46.tar.gz:
Publisher:
publish-dev.yml on opentrace/opentrace
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
opentraceai-0.5.0rc46.tar.gz -
Subject digest:
853c34cbf578ef38d098f54aa761b2e7842b04c6121635a63182881639b0715b - Sigstore transparency entry: 2368992260
- Sigstore integration time:
-
Permalink:
opentrace/opentrace@77db73ef1d777a7f06dfaf4b0747ea5a0fc7ee0e -
Branch / Tag:
refs/heads/main - Owner: https://github.com/opentrace
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-dev.yml@77db73ef1d777a7f06dfaf4b0747ea5a0fc7ee0e -
Trigger Event:
push
-
Statement type:
File details
Details for the file opentraceai-0.5.0rc46-py3-none-any.whl.
File metadata
- Download URL: opentraceai-0.5.0rc46-py3-none-any.whl
- Upload date:
- Size: 356.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2a2fd06a9df12dfd504591790ecab799dc279361199f484a1ecf7cb5c2f663d2
|
|
| MD5 |
b68d09144667de55f758dd3d31878dd8
|
|
| BLAKE2b-256 |
43d4564d8a252153eed3b4bfc86dfc5b9fedf3ad88ab2c8685cca7e99e8506fb
|
Provenance
The following attestation bundles were made for opentraceai-0.5.0rc46-py3-none-any.whl:
Publisher:
publish-dev.yml on opentrace/opentrace
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
opentraceai-0.5.0rc46-py3-none-any.whl -
Subject digest:
2a2fd06a9df12dfd504591790ecab799dc279361199f484a1ecf7cb5c2f663d2 - Sigstore transparency entry: 2368992896
- Sigstore integration time:
-
Permalink:
opentrace/opentrace@77db73ef1d777a7f06dfaf4b0747ea5a0fc7ee0e -
Branch / Tag:
refs/heads/main - Owner: https://github.com/opentrace
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish-dev.yml@77db73ef1d777a7f06dfaf4b0747ea5a0fc7ee0e -
Trigger Event:
push
-
Statement type:
