Cuba Exec

🚀 古巴执行官

AI代理的高级shell命令执行 --具有安全策略引擎、进程生命周期管理、有界输出捕获、POSIX信号和令牌高效响应的模型上下文协议（MCP）服务器。

6个工具。零配置。POSIX原生。默认安全。

______________________________________________________________________

为什么选择古巴执行官？

现有的命令执行MCP是精简的包装 subprocess.run.Cuba Exec解决了真正的问题：

______________________________________________________________________

快速开始

1.先决条件

• Python 3.14+
• Linux/macOS （进程组需要POSIX）

2.安装

git clone https://github.com/LeandroPG19/cuba-exec.git
cd cuba-exec
uv venv && uv pip install -e .

3.配置您的AI编辑器

{
  "mcpServers": {
    "cuba-exec": {
      "command": "/path/to/cuba-exec/.venv/bin/python",
      "args": ["-m", "cuba_exec"]
    }
  }
}

无需任何环境变量。零配置文件。它只是正常工作——默认情况下会阻止25个危险命令。

______________________________________________________________________

6工具

run --执行并等待

run(command="ls -la", cwd="/tmp", timeout_ms=5000)

答复：

[exit:0 time:12ms trunc:no]
total 156
drwxrwxrwt 22 root root 4096 Mar  8 2026 .
...

start --后台流程

start(command="npm run dev", cwd="/app")

答复：

[pid:12345 state:running]
Background process started. Use status(12345) to check output.

status --检查后台进程

status(pid=12345, tail_bytes=4096)

答复：

[pid:12345 state:running exit:- time:5432ms bytes:8192 trunc:no]
Server running on http://localhost:3000

send_signal --POSIX信号

send_signal(pid=12345, sig="SIGTERM")

SIGTERM触发器 优雅关闭：SIGTERM→ 等待5秒→ 西格尔。

有效信号： SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT.

send_input --stdin管

send_input(pid=12345, stdin="print('hello')\n")

用于交互式进程（Python REPL、bash提示符等）。

list_processes --流程发现

list_processes()

答复：

[processes:2]
  pid:12345 state:running exit:- time:5432ms bytes:8192 cmd:npm run dev
  pid:12346 state:completed exit:0 time:1200ms bytes:256 cmd:echo done

______________________________________________________________________

🛡️ 安全策略引擎

Cuba Exec包含一个多层安全引擎，是所有MCP命令服务器中最全面的。

安全层

默认行为（零配置）

开箱即用，Cuba Exec阻止25个危险命令：

rm, dd, mkfs, shutdown, reboot, halt, poweroff, init, systemctl,
passwd, chown, chmod, chgrp, mount, umount, fdisk, parted,
iptables, nft, ip6tables, crontab, at, useradd, userdel,
groupadd, groupdel, visudo

生产硬化

export CUBA_EXEC_ALLOWED_COMMANDS="ls,cat,echo,grep,find,head,tail,wc,git,python3,node,npm"
export CUBA_EXEC_BLOCKED_COMMANDS="rm,dd,mkfs,shutdown"
export CUBA_EXEC_ALLOWED_DIRS="/home/user/project,/tmp"
export CUBA_EXEC_AUDIT=1

壳牌操作员旁通预防

ls && rm -rf / --the rm 之后 && 也根据blocklist/allowlist进行验证。

已解析的运算符： ;, &&, ||, | --每个子命令都独立检查。

审核日志（stderr）

{"ts":"2026-03-08T15:00:00-0600","event":"exec","command":"ls -la","pid":12345,"exit":0,"ms":12,"ok":true}

______________________________________________________________________

输出格式（TOON）

所有响应都使用面向令牌的对象表示法——紧凑的标头，与冗长的JSON相比，每次工具调用可节省约200个令牌。

[exit:0 time:1543ms trunc:no]
...output...

错误代码

______________________________________________________________________

头+尾输出缓冲器——香农（1948）

命令输出已 极端情况下的高熵 （前序+结果/错误）和中间的低熵（进度条、重复日志）。

┌─────────────┬───────────────────────────────┬──────────────────────────────────────────┐
│  Head (25%) │        Truncated middle       │                Tail (75%)                │
│  ~16KB      │   [... N bytes truncated ...] │                ~48KB (ring buffer)       │
└─────────────┴───────────────────────────────┴──────────────────────────────────────────┘

• 头部：缓冲区的前25%——捕获标头、版本信息
• 尾部：最后75%通过环形缓冲区捕获结果、错误（最高熵）
• 环形缓冲区：O（1）写，O（C）存储器（Cormen等人，CLRS第4版）
• 默认：每个进程64KB。最大内存：20×64KB=1.28MB

______________________________________________________________________

POSIX过程组——IEEE标准1003.1

npm run dev 生成子进程。向父母发送SIGTERM不会杀死孩子。

Cuba Exec通过以下方式创建流程组 setsid:

asyncio.create_subprocess_exec(..., start_new_session=True)
os.killpg(os.getpgid(pid), signal.SIGTERM)  # Kills entire tree

优雅地关闭

SIGTERM → wait 5s → SIGKILL (if still alive)

两阶段关机（Stevens&Rago，2013）：SIGTERM允许清理，SIGKILL是不可捕捉的。

______________________________________________________________________

配置

所有默认值都是开箱即用的。通过环境变量进行覆盖：

______________________________________________________________________

建筑

cuba-exec/
├── pyproject.toml            # 1 dependency: fastmcp
└── src/
    └── cuba_exec/
        ├── __init__.py
        ├── __main__.py        # Entry point
        ├── server.py          # FastMCP 6 tool definitions (~105 LOC)
        ├── security.py        # SecurityPolicy engine (~135 LOC)
        ├── process_manager.py # Lifecycle FSM + signals + TTL (~520 LOC)
        └── output_buffer.py   # Head+Tail ring buffer (~110 LOC)

总计：约880 LOC。 FastMCP SDK处理协议样板。

依赖关系（共1个）

其他都是Python stdlib： asyncio, os, signal, time, json, re, pathlib.

______________________________________________________________________

古巴生态系统的一部分

一起： 记忆+推理+搜索+执行 --有能力的人工智能代理的四大支柱。

______________________________________________________________________

学术参考文献

______________________________________________________________________

许可证

CC BY NC 4.0 --免费使用和修改， 非商业用途.

______________________________________________________________________

作者

莱安德罗·佩雷斯G。

• github： @LeandroPG19
• 电子邮件： leandropatodo@gmail.com