Eltortilla1/synapse-code-mcp

> A structural code context server that connects your local repository to AI assistants via the Model Context Protocol.
Instead of copy-pasting files into a prompt, Synapse lets your AI assistant dynamically explore your codebase — pulling only the code it needs, when it needs it. The result: less context waste, smarter answers, and a workflow that scales to large projects — with no vector database or embedding API to set up.
> **Status:** Early-stage, actively developed. Contributions and bug reports are welcome — see Contributing.
---
Why Synapse?
Most AI coding tools already index files. Synapse solves a different problem: **context quality at scale**.
| Problem | Synapse solution |
|---|---|
| Reading an entire file when you only need its API surface | get_semantic_context with outline_only — signatures only, ≤ 50% of full content |
| AI doesn't know what files exist in an unfamiliar project | get_project_index — full symbol map at ≤ 40% of raw source size, one call |
| "Review my changes" requires pasting the diff manually | get_changed_files — structured git diff, git-aware by default |
| Dependency rabbit holes filling the context window | Configurable depth cap on import traversal |
The compression ratios above are enforced as automated test budgets — not marketing estimates.
Why not vector embeddings?
Most code-context MCP servers use semantic search backed by a vector database (e.g. Milvus, Qdrant) and an embedding API (OpenAI, VoyageAI). That gives them a real capability Synapse doesn't have: finding code by conceptual meaning ("find the authentication logic") rather than by structure or text.
Synapse trades that capability for a different set of properties:
- **Zero external dependencies** — no API keys, no vector database, no embedding provider to configure
- **Zero recurring cost** — no per-token embedding charges, no hosted database bill
- **Fully local and deterministic** — the same input always produces the same output, nothing leaves your machine, nothing to index ahead of time
- **Instant on any repo** — no indexing step before first use (see Performance: 120–257 ms on real repos)
If you need natural-language semantic search across millions of lines in many languages, a vector-backed server is the better tool. If you want structural context (signatures, dependency graphs, diffs) without standing up infrastructure, Synapse is built for that.
---
Tools
get_project_index
Returns a compressed semantic map of the entire project: all exported functions, classes, interfaces, types, enums, and top-level constants with their signatures — no bodies. The right first call when exploring an unfamiliar codebase.
**Parameters:** file_pattern (glob to narrow scope), include_non_exported, output_format ("markdown" default · "json" for structured output)
Use output_format: "json" to get the raw symbol data as a structured object, which is easier to post-process programmatically:
> **Large projects:** output grows linearly with the number of exported symbols. For monorepos or projects with 500+ files, use file_pattern to scope the index to one area at a time — e.g. "src/services/**/*.ts".
---
get_semantic_context
Returns a file's content alongside its local dependency graph — everything the AI needs to understand the code in context.
Add outline_only: true to get signatures without implementation bodies. Output is enforced by the benchmark suite to be ≤ 50% of full content length, while preserving full structural understanding.
**Parameters:** file_path (required), depth (import hops, default: 2), outline_only, output_format ("markdown" default · "json" for structured output)
---
get_changed_files
Lists files changed since a git ref, grouped by status (Added / Modified / Deleted / Renamed), with optional line counts and full unified diff.