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(远程连接)

快速开始

cargo build --release        # 产物: target/release/bolt (~1MB)

本地模式(stdio):由 MCP 客户端拉起本进程

# Claude Code
claude mcp add --transport stdio bolt -- /abs/path/to/bolt

# 或通用 MCP 客户端配置
# {"mcpServers": {"bolt": {"command": "/abs/path/to/bolt"}}}

远程模式(Streamable HTTP):AI 通过网络连接

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)

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

测试

cargo test --release          # 8 个单元测试(协议分发/策略/HTTP 解析/执行引擎/会话)

集成测试脚本在 docs/(stdio 12 项、HTTP 19 项,覆盖超时/取消/进程树/进度/并发/auth/Origin):

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 杀进程树;无信号优雅退出)

在其他设备上部署(最快方式)

单文件二进制已发布到 Gitea Release,配合一键脚本,目标设备(Linux amd64 + systemd)只需两条命令:

# 1. 下载并执行安装脚本(私有仓库下载附件需先 export 下载令牌)
export BOLT_DL_TOKEN=你的Gitea令牌
curl -fsSL https://git.jocay.qzz.io/jocay/bolt/raw/branch/main/deploy/install.sh | sh -s -- --http 0.0.0.0:8080

# 2. 完成(脚本自动:下载二进制 → 装到 /usr/local/bin → 写 /etc/bolt.env 与
#    systemd 单元 → 开机自启 → 启动服务)。看状态:
systemctl status bolt

常用安装参数(全部可选):

参数	含义
--http <addr>	监听地址,默认 127.0.0.1:8080;对外用 0.0.0.0:8080
--token <t>	Bearer 认证令牌(公网必填)
--allow <a,b> / --deny <a,b>	命令白/黑名单
--timeout-ms <n>	默认命令超时
--binary <路径或URL>	跳过下载,用本地已拷贝的二进制(如 scp 过去的)
--no-start / --no-enable	只安装不启动 / 不设开机自启

注意:仓库是私有时,Release 附件下载需要认证 —— export BOLT_DL_TOKEN=你的令牌 后再跑脚本;若目标设备与开发机同网,直接 scp root@开发机:/usr/local/bin/bolt ./bolt 后用 --binary ./bolt 最省事。也可以把仓库设公开,附件即可匿名下载。

systemd 服务部署(手动)

仓库内 deploy/ 提供现成的部署文件:

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                 # 开机自启 + 立即启动

常用管理命令:

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。