Kilo Code

Why this agent

Kilo Code 是 AI 编程 agent, 有两个形态:VS Code 扩展 (marketplace) 和终端 CLI(@kilocode/cli)。两个形态共享同一套 MCP schema —— 一份 install 片段适用两端。

Prerequisites

下面任一/全部:

• 安装了 Kilo Code 扩展的 VS Code。
• Kilo CLI 已安装:npm install -g @kilocode/cli;kilo --version 能跑。
• espctl 已安装在磁盘上某个稳定位置。
• (可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

Kilo 从 kilo.json(或 kilo.jsonc)读 MCP 服务:

把 mcp.espctl 条目并入:

{
  "mcp": {
    "espctl": {
      "type": "local",
      "command": ["/path/to/espctl", "mcp", "serve"],
      "environment": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      },
      "enabled": true,
      "timeout": 5000
    }
  }
}

替换:

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

同一份片段在 VS Code 扩展和 CLI 都能用 —— Kilo 两端共享 schema (见 kilo-docs/automate/mcp/using-in-cli.md 和 kilo-docs/automate/mcp/using-in-kilo-code.md)。

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

读取 install://kilo-code 资源。

或者用 Kilo CLI 的运行时命令:

kilo mcp add        # 交互式 —— 每个字段都会提示
kilo mcp list       # 看当前注册的服务

First-run verification

cd /path/to/your/esp-idf/project
kilo

在 Kilo 的 TUI / VS Code 聊天里:

你有哪些 espctl 工具?

预期:列出约 40 个 espctl 工具。在 Kilo 的交互式 TUI 里,可以用 /mcps 切换服务开关。

Troubleshooting

• 启动时 kilo.json 解析错 —— 检查 command: 是数组 (不是字符串)、environment:(不是 env)、type: "local" (或 HTTP 走 "remote")。
• 列出了工具但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。
• 想用 HTTP 传输? 把 type: "remote" + url: "https://esphome.cloud/mcp/esp-idf" + headers: { "Authorization": "Bearer your-access-key" }。
• 工具枚举超时 —— 调大 timeout(默认 5000ms)。espctl 工具 枚举一般 <1s,但网络慢或冷启动可能超时。
• 想临时禁用? 把 "enabled": false,不要删整个条目; Kilo 会跳过这个服务。

Tested as-of 2026-05-19

Kilo Code 特有注意事项

• schema 也支持 "type": "remote" 配 url + headers —— 适合让 Kilo 直接走浏览器侧 https://esphome.cloud/mcp/esp-idf HTTP 端点 而不是本地跑 espctl。
• Kilo 有 MCP Server Marketplace —— 社区发布 MCP 服务的索引。 espctl 目前是本地发布(就是这一页);未来可能进 marketplace 也行。
• .jsonc 变体允许注释 —— 适合在配置里给每个服务标注说明。 kilo.json 和 kilo.jsonc 都接受。