Synapps

Give your AI agent a deep understanding of your codebase — not just files and symbols, but the relationships between them.

Synapps is an MCP server and CLI that builds a queryable graph of your codebase using Language Server Protocol analysis. It indexes symbols, call chains, inheritance trees, interface implementations, and type dependencies across C#, Python, TypeScript/JavaScript, and Java projects — then lets AI agents (or humans) query that graph to make safer, faster, better-informed code changes.

Why Synapps

AI agents working with code today rely on grep and file reads. That works for simple lookups, but falls apart when the question is "what happens if I change this?" — when the answer depends on call chains, interface dispatch, inheritance, and test coverage spanning dozens of files.

Synapps gives your agent a compiler-grade understanding of how code connects, without reading every file.

Quick Start

pip install synapps-mcp
synapps init

synapps init walks you through setup:

1. Detects languages in your project (C#, Python, TypeScript, Java)

2. Checks prerequisites — Docker, Memgraph, and language servers for detected languages only

3. Shows fix commands for anything missing (platform-specific: brew on macOS, apt on Linux)

4. Indexes your project — builds the code graph automatically

5. Configures your MCP client — detects Claude Desktop, Claude Code, Cursor, or Copilot and offers to write the config

6. Installs pre-tool hooks — optional advisory hooks that remind agents to use graph tools before falling back to grep/file search (Claude Code, Cursor, GitHub Copilot)

After init completes, your AI agent can use Synapps tools immediately.

For development from source: pip install -e .

Prerequisites

• Python 3.11+

• Docker — Synapps auto-manages Memgraph containers. Not required when connecting to an external Memgraph instance.

• Language servers (only for languages in your project):

  • C#: .NET SDK (Roslyn Language Server is auto-downloaded on first index)

  • Python: Pyright (npm install -g pyright)

  • TypeScript/JavaScript: npm install -g typescript-language-server typescript

  • Java: Eclipse JDTLS (auto-managed)

Run synapps doctor to check your environment.

Manual MCP Configuration

synapps init handles this automatically. To configure manually:

Claude Desktop / Claude Code / Cursor:

{
  "mcpServers": {
    "synapps": {
      "command": "synapps-mcp"
    }
  }
}

Config file locations: Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json), Cursor (~/.cursor/mcp.json).

VS Code / GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "synapps": {
      "command": "synapps-mcp"
    }
  }
}

Features

Deep Call Graph

Synapps uses a two-phase indexing approach: LSP extracts structural symbols (classes, methods, properties), then tree-sitter finds call sites and LSP resolves what each call points to. The result is a graph of CALLS edges between methods — not string matches, but semantically resolved references.

This means your agent can follow a method call through 6 levels of indirection and know exactly what code is reachable, without reading a single file.

Tools: find_usages, find_callees (with depth for call trees), find_entry_points

Interface Dispatch Resolution

In dependency-injected codebases, service.Process() could mean any of 5 concrete implementations. Grep finds the interface method. Synapps finds the interface method and every concrete implementation, automatically.

Tools: find_usages, find_implementations

Impact Analysis

Before your agent changes a method, it should know: how many places call it, whether tests cover it, and what it depends on. analyze_change_impact answers all three in a single, token-efficient response — categorized into direct callers, transitive callers, test coverage, and downstream callees.

Tools: get_context_for (with scope="impact"), find_usages (with include_test_breakdown), get_context_for (with scope="edit")

Scoped Context

get_context_for is the recommended starting point for understanding any symbol. Instead of reading entire files, your agent gets exactly the context it needs:

• structure — type overview with member signatures (no method bodies)

• method — source code + interface contract + callees + dependencies

• edit — callers with line numbers, relevant dependencies, test coverage

• impact — blast radius analysis: direct callers, transitive callers, test coverage, callees

Tools: get_context_for

Automatic Graph Sync

The graph stays fresh without manual intervention. When auto_sync is enabled (the default), every tool call checks whether the codebase has changed and re-indexes only the changed files. For longer sessions, watch_project keeps the graph updated in real-time.

Tools: sync_project, list_projects (with path for index status)

HTTP Endpoint Tracing

Synapps traces HTTP dependencies across language boundaries by detecting server-side endpoint definitions and client-side HTTP calls, matching them by route pattern.

Tools: find_http_endpoints (use trace=True for the full dependency picture)

Known limitations: Dynamic URL construction (runtime string concatenation, builder patterns) and API gateway/middleware route rewrites cannot be resolved by static analysis.

Token-Efficient Output

Outputs use shortened symbol references, relative file paths, and compact Markdown summaries instead of raw JSON — reducing token consumption while preserving all information an agent needs.

Multi-Language Support

C#, Python, TypeScript/JavaScript, and Java projects all use the same tools, graph schema, and query patterns. Language detection is automatic based on file extensions, or can be specified explicitly with --language.

Webviewer

Synapps includes a built-in web UI that exposes the same tools available to AI agents via MCP — so you can see exactly what your agent sees. The webviewer provides interactive access to all query tools, plus a force-directed graph visualization for exploring symbol neighborhoods.

Capabilities:

• Search — find symbols by name across your indexed projects

• Navigate — trace usages, callees, hierarchy, and scoped context directly from the UI

• Analyze — view architecture overviews, dead code, and untested methods

• Explore — visualize symbol neighborhoods as an interactive graph with configurable depth, physics simulation, and layout controls

• Query — run raw Cypher queries and browse HTTP endpoints

The webviewer is useful for getting a visual overview of how code connects — particularly when onboarding to a new codebase or investigating complex call chains.

CLI Reference

synapps <command> [args]

Setup

Project Management

Graph Queries

Summaries

