jocay
130 lines
5.7 KiB
Markdown
130 lines
5.7 KiB
Markdown
# bolt — 极速单文件 MCP 命令执行服务器
|
|
|
|
让 AI(Claude Code / Claude Desktop / Cursor 等 MCP 客户端)通过 **MCP 协议**连接后,在服务器上执行 shell 命令。
|
|
|
|
- **单文件**:全部代码在 `src/main.rs`(约 1900 行,其中 400 行为单元测试),仅依赖 `serde_json`(Unix 下加 `libc`)
|
|
- **零框架**:手写 JSON-RPC 2.0 + MCP 协议 + Streamable HTTP 服务器,无 async runtime、无重量级依赖
|
|
- **双传输**:`stdio`(本地 AI 客户端默认)与 `Streamable HTTP`(远程连接)
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
cargo build --release # 产物: target/release/bolt (~1MB)
|
|
```
|
|
|
|
**本地模式(stdio)**:由 MCP 客户端拉起本进程
|
|
|
|
```bash
|
|
# Claude Code
|
|
claude mcp add --transport stdio bolt -- /abs/path/to/bolt
|
|
|
|
# 或通用 MCP 客户端配置
|
|
# {"mcpServers": {"bolt": {"command": "/abs/path/to/bolt"}}}
|
|
```
|
|
|
|
**远程模式(Streamable HTTP)**:AI 通过网络连接
|
|
|
|
```bash
|
|
bolt --http 127.0.0.1:8080 # 仅本机
|
|
bolt --http 0.0.0.0:8080 --token mysecret # 对外 + Bearer 认证
|
|
bolt --http 0.0.0.0:8080 --token mysecret --allow "git,docker,curl"
|
|
|
|
# Claude Code 连接远程
|
|
claude mcp add --transport http bolt http://127.0.0.1:8080/mcp
|
|
```
|
|
|
|
## 工具
|
|
|
|
| 工具 | 说明 |
|
|
|---|---|
|
|
| `run_command` | 执行 shell 命令:完整 shell 语法(管道/重定向/`&&`)、`cwd`、`env`、`timeout_ms`(超时自动杀进程树)、`max_output_bytes`(输出截断防膨胀)、`shell=false` 直接执行二进制;客户端可传 `_meta.progressToken` 接收进度通知,支持 `notifications/cancelled` 取消 |
|
|
| `shell_open` | 开启持久化交互式 shell 会话(`cd`、环境变量等状态跨次保留),可指定 `shell`(sh/bash/zsh/fish)与 `cwd` |
|
|
| `shell_write` | 向会话写入输入(自动补换行) |
|
|
| `shell_read` | 读取会话新输出,可阻塞等待(`timeout_ms`,0 = 等到会话退出) |
|
|
| `shell_close` | 关闭并杀掉会话进程树 |
|
|
|
|
`run_command` 返回:`exit_code` / `signal` / `timed_out` / `cancelled` / `duration_ms` / `stdout` / `stderr` / 截断标志等(同时提供 `content` 与 `structuredContent`)。
|
|
|
|
## 配置
|
|
|
|
CLI 参数(环境变量 `BOLT_*` 为回退):
|
|
|
|
| 参数 | 默认 | 说明 |
|
|
|---|---|---|
|
|
| `--http <addr>` | 无(stdio) | 启用 Streamable HTTP 监听地址,如 `127.0.0.1:8080` |
|
|
| `--token <t>` | 无 | HTTP 要求 `Authorization: Bearer <t>` |
|
|
| `--allow <a,b>` | 空 | 命令白名单(命令首词前缀匹配;非空时仅允许列表内命令) |
|
|
| `--deny <a,b>` | 空 | 命令黑名单(前缀匹配) |
|
|
| `--timeout-ms <n>` | 30000 | 命令默认超时(工具参数可覆盖,0 = 无限) |
|
|
| `--cwd <dir>` | 当前 | 命令默认工作目录 |
|
|
| `--max-output <n>` | 1M | 单流输出捕获上限(支持 K/M/G) |
|
|
| `--allow-origin <url>` | localhost/127.0.0.1 | 额外允许的 HTTP Origin(防 DNS rebinding) |
|
|
|
|
```bash
|
|
export BOLT_TOKEN=xxx BOLT_ALLOW="git,docker" BOLT_TIMEOUT_MS=60000
|
|
bolt --http 127.0.0.1:8080
|
|
```
|
|
|
|
## 协议实现(2025-06-18 规范)
|
|
|
|
- `initialize`(协议版本协商,支持 2024-11-05 / 2025-03-26 / 2025-06-18)、`ping`、`tools/list`、`tools/call`、`shutdown`
|
|
- `notifications/initialized`、`notifications/cancelled`、`notifications/exit`、`notifications/progress`(进度上报)
|
|
- 工具执行错误以 `isError: true` 返回;协议错误返回标准 JSON-RPC 错误码(-32601/-32602/-32700 等)
|
|
- Streamable HTTP:POST 请求(通知 → 202;请求 → JSON 或 SSE 响应)、GET 长连接 SSE 流(服务器通知广播 + 10s 心跳)、CORS、Origin 校验、Bearer 认证、无状态(不要求会话 ID)
|
|
|
|
## 性能
|
|
|
|
- 单线程事件循环 + 复用缓冲区,无锁热路径;输出计数用原子操作,进度推送不占主循环
|
|
- 子进程独占进程组(`setpgid`),超时/取消按进程组 `SIGKILL`,连带杀掉整棵进程树,无僵尸
|
|
- 实测(本机,含 Python 客户端逐字节 I/O 开销):
|
|
- ping 往返吞吐 ≈ **14,700 msg/s**
|
|
- 并发 `echo` 命令平均 **4.7 ms/次**(进程 spawn + 捕获输出)
|
|
- 构建配置:`lto = "fat"`、`codegen-units = 1`、`strip = true`,二进制约 0.7MB
|
|
|
|
## 测试
|
|
|
|
```bash
|
|
cargo test --release # 8 个单元测试(协议分发/策略/HTTP 解析/执行引擎/会话)
|
|
```
|
|
|
|
集成测试脚本在 `docs/`(stdio 12 项、HTTP 19 项,覆盖超时/取消/进程树/进度/并发/auth/Origin):
|
|
|
|
```bash
|
|
python3 /tmp/bolt_stdio_test.py # stdio 端到端
|
|
python3 /tmp/bolt_http_test.py # HTTP 端到端
|
|
```
|
|
|
|
## 安全说明
|
|
|
|
- 默认只接受本机连接(`127.0.0.1`),对外公开需显式 `0.0.0.0` + `--token`
|
|
- 该服务器等于远程 root shell 入口,务必配置白名单(`--allow`)与认证后再暴露公网
|
|
- Unix 下命令在独立进程组运行,取消/超时会连带杀掉子进程
|
|
|
|
## 平台
|
|
|
|
- Linux / macOS(完整功能:进程组杀、信号处理)
|
|
- Windows(基础功能:`cmd /C`、`taskkill /T` 杀进程树;无信号优雅退出)
|
|
## systemd 服务部署(开机自启)
|
|
|
|
仓库内 `deploy/` 提供现成的部署文件:
|
|
|
|
```bash
|
|
sudo install -m 0755 target/release/bolt /usr/local/bin/bolt
|
|
sudo cp deploy/bolt.service /etc/systemd/system/
|
|
sudo cp deploy/bolt.env.example /etc/bolt.env # 按需修改(监听地址在 service 文件 ExecStart)
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable --now bolt # 开机自启 + 立即启动
|
|
```
|
|
|
|
常用管理命令:
|
|
|
|
```bash
|
|
systemctl status bolt # 查看状态
|
|
systemctl restart bolt # 重启(改完配置后)
|
|
systemctl stop bolt # 停止
|
|
systemctl disable bolt # 取消开机自启
|
|
journalctl -u bolt -f # 实时查看日志
|
|
```
|
|
|
|
特性:崩溃自动重启(`Restart=on-failure`,2 秒间隔)、优雅停机(SIGTERM 时杀掉所有子进程树)、日志进 journald、`LimitNOFILE=65536`。默认监听 `127.0.0.1:8080`,对外暴露前务必在 `/etc/bolt.env` 设置 `BOLT_TOKEN`。
|