{
  "markdown": "<div align=\"center\">\n\n# 🧠 Codebase Synapse\n\n**Give your AI agent a deep understanding of your entire codebase.**\n\nAn 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.\n\n<br/>\n\n<img src=\"docs/assets/hero-banner.png\" alt=\"Codebase Synapse — Knowledge graph visualization\" width=\"700\"/>\n\n<br/>\n\nWorks with **Claude Code** · **Cursor** · **Windsurf** · **Zed** · **Any MCP client**\n\n[![CI](https://github.com/iwiels/codebase-synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/iwiels/codebase-synapse/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/codebase-synapse.svg?style=flat-square)](https://www.npmjs.com/package/codebase-synapse)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg?style=flat-square)](LICENSE)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-8A2BE2?style=flat-square)](https://registry.modelcontextprotocol.io)\n\n</div>\n\n---\n\n## The Problem\n\nAI 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**.\n\n**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.\n\n<div align=\"center\">\n<img src=\"docs/assets/demo-terminal.png\" alt=\"Codebase Synapse demo — indexing and impact analysis\" width=\"650\"/>\n</div>\n\n### How it works\n\n```mermaid\ngraph LR\n    A[\"📁 Your Codebase\"] -->|Tree-sitter| B[\"🧩 Parser\"]\n    B -->|Symbols & Edges| C[\"🕸️ Knowledge Graph\"]\n    C -->|SQLite| D[\"💾 Local DB\"]\n    D -->|52 MCP Tools| E[\"🤖 AI Agent\"]\n    \n    style A fill:#1a1b26,stroke:#7aa2f7,color:#c0caf5\n    style B fill:#1a1b26,stroke:#bb9af7,color:#c0caf5\n    style C fill:#1a1b26,stroke:#9ece6a,color:#c0caf5\n    style D fill:#1a1b26,stroke:#e0af68,color:#c0caf5\n    style E fill:#1a1b26,stroke:#f7768e,color:#c0caf5\n```\n\n## ⚡ Quick Start\n\n### 1. Index your project (CLI, Zoekt-style)\n\n```bash\ncodebase-synapse index /path/to/your/repo\n```\n\nIndexing 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.\n\n### 2. Start the MCP server\n\n```bash\nnpx codebase-synapse\n```\n\nThat's it. No Docker. No database setup. No cloud. The server starts via stdio and serves the pre-built index to your MCP client.\n\n### Configure your client\n\n<details>\n<summary><b>Claude Code / Claude Desktop</b></summary>\n\nAdd to your `claude_desktop_config.json` or `mcp_servers.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"codebase-synapse\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"codebase-synapse\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Cursor</b></summary>\n\nAdd to your `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"codebase-synapse\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"codebase-synapse\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Other MCP clients</b></summary>\n\nAny MCP client that supports **stdio** transport works. Just point it at:\n\n```bash\nnpx -y codebase-synapse\n```\n\n</details>\n\n## ✨ What It Does\n\n### 🔍 Search & Discovery\n| Tool | Description |\n|:-----|:------------|\n| `semantic_search` | Vector similarity search using local embeddings (all-MiniLM-L6-v2) |\n| `search_code` | Full-text search across code (FTS5 + BM25 ranking) |\n| `search_symbol` | Find functions, classes, types by name or pattern |\n| `hybrid_search` | Combined semantic + lexical search with RRF fusion |\n| `find_similar` | Find structurally similar code using MinHash + LSH |\n| `find_symbol_everywhere` | Locate a symbol across all indexed projects |\n\n### 🕸️ Knowledge Graph\n| Tool | Description |\n|:-----|:------------|\n| `get_callers` / `get_callees` | Navigate the call graph in either direction |\n| `get_imports` / `get_dependents` | Trace dependency chains |\n| `impact_analysis` | Compute blast radius before editing a file |\n| `find_path` | Find the shortest connection between two symbols |\n| `find_dead_code` | Detect unreachable functions and unused exports |\n| `get_pagerank` | Identify the most critical nodes in your architecture |\n| `query_graph` | Run Cypher-like queries against the knowledge graph |\n\n### 🏗️ Architecture\n| Tool | Description |\n|:-----|:------------|\n| `get_architecture` | Full project architecture overview (languages, entry points, hotspots) |\n| `get_file_structure` | Directory tree with symbol annotations |\n| `project_overview` | High-level summary with key metrics |\n| `get_route_map` | Extract HTTP routes and their handler mappings |\n| `suggest_boundaries` | Detect module boundaries via Leiden clustering |\n| `check_boundaries` | Validate cross-module dependencies against defined boundaries |\n| `get_clusters` | Community detection across the codebase |\n\n### 🔬 Git Archaeology\n| Tool | Description |\n|:-----|:------------|\n| `git_archaeology` | Deep history analysis of a file (authors, churn, evolution) |\n| `get_hotspots` | Files with highest complexity × change frequency |\n| `detect_change_coupling` | Files that always change together |\n| `get_recent_semantic_changes` | Semantically meaningful recent changes |\n| `index_git_history` | Build temporal analysis from git log |\n\n### 🧠 Memory & Context\n| Tool | Description |\n|:-----|:------------|\n| `memory_store` / `memory_search` / `memory_list` | Persistent notes, facts, and decisions across sessions |\n| `session_remember` / `session_recall` | Short-term memory within a session |\n| `get_context` | Budgeted context preparation for AI agents |\n| `get_edit_context` | Focused context for a specific file edit |\n| `get_working_set` | Recently accessed and modified files |\n| `manage_adr` | Architecture Decision Records management |\n\n### 🛡️ Codebase Guard\n\nIncluded 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.\n\nIt uses PageRank scores and blast-radius data from the knowledge graph to identify architectural hubs. No more accidental edits to core files.\n\n## 🔧 Technical Details\n\n| | |\n|:--|:--|\n| **Language** | Rust (compiled native binary) |\n| **Transport** | MCP stdio (JSON-RPC) |\n| **Storage** | SQLite (WAL mode, zero config) |\n| **Embeddings** | all-MiniLM-L6-v2 via Candle (offline, local, lazy-loaded) |\n| **Parsing** | Tree-sitter (10 languages) |\n| **Distribution** | npm with prebuilt binaries (Windows, macOS, Linux × x64, arm64) |\n\n### Supported Languages\n\nRust · Python · TypeScript · JavaScript · Go · Java · C# · PHP · C · C++\n\n### Architecture\n\n```\nsrc/\n├── parser/       # Tree-sitter parsing & entity extraction\n├── graph/        # Knowledge graph, PageRank, Leiden clustering\n├── indexer/      # Repository indexing pipeline\n├── search/       # BM25 full-text + vector cosine + hybrid RRF\n├── embedding/    # Candle-based local embeddings (feature-gated)\n├── memory/       # Persistent & session memory stores\n├── mcp/          # MCP protocol transport + 52 tool handlers\n├── git/          # Git archaeology, intent classification, hotspots\n├── context/      # Budgeted context preparation for AI\n├── cypher/       # Nom-based Cypher parser → SQL CTE planner\n├── similarity/   # MinHash + LSH structural similarity\n├── semantic/     # Multi-signal scoring (tokens, directory, AST)\n└── cli/          # Interactive TUI installer + artifact export/import\n```\n\n## 🤝 Contributing\n\nContributions are welcome! The project uses standard Rust tooling:\n\n```bash\n# Run tests\ncargo test\n\n# Lint\ncargo clippy -- -D warnings\n\n# Format\ncargo fmt --all\n```\n\n## 📄 License\n\n[Apache-2.0](LICENSE)\n",
  "bytes": 7924,
  "sha": "dfaff81698bb570b07993d7cb9a78e9d661fe627eb124b541fbbef6ffc7cc39a",
  "repo_slug": "iwiels/codebase-synapse",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_iwiels_codebase_synapse_cc567934/readme"
}