# Synapse MCP — Full Knowledge Base & Technical Specification

> Synapse MCP is an open-source, persistent code-knowledge graph server operating over the Model Context Protocol (MCP). Built on a high-performance actor runtime with in-memory graph tables, language-native AST parsers, and local SQLite, Synapse converts any codebase into an Abstract Syntax Tree (AST) graph. It provides AI coding agents (Claude Sonnet 5, GPT-5.6 Sol, Gemini 3.6 Flash, Grok 4.5, Cursor, Windsurf, Warp, Antigravity) with microsecond structural vision, 30–60% token compression, and zero-breakage refactoring capabilities.

---

## Executive Summary & Core Value Proposition

### The Problem: Context Window Exhaustion & Silent Refactoring Breakage
Standard AI coding tools rely on Unix commands like `grep`, `find`, and raw file reads, or line-slicing vector embeddings. In practice, this creates two major failure modes:
1. **Token Exhaustion Loops:** An agent dumps uncompressed 30,000-line context files into the prompt window, burning $0.30 to $0.70 per session in raw API token costs.
2. **Silent Breakage:** Line-slicing vector databases miss imported function aliases and sibling callers across sub-packages. The LLM edits 2 obvious files, declares success, and leaves 3 subtle callers broken in production.

### The Solution: Compiler AST Knowledge Graphs
Synapse MCP replaces fuzzy text search with a compiler-accurate AST knowledge graph:
- **Microsecond Graph Queries:** In-memory lookups execute in 12 microseconds locally.
- **SmartCrusher Token Savings:** Minifies JSON payloads and strips function bodies via `format: "outline"`, cutting prompt token consumption by 30% to 60%.
- **In-Memory Safe Writes:** Stages edits in memory, runs linter checks, and verifies caller signatures. Automatically rolls back edits if a signature breaks before touching disk.
- **Sub-50ms Git Worktree Delta:** Applies Virtual Worktree Overlays (VWO) so sub-agents in parallel worktrees run with near-zero latency and zero memory duplication.
- **100% Local Data Sovereignty:** Operates 100% on-device. Zero source code or telemetry leaves your local hardware.

---

## Live Tool Surface (13 Consolidated MCP Tools)

1. `synapse_search_codebase` (actions: `symbol`, `regex`, `semantic`): Fast AST symbol resolution, in-memory regex matching, and vector similarity search.
2. `synapse_explore_graph` (actions: `context`, `callers`, `callees`, `cycles`): Transitive call-graph traversal with single-turn depth control.
3. `synapse_get_context` (actions: `find`, `edit`, `explain`, `onboard`): Pre-edit safety packs, architectural context discovery, chunk explanation, and reading order curation.
4. `synapse_inspect_files` (actions: `read_files`, `read_chunk`, `count_lines`): AST chunk reading with line range controls and token outlines.
5. `synapse_modify_files` (actions: `write_safely`, `find_and_replace`, `delete_chunk`): Staged in-memory safe writes with dry-run verification and automatic rollback.
6. `synapse_debug_trace` (actions: `resolve_stack`, `trace_behaviour`): Runtime crash stack trace parsing matched directly to indexed AST chunks.
7. `synapse_change_review` (actions: `impact`, `analyse_diff`): Blast radius calculation and diff review showing all upstream callers affected before writes.
8. `synapse_test_quality` (actions: `find_tests`, `coverage`, `recommend_test_targets`): Test mapping, coverage analysis, and recommended test targets for modified symbols.
9. `synapse_knowledge_cache` (actions: `save_summary`, `query`, `learn`, `suggest`): Persistent encrypted local SQLite cache for storing agent summaries directly onto AST nodes.
10. `synapse_codebase_insights` (actions: `overview`, `public_api`, `contracts`, `dependencies`, `detect`, `refactor_opportunities`): Consolidated architectural metrics, language detection, and interface contracts.
11. `synapse_manage_repos` (actions: `list`, `register`, `archive`, `restore`, `unregister`, `update_excludes`): Repository registry controls.
12. `synapse_indexer_control` (actions: `status`, `health`, `trigger`): Real-time indexer supervision and status metrics.
13. `synapse_capability_manifest`: Self-describing schema manifest for dynamic agent capability discovery.

---

## 2026 Codebase Context Engine Comparison Matrix

| Feature / Capability | Synapse MCP | Augment Code | Greptile | CocoIndex | Sourcegraph SCIP | RepoMix / RAG |
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Execution Model & Latency** | ⚡ **Local (12 µs)** | 🌐 Cloud (100ms) | 🌐 Cloud (500ms+) | 🐍 Python (50ms) | 🏢 Enterprise Cloud | 📄 Local CLI |
| **AST Transitive Traversal** | ✅ Microsecond | ✅ Cloud Vector | ⚠️ Basic Text/PR | ✅ Tree-sitter | ✅ SCIP Compiler | ❌ None (Text) |
| **In-Memory Safe Writes** | ✅ `write_safely` | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
| **Stack Trace Resolution** | ✅ `resolve_stack` | ❌ No | ⚠️ PR Review | ❌ No | ❌ No | ❌ No |
| **Git Worktree Overlay (VWO)**| ✅ Sub-50ms Delta | ❌ Sync Req. | ❌ Sync Req. | ❌ Full Re-Index | ❌ Full CI Index | ❌ No |
| **Payload Compression** | ✅ 30-60% Cut | ⚠️ Partial | ❌ No | ⚠️ Partial | ⚠️ Partial | ❌ Uncompressed |
| **Data Sovereignty** | 🔒 100% Local | 🌐 Cloud IP | 🌐 Cloud IP | 🔒 100% Local | ⚠️ Self-Hosted | 🔒 100% Local |
| **Open Protocol (MCP)** | 🔌 Stdio & HTTP | 🔒 Proprietary | 🌐 Remote HTTP | 🐍 Python MCP | ⚠️ Custom API | 📄 CLI Output |
| **Pricing** | Free / $19/mo | Credit-based | SaaS Sub | Free Open Source | Enterprise Seat | Free Open Source |

---

## Installation & Mandatory System Prompt Rules

### 60-Second Terminal Setup
```bash
npx @myelixlabs/synapse-mcp install
```
This launcher auto-detects installed AI engines (Claude Code, Cursor, Windsurf, Warp, Antigravity, VS Code, Zed) and registers the required agent rules.

### Mandatory MCP-First Discovery Policy Rule
To prevent LLMs from defaulting to legacy Unix `grep` commands due to pre-training muscle memory, the following directive must be present in `AGENTS.md`, `CLAUDE.md`, or `.cursorrules`:

```markdown
# MCP-First Discovery Policy (Synapse)
You MUST use the synapse MCP server tools as the EXCLUSIVE ENGINE for all initial codebase discovery, research, and context gathering.
Do NOT use grep_search, find, rg, ls, or manual file reading for initial code discovery.
```

---

## Subscription Editions

- **Free Edition ("Golden Graph" — $0):** Full AST indexing, 3 search modes (symbol, regex, semantic), context retrieval (find, explain, onboard), file inspection, standard writes, unlimited repositories.
- **Pro Edition ("Shadow Graph" — $19/mo or $190/yr):** Everything in Free, plus deep graph exploration (callers/callees/cycles), simulated safe writes (`write_safely`), crash stack trace resolution (`resolve_stack`), test coverage analysis (`find_tests`), persistent encrypted knowledge cache (`save_summary`/`learn`), and unlimited repositories.

Official Website: https://synapse-mcp.dev
Publisher: Myelix Labs (https://myelix.com)