内容
# sbt-mcp
一款连接正在运行的 sbt 服务器的 MCP（模型上下文协议）服务器，使 Claude 等 AI 编程助手能够在无需 JVM/sbt 启动延迟的情况下编译和运行测试。
它不为每个命令启动新的 `sbt` 进程，而是通过 Unix 域套接字使用 LSP/JSON-RPC 协议与已经运行的 sbt 服务器通信。
## 安装
```sh
go install github.com/patriknw/sbt-mcp@latest
```
或从源代码构建：
```sh
go build .
```
## 使用
### 1. 在项目中启动 sbt
在终端中，启动 sbt 并等待 shell 提示符：
```sh
cd your-sbt-project
sbt
```
### 2. 配置 AI 助手
在项目根目录中添加 `.mcp.json`：
```json
{
"mcpServers": {
"sbt": {
"command": "sbt-mcp"
}
}
}
```
### 3. 使用它
助手现在可以访问一个 `sbt` 工具，该工具在运行的 sbt 服务器上执行命令。示例：
（不想自己启动 sbt？参见 [自动启动](#自动启动)。）
- `compile`
- `runtime-core/compile`
- `testOnly com.example.MySpec`
- `runtime-core/testOnly com.example.MySpec -- -t "should handle deposits"`
- `clean`, `reload`, `scalafmtAll`
## 自动启动
默认情况下，sbt-mcp **附加** 到您自己启动的 sbt 服务器（参见步骤 1），如果没有运行，则不执行任何操作 - 工具调用然后返回一个明确的“sbt 服务器未运行”的错误，告诉您启动 `sbt`。
启用 **自动启动** 后，sbt-mcp 将在没有可用的 sbt 服务器运行时启动 sbt 服务器，并在退出时关闭它。使用 `--autostart` 标志或 `SBT_MCP_AUTOSTART=1` 环境变量启用它：
```json
{
"mcpServers": {
"sbt": {
"command": "sbt-mcp",
"args": ["--autostart"]
}
}
}
```
自动启动启用时的行为：
- **没有服务器运行** （没有 `active.json`，或它指向一个过时的套接字）：sbt-mcp 运行 `sbt` 在项目目录中，等待服务器启动，然后连接。第一个命令可能需要一段时间在大项目上（sbt/JVM 启动）。等待超时默认为 180 秒，可以使用 `--autostart-timeout <seconds>` 或 `SBT_MCP_AUTOSTART_TIMEOUT` 进行配置。
- **服务器已经运行** ：sbt-mcp 附加到它，并且永远不会启动第二个服务器。
- **生命周期** ：sbt-mcp 只拥有它启动的服务器。当 MCP 服务器退出 - 正常关闭或 `SIGINT`/`SIGTERM` 从 MCP 主机 - 它关闭该服务器的标准输入，如果需要，杀死其进程组，以便不会留下孤儿 JVM。您自己启动的服务器永远不会被触及。
sbt 的启动输出被转发到 sbt-mcp 的标准错误流（MCP 日志）。
**何时使用哪一个：**
- *默认（仅附加）* - 您在工作时保持一个 `sbt` shell 打开。您实时看到其输出，可以直接在其中运行命令。推荐用于交互式使用。
- *自动启动* - 无头或 CI 环境中，没有其他东西启动 sbt，因此 MCP 服务器必须自己启动（并关闭）它。
## 工具参数
| 参数 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `command` | 字符串 | *必填* | sbt 命令，与在 sbt shell 中输入的完全一样 |
| `directory` | 字符串 | `.` | 包含 `build.sbt` 的项目目录 |
| `tail_lines` | 数字 | `20` | 返回输出的最后 N 行。设置为 0 以禁用。如果设置了 `grep_pattern`，则忽略。 |
| `grep_pattern` | 字符串 | | 使用 `grep -iE` 过滤输出。支持扩展正则表达式，例如 `FAILED\|should\|error`。 |
| `head_lines` | 数字 | `0` | 将 grep 结果限制为前 N 个匹配项。仅在设置 `grep_pattern` 时适用。 |
| `timeout` | 数字 | `300` | 命令超时，单位为秒。 |
## 输出过滤
sbt 输出可能很冗长。该工具过滤输出以减少 token 使用量，镜像常见的 shell 模式：
```sh
# 默认值：最后 20 行（像 sbt "compile" 2>&1 | tail -20）
{"command": "compile", "tail_lines": 20}
# grep 查找失败（像 ... | grep -iE "FAILED|error" | head -20）
{"command": "testOnly com.example.MySpec", "grep_pattern": "FAILED|error", "head_lines": 20}
# 所有输出
{"command": "compile", "tail_lines": 0}
```
## 工作原理
1. 读取 `project/target/active.json` 以发现 sbt 服务器的 Unix 域套接字
2. 连接并执行 LSP `initialize` 握手
3. 通过 `sbt/exec` JSON-RPC 请求发送命令
4. 从 `window/logMessage` 通知中收集输出
5. 使用 `grep`/`tail`/`head` 过滤输出并返回结构化 JSON
连接在工具调用之间持续存在 - 无需重新连接开销。
## 要求
- sbt 1.1+（sbt 服务器支持）
- macOS 或 Linux（Unix 域套接字）
- Go 1.23+（从源代码构建）
## 许可证
Apache License 2.0
