Symgraph

symgraph

[](https://github.com/grahambrooks/symgraph/actions/workflows/ci.yml) [](https://github.com/grahambrooks/symgraph/actions/workflows/release.yml) [](https://opensource.org/licenses/MIT) [](https://www.rust-lang.org) [](https://modelcontextprotocol.io)

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 |

1. Download the .mcpb file for your platform from Releases
2. Open Claude Desktop
3. Drag and drop the .mcpb file onto Claude Desktop, or use File > Install MCP Server
4. 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 ]        # Start the MCP server (stdio / HTTP)
symgraph status [path]                # Show index statistics
symgraph search                # Find symbols by name
symgraph context             # 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              # Who calls this symbol
symgraph callees              # What this symbol calls
symgraph references           # All references to a symbol
symgraph node                 # Detailed symbol info
symgraph definition           # Source of a symbol [--context-lines N]
symgraph hierarchy            # Parent/child (contains) hierarchy
symgraph implementations      # Interface/trait implementations
symgraph file                   # Symbols defined in a file
symgraph path               # Call path(s) between two symbols
symgraph unused                       # Dead code (no incoming references)

# Impact, git history & coupling
symgraph impact  [--churn]    # Change impact + coupling breakdown
symgraph diff-impact [--git-ref REF]  # Impact of a region / diff
symgraph blame                # 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         # 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 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: Install the code-intelligence plugin for the guided /explore-code skill (plus a SessionStart hook that auto-indexes new projects). The skill now ships via the gb-agent-skills plugin marketplace rather than being copied into your project. In Claude Code:

/plugin marketplace add grahambrooks/gb-agent-skills
/plugin install code-intelligence@gb-agent-skills

The plugin uses bx to launch the symgraph MCP server on demand, so install bx first. Once installed, use the skill 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):

1. Download the .mcpb file for your platform from Releases
2. Drag and drop onto Claude Desktop, or use File > Install MCP Server
3. 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):

1. --db / SYMGRAPH_DB — explicit override.
2. --in-memory / SYMGRAPH_IN_MEMORY=1 — ephemeral (good for long-running

MCP sessions, CI, and read-only checkouts; rebuilt on start).

1. SYMGRAPH_STORAGE strategy, or the auto default:

• reuse an existing .symgraph/ if present (back-compat), else
• git → /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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: grahambrooks
• Source: grahambrooks/symgraph
• License: MIT

Install and usage instructions live in the source repository linked above.