Synapse
About
Structural code context server for AI agents — zero vector database, zero embedding API, fully local.
Details
- Author
- eltortilla1
- Categories
- Other, Developer Tools
Jump to
Setup
Install Synapse in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/eltortilla1/synapse-code-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
A structural code context server that connects your local repository to AI assistants via theModel 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.
AI Assistant ──MCP──► Synapse MCP ──fs/git──► Your Repository (pulls) (server) (local)
Status:Early-stage, actively developed. Contributions and bug reports are welcome — seeContributing.
Most AI coding tools already index files. Synapse solves a different problem:context quality at scale.
The compression ratios above are enforced as automated test budgets — not marketing estimates.
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 (seePerformance: 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.
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.
# Project Index: my-app (47 files, 312 symbols) ## src/services/user-service.ts UserService (class) [export] constructor(db: Database) findById(id: string): Promise<User | null> create(data: CreateUserDto): Promise<User> ## src/models/user.ts User (interface) [export] id: string email: string createdAt: Date createUser(data: Partial<User>): User [export]
Parameters:file_pattern(glob to narrow scope),include_non_exported,output_format("markdown"default ·"json"for structured output)
Useoutput_format: "json"to get the raw symbol data as a structured object, which is easier to post-process programmatically:
{ "root": "/path/to/project", "totalFiles": 47, "totalSymbols": 312, "files": [ { "relativePath": "src/services/user-service.ts", "language": "typescript", "symbols": [...] } ] }
Large projects:output grows linearly with the number of exported symbols. For monorepos or projects with 500+ files, usefile_patternto scope the index to one area at a time — e.g."src/services//.ts".
Returns a file's content alongside its local dependency graph — everything the AI needs to understand the code in context.
Addoutline_only: trueto 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)
Lists files changed since a git ref, grouped by status (Added / Modified / Deleted / Renamed), with optional line counts and full unified diff.
Changed files since main (8 files): Added (2): src/services/payment.ts (+120 −0) tests/unit/payment.test.ts (+89 −0) Modified (5): src/models/order.ts (+14 −3) ... Summary: +245 −18 lines
Parameters:base_ref(default:HEAD~1),include_diff,file_pattern
Structured view of the repository, respecting.gitignorerules.
Parameters:path,max_depth,show_hidden
Fast text or regex search across the project, returning matches with file paths and line numbers. Usesripgrepwhen available, falls back to a pure Node.js scanner.
Parameters:query(required),file_pattern,is_regex,max_results
Dependency graph traversal (followingimport/requirechains) is TypeScript/JavaScript only. For all other languages, Synapse still reads and searches files normally — it just won't walk the import graph.
Note:dependency graph traversal follows bothrelativeimports (./foo,../bar) andpath aliasesconfigured viatsconfig.jsoncompilerOptions.paths(e.g.@/components/Foo), as long as atsconfig.jsonis present at the project root. Projects without atsconfig.jsonfall back to relative-only resolution.
npx synapse-code-mcp --root /path/to/your/project
Add to~/Library/Application Support/Claude/claude_desktop_config.json(macOS) or%APPDATA%\Claude\claude_desktop_config.json(Windows):
{ "mcpServers": { "synapse": { "command": "npx", "args": ["synapse-code-mcp", "--root", "/absolute/path/to/your/project"] } } }
claude mcp add synapse -- npx synapse-code-mcp --root /path/to/your/project
Or add directly to~/.claude/settings.json:
{ "mcpServers": { "synapse": { "command": "npx", "args": ["synapse-code-mcp", "--root", "/path/to/your/project"] } } }
Add to.cursor/mcp.jsonin your home directory or project root:
{ "mcpServers": { "synapse": { "command": "npx", "args": ["synapse-code-mcp", "--root", "/path/to/your/project"] } } }
Add to~/.codeium/windsurf/mcp_config.json:
{ "mcpServers": { "synapse": { "command": "npx", "args": ["synapse-code-mcp", "--root", "/path/to/your/project"] } } }
Tip:Replace/path/to/your/projectwith the absolute path to the repository you want to serve. You can run multiple Synapse instances — one per project — each with a different key undermcpServers.
Options: --root <path> Project root directory (default: cwd) --max-file-size <bytes> Skip files larger than this (default: 524288 = 512 KB) --max-search-results <n> Cap on search results returned (default: 50) --max-tree-depth <n> Maximum directory depth for tree view (default: 5) --max-dependency-depth <n> Import hops for semantic context (default: 2) --log-level <level> debug | info | warn | error (default: info)
Drop asynapse.config.jsonat your project root to override defaults for that project:
{ "maxFileSize": 1048576, "maxDependencyDepth": 3, "extraIgnorePatterns": [".generated.ts", "/__mocks__/"], "cacheEnabled": true }
cacheEnabled(defaulttrue) controls the on-disk incremental index cache (.synapse-cache/index.json) used byget_project_indexandget_semantic_contextto skip re-parsing unchanged files. Set tofalseto disable it.
All fields are optional. CLI flags take precedence oversynapse.config.json.
Measured on real open-source TypeScript repositories (single run,--depth 1clone, no warm cache):
The automated benchmark suite enforces upper bounds on a synthetic fixture (3 000 minimal.tsfiles) to catch regressions under worst-case conditions:
The CI budgets are deliberately generous safety margins, not performance estimates — they exist to catch catastrophic regressions (e.g. an accidental O(n²) bug), not to predict real-world timing. The real-repo numbers above are the meaningful reference for expected performance. For large monorepos (1 000+ files), usefile_patternto scope the index to one area at a time.
Synapse is aread-onlyserver. It never writes to the filesystem or modifies the git repository.
- Path traversal protection— every file read goes throughresolveAndValidate(root, path), which throws aPATH_ESCAPEerror if the resolved path escapes the project root. The AI client receives the error code, never the file contents.
- Root scoping— only the directory tree under--rootis accessible. Paths pointing outside (e.g.../../etc/passwd) are rejected at the validation layer.
- File size cap— files larger thanmaxFileSize(default 512 KB) are rejected before reading.
- Binary detection— compiled artifacts and binary files are detected and skipped automatically.
- No outbound network calls— Synapse communicates only over the local stdio pipe to the MCP client. It makes no HTTP requests.
1. get_project_index() → Understand the full shape of the project in one call 2. get_semantic_context("src/core/engine.ts", outline_only: true) → Inspect a module's API surface without reading implementation 3. get_semantic_context("src/core/engine.ts") → Read full source + dependency graph for the relevant file
1. get_changed_files(base_ref: "main") → See what changed, grouped and summarised 2. get_changed_files(base_ref: "main", include_diff: true) → Full unified diff in context 3. get_semantic_context("src/changed-file.ts") → Understand the context around a changed file
1. search_codebase("handlePayment") → Find where the symbol is defined and used 2. get_semantic_context("src/services/payment.ts", depth: 3) → Pull the file + all its local dependencies
- Node.js ≥ 18
- Git— required only forget_changed_files
- ripgrep*(optional)*— significantly faster search; Synapse falls back to a pure Node.js scanner ifrgis not on$PATH
git clone https://github.com/Juanmidev1/synapse-code-mcp.git cd synapse-code-mcp npm install npm run dev # watch mode (tsx, no compile step) npm test # run all tests (Vitest) npm run typecheck # type-check without emitting npm run lint # ESLint npm run build # compile to dist/
npm run build npx @modelcontextprotocol/inspector dist/index.js --root .
This opens a browser UI where you can invoke all tools interactively and inspect their input/output.
src/ index.ts CLI entry point, argument parsing server.ts MCP server, tool registration tools/ Thin tool handlers (validation + formatting only) core/ fs/ File tree building, file reading, ignore resolution search/ ripgrep adapter + pure-Node fallback analysis/ Dependency graph (ts-morph), outline extractor, project indexer, index cache git/ Git adapter (diff, changed files) config/ Config loading and Zod validation types/ Shared TypeScript interfaces utils/ Logger (pino), path helpers, typed errors tests/ unit/ Per-module unit tests integration/ Tool handler integration tests protocol/ End-to-end MCP protocol tests (InMemoryTransport) performance/ Benchmark suite with time and heap budgets build/ Tests against the compiled dist/ output (catches source-vs-build divergence)
SeeROADMAP.mdfor what is planned and what ideas are open for community contributions.
This project is in active early development. Bug reports, feature requests, and pull requests are all welcome — the codebase is intentionally small and straightforward to navigate.
- CONTRIBUTING.md— how to set up the environment, run tests, commit conventions, and architectural rules
- CODE_OF_CONDUCT.md— community standards (Contributor Covenant 2.1)
- ROADMAP.md— what is planned and what is open for community PRs
New to the project? Browse issues taggedgood first issuefor the best entry points.
AI code security scanner with 100 built-in rules covering OWASP Top 10 and CWE Top 25
AI-to-AI code review platform — Claude, Codex, and Gemini cross-check each other via MCP, REST API, and CLI for consensus-based results.
A stateful LSP runtime for AI agents: warm language server sessions with 50+ tools for go-to-definition, find-references, diagnostics, rename, and more across 30+ languages.
Persistent code index using Tree-sitter for fast, precise code search. Replaces grep with ~50 token responses instead of 2000+.
Orchestrates a dual-AI engineering loop where a Primary AI plans and implements, while a Review AI validates and reviews, with continuous feedback for optimal code quality. Supports custom AI pairing (Claude, Codex, Gemini, etc.)
AmazingMCP — MCP Server for .NET / C# Codebases
An MCP server that gives AI agents deep understanding of C# codebases via Roslyn — type search, dependency graphs, usage analysis, and architecture overviews, all from a live in-memory compilation.
ast-mcp-server gives coding agents compact, type-aware access to TypeScript and JavaScript projects. It uses the real compiler project model through ts-morph, so declarations, references, rename locations, and diagnostics come from the AST instead of text-search guesses.
A platform-agnostic code analysis library with semantic search capabilities and MCP server support.
Enforce consistent C++ style and best practices across your codebase. Analyze naming conventions, memory safety, and const correctness, and get actionable modernization suggestions up to C++23. Accelerate reviews with ready-made prompts and quick access to curated guidelines.
AI-Safe Code Analysis with 113+ MCP tools for guard validation, memory, workflow, and testing.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