Attach non-derivable context to symbols — design rationale, constraints, ownership, deprecation plans. Don't use these for structural descriptions; that information is queryable live via get_context_for, find_dependencies, etc.

MCP Tools

19 tools available to any MCP client connected to synapps-mcp, organized into 9 categories.

Project Management

Symbol Discovery

Call Graph

Context & Impact Analysis

Code Intelligence

HTTP Endpoints

Architecture

Code Quality

Summaries

Raw Queries

Container Management

Synapps uses Memgraph as its graph database, managed via Docker. By default, all projects share a single container for simplicity.

In shared mode, each project's data is scoped by its Repository node in the graph — indexing project A has no effect on project B.

Dedicated containers

Add "dedicated_instance": true to the project's .synapps/config.json:

{
  "dedicated_instance": true
}

Synapps provisions a per-project container (synapps-<project-name>) on a dynamically allocated port.

External Memgraph

Set the connection in ~/.synapps/config.json:

{
  "external_host": "memgraph.example.com",
  "external_port": 7687
}

Docker is not required in external mode.

Managing containers

docker ps --filter "name=synapps-"     # List Synapps containers
docker stop synapps-shared              # Stop the shared container

Containers persist across sessions and are automatically restarted on the next command if stopped.

Global config lives at ~/.synapps/config.json. Per-project config (.synapps/config.json) is only created when using dedicated containers. Add .synapps/ to your .gitignore.

Graph Model

Node Labels

Structural (identified by path): :Repository, :Directory, :File

Symbols (identified by full_name): :Package, :Class (classes, abstract classes, enums, records — distinguished by kind), :Interface, :Method (signature, is_abstract, is_static, line), :Property (type_name), :Field (type_name), :Endpoint (route, http_method, name)

A :Summarized label is added to any node with an attached summary.

Relationships

Fully-qualified names (e.g. MyNamespace.MyClass.DoWork) are used as symbol identifiers throughout.

Ignoring Files

Place a .synignore file in your project root to exclude paths from indexing (.gitignore syntax):

worktrees/
generated/
vendor/
*.generated.cs
**/test_data/**

Without .synignore, Synapps uses built-in exclusions (.git, node_modules, __pycache__, dist, build, etc.).

Pre-Tool Hooks

Synapps can install advisory pre-tool hooks that remind AI agents to use graph tools before falling back to grep and file search. Hooks are non-blocking — they emit a reminder to stderr but never prevent the tool call.

Hooks are installed during synapps init for any detected agents. They are index-aware: the reminder only appears when the current project has a .synapps/config.json (i.e., has been indexed).

Supported Agents

How It Works

Gate scripts are installed at ~/.synapps/hooks/:

• common.sh — shared helper: walks from $PWD upward looking for .synapps/config.json; emits a reminder to stderr if found

• claude-gate.sh / cursor-gate.sh — source common.sh, check for index, emit reminder, exit 0

• copilot-gate.sh — same, but also reads toolName from stdin JSON to filter for search-related tools, and emits {"permissionDecision":"allow"} on stdout (required by Copilot protocol)

Manual Hook Removal

To remove hooks, delete ~/.synapps/hooks/ and remove the Synapps entries from each agent's config file. Synapps entries are identifiable by script paths containing ~/.synapps/hooks/.

AI Agent Configuration

Synapps automatically provides usage instructions to MCP-compliant clients via the protocol — most agents make good tool choices out of the box.

The snippet below is an optional addition for your AI platform's rules file. It reinforces tool selection patterns and adds guidance beyond what the MCP protocol delivers.

## Synapps MCP

Use Synapps MCP tools for code navigation instead of grep or file reads.

### Workflow
- Projects must be indexed before querying. Use `list_projects` to check, `index_project` to index, `sync_project` to refresh.
- If queries return empty results, use `list_projects(path=...)` to verify the project is indexed.

### Before editing code
- Call `get_context_for` with `scope="edit"` to see callers, dependencies, and test coverage.

### Tool selection
- Find symbols: `search_symbols` (with kind/namespace/file_path/language filters)
- Symbol metadata and source code: `get_context_for` (scopes: `structure`, `method`, `edit`, `impact`)
- Callers / all usages: `find_usages` (auto-selects by kind; `include_test_breakdown` for prod/test split)
- Callees: `find_callees` (use `depth` for call tree)
- Entry points: `find_entry_points`
- Implementations: `find_implementations` | Inheritance: `get_hierarchy`
- Dependencies: `find_dependencies` (use `depth` for transitive)
- Impact analysis: `get_context_for` with `scope="impact"`
- Architecture overview: `get_architecture` (packages, hotspots, HTTP map, stats in one call)
- Dead code *(experimental)*: `find_dead_code` (methods with zero callers, use `exclude_pattern` for additional filtering)
- Test coverage *(experimental)*: `find_tests_for` (which tests cover a method) and `find_untested` (methods with no test coverage)
- HTTP endpoints: `find_http_endpoints` (use `trace=True` for full dependency picture)
- Annotations: `summary` (set/get/list) for non-derivable context
- Raw Cypher: `get_schema` then `execute_query` (last resort)

### Anti-patterns
- Don't guess symbol names — use `search_symbols`
- Don't use `execute_query` when a dedicated tool exists
- Don't read files with grep when `get_context_for` works
- Don't skip `get_context_for` with `scope="edit"` before modifying a method

Where to add it:

For Cursor's .mdc format, wrap the content in frontmatter with description and globs fields. For VS Code/Copilot, the MCP server config (.vscode/mcp.json) is separate from the rules file.

Development

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Unit tests (no Docker, Memgraph, or .NET required)
pytest tests/unit/

# Integration tests (requires Docker + Memgraph on localhost:7687)
docker compose up -d
pytest tests/integration/ -m integration