exocommand (Fcannizzaro)

@fcannizzaro/exocommand

An MCP server that exposes user-defined shell commands as tools for AI coding assistants.

概述

Exocommand是一个集中式 主控程序 管理多个项目的服务器，每个项目都有自己的shell命令集，这些命令在 .exocommand YAML文件。您可以向服务器注册项目，并精确控制每个代理可以发现和执行哪些命令，而不是让AI代理不受限制地访问终端。

特性

• 多项目注册表 --注册多个项目，每个项目都有一个唯一的访问密钥。服务器从单个进程管理所有这些。
• TUI仪表板 --在终端中运行时，服务器会显示一个实时仪表板，其中包含项目选项卡、执行卡、状态指示器和动画微调器。
• YAML配置 --在中为每个项目定义命令 .exocommand 带有名称、描述和shell命令的文件。
• 实时重新加载 --服务器监视每个项目的配置文件的更改，并自动通知连接的客户端。
• 流输出 --默认情况下，stdout和stderr通过SSE实时逐行流式传输到客户端。如果服务器在执行过程中崩溃，客户端将保留已接收到的所有行。
• 任务模式 --由MCP实验任务API支持的选择性执行模式，用于无故障、独立轮询的命令执行。
• 取消 --客户端可以取消长时间运行的命令；生成的进程立即被终止。
• 多会话 --使用Streamable HTTP传输，支持跨项目的多个并发MCP会话。

快速开始

1. 创建配置文件 在您的项目目录中（如果已有，请跳过）：

bunx @fcannizzaro/exocommand init

1. 注册项目 通过指向包含以下内容的目录 .exocommand 文件（或直接指向文件）：

bunx @fcannizzaro/exocommand add .

这将验证配置并打印访问密钥：

  ✓ Project registered

    Key     a1b2c3d4e5f6
    Header  exocommand-project: a1b2c3d4e5f6
    Config  /path/to/project/.exocommand

1. 启动服务器：

bunx @fcannizzaro/exocommand

使用 @fcannizzaro/exocommand@latest 始终从npm运行最新版本。

服务器启动于 http://127.0.0.1:5555/mcp 默认情况下。

1. 连接MCP客户端 随着 exocommand-project 设置为访问密钥的标头（请参见 连接AI客户端).

CLI命令

• 注册表存储在 ~/.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: ../

每个顶级键都是一个命令名。名称可以包含字母、数字、连字符和下划线。

环境变量

执行模式

这 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": ""
      }
    }
  }
}

服务器公开了两个工具：

记得告诉代理他们可以使用这些工具在项目上运行命令。例如：

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") \
  # ...

许可证

麻省理工学院