How do I use codebase-synapse?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codebase-synapse What's the impact of updating handleLogin in terms of callers and dependent files?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

codebase-synapse

by iwiels

Overview Schema Source Related Servers Discussions Admin

Rust

Local

🧠 Codebase Synapse

Give your AI agent a deep understanding of your entire codebase.

An MCP server that indexes your codebase into a local knowledge graph with 52 AI tools — semantic search, call-graph traversal, git archaeology, blast-radius analysis, and more.

Works with Claude Code · Cursor · Windsurf · Zed · Any MCP client

npm version License: Apache-2.0 MCP Registry

The Problem

AI coding agents (Claude, Cursor, etc.) are powerful — but they work with limited context. They can only see the files you open or feed them. Ask about call chains, architectural patterns, or blast-radius impact, and they guess.

Codebase Synapse fixes this. It indexes your entire repo into a local knowledge graph stored in SQLite, giving your AI agent real answers backed by structural analysis — not hallucinations.

How it works

graph LR
    A["📁 Your Codebase"] -->|Tree-sitter| B["🧩 Parser"]
    B -->|Symbols & Edges| C["🕸️ Knowledge Graph"]
    C -->|SQLite| D["💾 Local DB"]
    D -->|52 MCP Tools| E["🤖 AI Agent"]
    
    style A fill:#1a1b26,stroke:#7aa2f7,color:#c0caf5
    style B fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style C fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style D fill:#1a1b26,stroke:#e0af68,color:#c0caf5
    style E fill:#1a1b26,stroke:#f7768e,color:#c0caf5

Related MCP server: codeweave-mcp

⚡ Quick Start

1. Index your project (CLI, Zoekt-style)

codebase-synapse index /path/to/your/repo

Indexing runs as a separate CLI command and writes into ~/.codebase-synapse/codebase.db. The first index is the slow one; re-running it only re-indexes changed files. The MCP server never indexes — it only reads the pre-built index.

2. Start the MCP server

npx codebase-synapse

That's it. No Docker. No database setup. No cloud. The server starts via stdio and serves the pre-built index to your MCP client.

Configure your client

Add to your claude_desktop_config.json or mcp_servers.json:

{
  "mcpServers": {
    "codebase-synapse": {
      "command": "npx",
      "args": ["-y", "codebase-synapse"]
    }
  }
}

Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "codebase-synapse": {
      "command": "npx",
      "args": ["-y", "codebase-synapse"]
    }
  }
}

Any MCP client that supports stdio transport works. Just point it at:

npx -y codebase-synapse

✨ What It Does

🔍 Search & Discovery

Tool	Description
`semantic_search`	Vector similarity search using local embeddings (all-MiniLM-L6-v2)
`search_code`	Full-text search across code (FTS5 + BM25 ranking)
`search_symbol`	Find functions, classes, types by name or pattern
`hybrid_search`	Combined semantic + lexical search with RRF fusion
`find_similar`	Find structurally similar code using MinHash + LSH
`find_symbol_everywhere`	Locate a symbol across all indexed projects

🕸️ Knowledge Graph

Tool	Description
`get_callers` / `get_callees`	Navigate the call graph in either direction
`get_imports` / `get_dependents`	Trace dependency chains
`impact_analysis`	Compute blast radius before editing a file
`find_path`	Find the shortest connection between two symbols
`find_dead_code`	Detect unreachable functions and unused exports
`get_pagerank`	Identify the most critical nodes in your architecture
`query_graph`	Run Cypher-like queries against the knowledge graph

🏗️ Architecture

Tool	Description
`get_architecture`	Full project architecture overview (languages, entry points, hotspots)
`get_file_structure`	Directory tree with symbol annotations
`project_overview`	High-level summary with key metrics
`get_route_map`	Extract HTTP routes and their handler mappings
`suggest_boundaries`	Detect module boundaries via Leiden clustering
`check_boundaries`	Validate cross-module dependencies against defined boundaries
`get_clusters`	Community detection across the codebase

🔬 Git Archaeology

