Crush

Why this agent

Crush 是 Charm 出品的开源 华丽终端 AI 编程 agent,多模型支持、LSP 集成、原生 MCP 支持(三种 传输:stdio / http / sse)。

Prerequisites

• 已安装 Crush:brew install charmbracelet/tap/crush、 npm install -g @charmland/crush,或其他官方支持的包管理器。 crush --version 能跑。
• espctl 已安装在磁盘上某个稳定位置(下文需要完整路径)。
• (可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

Crush 从 crush.json 配置文件读取 MCP 服务 —— 项目根目录 (./crush.json)或全局(~/.config/crush/crush.json)。把 mcp.espctl 条目并入:

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "espctl": {
      "type": "stdio",
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      },
      "timeout": 120,
      "disabled": false
    }
  }
}

替换:

• /path/to/espctl —— 你电脑上 espctl 程序的完整路径。
• CONTROL_BASE_URL —— 你的 Aegis 构建服务器地址。
• MCP_AUTH_SECRET —— 构建服务器给你的访问密钥。

Crush 支持值的 shell 风格展开:可以用 "$MCP_AUTH_SECRET"(环境变 量查找)或 "$(cat ~/.aegis/token)"(命令替换),不必直接粘贴明文。

或者 —— 拿到预填好的代码片段:

读取 install://crush 资源。

First-run verification

重启 Crush(crush 下次启动会加载新配置)。然后在任意会话里:

你能调用哪些 espctl 工具?

预期:列出约 40 个 espctl 工具。

Troubleshooting

• 启动时 crush.json 解析错 —— Crush 把解析错打到 stderr。 常见原因:顶层 key 应该是 mcp(不是 Claude-Code 风格的 mcpServers);每个 server 的 type 字段必填。
• 列出了工具但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
• 想临时禁用? 把 "disabled": true,而不是删整个条目;Crush 下次启动会跳过这个服务。
• 想限制 Crush 看到哪些 espctl 工具? 在 espctl 条目里加 "disabled_tools": ["tool-name", ...]。

Tested as-of 2026-05-19

Crush 特有注意事项

• Crush 的 MCP 传输支持 HTTP 和 SSE,不只是 stdio。如果你想让 Crush 直接指向浏览器侧 https://esphome.cloud/mcp/esp-idf HTTP 端点 而不是本地跑 espctl server,把片段换成:

  "espctl": {
    "type": "http",
    "url": "https://esphome.cloud/mcp/esp-idf",
    "timeout": 120,
    "disabled": false,
    "headers": {
      "Authorization": "Bearer $MCP_AUTH_SECRET"
    }
  }
  

• Crush 在 command、args、env、headers、url 里都支持 shell 展开($VAR、${VAR:-default}、$(cmd))。用 ${MCP_AUTH_SECRET:?set MCP_AUTH_SECRET} 在环境变量未设时直接 在加载时报错,而不是静默用空值。