symgraph

Semantic code intelligence MCP server - build knowledge graphs of codebases to enhance AI-assisted code exploration.

symgraph is a rust implementation of https://github.com/colbymchenry/codegraph. Why? Ongoing exploration of compiled binary deployment of MCP Servers.

Features

Multi-language support: Rust, TypeScript, JavaScript, Python, Go, Java, C, C++
Symbol extraction: functions, classes, methods, structs, interfaces, traits, enums, constants
Relationship tracking: calls, contains, imports, exports, extends, implements
Impact analysis: trace the effect of changes through the codebase
Advanced code intelligence:
- Find call paths between functions
- Detect unused/dead code
- Explore class hierarchies
- Locate all interface implementations
- Analyze change impact by line range
Incremental indexing: only re-indexes changed files using content hashing
Dual transport: stdio (default) and HTTP server modes

Installation

macOS & Linux

curl -fsSL https://raw.githubusercontent.com/grahambrooks/symgraph/main/install.sh | bash

To also configure symgraph as an MCP server for Claude Code and Claude Desktop:

curl -fsSL https://raw.githubusercontent.com/grahambrooks/symgraph/main/install.sh | bash -s -- --mcp

Install a specific version:

SYMGRAPH_VERSION=2026.3.30 curl -fsSL https://raw.githubusercontent.com/grahambrooks/symgraph/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/grahambrooks/symgraph/main/install.ps1 -OutFile install.ps1; .\install.ps1

To also configure symgraph as an MCP server for Claude Code and Claude Desktop:

irm https://raw.githubusercontent.com/grahambrooks/symgraph/main/install.ps1 -OutFile install.ps1; .\install.ps1 -Mcp

Install a specific version:

$env:SYMGRAPH_VERSION="2026.3.30"; irm https://raw.githubusercontent.com/grahambrooks/symgraph/main/install.ps1 -OutFile install.ps1; .\install.ps1

Both scripts install to ~/.symgraph/bin/ by default. Override with SYMGRAPH_INSTALL_DIR.

Claude Desktop (MCPB Bundle)

Download and install the MCPB bundle for your platform:

Platform	Download
macOS (Apple Silicon)	symgraph-x.x.x-darwin-arm64.mcpb
macOS (Intel)	symgraph-x.x.x-darwin-x64.mcpb
Windows	symgraph-x.x.x-windows-x64.mcpb
Linux	symgraph-x.x.x-linux-x64.mcpb

Download the .mcpb file for your platform from Releases
Open Claude Desktop
Drag and drop the .mcpb file onto Claude Desktop, or use File > Install MCP Server
Configure the project root when prompted

From Source

git clone https://github.com/grahambrooks/symgraph
cd symgraph
make install

Usage

Index a Codebase

# Index current directory
symgraph index

# Index specific directory
symgraph index ~/projects/myapp

Start MCP Server

# Start with stdio transport (for Claude Desktop)
symgraph serve

# Start with HTTP transport
symgraph serve --port 8080

CLI Commands

Almost every MCP tool is also a CLI subcommand (handy for testing and for agents driven by a CLI skill instead of MCP). Run symgraph help for the full list with arguments and options.

# Core
symgraph index [path]                 # Index a codebase
symgraph serve [--port <PORT>]        # Start the MCP server (stdio / HTTP)
symgraph status [path]                # Show index statistics
symgraph search <query>               # Find symbols by name
symgraph context <task...>            # Build context for a task
symgraph where [path]                 # Show where the index is stored
symgraph prune                        # Remove stale cached indexes

# Symbol relationships (query the current project's index)
symgraph callers <symbol>             # Who calls this symbol
symgraph callees <symbol>             # What this symbol calls
symgraph references <symbol>          # All references to a symbol
symgraph node <symbol>                # Detailed symbol info
symgraph definition <symbol>          # Source of a symbol [--context-lines N]
symgraph hierarchy <symbol>           # Parent/child (contains) hierarchy
symgraph implementations <symbol>     # Interface/trait implementations
symgraph file <path>                  # Symbols defined in a file
symgraph path <from> <to>             # Call path(s) between two symbols
symgraph unused                       # Dead code (no incoming references)

# Impact, git history & coupling
symgraph impact <symbol> [--churn]    # Change impact + coupling breakdown
symgraph diff-impact [--git-ref REF]  # Impact of a region / diff
symgraph blame <symbol>               # git blame a symbol's definition
symgraph churn [path] [--days N]      # File change frequency (volatility)
symgraph module-graph [--granularity file|dir|module]   # Deps, fan-in/out, cycles
symgraph coupling-score [--churn]     # Rank coupling: strength × distance × volatility
symgraph god-struct [--churn]         # Structs ranked by architectural debt
symgraph dispatch-sites <enum>        # Files that match/switch on an enum

