使用说明内容（Markdown格式）

Cuba-Exec MCP 服务器使用指南

项目简介

Cuba-Exec 是一个基于 MCP（Model Context Protocol）的后端服务器，提供对外部命令执行、后台进程管理、输出截断以及安全策略控制等能力。通过 FastMCP 框架暴露 6 套工具供 LLM 客户端调用，具备会话管理、访问控制和日志审计等特性，适用于需要向 LLM 客户端提供可控的系统命令执行上下文的场景。

主要功能点

基于 MCP 的服务端实现，暴露多种工具供客户端调用
命令执行工具：run（同步执行并返回结果）、start（后台执行并返回 PID）
后台进程管理工具：status、send_signal、send_input、list_processes
安全策略引擎：命令白/黑名单、目录限制、操作符检查、审计日志
输出缓冲与截断：对 stdout/stderr 进行头尾截取，防止输出超限
进程组与信号管理：使用 setsid 创建新会话，支持 SIGTERM/SIGKILL 等信号
idle 清理与 TTL 机制：定期清理超时闲置的后台进程
审计日志：将执行事件以结构化日志输出到标准错误
依赖最少：依赖 fastmcp 与 stdlib，覆盖常见 MCP 服务器需求

安装步骤

安装前提
- Python 3.11 及以上
- Linux/macOS（POSIX 相关特性用于进程组管理）
获取代码并安装
- 克隆仓库并进入目录
- 创建并激活虚拟环境
- 安装可编辑模式依赖（本仓库使用的包名为 cuba_exec，对应 setup）
运行服务器
- 在虚拟环境中运行：python -m cuba_exec
- 服务器将按环境变量进行配置，默认并发进程数、缓存大小、TTL 等参数可以通过环境变量覆盖
服务器配置（MCP 客户端需要） MCP 客户端需要知道服务器的启动命令与参数，以便与服务器建立连接。以下配置示例用于客户端配置，在客户端侧使用，无需代码： { "server_name": "Cuba-Exec", "command": "/path/to/your/venv/bin/python", "args": ["-m", "cuba_exec"] }

服务器配置（参数含义）

server_name: MCP 服务器的名称，客户端在日志或错误信息中会显示，示例为 Cuba-Exec
command: 启动服务器所使用的执行命令（通常是虚拟环境中的 Python 可执行文件）
args: 启动参数，示例为 -m cuba_exec，表示以模块方式执行 Cuba-Exec 服务

注：以上配置信息用于 MCP 客户端以标准方式启动并连接服务器。MCP 客户端本身不需要对 Cuba-Exec 的源码进行修改。

基本使用方法

通过 MCP 客户端向 Cuba-Exec 服务器发送工具请求，例如：
- run：在指定 shell 中执行命令并返回输出（包含 stdout/stderr，输出可被截断）
- start：后台执行命令，返回 PID，后续可通过 status 查看输出
- status：查看后台进程的状态、退出码以及最近输出
- send_input：向正在运行的进程发送 stdin
- send_signal：对进程组发送 POSIX 信号，支持优雅关停（SIGTERM）和强制结束（SIGKILL）
- list_processes：列出当前正在管理的后台进程及其状态
安全性
- 通过环境变量控制 white/black list、允许目录、是否输出审计日志
- 操作符和分命令的逐子命令校验，避免危险命令被执行
输出
- 使用头部+尾部缓冲，避免长时间输出导致资源耗尽
- 支持截断显示、明确的状态字段和错误信息

主要注意事项

启动时应确保 Python 环境和依赖满足版本要求（Python 3.11+）
生产环境建议通过环境变量开启审计日志、设置允许目录和命令策略等安全措施
服务器内部实现了对进程组的隔离与信号处理，确保长时间运行的后台进程能被正确管理和清理

基本示例流程

客户端向 Cuba-Exec 请求 run 命令，例如执行一个简单的 ls 命令
服务器返回执行结果及相关元信息（exit code、耗时、输出长度、是否截断）
客户端若需要持续输出，可改用 start 启动后台进程，通过 status 持续获取输出
如需终止或重设进程，可使用 send_signal 发送 SIGTERM/SIGKILL，或 send_input 注入输入

Cuba-Exec MCP 服务器