@fcannizzaro/exocommand
An MCP server that exposes user-defined shell commands as tools for AI coding assistants.
](https://github.com/fcannizzaro/exocommand/actions/workflows/publish.yaml) ](https://www.npmjs.com/package/@fcannizzaro/exocommand)
概述
Exocommand是一个集中式 主控程序 管理多个项目的服务器，每个项目都有自己的shell命令集，这些命令在 .exocommand YAML文件。您可以向服务器注册项目，并精确控制每个代理可以发现和执行哪些命令，而不是让AI代理不受限制地访问终端。
特性
- 多项目注册表 --注册多个项目，每个项目都有一个唯一的访问密钥。服务器从单个进程管理所有这些。
- TUI仪表板 --在终端中运行时，服务器会显示一个实时仪表板，其中包含项目选项卡、执行卡、状态指示器和动画微调器。
- YAML配置 --在中为每个项目定义命令
.exocommand带有名称、描述和shell命令的文件。 - 实时重新加载 --服务器监视每个项目的配置文件的更改，并自动通知连接的客户端。
- 流输出 --默认情况下，stdout和stderr通过SSE实时逐行流式传输到客户端。如果服务器在执行过程中崩溃，客户端将保留已接收到的所有行。
- 任务模式 --由MCP实验任务API支持的选择性执行模式，用于无故障、独立轮询的命令执行。
- 取消 --客户端可以取消长时间运行的命令；生成的进程立即被终止。
- 多会话 --使用Streamable HTTP传输，支持跨项目的多个并发MCP会话。
快速开始
- 创建配置文件 在您的项目目录中（如果已有，请跳过）：
bunx @fcannizzaro/exocommand init- 注册项目 通过指向包含以下内容的目录
.exocommand文件（或直接指向文件）：
bunx @fcannizzaro/exocommand add .这将验证配置并打印访问密钥：
✓ Project registered
Key a1b2c3d4e5f6
Header exocommand-project: a1b2c3d4e5f6
Config /path/to/project/.exocommand- 启动服务器：
bunx @fcannizzaro/exocommand使用 @fcannizzaro/exocommand@latest 始终从npm运行最新版本。服务器启动于 http://127.0.0.1:5555/mcp 默认情况下。
- 连接MCP客户端 随着
exocommand-project设置为访问密钥的标头（请参见 连接AI客户端).
CLI命令
| 命令 | 描述 |
|---|---|
exocommand | 启动MCP服务器。 |
exocommand init | 创建示例 .exocommand 当前目录中的配置文件。如果文件已存在，则出现错误。 |
| `exocommand add | |
| ` | 注册一个项目。接受目录（自动解析 .exocommand 内部）或直接文件路径。验证配置并打印访问密钥。 |
exocommand ls | 列出所有已注册的项目及其访问密钥和配置路径。缺失的配置已被标记。 |
exocommand rm | 按访问密钥或文件系统路径删除项目。 |
- 注册表存储在
~/.exocommand/exocommand.db.json. - 访问密钥是12个字符的十六进制字符串。
- 重新添加已注册的路径将返回现有密钥（无重复项）。
配置
创建一个 .exocommand 项目根目录中的文件：
build:
description: "Run the production build"
command: "cargo build --release"
clippy:
description: "Run clippy linter"
command: "cargo clippy"
list-external:
description: "List files in parent directory"
command: "ls -a"
cwd: ../每个顶级键都是一个命令名。名称可以包含字母、数字、连字符和下划线。
| 字段 | 必填 | 描述 |
|---|---|---|
description | 是 | 命令的作用是什么。 |
command | Yes | 要运行的shell命令。 |
cwd | 否 | 命令的工作目录。相对路径从配置文件的目录中解析。 |
环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
EXO_PORT | 服务器端口 | 5555 |
EXO_TASK_MODE | 启用任务模式(true 或 1) | false |
执行模式
这 execute 该工具支持两种执行模式：
流媒体（默认） --每一条输出线都会在响应流上作为SSE事件发送。客户端实时接收线路。如果服务器在执行过程中崩溃，则发送到该点的所有行都已包含在客户端中。取消通过标准MCP请求信号（客户端断开连接或 notifications/cancelled).
任务模式 --通过启用 EXO_TASK_MODE=true.使用实验MCP任务API。服务器创建一个后台任务，客户端可以独立轮询其状态。任务感知客户端具有完全的崩溃恢复能力（断开连接、重新连接和恢复轮询）。支持通过以下方式进行结构化取消 tasks/cancel.
连接AI客户端
将任何兼容MCP的客户端指向服务器 /mcp 终点。客户必须包括 exocommand-project 初始化请求上带有项目访问密钥的标头。
例如，与 开源代码:
{
"mcp": {
"exocommand": {
"enabled": true,
"type": "remote",
"url": "http://host.docker.internal:5555/mcp",
"headers": {
"exocommand-project": ""
}
}
}
}服务器公开了两个工具：
| 工具 | 说明 |
|---|---|
listCommands() | 返回项目配置文件中的所有可用命令。 |
execute(name, timeout?) | 按名称执行命令，将输出流式传输回客户端。可选 timeout （以秒为单位）在给定的持续时间后终止进程并返回缓冲输出。 |
记得告诉代理他们可以使用这些工具在项目上运行命令。例如：
You can run predefined shell commands using the `listCommands()` and `execute(name, timeout?)` tools. Use `listCommands()` to see all available commands, and `execute(name, timeout?)` to run a specific command, with an optional timeout in seconds.安全
在Docker中运行代理时，挂载 .exocommand 将文件设置为只读卷，以防止代理修改它们。
如果使用脚本启动容器化代理，则可以自动装载 .exocommand 文件存在于启动目录中时：
docker run \
# ...
$([ -f "$PWD/.exocommand" ] && echo "-v $PWD/.exocommand:$PWD/.exocommand:ro") \
# ...