Add --format json for machine-readable output (supported by every command except blame, churn, and diff-impact), and --db <path> to point at a specific index database. The MCP tools accept the same format: "json" argument — both surfaces render through one shared ops layer, so CLI and server output match.

MCP Tools

Core Tools

Tool	Description
`symgraph-context`	Build focused code context for a specific task
`symgraph-search`	Quick symbol search by name
`symgraph-callers`	Find all callers of a symbol
`symgraph-callees`	Find all callees of a symbol
`symgraph-impact`	Impact + inbound coupling breakdown (contract/model/intrusive)
`symgraph-node`	Get detailed symbol information
`symgraph-definition`	Get the full source code of a symbol with context
`symgraph-file`	List all symbols defined in a specific file
`symgraph-references`	Find all references to a symbol
`symgraph-reindex`	Trigger incremental reindexing of changed files
`symgraph-status`	Get index statistics

Advanced Tools

Tool	Description
`symgraph-hierarchy`	Get class/module hierarchy (parent/child relationships)
`symgraph-path`	Find call paths between two symbols
`symgraph-unused`	Find unused/dead code with no incoming references
`symgraph-implementations`	Find all implementations of an interface/trait
`symgraph-diff-impact`	Analyze the impact of changing a specific code region

Git-aware Tools

Tool	Description
`symgraph-blame`	Git blame a symbol's definition lines
`symgraph-churn`	File change frequency over a recent window (volatility)

Coupling Analysis Tools

These fold the resolved graph onto the strength × distance × volatility framework. Edges come from accesses (field reads), mutates (field writes / &mut), imports, and enum-dispatch references — so run symgraph-reindex after code changes to populate them. Resolution is name-based (heuristic), best for ranking hotspots. All accept format="json".

Tool	Description
`symgraph-module-graph`	Dependency adjacency, fan-in/fan-out, and cycles (SCCs) at a `file`/`dir`/`module` boundary
`symgraph-coupling-score`	Rank module-pair coupling by strength × distance × volatility (churn)
`symgraph-god-struct`	Rank structs/classes by pub-field × inbound-refs × churn (architectural debt)
`symgraph-dispatch-sites`	Find every file that matches/switches on an enum's members (control coupling)

Example Use Cases

Find dead code for cleanup:

Use symgraph-unused to find all unused functions and classes

Understand function call chains:

Use symgraph-path with from="main" and to="database_query" to see how data flows

Assess change impact:

Use symgraph-diff-impact with file_path="src/auth.rs" start_line=45 end_line=60
to see what would be affected by changes in that region

Explore OOP hierarchies:

Use symgraph-hierarchy with symbol="BaseHandler" to see all parent/child relationships

Find all trait implementations:

Use symgraph-implementations with symbol="Iterator" to find all structs implementing Iterator

Project Setup

Add symgraph to your project in two steps: index your code, then configure your AI tool.

Step 1: Index Your Project

cd /path/to/your/project
symgraph index

This creates a .symgraph/ directory containing the SQLite knowledge graph. Add .symgraph/ to your .gitignore.

Re-run symgraph index after significant code changes, or use the symgraph-reindex MCP tool to incrementally update from within your AI tool.

Step 2: Configure Your AI Tool

Claude Code

Register symgraph as an MCP server for your project:

cd /path/to/your/project
claude mcp add symgraph -- symgraph serve

Or add .mcp.json to your project root:

{
  "mcpServers": {
    "symgraph": {
      "type": "stdio",
      "command": "symgraph",
      "args": ["serve"]
    }
  }
}

Optional: Add the /explore-code skill for guided code exploration:

mkdir -p .claude/skills
cp -r /path/to/symgraph/.claude/skills/explore-code .claude/skills/

Then use it in Claude Code:

/explore-code how does the authentication middleware work?
/explore-code what would break if I changed the User struct?

Claude Desktop

Via MCPB bundle (easiest):

Download the .mcpb file for your platform from Releases
Drag and drop onto Claude Desktop, or use File > Install MCP Server
Set the project root when prompted

Via manual config — add to claude_desktop_config.json:

{
  "mcpServers": {
    "symgraph": {
      "command": "symgraph",
      "args": ["serve"],
      "env": {
        "SYMGRAPH_ROOT": "/path/to/your/project"
      }
    }
  }
}

GitHub Copilot

Per-repository — add .copilot/mcp.json to your project:

