内容
# mamari
> 本地代码智能MCP服务器，适用于AI编程代理。构建任何代码仓库的可查询符号图，然后通过一个紧凑的路由器进行导航——无需批量读取文件，也无需虚构的调用图：无法证明的调用被标记为`未解析`，而不会被猜测。为Go、Python、JS/TS、Java、C#、Kotlin、Rust、PHP等提供结构化、诚实的解决方案。
[](https://github.com/waelhoury/mamari/actions/workflows/ci.yml)
[](https://github.com/waelhoury/mamari/releases/latest)
[](LICENSE)
[](go.mod)
[](https://modelcontextprotocol.io)
Mamari将您的代码库索引到`.mamari/index.json`，然后运行一个本地的标准输入输出MCP服务器，Claude Code、Codex、VS Code或任何MCP-capable代理都可以与其通信。代理获取精确的符号图、跨文件调用跟踪和预算源切片，而不是在整个文件读取上花费令牌。
一个紧凑的MCP路由器保持固定的会话开销小。响应是令牌预算和字节确定的，并且实现经过`go test -race`测试。
**本地优先** — 您的源代码永远不会离开您的机器。MCP服务器是您笔记本电脑上的一个进程。
---
## 目录
- [功能](#功能)
- [语言支持](#语言支持)
- [快速入门](#快速入门)
- [安装](#安装)
- [MCP客户端设置](#mcp客户端设置)
- [代理如何使用Mamari](#代理如何使用mamari)
- [团队部署](#团队部署)
- [MCP工具](#mcp工具)
- [监视模式](#监视模式)
- [CLI参考](#cli参考)
- [工作原理](#工作原理)
- [操作特性](#操作特性)
---
## 功能
- **从不猜测调用图** — 每个调用边都被标记为`精确`、`作用域`、`启发式`或`未解析`。当Mamari无法证明目标（动态调度、反射、模糊重载）时，它会说`未解析`而不是发明边。代理获取一个可以行动的图，而无需进行二次猜测——依赖于此的工作流（影响、死代码、审查）将已证明的内容与需要查看的内容分开。
- **代码审查和死代码流** — `review`将git diff转换为“我的更改会破坏什么？”，更改的符号具有已证明和可能的爆炸半径、未测试的更改、热点风险和共同更改提示。`dead_code`查找未引用的符号，并且如果未解析的边可能仍能到达，则拒绝调用任何死代码。
- **符号图** — 函数、类、方法、接口、类型、枚举、Vue组件、RDF形状及其调用/导入边
- **一个工具的默认MCP表面** — 精简的`mamari`路由器以低启动成本公开主要工作流；34个命名工具通过自适应/完整模式仍然可用
- **自然语言搜索** — `search_code`根据相关性而不是文本匹配来排名证据片段
- **本地语义向量** — `semantic_query`通过词汇共现、软件概念、IDF加权和调用图扩散来弥合词汇不匹配；无需API密钥或外部服务
- **架构图** — `repo_map`总结了语言、包、入口点、路由、热点、连接细化的图社区、类型耦合和模块边界
- **内置图浏览器** — `mamari ui --watch`提供本地、无依赖的视觉图，**分层**（包→文件→符号，带有breadcrumb drill-down），以及搜索、语言/种类/边过滤器、置信度感知的加权链接（包括包级导入边）、**健康叠加层**（死/未测试/热点/高复杂度着色）、缩放/平移/拖拽和源/调用者/被调用者检查
- **确定性工作流** — `inspect_flow`回答“X如何工作？”只需一次往返；`inspect_symbol`将跟踪+源在一个数据包中组合，并具有紧凑的`format=node`符号读取模式
- **RDF/SHACL/TTL** — 带有前缀解析和`sh:NodeShape`图的Turtle文件的完整词汇索引
- **令牌预算响应** — 大容量发现和上下文工具将完整序列化响应塑造成有界预算
- **监视模式** — 仅重新索引更改的文件；MCP服务器在内存中更新，无需重启
- **SCIP导入** — 从Sourcegraph SCIP索引中进行增量摄取，以实现编译器支持的跨引用
- **稳定符号ID** — ID在行号偏移后生存（例如，添加导入）；差异反映真实的重命名，而不是空白混淆
- **无竞争** — 工作线程池+互斥锁保护索引，经`go test -race`测试
---
## 语言支持
| 语言 | 解析器 | 调用解析 | 备注 |
|---|---|---|---|
| JavaScript / TypeScript | 纯Go（无cgo） | 精确/启发式/作用域 | 类型参数、字段、局部变量、别名、导入和构造实例 |
| Vue SFC | 纯Go（无cgo） | 启发式/作用域 | 模板绑定、`renders-component`、`passes-prop`、`binds-model`、`listens-event` |
| Python | tree-sitter（cgo） | 精确/作用域 | 注解、构造函数推断、导入别名和`self`字段 |
| Java | tree-sitter（cgo） | 精确/作用域 | Spring MVC `@RequestMapping` → `http-route` 边 |
| Go | tree-sitter（cgo） | 精确/作用域 | 结构体嵌入促进方法调用 |
| C# | tree-sitter（cgo） | 精确/作用域 | ASP.NET Core `[Route]`/`[HttpGet]` → `http-route` 边 |
| Dockerfile | 结构指令扫描器 | 精确/作用域 | 阶段、基准镜像、跨阶段复制、端口、命令、健康检查 |
| Kubernetes / Kustomize YAML | YAML AST | 精确/作用域 | 多文档资源、选择器、运行时依赖、叠加层、组件、补丁 |
| Rust, Ruby, PHP, C, C++, Kotlin, Bash, Scala, Lua, Elixir, Dart, Haskell, Clojure, Swift | tree-sitter（cgo） | 精确/作用域 | 通过共享的通用tree-sitter引擎实现真正的类/方法嵌套和调用解析 — 参见`CHANGELOG.md`中的语言覆盖范围展开 |
| R | tree-sitter（cgo） | 精确/作用域 | `name <- function(...)`定义；裸、`pkg::fn`和`obj$method`调用解析 |
| Julia | tree-sitter（cgo） | 精确/作用域 | 长函数和短函数、`struct`/`abstract`/`module`；裸和`Mod.fn`调用 |
| Zig | tree-sitter（cgo） | 精确/作用域 | `fn`声明、`struct`/`enum`/`union`容器；裸和`recv.method`调用 |
| OCaml | tree-sitter（cgo） | 精确/作用域 | 函数`let`-绑定、模块、模块类型、类/方法、类型；柯里化应用 + `Mod.fn`调用 |
| Terraform / OpenTofu（`.tf`） | tree-sitter（cgo） | 精确/模块作用域 | 资源、数据、模块、变量、局部变量、输出、提供者和短暂资源的规范地址；依赖边和局部模块源导入 |
| Generic HCL（`.hcl`） | tree-sitter（cgo） | N/A（声明式） | 结构化索引的标注块，无需假设Terraform语义 |
| Turtle / SHACL | 词法 | N/A | 文件作用域前缀解析、命名的`sh:NodeShape`块 |
| JSON | 文件/配置识别 | N/A | 加载元数据和支持的配置发现；无通用JSON AST符号图 |
---
## 快速入门
```bash
# 1. 在macOS或Linux上安装发布的版本
curl -fsSL https://raw.githubusercontent.com/waelhoury/mamari/main/scripts/install.sh | sh
# 如果发布页面仍然为空，请使用以下命令：
# go install github.com/waelhoury/mamari/cmd/mamari@latest
# 2. 打开代码库
cd /path/to/your/project
# 3. 索引并配置MCP客户端
mamari init --mcp codex
```
将`codex`替换为：
| 值 | 用途 |
|---|---|
| `claude` | Claude Code，无论是从终端、VS Code还是IntelliJ启动 |
| `codex` | Codex CLI或Codex IDE扩展 |
| `vscode` | VS Code中的GitHub Copilot |
| `jetbrains` | IntelliJ-based IDE中的GitHub Copilot或JetBrains AI Assistant |
| `all` | Claude Code、Codex和VS Code项目文件 |
该命令构建`.mamari/index.json`，解析稳定的绝对路径，
验证索引和Mamari可执行文件都可用，然后配置
选定的客户端。然后它打印客户端的精确重启、信任和验证步骤。
默认启用实时文件系统更新。
---
## 安装
### 发布二进制文件（推荐）
发布存档包含用于macOS、Linux和Windows的Mamari二进制文件，支持amd64和arm64；无需安装Go。安装程序在替换本地二进制文件之前，会根据发布的SHA-256校验和验证每个存档。
`v0.1.x`二进制文件故意不进行Apple-notarized或Windows Authenticode签名，因此操作系统可能会在第一次运行前要求确认。SHA-256校验和和GitHub构建提供证明与每个发布一起发布；代码签名计划在`v1.0.0`之前进行。
安装程序需要至少有一个已发布的
[GitHub release](https://github.com/waelhoury/mamari/releases)。如果发布页面仍然为空，请使用下面的源代码安装，直到创建第一个标签。
支持的发布目标是macOS 12 Monterey或更高版本，内核为3.2的Linux和glibc 2.17或更高版本，以及Windows 10 / Windows Server 2016或更高版本。
这些底线遵循[Go 1.26的平台要求](https://go.dev/wiki/MinimumRequirements)；
Linux glibc底线也通过打包的二进制文件在发布验证期间进行检查。
macOS或Linux：
```bash
curl -fsSL https://raw.githubusercontent.com/waelhoury/mamari/main/scripts/install.sh | sh
```
默认目的地是`~/.local/bin`。使用
`MAMARI_INSTALL_DIR`覆盖它，或使用`MAMARI_VERSION=v0.1.0`固定版本。
Windows PowerShell：
```powershell
irm https://raw.githubusercontent.com/waelhoury/mamari/main/scripts/install.ps1 | iex
```
Windows安装程序写入
`%LOCALAPPDATA%\Programs\Mamari\bin`并将该目录添加到用户PATH。
您也可以直接从
[GitHub Releases](https://github.com/waelhoury/mamari/releases/latest)下载存档和`checksums.txt`。
### 从源代码构建
源代码构建需要Go 1.26.5和C/C++编译器来编译tree-sitter语法。
```bash
go install github.com/waelhoury/mamari/cmd/mamari@latest
```
或克隆存储库并运行`go build -o mamari ./cmd/mamari`。
---
## MCP客户端设置
通常的设置是来自存储库根目录的单个命令：
```bash
mamari init --mcp <claude|codex|vscode|jetbrains|all>
```
这故意显式而不是从编辑器猜测：VS Code或
IntelliJ可能托管多个不同的代理，配置错误代理
比输入其名称更糟糕。
设置是防御性的：
- 相对索引路径相对于 `--repo` 解决，即使命令从其他目录运行；
- 编写的配置使用绝对可执行文件和索引路径，以便GUI启动的
客户端不依赖于其继承的`PATH`或工作目录；
- Mamari在写入配置之前验证可执行文件是否可运行以及索引是否可以加载；
- 现有的非Mamari配置被保留；
- 现有的`mamari`条目不会被替换，除非提供`--mcp-force`；
- JSON和TOML配置文件被原子替换。
如果存储库已经索引，配置或修复客户端而不重新索引：
```bash
mamari setup-mcp --repo . --client codex --write
```
### Claude Code
```bash
mamari init --mcp claude
```
这会写入项目根目录`.mcp.json`：
```json
{
"mcpServers": {
"mamari": {
"command": "/绝对路径/to/mamari",
"args": ["serve", "--index", "/绝对路径/to/project/.mamari/index.json"]
}
}
}
```
重启Claude Code，批准项目MCP服务器，并运行 `/mcp` 或
`claude mcp list`。Claude Code使用与终端、VS Code终端或IntelliJ终端启动时相同的项目配置。
参见 [Claude Code MCP文档](https://code.claude.com/docs/en/mcp)。
### Codex
```bash
mamari init --mcp codex
```
这会写入项目根目录`.codex/config.toml`。信任项目，重启
Codex，并运行 `/mcp` 或 `codex mcp list`。Codex CLI和IDE扩展
共享此项目配置。参见
[Codex MCP文档](https://learn.chatgpt.com/docs/extend/mcp)。
### VS Code中的GitHub Copilot
```bash
mamari init --mcp vscode
```
这会写入 `.vscode/mcp.json`。重新加载VS Code窗口，批准服务器，
并从命令面板运行 **MCP: List Servers**。参见
[VS Code MCP文档](https://code.visualstudio.com/docs/agent-customization/mcp-servers)。
### IntelliJ和其他JetBrains IDE
JetBrains将MCP配置存储在IDE管理的设置中，因此Mamari不会猜测或修改私有IDE文件。相反，此命令索引项目，
验证两个路径，并打印可粘贴的JSON以供JetBrains主机使用：
```bash
mamari init --mcp jetbrains
```
对于GitHub Copilot：
1. 在代理模式下打开Copilot聊天。
2. 打开 **MCP → 添加MCP工具**。
3. 粘贴打印的 `servers` JSON并批准本地服务器。
对于JetBrains AI Assistant，包括其中托管的Claude或Codex代理：
1. 打开 **设置 → 工具 → AI Assistant → 模型上下文协议（MCP）**。
2. 在项目级别添加打印的`mcpServers` JSON。
3. 打开 **设置 → 工具 → AI Assistant → 代理** 并启用
**传递自定义MCP服务器**。
参见 [GitHub Copilot JetBrains MCP指南](https://docs.github.com/en/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp)
和 [JetBrains MCP文档](https://www.jetbrains.com/help/ai-assistant/mcp.html)。
如果Codex或Claude Code仅在IntelliJ的终端中运行，而不是在JetBrains AI Assistant中运行，请使用 `--mcp codex` 或 `--mcp claude`；不需要JetBrains特定的配置。
### 验证设置
Mamari在设置期间验证运行时。这些客户端检查确认主机已加载它：
| 客户端 | 验证 |
|---|---|
| Claude Code | `/mcp` 或 `claude mcp list` |
| Codex | `/mcp` 或 `codex mcp list` |
| VS Code / Copilot | **MCP: List Servers** |
| JetBrains | 在MCP状态/工具列表中确认 `mamari` |
您也可以独立检查本地索引：
```bash
mamari version
mamari status --index .mamari/index.json
```
然后询问：
> 使用Mamari映射此存储库并识别其主要入口点。
### 安全重新配置
Mamari拒绝覆盖现有的 `mamari` 服务器条目。在检查
现有配置后，只需替换该条目：
```bash
mamari init --mcp codex --mcp-force
# 或在不重建索引的情况下：
mamari setup-mcp --client codex --write --force
```
## 代理如何使用Mamari
设置完成后，重启或重新加载AI客户端。客户端自动启动
`mamari serve` 以适用于此存储库 — 正常使用MCP时不要运行单独的
`mamari serve` 进程。
生成的配置包含到此存储库的 `.mamari/index.json` 的绝对路径，
因此每个项目都有自己的本地Mamari进程和代码图。
默认情况下，代理看到一个名为 `mamari` 的只读MCP工具。
该工具会路由诸如以下操作：
| 代理任务 | Mamari操作 |
|---|---|
| 了解存储库架构 | `map` |
| 跟随某个功能的工作原理 | `explore` |
| 查找相关代码或确切标识符 | `search` / `exact` |
| 检查调用者和被调用者 | `trace` |
| 读取围绕符号的聚焦源 | `node` / `context` |
| 估计更改的爆炸半径 | `impact` |
| 审查当前更改 | `review` |
| 查找未引用的或重复的代码 | `dead_code` / `duplicates` |
例如，当被问及：
> 解释此存储库中身份验证的工作原理。
代理可以调用 `mamari` 工具，操作为 `explore`，查询为 `authentication flow`，
然后在发现的符号上使用 `trace` 或 `context`。
Mamari 提供本地代码智能；AI 客户端继续使用其正常的文件编辑和终端工具进行更改。
当MCP客户端运行时，Mamari会监视存储库。保存的编辑、创建、重命名和删除会增量地重新处理到内存图而无需重启客户端。
磁盘 `.mamari/index.json` 保持会话的启动快照，除非服务器被故意配置为 `--persist`。
如果在MCP客户端关闭时文件或分支发生变化，请在下一次会话之前刷新启动索引：
```bash
mamari index --repo .
```
### 鼓励一致的代理使用
MCP使Mamari可用，但模型仍然决定何时调用它。
为了更一致的存储库导航，请在项目的`AGENTS.md`、`CLAUDE.md`或等效的代理指令文件中添加以下内容：
```md
在进行广泛的存储库搜索或整个文件读取之前，请使用Mamari MCP工具。
- 以 `map` 开始处理架构问题。
- 对于功能流问题，请使用 `explore`，对于发现问题，请使用 `search`。
- 在标识符号后，请使用 `trace`、`node` 或 `context`。
- 在更改共享代码之前，请使用 `impact`，在审查更改时，请使用 `review`。
- 将精确/作用域边视为已证明，将启发式/未解析边视为不确定。
```
这些说明是可选的。没有它们，Mamari仍然可用，显式提示（例如“使用Mamari跟踪此流程，然后再编辑”）有效，
无需任何存储库指令文件。
---
## 团队部署
（无中文翻译，此部分保持原文）
## MCP 工具
（无中文翻译，此部分保持原文）
## 监视模式
（无中文翻译，此部分保持原文）
## CLI 参考
（无中文翻译，此部分保持原文）
## 工作原理
（无中文翻译，此部分保持原文）
## 操作特性
（无中文翻译，此部分保持原文）
## 团队部署
对于每个团队成员和代码库：
1. 从发布二进制文件安装 Mamari 并运行 `mamari version`。
2. 在代码库根目录运行 `mamari init --mcp <client>`。
3. 按照打印的重启/信任说明进行操作，并确认 `mamari` 出现。
4. 在依赖更深入的图分析之前，运行打印的映射提示。
5. （可选）`mamari install-skill code-review` 将一个通用的、基于 mamari 的代码审查技能放入 `./.claude/skills/`（提交它以与团队共享）。该技能发现代码库自己的编码标准，并驱动审查/影响/死代码/重复流程 - 参见[捆绑技能](#捆绑技能)。
### 捆绑技能
Mamari 在二进制文件中嵌入了 Claude Code 技能。可以通过单个命令将技能安装到代码库（或用户范围）中 - 无需复制单独的文件：
```bash
mamari install-skill --list # 显示捆绑技能
mamari install-skill code-review # 安装到 ./.claude/skills（每个代码库；提交以共享）
mamari install-skill code-review --user # 安装到 ~/.claude/skills（所有代码库）
```
现有的 `SKILL.md` 永远不会在没有 `--force` 的情况下被覆盖，因此本地自定义是安全的。`code-review` 与堆栈和语言无关：它读取代码库自己的标准（CONTRIBUTING/docs/lint 配置）并仅应用适合更改文件的堆栈镜头。
通过 `init --mcp` 或 `setup-mcp --write` 生成的绝对路径配置是机器本地的，通常不应提交。对于每次克隆，推荐的团队设置是每个克隆在本地运行单命令初始化；这样可以避免机器特定的二进制路径和 GUI `PATH` 差异。现有的共享 MCP 文件将被合并，Mamari 只会更改其命名的服务器条目。
对于 git 跟踪索引，请使用 `mamari init --commit-index`，提交 `.mamari/committed/`，并让每个克隆运行 `mamari hooks install`。本地索引仍然是推荐的默认设置，因为它们始终反映每个开发者的工作树。
## MCP 工具
`mamari serve` 默认使用精简的单工具 MCP 界面，以最小化每次会话的固定 `tools/list` 模式成本。单个 `mamari` 工具通过 `action` 路由操作，例如 `explore`、`map`、`search`、`exact`、`trace`、`node`、`context`、`source`、`impact`、`graph`、`review`、`dead_code` 和 `doctor`；在 `query` 中传递主查询/符号/路径，并在 `args_json` 中传递可选的工作流参数。
如果您更喜欢以下旧版命名工具菜单，请使用 `mamari serve --toolset adaptive` 启动服务器。自适应模式仅注册对加载的代码库/会话有用的命名工具：当索引具有 TTL 术语或 SHACL 形状时，RDF/Turtle 工具会出现；当传递 `--link` 时，跨代码库工具会出现；当监视时，`changed_since` 会出现，这是默认行为。传递 `--watch=false` 以针对不可变的加载索引运行。传递 `mamari serve --toolset full` 或 `mamari serve --full-toolset` 以无条件地注册每个命名工具，包括 `manage_notes`、`manage_adr` 和 `diff_index` 等罕见管理员工具。
### 主要路由器
| 工具 | 功能 |
|---|---|
| `mamari` | 一个紧凑的 MCP 工具，根据 `action` 调度到主工作流，保留 Mamari 的强大功能，同时模式占地面积更小 |
### 发现
| 工具 | 功能 |
|---|---|
| `search_code` | 自然语言搜索 - 按路径、符号名称和精确字面值排序证据片段 |
| `semantic_query` | 基于词汇不匹配问题的本地向量搜索，由持久量化语义索引支持 |
| `inspect_exact` | 已知标识符的工作流匹配，路由字面值、MIME 类型、RDF 谓词 |
| `inspect_flow` | 端到端“X 如何工作？” - 运行发现、锚定符号、跟踪、获取源 |
| `repo_map` | 页面排名文件/符号概览以及包、入口点、路由、热点、图社区、类型耦合和模块边界 |
### 代码审查和维护
| 工具/操作 | 功能 |
|---|---|
| `review` | 审查 git diff（`query` = 基准引用，默认为 `HEAD`）：将更改的行映射到拥有它们的符号，然后报告每个符号的爆炸半径 **分为已证明（精确/作用域）和可能（启发式/未解决）调用者**，无论测试是否到达它，**更改分类**（`signature` / `body` / `new` - 带调用者的签名更改被标记为调用者破坏），热点风险和“您通常还会触摸这些”共同更改提示。传递 `args_json.coverage`（lcov 路径）以使未测试的判决反映实际运行的测试套件。每日“我的更改会破坏什么？”工作流 - 并且它永远不会将未证明的调用者呈现为确定 |
| `dead_code` | 查找没有已解析引用的符号，**并单独**列出由于未解析的同名调用 *可能* 到达而被阻止的符号 - Mamari 报告第一个为未引用的，并拒绝调用第二个死。诚实至上 |
| `duplicates` | 结构（类型 2）克隆集群 - 具有相同形状和不同名称/字面值的函数 - 用于查找复制粘贴和可重用机会。在索引时通过指纹识别，因此查询很便宜 |
| `report` | 代码库 **报告卡**：解析健康状况、边缘置信度分解（未解析 % 陈述，不隐藏）、死代码、静态测试可达性 %、重复集群、复杂性/热点热点、最大爆炸半径（不同的已证明调用者）、神文件。借助 `--fail-on`，它兼作 CI 质量门控 |
| `tests_for` / `untested_symbols` | 哪些测试演练了一个符号（已解析 vs 可能），以及哪些符号没有测试到达 |
### 符号图
| 工具 | 功能 |
|---|---|
| `list_symbols` | 按种类、源/测试/故事筛选符号列表 |
| `find_symbol` | 模糊排名符号查找 - 精确生产符号优先于测试和噪声 |
| `trace_symbol` | 符号的跨文件调用者、被调用者和导入边 |
| `inspect_symbol` | 组合包：跟踪 + 前端边 + 调用者/被调用者的预算源；使用 `format: node` 进行紧凑的源/文档字符串/返回类型/调用者/被调用者读取 |
| `find_references` | 符号或 RDF 术语的所有引用站点 |
| `impact` | 更改给定符号所影响的下游符号 |
| `query_graph` | 在符号图上限制、类似 Cypher 的 `MATCH/WHERE/RETURN/ORDER BY/LIMIT` 查询，包括链接的多跳模式和可变长度遍历（`*`、`*N`、`*N..M`）用于临时多跳/属性/可传递可达性问题（例如热点热点，“在 3 跳范围内可调用的所有内容”）- 不是完整的 Cypher |
### 源代码获取
| 工具 | 功能 |
|---|---|
| `fetch_context` | 符号、`file:line` 或 RDF 术语的预算源切片 |
| `fetch_source` | 精确 `file:start:end` 范围的原始源代码行 |
### RDF / 乌龟
| 工具 | 功能 |
|---|---|
| `inspect_term` | 分组术语证据 + 实现标识符 + 预算源 |
| `trace_term` | RDF 术语从 TTL 形状到代码引用的完整跟踪 |
| `list_terms` | 列出所有索引 RDF 术语，可选按命名空间前缀筛选 |
| `list_dynamic_iris` | 动态 IRI 调用站点（命名空间模板、计算 IRI） |
| `search_literal` | 跨所有索引字面值进行精确字符串搜索 |
| `find_containing_shape` | 查找包含给定术语的 `sh:NodeShape` 块 |
### 跨代码库（需要 `mamari serve --link <index.json,...>`）
| 工具 | 功能 |
|---|---|
| `find_route` | 将 HTTP 路由或裸事件名称解析为其处理程序/监听器和调用者/发射器，跨主要代码库和每个链接代码库 |
| `list_linked_repos` | 列出主要代码库和每个链接代码库，包含文件/符号计数 |
| `cross_repo_architecture` | 跨链接代码库集的每个 HTTP/事件耦合边，以及基于组合的多代码库图的社区检测 - 跨越 >1 代码库的社区是真正的跨代码库架构边界 |
### 知识库
| 工具 | 功能 |
|---|---|
| `manage_notes` | 添加/列出/删除附加到符号 ID 的自由格式注释 |
| `manage_adr` | 获取/列出/更新/删除项目级架构决策记录文档的命名部分 - 用于不附加到一个符号的持久决策 |
### 索引管理
| 工具 | 功能 |
|---|---|
| `doctor` | 索引健康报告 - 解析覆盖率、边缘置信度、未解析调用摘要 |
| `import_scip` | 从 Sourcegraph SCIP `index.scip` 文件进行附加摄入 |
## 监视模式
`mamari serve` 默认情况下通过重新烘焙仅更改的文件来保持内存中的 MCP 索引。编辑、创建、重命名和删除都得到了处理 - 更改文件的先前证据被丢弃，文件被重新扫描，并且重新计算跨文件解析。
```bash
# 启用实时重新索引的 MCP 服务器（默认）
mamari serve --index .mamari/index.json
# 还要在每次重新烘焙后重写磁盘索引
mamari serve --index .mamari/index.json --persist
# 故意保持加载的索引不可变
mamari serve --index .mamari/index.json --watch=false
# 独立文件监视器（无 MCP 服务器）
mamari watch --repo . --debounce-ms 200
```
`--debounce-ms` 将编辑器的多个文件系统事件合并，这些事件可能会在写入后发出多个文件系统事件。
## CLI 参考
每个 MCP 工具都有一个具有 `--json` 的 CLI 等价物，用于 MCP 响应形状。
```bash
# 索引和状态
mamari init --mcp codex # 索引 + 验证 Codex 项目配置
mamari init --repo .
mamari index --repo .
mamari status
mamari doctor --index .mamari/index.json --json
# Git 可移植索引（选择加入）：提交索引，以便 `git pull` 单独使用 Mamari，无需运行 `mamari index`。
mamari init --commit-index # 写入 .mamari/committed/index.json + 安装 pre-commit 钩子
mamari hooks install # 相同的钩子安装，用于已经索引的代码库
mamari index --commit # 手动刷新 .mamari/committed/index.json
mamari doctor --check-committed # CI 守护进程：如果提交的索引与工作树不一致，则失败
# 发现
mamari search-code "如何防止后台作业运行多次"
mamari inspect-exact "POST /api/datasets application/json"
mamari inspect-flow "数据集权限范围" --budget 1800
# 符号图
mamari list-symbols --json --limit 20
mamari find-symbol useDataset --source-only --json
mamari trace-symbol useDataset --json --with-edges
mamari inspect-symbol getAccessLevelIcon --budget 1800 --json
mamari inspect-symbol TraceSymbol --format node --budget 900 --json
mamari find-references useDataset --json
mamari impact useDataset --json
mamari repo-map --mentioned useDataset --architecture --budget 1800 --json
# 代码审查和维护
mamari review --base main --callers # 我的分支更改了什么，它影响了什么？
mamari review --json # 未提交的更改 vs HEAD
mamari review --base main --coverage coverage/lcov.info # 未测试 = 实际运行的测试套件中发生了什么
mamari dead-code --json # 未引用的符号 + 诚实的“不确定”列表
mamari dead-code --include-exported --json
mamari duplicates --json # 结构克隆集群（可重用性）
mamari report # 代码库报告卡：死代码、未测试 %、重复、热点
mamari report --fail-on "dead<=150,untested-pct<=80" # CI 门控：当超过阈值时退出非零
mamari query-graph "MATCH (a:function)-[:calls*1..3]->(b:function) WHERE a.name = 'handleRequest' RETURN b.name, b.file" --json
# 源代码获取
mamari fetch-context useDataset --budget 1200 --callers --callees --json
mamari fetch-context src/composables/useDataset.ts:65 --budget 800 --json
mamari fetch-source src/composables/useDataset.ts:60:80
# RDF / 乌龟
mamari trace-term dcterms:identifier --json
mamari trace-term dcterms:identifier --json --compact
mamari trace-term dcterms:identifier --json --grouped
mamari inspect-term sh:in --budget 900 --mode evidence --json
mamari find-references sh:path --json
mamari list-terms
mamari list-terms dcterms
# SCIP 导入
mamari import-scip --index .mamari/index.json --scip index.scip
# MCP 服务器
mamari serve --index .mamari/index.json
mamari serve --index .mamari/index.json --full-toolset # 无条件注册每个 MCP 工具
# 本地可视化图浏览器
mamari ui --index .mamari/index.json --watch
mamari setup-mcp --client all --index .mamari/index.json # 预览所有基于文件的客户端配置
mamari version
```
## 工作原理
Mamari 构建了一个 **代码图协议（CGP）** 索引 - 一个具有稳定 ID、类型化边和置信度的 JSON 符号图。
`mamari index` 还会在主索引旁边写入边车：`.mamari/literals.jsonl` 用于大型字面值负载，当设置了 `MAMARI_PERSIST_SEARCH=1` 时，还会写入 gob 编码的 `.mamari/search.json` 用于标记化的 `search_code` 缓存。搜索边车仍然是可选的，因为重建该缓存已经高度并行化。`semantic_query` 在首次使用时延迟构建 `.mamari/semantic.gob`；其 int8 向量是哈希验证的，自动失效于监视重新烘焙，并被后续进程重用。
默认情况下，`.mamari/` 被 gitignore - 每个开发人员都本地索引。选择加入 `mamari init --commit-index`（或在已经索引的代码库上使用 `mamari hooks install`）还会写入纯 JSON、可差异审查的副本到 `.mamari/committed/index.json`，取消忽略该子目录，并安装一个 pre-commit 钩子，该钩子在每次提交之前重新生成它。钩子脚本本身位于 `.git/hooks/` 中，git 不跟踪它，因此每个克隆都需要运行一次本地 `mamari hooks install` 以保持索引 *更新*（此交易与 husky 等工具类似）- 但提交的索引数据本身在 `git clone`/`git pull` 时立即可用，无需任何设置。
**JS / TS / Vue** 文件由一个标记驱动的结构解析器（纯 Go，无 cgo）解析，该解析器在提取调用之前会屏蔽字符串、模板字面值、正则表达式字面值和注释。这样可以消除散文/JSDoc 假阳性。Vue SFC 还会从模板分析中生成 `renders-component`、`passes-prop`、`binds-model` 和 `listens-event` 边，以及从 `defineProps`/`defineModel`/`defineEmits` 声明中生成轻量级 `vue-prop`/`vue-model`/`vue-emit` 符号。
**Python、Java、Go、C#、Rust、Ruby、PHP、C、C++、Kotlin、Bash、Scala、Lua、Elixir、Dart、Haskell、Clojure 和 Swift** 使用 tree-sitter（cgo）进行解析，提供结构嵌套、多行签名、导入和作用域调用解析，只要有静态类型/导入证据允许。由此解析的调用被标记为 `exact` 或 `scoped`；动态接收者仍然被明确地标记为未解析，而不是被悄悄地提升。Java 的 Spring MVC 注解和 C# 的 ASP.NET Core 路由属性会生成具有 `handles-route` 边的 `http-route` 符号。
**Terraform 和 OpenTofu 原生 `.tf` 文件** 使用 HCL tree-sitter 语法和 Terraform 感知索引。Mamari 保留诸如 `var.region`、`local.name`、`data.aws_ami.ubuntu`、`aws_instance.web`、`module.network` 和 `ephemeral.random_password.db` 等规范地址，以及 `action.aws_lambda_invoke.restart` 用于当前 Terraform 操作块；解析表达式遍历到同一模块目录内的精确 `depends-on` 边；识别别名提供程序；并通过 `imports` 边链接本地模块 `source` 目录。普通的 `.hcl` 文件保留通用 HCL 块行为。
**Turtle/SHACL** 文件在词法上被索引，具有文件范围的 prefix 解析和命名 `sh:NodeShape` 块提取。大型的字面值负载被写入一个边车 `.mamari/literals.jsonl`，以便符号工作流跳过加载成本。
**未解析的调用** 被表示为 `unresolved:<name>` 边，而不是被猜测 - 图永远不会无声地误报调用。
构建使用大小为 `runtime.NumCPU()` 的工作线程池并行化。所有索引突变都由内部互斥锁保护，并使用 `go test -race` 进行测试。
## 操作特性
相同的查询在运行之间和新的服务器进程之间返回字节相同的响应。排名是确定性的，生成检查的缓存会在文件更改后失效，并且测试套件包括竞争检测。
默认情况下，`mamari serve` 安装自适应 Go 堆限制，等于 224 MiB 加上主要和链接索引的大小。现有的 `GOMEMLIMIT` 优先使用。显式限制可以使用 `--memory-limit-mb N`，或使用 `--memory-limit-mb 0` 使运行时限制保持不变。
### 当前限制
- 结构索引并不等同于编译器等价的解析。动态调度、反射、依赖注入、代理、宏和元编程可能会使调用保持诚实的未解析状态。
- 语法比固定的 tree-sitter 语法更新颖的文件可能会将一个原本有效的标记为 `partial`。
- XML、RDF/XML（`.rdf`）和 Markdown 当前未被索引。RDF 和 SHACL 支持通过 Turtle（`.ttl`）提供。
- `semantic_query` 是本地和代码库自适应的；它不提供大型预训练嵌入模型，因此代码库词汇之外的广泛释义可能较弱。
- `query_graph` 支持链接和有界可变长度模式，以及公共聚合，但故意省略完整的 Cypher 功能，例如 `OPTIONAL MATCH`、`UNION`、`WITH` 和子查询。
## 贡献
欢迎提出错误报告和拉取请求。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发和验证工作流程，并参阅 [SECURITY.md](SECURITY.md) 了解私有漏洞报告。维护者发布步骤在 [RELEASE.md](RELEASE.md) 中。
```bash
go test ./...
go test -race ./...
gofmt -l .
```
每次推送时，CI 都会运行格式化、检查、测试、竞态测试、发布配置验证和 Unix/Windows 安装程序烟雾测试。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器