内容
# ScalaSemantic
[](https://central.sonatype.com/namespace/io.github.mercurievv)
[](https://github.com/mercurievv/ScalaSemantic/actions/workflows/ci.yml)
[](https://mercurievv.github.io/ScalaSemantic/)
[](LICENSE)
**ScalaSemantic** 帮助 AI 理解您的 Scala 代码，就像编译器一样。您不需要让代理从文本搜索（grep）中猜测，而是可以查询编译器生成的 **SemanticDB** 以获取确切的符号、类型、隐式转换、继承关系、使用情况和调用路径。
对于 Scala 开发人员来说，这意味着代理可以回答以下问题：
- 方法在哪里真正被使用，而不会出现 `grep` 的错误匹配；
- 哪些类扩展了特质或重写了成员；
- 哪些 `given` 可以满足类型；
- 一个方法如何调用另一个方法，跨项目。
它通过 [MCP](https://modelcontextprotocol.io) 公开，因此像 Claude Code、Codex 和 Gemini CLI 这样的客户端可以将它作为本地工具调用，同时您继续使用正常的 Scala 构建。
📖 **文档站点：<https://mercurievv.github.io/ScalaSemantic/>** （mdoc-checked，因此其代码样本在构建时执行）。
## 为什么，与 `grep` 相比
`grep` 匹配字符；ScalaSemantic 理解编译后的程序。
| 您想知道… | `grep` | ScalaSemantic |
|---|---|---|
| 谁扩展了 `Animal`？ | 包含“Animal”的每一行 | 确切的子类型 — `class_hierarchy` |
| 方法 `foo` 的所有用法 | 所有的“foo”，包括无关的 | 确切的符号引用 — `find_usages` |
| 哪些 `given` 生成 `Show[Int]`？ | — 不可能 | `resolve_implicits` |
| 从 `a` 到 `c` 的调用路径？ | — 不可能 | `call_path` |
每个功能都由一个测试支持，该测试在存储库自己的 SemanticDB 上运行 → [`AnalyzerSuite`](analysis/src/test/scala/com/github/mercurievv/scalasemantic/analysis/AnalyzerSuite.scala)。
完整的权衡取舍，包括 `grep` 胜出的地方：[docs/explanation/scala-semantic-vs-grep.md](docs/explanation/scala-semantic-vs-grep.md)。
## 快速入门
您的 MCP 客户端在标准输入/输出上启动服务器。需要两件事（仅需 **JVM** — 无需 coursier，无需 sbt）：
1. 目标项目 **编译为 SemanticDB** (`semanticdbEnabled := true`)；
2. MCP 客户端配置，通过项目根目录启动服务器。
选择一种设置：
### sbt 插件 — 推荐
最少手动操作：在 sbt 1 和 sbt 2 上有效，启用 SemanticDB，并为您生成 MCP 客户端配置；第一次启动时生成 jar。
```scala
// project/plugins.sbt — 将 x.y.z 替换为最新版本（参见徽章/发布页面）
addSbtPlugin("io.github.mercurievv" % "sbt-scalasemantic-mcp" % "x.y.z")
// build.sbt
enablePlugins(ScalaSemanticMcpPlugin)
```
最新版本：[](https://central.sonatype.com/artifact/io.github.mercurievv/sbt-scalasemantic-mcp_2.12_1.0) · [GitHub 发布](https://github.com/MercurieVV/ScalaSemantic/releases/latest)
`sbt mcpClientConfig` 打印配置；`sbt mcpRun` 运行服务器进行测试。默认 `mcpClient := "claude"` 发出 `.mcp.json` 样式的 JSON。设置为 `mcpClient := "codex"` 以获取 Codex `config.toml`，`mcpClient := "gemini"` 以获取 Gemini CLI JSON，`mcpClient := "cline"` 以获取 Cline，`mcpClient := "roo"` 以获取 Roo Code，`mcpClient := "continue"` 以获取 Continue YAML，或 `mcpClient := "generic-json"` 以获取其他 MCP 客户端。
### 任意构建工具 / 操作系统
- **自动下载启动器** — `curl -fsSL .../scripts/install.sh | sh` （Windows：`…ps1`），然后将您的 MCP 客户端 `command` 设置为 `~/.local/bin/scalasemantic-mcp`。在第一次运行时获取并缓存 fat jar。
- **纯 `java -jar`** — 从 [最新版本](https://github.com/MercurieVV/ScalaSemantic/releases/latest) 获取 `scalasemantic-mcp.jar` 并直接运行。
**可选启动器标志** — 在项目根目录后追加到 MCP 客户端 `args` （启动器将其转发到服务器；括号中为等效环境变量）：
- `--prefetch` — 下载并缓存 jar，然后不提供服务退出。
- `--log` （`SCALASEMANTIC_LOG`）— 将工具调用输入记录到文件。
- `--log-output` （`SCALASEMANTIC_LOG_OUTPUT`）— 将工具调用输出记录到文件。
-
```json
{
"mcpServers": {
"scala-semantic": {
"command": "~/.local/bin/scalasemantic-mcp",
"args": ["/abs/path/to/project", "--log", "--log-output"]
}
}
}
```
完整的设置、生成的配置和生命周期： **[docs/getting-started/integration.md](docs/getting-started/integration.md)**。
## 工具
| 工具 | 答案 |
|------|---------|
| `find_symbol` | 将普通/部分名称解析为 SemanticDB 符号字符串 — **从这里开始** |
| `find_usages` | 符号的引用，def/ref 分割，分页 |
| `method_signature` | 完整的签名，包括隐式/使用参数列表 |
| `class_hierarchy` | 父级，线性化，索引范围内的已知子类型 |
| `find_overloads` | 共享名称和所有者的所有重载 |
| `members` | 已声明与继承的成员（override-aware） |
| `type_at_position` | 位于 0-based 位置的符号 + 类型 |
| `resolve_implicits` | 生成类型的 `given` 定义 |
| `trace_implicit_chain` | given 的传递隐式依赖 |
| `call_path` | 两个方法之间的最短调用路径 |
每个工具都采用 SemanticDB 符号字符串；首先调用 `find_symbol` 从普通名称获取一个。服务器初始化时还会发送 `instructions`，告诉代理 **优先使用这些工具而不是 `grep`** 来解决 Scala 代码问题。结果 **默认精简** （位置为 `uri:line:col`，签名一行，省略空字段）；传递 `"detailed": true` 以展开，`find_usages` 分页。
## 支持的 Scala 版本
服务器 *读取* SemanticDB，因此它是编译器版本无关的：它适用于任何发出 SemanticDB 的项目。通过测试强制执行跨版本行为 — 分析器针对 **Scala 2.13 和 3.x** 的黄金 SemanticDB 进行测试（参见 [docs/project/development.md](docs/project/development.md#cross-version-compatibility-test)）。服务器本身在任何 JVM 上运行（`java` 11+）；目标项目的 Scala 版本是独立的。
## 文档
- **[文档站点](https://mercurievv.github.io/ScalaSemantic/)** — 渲染的、mdoc-checked 的微站点
- [快速入门](docs/getting-started/quickstart.md) — 最短的 sbt 设置路径
- [集成](docs/getting-started/integration.md) — 与客户端注册，sbt 插件，其他构建工具
- [工具参考](docs/reference/tools.md) — MCP 工具，符号语法，请求形状
- [示例](docs/usage/examples.md) — 样板 MCP 查询和响应
- [ScalaSemantic 与 grep](docs/explanation/scala-semantic-vs-grep.md) — 权衡取舍和测量的上下文成本
- [开发](docs/project/development.md) — 模块布局，构建和测试，跨版本测试
- [设计决策](docs/project/design.md) — 实现笔记和未来扩展点
- [发布](docs/project/releasing.md) — Sonatype Central 发布流程
## 许可证
[MIT](LICENSE)
