代码理解工具

Synaps

让你的AI代理深入了解你的代码库——不仅仅是文件和符号，还有它们之间的关系。

Synapps是一个MCP服务器和CLI，它使用语言服务器协议分析构建代码库的可查询图。它对符号、调用链、继承树、接口实现和C#、Python、TypeScript/JavaScript和Java项目的类型依赖关系进行索引，然后让AI代理（或人类）查询该图，以进行更安全、更快、更明智的代码更改。

为什么选择Synaps

如今，处理代码的AI代理依赖于grep和文件读取。这适用于简单的查找，但当问题出现时就会崩溃 “如果我改变这个，会发生什么？” --当答案取决于调用链、接口调度、继承和跨越数十个文件的测试覆盖率时。

Synapps让你的代理在不读取每个文件的情况下，对代码如何连接有编译器级的理解。

快速开始

pip install synapps-mcp
synapps init

synapps init 引导您完成设置：

1. 检测语言 在你的项目中（C#、Python、TypeScript、Java）
2. 检查先决条件 --Docker、Memgraph和仅用于检测到的语言的语言服务器
3. 显示修复命令 对于任何缺失的内容（特定于平台： brew 在macOS上， apt 在Linux上）
4. 为您的项目建立索引 --自动构建代码图
5. 配置您的MCP客户端 --检测Claude Desktop、Claude Code、Cursor或Copilot，并提供编写配置
6. 安装预工具挂钩 --可选的咨询挂钩，提醒代理在返回grep/文件搜索之前使用图形工具（Claude Code、Cursor、GitHub Copilot）

init完成后，您的AI代理可以立即使用Synapps工具。

从源代码开发： pip install -e .

先决条件

• Python 3.11+
• 码头工人 --Synapps自动管理Memgraph容器。连接到外部Memgraph实例时不需要。
• 语言服务器 （仅适用于项目中的语言）：
  • CNET SDK（Roslyn语言服务器在第一个索引上自动下载）
  • Python：Pyright(npm install -g pyright)
  • Types/JavaScript： npm install -g typescript-language-server typescript
  • Java：Eclipse JDTLS（自动管理）

跑 synapps doctor 检查你的环境。

手动MCP配置

synapps init 自动处理此问题。要手动配置，请执行以下操作：

克劳德桌面 / 克劳德代码 / 光标:

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

配置文件位置：Claude Desktop(claude_desktop_config.json)克劳德代码(.mcp.json)，光标(~/.cursor/mcp.json).

VS代码/GitHub副本 (.vscode/mcp.json):

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

特性

深度调用图

Synapps使用两阶段索引方法：LSP提取结构符号（类、方法、属性），然后树保姆找到调用点，LSP解析每个调用指向的内容。结果是方法之间的CALLS边图——不是字符串匹配，而是语义解析的引用。

这意味着您的代理可以通过6个间接级别跟踪方法调用，并准确知道可以访问哪些代码，而无需读取单个文件。

工具： find_usages, find_callees （与 depth 用于呼叫树）， find_entry_points

接口调度解决方案

在依赖注入的代码库中， service.Process() 可以指5个具体实现中的任何一个。Grep找到了接口方法。Synapps找到接口方法 和 每一个具体的实现都是自动的。

工具： find_usages, find_implementations

影响分析

在您的代理更改方法之前，它应该知道：有多少地方调用它，测试是否覆盖它，以及它依赖于什么。 analyze_change_impact 在一个单一的、令牌高效的响应中回答所有三个问题，分为直接调用者、传递调用者、测试覆盖率和下游调用者。

工具： get_context_for （与 scope="impact"), find_usages （与 include_test_breakdown), get_context_for （与 scope="edit")

范围上下文

get_context_for 是理解任何符号的推荐起点。您的代理不会读取整个文件，而是获得它所需的上下文：

• structure --带成员签名的类型概述（无方法体）
• method --源代码+接口契约+被调用者+依赖关系
• edit --具有线路号、相关依赖关系、测试覆盖率的呼叫者
• impact --爆炸半径分析：直接呼叫者、传递呼叫者、测试覆盖率、被呼叫者

工具： get_context_for

自动图形同步

图表保持新鲜，无需人工干预。当 auto_sync 启用（默认）后，每次工具调用都会检查代码库是否已更改，并仅对更改的文件重新索引。对于较长的会话， watch_project 实时更新图形。

工具： sync_project, list_projects （与 path 用于索引状态）

HTTP端点跟踪

Synapps通过检测服务器端端点定义和客户端HTTP调用，按路由模式进行匹配，来跟踪跨语言边界的HTTP依赖关系。

工具： find_http_endpoints （使用 trace=True 对于完整的依赖关系图片）

已知限制： 动态URL构建（运行时字符串串联、构建器模式）和API网关/中间件路由重写无法通过静态分析来解决。

令牌高效输出