{
  "mcpServers": {
    "symgraph": {
      "command": "symgraph",
      "args": ["serve"]
    }
  }
}

VS Code user settings — add to settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "symgraph": {
      "command": "symgraph",
      "args": ["serve"],
      "env": {
        "SYMGRAPH_ROOT": "${workspaceFolder}"
      }
    }
  }
}

See GitHub Copilot MCP documentation for more details.

OpenAI Codex

codex mcp add symgraph --command "symgraph" --args "serve"

Or add to ~/.codex/config.toml:

[mcp_servers.symgraph]
command = "symgraph"
args = ["serve"]

See OpenAI Codex MCP documentation for more details.

HTTP Mode (Any MCP Client)

For shared or remote setups, run symgraph as an HTTP server:

symgraph serve --port 8080

Then point your MCP client at http://localhost:8080/mcp.

Environment Variables

Variable	Description	Default
`SYMGRAPH_ROOT`	Project root directory	Current directory
`SYMGRAPH_DB`	Explicit index database path (highest priority)	—
`SYMGRAPH_STORAGE`	Index location strategy: `git` / `cache` / `local`	auto
`SYMGRAPH_IN_MEMORY`	`1` ⇒ ephemeral in-memory index (no disk writes)	off
`SYMGRAPH_AUTH_TOKEN`	Bearer token for HTTP `/mcp`	—

Index Storage

The index is persistent and shared between the CLI and the MCP server, so you symgraph index once and both use it. The location is resolved by this chain (use symgraph where to see what's chosen):

--db <path> / SYMGRAPH_DB — explicit override.
--in-memory / SYMGRAPH_IN_MEMORY=1 — ephemeral (good for long-running MCP sessions, CI, and read-only checkouts; rebuilt on start).
SYMGRAPH_STORAGE strategy, or the auto default:
- reuse an existing .symgraph/ if present (back-compat), else
- git → <git-common-dir>/symgraph/index.db — co-located with the repo, never tracked, no .gitignore entry needed (the default in a git repo; handles worktrees/submodules), else
- cache → an OS cache dir keyed by the repo path (for non-git dirs).

symgraph prune removes cached indexes whose source repo no longer exists. local storage writes a self-.gitignore so even in-tree indexes don't dirty git status.

Architecture

symgraph/
├── src/
│   ├── main.rs          # CLI entry point
│   ├── lib.rs           # Core indexing logic
│   ├── types.rs         # Type definitions (Node, Edge, etc.)
│   ├── db/              # SQLite database operations
│   ├── extraction/      # Tree-sitter code extraction
│   ├── graph/           # Graph traversal algorithms
│   ├── context/         # Context building for AI tasks
│   └── mcp/             # MCP protocol handlers
└── .symgraph/
    └── index.db         # SQLite database (per-project)

Core Concepts

Node: A code symbol (function, class, method, etc.)
Edge: A relationship between nodes (calls, contains, imports, etc.)
Knowledge Graph: The complete set of nodes and edges for a codebase

Development

Prerequisites

Rust 1.70+
SQLite (bundled via rusqlite)

Building

make build           # Release build
make test            # Run tests
make check           # Format, lint, and test
make install         # Build and install to /usr/local/bin

Project Structure

Module	Description
`types`	Core type definitions (NodeKind, EdgeKind, Language, etc.)
`db`	SQLite database schema and operations
`extraction`	Tree-sitter based code parsing and symbol extraction
`graph`	Graph algorithms (callers, callees, impact analysis)
`context`	Context builder for AI task assistance
`mcp`	MCP protocol server implementation

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.claude/skills/explore-code		.claude/skills/explore-code
.github/workflows		.github/workflows
devcontainer-feature		devcontainer-feature
docs		docs
src		src
tests		tests
.gitignore		.gitignore
.mcp.json		.mcp.json
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
catalog-info.yaml		catalog-info.yaml
install.ps1		install.ps1
install.sh		install.sh
manifest.json		manifest.json

Folders and files

Latest commit

History

Repository files navigation

symgraph

Features

Installation

macOS & Linux

Windows (PowerShell)

Claude Desktop (MCPB Bundle)

From Source

Usage

Index a Codebase

Start MCP Server

CLI Commands

MCP Tools

Core Tools

Advanced Tools

Git-aware Tools

Coupling Analysis Tools

Example Use Cases

Project Setup

Step 1: Index Your Project

Step 2: Configure Your AI Tool

Claude Code

Claude Desktop

GitHub Copilot

OpenAI Codex

HTTP Mode (Any MCP Client)

Environment Variables

Index Storage

Architecture

Core Concepts

Development

Prerequisites

Building

Project Structure

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages