MercurieVV/ScalaSemantic

# Scala 语义 [](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 代码。与其让 agent 通过文本搜索 (grep) 来猜测，不如让它直接查询编译器生成的 **SemanticDB**，以获取精确的符号、 类型、隐式 (implicits)、继承、用法以及调用路径。 对于 Scala 开发者而言，这意味着 agent 可以回答如下问题： - 某个方法真正被使用的地方，且不会出现 `grep` 那样的错误匹配； - 哪些类扩展了 trait 或覆盖了某个成员； - 哪些 `given` 可以满足某个类型； - 某个方法在整个项目中是如何调用另一个方法的。 它通过 [MCP](https://modelcontextprotocol.io) 暴露接口，因此像 Claude Code 这样的客户端可以将其 作为本地工具进行调用，同时你仍可继续使用正常的 Scala 构建。 📖 **文档站点：** （经过 mdoc 检查，因此其代码 示例会在构建时执行）。 ## 为什么选择它，而不是 `grep` `grep` 只能匹配字符；而 ScalaSemantic 能理解已编译的程序。 | 你想知道… | `grep` | ScalaSemantic | |---|---|---| | 谁 extends 了 `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/COMPARISON.md](docs/COMPARISON.md)。 ## 快速开始 你的 MCP 客户端会通过 stdio 启动该服务器。只需两样东西（只需要 **JVM** — 不需要 coursier，也不需要 sbt）： 1. 目标项目**已使用 SemanticDB 编译**（`semanticdbEnabled := true`）； 2. 一个 `.mcp.json` 条目，用于以该项目的根目录作为参数启动服务器。 选择一种设置方式： ### sbt 插件 — 推荐 最省事：它会自动启用 SemanticDB 并为你生成 `.mcp.json`；jar 包会在首次启动时下载。 ``` // project/plugins.sbt addSbtPlugin("io.github.mercurievv" % "sbt-scalasemantic-mcp" % "0.2.1") // build.sbt enablePlugins(ScalaSemanticMcpPlugin) ``` `sbt mcpClientConfig` 会打印出该条目；`sbt mcpRun` 会运行服务器以进行测试。 ### 任何构建工具 / 操作系统 - **自动下载启动器** — `curl -fsSL .../scripts/install.sh | sh`（Windows 系统使用：`…ps1`），然后将 `.mcp.json` 中的 `command` 设置为 `~/.local/bin/scalasemantic-mcp`。首次运行时会获取并缓存 fat jar。 - **直接使用 `java -jar`** — 从 [最新发布版本](https://github.com/MercurieVV/ScalaSemantic/releases/latest) 获取 `scalasemantic-mcp.jar` 并直接运行。 完整的设置、生成的配置以及生命周期：**[docs/INTEGRATION.md](docs/INTEGRATION.md)**。 ## 工具 | 工具 | 回答 | |------|---------| | `find_symbol` | 将普通/部分名称解析为 SemanticDB 符号字符串 — **从这里开始** | | `find_usages` | 对某个符号的引用，区分 def/ref，支持分页 | | `method_signature` | 完整的方法签名，包含 implicit/using 参数列表 | | `class_hierarchy` | 父类、线性化顺序、全索引范围内已知的子类型 | | `find_overloads` | 共享相同名称和所有者的所有重载 | | `members` | 声明的成员与继承的成员对比（感知 override） | | `type_at_position` | 位于 0 基点位置的符号 + 类型 | | `resolve_implicits` | 生成某个类型的 `given` 定义 | | `trace_implicit_chain` | 某个 given 的传递隐式依赖 | | `call_path` | 两个方法之间的最短调用路径 | 每个工具都接收一个 SemanticDB 符号字符串；请先调用 `find_symbol` 通过普通名称获取该字符串。 在 `initialize` 时，服务器还会发送 `instructions`，告知 agent 在回答 Scala 代码问题时 **优先使用这些工具，而不是 `grep`**。结果默认是**精简的**（位置以 `uri:line:col` 格式显示， 签名为单行，省略空字段）；传入 `"detailed": true` 可以展开详情，并且 `find_usages` 支持 分页。 ## 支持的 Scala 版本 服务器*读取* SemanticDB，因此它与编译器版本无关：它可以作用于任何 生成 SemanticDB 的项目。跨版本行为由测试强制保证 —— 分析器已针对 来自 **Scala 2.13 和 3.x** 的标准 SemanticDB 进行了测试（参见 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#cross-version-compatibility-test)）。 服务器本身运行在任何 JVM 上（`java` 11+）；目标项目的 Scala 版本是独立的。 ## 文档 - **[文档网站](https://mercurievv.github.io/ScalaSemantic/)** — 渲染后的、经过 mdoc 检查的微型网站 - [集成](docs/INTEGRATION.md) — 向客户端注册、sbt 插件、其他构建工具 - [对比](docs/COMPARISON.md) — 对比 `grep`（优缺点），以及关于 Metals/LSP 的说明 - [开发](docs/DEVELOPMENT.md) — 模块结构、构建与测试、跨版本测试 - [设计决策](docs/DESIGN.md) — 为什么使用 upickle、可扩展性（外部 jar 工具）、文档工具 - [发布](docs/RELEASING.md) — Sonatype Central 发布流程 ## 许可证 [MIT](LICENSE)

标签：AI编程辅助, MCP, Scala, SemanticDB, 云安全监控, 代码分析, 凭证管理, 静态分析