Tool	Description
`git_archaeology`	Deep history analysis of a file (authors, churn, evolution)
`get_hotspots`	Files with highest complexity × change frequency
`detect_change_coupling`	Files that always change together
`get_recent_semantic_changes`	Semantically meaningful recent changes
`index_git_history`	Build temporal analysis from git log

🧠 Memory & Context

Tool	Description
`memory_store` / `memory_search` / `memory_list`	Persistent notes, facts, and decisions across sessions
`session_remember` / `session_recall`	Short-term memory within a session
`get_context`	Budgeted context preparation for AI agents
`get_edit_context`	Focused context for a specific file edit
`get_working_set`	Recently accessed and modified files
`manage_adr`	Architecture Decision Records management

🛡️ Codebase Guard

Included as a bonus: codebase-guard is a PreToolUse hook for Claude Code that blocks writes to high-impact files until the agent runs impact_analysis first.

It uses PageRank scores and blast-radius data from the knowledge graph to identify architectural hubs. No more accidental edits to core files.

🔧 Technical Details


Language	Rust (compiled native binary)
Transport	MCP stdio (JSON-RPC)
Storage	SQLite (WAL mode, zero config)
Embeddings	all-MiniLM-L6-v2 via Candle (offline, local, lazy-loaded)
Parsing	Tree-sitter (10 languages)
Distribution	npm with prebuilt binaries (Windows, macOS, Linux × x64, arm64)

Supported Languages

Rust · Python · TypeScript · JavaScript · Go · Java · C# · PHP · C · C++

Architecture

src/
├── parser/       # Tree-sitter parsing & entity extraction
├── graph/        # Knowledge graph, PageRank, Leiden clustering
├── indexer/      # Repository indexing pipeline
├── search/       # BM25 full-text + vector cosine + hybrid RRF
├── embedding/    # Candle-based local embeddings (feature-gated)
├── memory/       # Persistent & session memory stores
├── mcp/          # MCP protocol transport + 52 tool handlers
├── git/          # Git archaeology, intent classification, hotspots
├── context/      # Budgeted context preparation for AI
├── cypher/       # Nom-based Cypher parser → SQL CTE planner
├── similarity/   # MinHash + LSH structural similarity
├── semantic/     # Multi-signal scoring (tokens, directory, AST)
└── cli/          # Interactive TUI installer + artifact export/import

🤝 Contributing

Contributions are welcome! The project uses standard Rust tooling:

# Run tests
cargo test

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt --all

📄 License

Apache-2.0

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

gread A
io.github.NitroRCr
An MCP server that gives your AI access to the source code and docs of all public github repos
Version Control Code Analysis Documentation Access
5361
Meeba Brain A
io.github.meemoprasad
Repository knowledge graph MCP server for codebase understanding and debugging.
Code Analysis Developer Tools
51
ArchGraphOAuth
dev.archgraph
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code Analysis Software Architecture Developer Tools
2
Symvanta A
com.symvanta
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Code Analysis Developer Tools
271

Related MCP Servers

Axon.MCP.Server
Code Analysis Developer Tools Search
ali-kamali
F
license
Not graded
quality
D
maintenance
An MCP server that transforms codebases into intelligent, queryable knowledge bases, enabling AI assistants to perform semantic search, explore architecture, and analyze code relationships.
Updated 2 months ago (2026-06-30 01:32 UTC)
166
-
codeweave-mcp
Code Analysis Developer Tools RAG Systems
semihkayan
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI agents structured code understanding and precise code intelligence via local indexing of AST, call graphs, and semantic search.
Updated 4 months ago (2026-05-26 10:13 UTC)
81
4
Apache 2.0
Knowledge Master
Knowledge & Memory Developer Tools Code Analysis
subzone
A
license
A
quality
C
maintenance
A local knowledge graph MCP server that provides AI agents with permanent, structured memory about codebases, enabling semantic search, blast radius analysis, and convention enforcement.
Updated a month ago (2026-08-06 19:04 UTC)
8
2
MIT
codemap
Code Analysis Developer Tools
abdul-hamid-achik
A
license
Not graded
quality
A
maintenance
MCP server for local-first code intelligence, providing structural code graph, semantic search, and impact analysis to AI agents.
Updated 4 days ago (2026-09-08 05:24 UTC)
2
MIT