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:

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 <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

Advanced Tools

Git-aware Tools

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".

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

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 <path> / 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).
3. 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

License

MIT