Synapse MCP Server

Structural code context server for AI agents — zero vector database, zero embedding API, fully local.

Documentation

Synapse 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.

AI Assistant  ──MCP──►  Synapse MCP  ──fs/git──►  Your Repository
   (pulls)               (server)                   (local)

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, and types 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

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

`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.

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

`get_project_tree`

Structured view of the repository, respecting .gitignore rules.

Parameters: path, max_depth, show_hidden

`search_codebase`

Fast text or regex search across the project, returning matches with file paths and line numbers. Uses ripgrep when available, falls back to a pure Node.js scanner.

Parameters: query (required), file_pattern, is_regex, max_results

Language support

Synapse uses ts-morph (TypeScript compiler API) for deep analysis of TypeScript and JavaScript. For other languages, it applies regex-based extraction of function and class names.

Feature	TypeScript / JS	Python · Go · Rust	Other
`get_project_tree`	✓	✓	✓
`search_codebase`	✓	✓	✓
`get_semantic_context` — full source	✓	✓	✓
`get_semantic_context` — dependency graph	✓	—	—
`get_semantic_context outline_only`	✓ full signatures	✓ names only	—
`get_project_index`	✓ full signatures	✓ names only	—

Dependency graph traversal (following import/require chains) is TypeScript/JavaScript only. For all other languages, Synapse still reads and searches files normally — it just won't walk the import graph.

Limitation: dependency graph traversal only follows relative imports (./foo, ../bar). Path aliases configured via tsconfig.json paths (e.g. @/components/Foo) are not resolved and will be silently skipped — the dependency graph will be incomplete for projects that rely heavily on aliased imports. Support for resolving aliases is tracked in the roadmap.

Installation

Global install (recommended):

npm install -g synapse-code-mcp

Run without installing:

npx synapse-code-mcp --root /path/to/your/project

Setup

Claude Desktop

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 Code (CLI)

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"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your home directory or project root:

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["synapse-code-mcp", "--root", "/path/to/your/project"]
    }
  }
}

Windsurf

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/project with the absolute path to the repository you want to serve. You can run multiple Synapse instances — one per project — each with a different key under mcpServers.

Configuration

CLI flags

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)

Per-project config file

Drop a synapse.config.json at your project root to override defaults for that project:

{
  "maxFileSize": 1048576,
  "maxDependencyDepth": 3,
  "extraIgnorePatterns": ["*.generated.ts", "**/__mocks__/**"]
}

All fields are optional. CLI flags take precedence over synapse.config.json.

Performance

Measured on real open-source TypeScript repositories (single run, --depth 1 clone, no warm cache):

Repository	Files indexed	Time	Heap growth
zod	55	120 ms	3 MB
TypeScript compiler `src/`	247	257 ms	24 MB

The automated benchmark suite enforces upper bounds on a synthetic fixture (3 000 minimal .ts files) to catch regressions under worst-case conditions:

Operation	CI budget (synthetic fixture)
`get_project_tree` — 3 000 files	5 s
`get_semantic_context` — depth 3	10 s
`get_changed_files`	2 s
`get_project_index` — 60 files	30 s
`get_project_index` — 600 files	120 s

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), use file_pattern to scope the index to one area at a time.

Security

Synapse is a read-only server. It never writes to the filesystem or modifies the git repository.

Path traversal protection — every file read goes through resolveAndValidate(root, path), which throws a PATH_ESCAPE error 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 --root is accessible. Paths pointing outside (e.g. ../../etc/passwd) are rejected at the validation layer.
File size cap — files larger than maxFileSize (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.

Suggested workflows

Explore a new codebase:

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

Code review before a PR:

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

Debug a feature:

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

Requirements

Node.js ≥ 18
Git — required only for get_changed_files
ripgrep (optional) — significantly faster search; Synapse falls back to a pure Node.js scanner if rg is not on $PATH

Development

git clone https://github.com/Eltortilla1/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/

Test with MCP Inspector

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.

Project structure

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
    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

Roadmap

See ROADMAP.md for what is planned and what ideas are open for community contributions.

Contributing

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 tagged good first issue for the best entry points.

License

MIT