输出使用缩短的符号引用、相对文件路径和紧凑的Markdown摘要，而不是原始JSON——在保留代理所需的所有信息的同时减少了令牌消耗。

多语言支持

C#、Python、Types/JavaScript和Java项目都使用相同的工具、图模式和查询模式。语言检测是基于文件扩展名自动进行的，也可以通过显式指定 --language.

网络查看器

Synapps包含一个内置的web UI，它通过MCP向AI代理提供相同的工具，因此您可以准确地看到代理看到的内容。webviewer提供对所有查询工具的交互式访问，以及用于探索符号邻域的力导向图可视化。

能力：

• 搜索 --在索引项目中按名称查找符号
• 导航 --直接从UI跟踪用法、被调用者、层次结构和作用域上下文
• 分析 --查看架构概述、死代码和未经测试的方法
• 探索 --将符号邻域可视化为具有可配置深度、物理模拟和布局控件的交互式图形
• 查询 --运行原始Cypher查询并浏览HTTP端点

webviewer对于直观地了解代码如何连接非常有用，特别是在进入新代码库或调查复杂的调用链时。

CLI 参考

synapps <command> [args]

设置

项目管理

图形查询

摘要

为符号附加不可衍生的上下文——设计原理、约束、所有权、弃用计划。不要将这些用于结构描述；该信息可通过实时查询 get_context_for, find_dependencies等等。

MCP工具

连接到的任何MCP客户端都可以使用19个工具 synapps-mcp，分为9类。

项目管理

符号发现

调用图

背景和影响分析

代码智能

HTTP端点

建筑

代码质量

摘要

原始查询

容器管理

Synapps使用Memgraph作为其图形数据库，通过Docker进行管理。默认情况下，为了简单起见，所有项目共享一个容器。

在共享模式下，每个项目的数据由其 Repository 图中的节点——索引项目A对项目B没有影响。

专用集装箱

添加 "dedicated_instance": true 到项目的 .synapps/config.json:

{
  "dedicated_instance": true
}

Synapps为每个项目提供一个容器(synapps-<project-name>)在动态分配的端口上。

外部Memgraph

在中设置连接 ~/.synapps/config.json:

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

外部模式下不需要Docker。

管理容器

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

容器在会话中持续存在，如果停止，会在下一个命令中自动重新启动。

全局配置位于 ~/.synapps/config.json.根据项目配置(.synapps/config.json)仅在使用专用容器时创建。添加 .synapps/ 到你的 .gitignore.

图形模型

节点标签

结构性的 （由 path): :Repository, :Directory, :File

符号 （由 full_name): :Package, :Class （类、抽象类、枚举、记录——以 kind), :Interface, :Method (signature, is_abstract, is_static, line), :Property (type_name), :Field (type_name), :Endpoint (route, http_method, name)

A. :Summarized 标签将添加到任何附有摘要的节点上。

关系

完全限定的名称（例如。 MyNamespace.MyClass.DoWork)始终用作符号标识符。

忽略文件

地点a .synignore 项目根目录中的文件，用于从索引中排除路径(.gitignore 语法）：

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

没有 .synignore，Synapps使用内置排除(.git, node_modules, __pycache__, dist, build等等）。

预工具挂钩

Synapps可以安装咨询性的预工具挂钩，提醒AI代理在回到grep和文件搜索之前使用图形工具。钩子是非阻塞的——它们向stderr发出提醒，但从不阻止工具调用。

在以下过程中安装挂钩 synapps init 对于任何检测到的代理。它们是索引感知的：只有当当前项目有 .synapps/config.json （即已编入索引）。

支持的代理

运作原理

Gate脚本安装在 ~/.synapps/hooks/:

• common.sh --共享助手：从 $PWD 向上寻找 .synapps/config.json；如果发现stderr，则向其发出提醒
• claude-gate.sh / cursor-gate.sh --来源 common.sh，检查索引，发出提醒，退出0
• copilot-gate.sh --相同，但也读 toolName 从stdin JSON到过滤搜索相关工具，并发出 {"permissionDecision":"allow"} 在stdout上（Copilot协议要求）

手动吊钩拆卸

要移除挂钩，请删除 ~/.synapps/hooks/ 并从每个代理的配置文件中删除Synapps条目。Synapps条目可通过包含以下内容的脚本路径进行识别 ~/.synapps/hooks/.

AI代理配置

Synapps通过协议自动向符合MCP的客户端提供使用说明——大多数代理都能开箱即用地做出良好的工具选择。

下面的片段是 可选的 为您的AI平台规则文件添加。它强化了工具选择模式，并增加了MCP协议所提供的指导。

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

在哪里添加：

对于Cursor的 .mdc 格式化，将内容包装在frontmatter中 description 和 globs 领域。对于VS代码/副本，MCP服务器配置(.vscode/mcp.json)与规则文件分开。

发展

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