jocaybolt — 极速单文件 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、shutdownnotifications/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杀进程树;无信号优雅退出)
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。