GitHub Copilot

Why this agent

GitHub Copilot(VS Code 扩展形态,跟 GitHub Copilot CLI 不同)是 Microsoft 内嵌在 VS Code 的 AI 编程伙伴。从 VS Code 1.99(2025 年 4 月)起,MCP 是 VS Code 内核原生支持 —— Copilot Chat 扩展消费的是共享的 mcp.json,任何 VS Code MCP host 都读同一份。参考: microsoft/vscode-docs/docs/copilot/reference/mcp-configuration.md。

本页的 install 片段同时把 espctl 接进 Continue、Cline 以及任何其他你装了的 VS Code MCP host —— VS Code 是注册表,扩展是消费者。

Prerequisites

VS Code 1.99 或更高版本,启用了 GitHub Copilot Chat 扩展,有有效 Copilot 订阅。
espctl 已安装在磁盘上某个稳定位置。
(可选,用于远程构建)Aegis 构建服务器地址 + MCP_AUTH_SECRET。

Install snippet (or alternative)

在工作区根目录新建 .vscode/mcp.json(或者通过 Command Palette → MCP: Open User Configuration 打开用户配置文件):

{
  "servers": {
    "espctl": {
      "type": "stdio",
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": {
        "CONTROL_BASE_URL": "https://esphome.cloud",
        "MCP_AUTH_SECRET": "your-access-key"
      }
    }
  }
}

替换:

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

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

读取 install://github-copilot 资源。

VS Code 保存文件时自动 picks up,不用重启。验证或单独重启某个 server,用 Command Palette → MCP: Show Installed Servers。

First-run verification

打开 Copilot Chat(Windows/Linux Ctrl+Alt+I,macOS Cmd+Ctrl+I), 问:

你有哪些 espctl 工具?

预期:Copilot 列出 ~40 个 espctl 工具,每次调用前默认弹确认框。

Troubleshooting

VS Code 报 “MCP server failed to start” —— VS Code Output 面板有个 “MCP” 频道,打开看子进程实际 stderr。最常见原因: command 路径不对(必须绝对路径)。
工具列出来了但每次调用返回 “auth required” —— MCP_AUTH_SECRET 缺失或已失效。回到控制面重新签发一份访问密钥再填进配置。

想把密钥放 VS Code secret store,不要明文 env? VS Code mcp.json 支持 inputs: 数组弹窗输入:

{
  "inputs": [
    { "type": "promptString", "id": "mcp-auth-secret", "description": "Aegis MCP auth", "password": true }
  ],
  "servers": {
    "espctl": {
      "type": "stdio",
      "command": "/path/to/espctl",
      "args": ["mcp", "serve"],
      "env": { "MCP_AUTH_SECRET": "${input:mcp-auth-secret}" }
    }
  }
}

想用 HTTP 传输? 把 type:"stdio" + command 块替换成 type:"http"、url:"https://esphome.cloud/mcp/esp-idf"、 headers: { "Authorization": "Bearer ${input:mcp-auth-secret}" }。
想沙箱化? 加 sandboxEnabled: true + sandbox: 块 (仅 macOS/Linux),配 filesystem.allowWrite + network.allowedDomains。完整 schema 见 VS Code MCP 文档。

Tested as-of 2026-05-19

GitHub Copilot (VS Code) 特有注意事项

VS Code MCP 是所有 MCP-host 扩展共享的 —— espctl 一旦写进 mcp.json,Continue、Cline、Roo Code 以及其他装着的 VS Code MCP host 都能看到。本 matrix 不需要为每个扩展再开 install:// 分支。
工作区 mcp.json(.vscode/mcp.json)默认会被 git 跟踪;用户 profile mcp.json 是机器级别。如果项目想限 espctl 只对 ESP-IDF 项目可见,用工作区 scope;如果想让 Copilot 一直能调,用用户 scope。
Copilot CLI(copilot-cli)是另一个产品,有自己独立演进的 MCP 故事 —— 见 Copilot CLI。
Cursor 复用 VS Code 编辑器外壳但不用 VS Code 的 MCP 配置 —— Cursor 有自己的 .cursor/mcp.json(matrix 里 Cursor 已经覆盖了)。

Keyboard shortcuts

ESP-IDF MCP 用户手册