Synapse MCP server
Commit Nov 3, 2026Provides local-first AST code context for AI agents through symbol navigation, source references, and repository indexing without uploading code.
Also known as Locker-Room-Tools/synapse
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 3, 2026
- License
- MIT
What is Synapse MCP?
Synapse provides local-first AST code context for AI agents through symbol navigation, source references, and repository indexing without uploading code.
Summary generated from the project's README
About Synapse MCP server
Providing local-first AST code context to AI agents is what Synapse enables for developers who need to maintain privacy. It allows agents to navigate symbols, view source references, and index repositories without uploading any source code to external services. This tool works locally by using a polling daemon to watch for changes and build a local index, ensuring that the context provided to the agent is always current.
Developers can connect Synapse to a wide variety of agents including Claude Code, Cursor, Windsurf, Zed, and Copilot. Setup is handled via a CLI that installs the necessary MCP entry and managed skills. The system uses a local grammar cache for parsing, meaning it never downloads parsers implicitly during the indexing process. Users can manage what files are processed using a layered ignore system that supports gitignore syntax, allowing for fine-grained control over the repository scope.
Synapse offers different tool profiles depending on needs. The default profile provides synapse_orient for ranked matches of repository terms and synapse_inspect for batch inspection of symbol definitions and call hierarchies. A full profile expands these capabilities to include project maps, dependency navigation, and structural context tools.
What you can do with it
- 1Navigate repository symbolsAn AI agent can find specific code definitions and their callers using ranked matches for repository terms.
- 2Inspect code hierarchiesA developer can request a snapshot of a symbol's definition, its bounded source, and its relationship to other callers and callees.
- 3Maintain code privacyTeams can provide deep structural context to AI agents without the risk of uploading their proprietary source code to external services.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelocker-room-tools/synapse is public and reachablegithub.com/locker-room-tools/synapse ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-03github.com/locker-room-tools/synapse ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubQuickstart
- Use Python >=3.12.
- Install Synapse as a managed CLI tool:
uv tool install locker-room-tools-synapse-mcp. - Connect it globally to your agent:
synapse install codex - Restart the agent once.
Replace codex with amp, antigravity, claude-code, cline, continue, copilot,
copilot-vscode, crush, cursor, droid, gemini, goose, hermes, kimi, kiro,
opencode, openclaw, qwen, roo, windsurf, or zed. No repository files are created. The
first synapse_orient or synapse_inspect call initializes the local index and daemon
automatically.
See Installation and lifecycle for upgrades, custom scopes, troubleshooting, and uninstall instructions. See MCP tools for tool contracts and recommended agent flows.
Development
Create a virtual environment and install the repository with development dependencies:
uv venv && uv pip install -e ".[dev]". Then run synapse grammars install once.
Grammar installation is an explicit network operation. Indexing, watching, querying, and MCP serving only use the local grammar cache and never download parsers implicitly.
Available MCP tools
Synapse exposes 19 deterministic MCP tools. The default profile is exactly two:
synapse_orient (ranked, production-first matches for literal repository terms, with
compact symbol handles) and synapse_inspect (one-snapshot batch inspection of selected
symbols: definitions, bounded source, call-proven callers/callees plus neutral incoming
and outgoing references, all with stored resolution, confidence, and usage kind). Both
initialize and refresh the workspace automatically. The full
profile adds initialization, symbol lookup, definitions, references, structural context,
dependency navigation, project maps, indexing, daemon-health, and
configuration/ignore-management tools. The complete
parameter and response reference is in docs/tools.md.
Configuration
Ignore rules come from three layers, applied in order — the last matching rule wins, so a later layer can re-include what an earlier one ignored:
| Layer | Location | Written by |
|---|---|---|
| built-in defaults | packaged with Synapse | negate a rule to turn it off |
| global | ~/.config/synapse/ignore |
synapse ignore add ... --scope global |
| project | <workspace>/.synapseignore |
synapse ignore ..., or agents over MCP |
.synapseignore uses gitignore syntax — bare names (node_modules), directory-only rules
(build/), root anchoring (/dist), globs (*.min.js, docs/**), # comments, and !
negation. Absolute paths and .. segments are rejected. .git is always ignored.
synapse ignore init --node --dotnet
init seeds the file from ecosystem templates; run synapse ignore presets to see all 14 and
which ones your workspace matches. With no flags it detects them from marker files. Synapse also
creates the file automatically the first time it initializes a recognizable workspace — it never
touches an existing one, and you can opt out with SYNAPSE_NO_IGNORE_BOOTSTRAP=1 or
"auto_ignore_bootstrap": false in .synapse/config.json.
.synapseignore is a plain, flat file with no managed sections. It is meant to be committed
so the whole team indexes the same tree; Synapse only ever appends to it or removes an exact line.
synapse ignore list prints every effective rule in order with its layer, file, and line.
Removing a rule that comes from a lower layer appends a negation rather than failing.
Earlier versions kept an ignored_directories list in config.json. That still works, but an
ignore file supersedes it, and the first write migrates the entries across; synapse ignore migrate does it explicitly. watch.* settings stay in config.json and are unaffected.
A change needs no reindex: the next watch sweep purges newly-ignored files and picks up restored ones.
Watch daemon
Synapse requires a healthy dependency-free polling daemon before query tools can read an
index. The navigation tools (or synapse_ensure_workspace on the full profile) start or
repair it lazily, and the MCP entry point restores
it for initialized workspaces after a reboot. Logs are written under the workspace data
directory at logs/watch.log, and status is written to watch.json in the same data directory.
A running daemon is not by itself enough to answer a question. Before serving evidence the navigation tools also check that the index exists, the parsers are installed, and the stored relations were produced by the current extraction semantics — a Synapse upgrade therefore triggers one automatic rebuild rather than silently reusing stale relations.
Use synapse watch status --workspace . --json to inspect running, backend, pending, PID,
timestamps, errors, and staleness_seconds. Stop a detached daemon with
synapse watch stop --workspace .. For a bounded smoke check that performs one reconciliation
sweep and exits, run synapse watch start --workspace . --foreground --once.
The shipped backend is currently polling-only. Its interval defaults to the user config
watch.poll_interval_s; native OS event watching is intentionally deferred behind the core
WatchBackend protocol.
Agent setup helpers
synapse install <agent> [--dry-run] [--offline] [--no-skill] [--no-hook] [--force]— writes the MCP entry, instructions, the managed skill, and (on agents that support context-injecting hooks: Claude Code, Qwen, Crush) a suggest-only pre-shell hook; see the support matrix and Hookssynapse init --path <path> [--dry-run] [--offline]synapse status --path <path> [--json]synapse uninstall <agent> --global [--keep-skill] [--keep-hook] [--keep-instructions] [--keep-config] [--dry-run]— removes the MCP entry, managed skill, and hook; index/cache data is untouchedsynapse setup <agent> --path <path>for advanced project-scoped integrationsynapse mcp install <agent> --workspace <path> [--scope project|user] [--print]synapse uninstall <agent> --path <path> [--scope project|user]synapse doctor --path <path> [--agent <agent>] [--scope project|user]
Project setup, mcp install, manual indexing, serve, and foreground watch mode remain
available for advanced integration and diagnostics.
Read docs/architecture.md before changing the project structure.
Synapse MCP questions
Does Synapse upload my source code to external services?
No, it provides local-first AST code context for AI agents without uploading source code to external services.
Which AI agents are supported by Synapse?
Synapse supports a wide range of agents including Claude Code, Cursor, Windsurf, Zed, Copilot, Gemini, and many others.
How does Synapse handle file ignoring?
It uses a three-layer system (built-in, global, and project) where the last matching rule wins, utilizing gitignore syntax in .synapseignore files.
Does Synapse download parsers automatically?
No, grammar installation is an explicit network operation; indexing and serving only use the local grammar cache.