# GitHub Copilot

当宿主支持时，通过托管的 OAuth 配置连接 VS Code 和 GitHub Copilot。

- Canonical: https://docs.xmemo.dev/zh/docs/mcp/copilot
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 89da3a37e97e05ec3cbc29a8fa3f11b3cedd4385b04602234bbe99594d360d2a
- Edition-Digest: d92ccb0911392f82314953d5cdbc5110297225c14d07aab89f8e22dfece36f0d
- Source-Revision: sha256:79ae0e28c58efc497cff8929ba46d7fb7bcfdbf5c9e0b86c939e6f7182cd270b

## 前置条件

使用带有 GitHub Copilot Chat 和 MCP 支持的 VS Code。接口与前置条件：

- 具体接口：带有 GitHub Copilot Chat 扩展的 VS Code (编辑器 OAuth 路径)。
- 配置文件：%APPDATA%\Code\User\mcp.json (Windows)、~/Library/Application Support/Code/User/mcp.json (macOS) 或 ~/.config/Code/User/mcp.json (Linux)。
- 使用 servers 键而不是 mcpServers。
- 端点：https://xmemo.dev/mcp。
- 账户：在 https://xmemo.dev 拥有有效的 XMemo 账户。

## 安装 / 设置

在 servers 键下编辑您的 VS Code 用户配置 mcp.json 并添加托管的 XMemo URL。不要在此处使用 Copilot CLI 配置；其直接路径有其自己的路由 (/docs/mcp/copilot-cli)：

- 编辑器条目仅保留 URL。
- 第一次工具调用将打开浏览器 OAuth。
- 不要在此 VS Code 条目中添加 Authorization 标头。

## 设置凭据

无需密钥 — 在 VS Code / GitHub Copilot Chat 中完成浏览器 OAuth。不要设置 XMEMO_KEY 或将承载令牌粘贴到 mcp.json 中：

```text
No XMEMO_KEY
Complete browser OAuth in VS Code / GitHub Copilot Chat
```

## 生成 / 确认 XMEMO_AGENT_INSTANCE_ID

经过审查的 VS Code OAuth 列表没有客户端身份标头。不要向 mcp.json 添加 XMEMO_AGENT_INSTANCE_ID；确认此 OAuth 路径使用其授权管理的归属。

## 保留现有配置块

使用经过审查的 VS Code / GitHub Copilot 配置块。保留 servers 键和仅包含 URL 的 OAuth 形态；不要将 Copilot CLI 承载配置复制到其中：

```json
{
  "servers": {
    "xmemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## 重启客户端

保存 mcp.json 后重新加载 VS Code 窗口 (Developer: Reload Window) 或重启 MCP 连接，以便 Copilot 读取当前的服务器定义。

## 使用真实的召回调用进行测试

使第一次 MCP 调用为只读。这是实际的召回调用，而不是健康检查占位符，并且它不会写入记忆。

```text
recall({ query: "connection check", limit: 1 })
```

## 预期响应（字面形态）

成功的调用将返回以下公开的排序文本形态；引用和内容是来自授权记忆空间的真实值。

```text
### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>
```

## 首个实用任务：合成记忆生命周期

在 GitHub Copilot Chat 内演练完整的合成记忆任务：

- 1. 保存合成事实：要求 Copilot Chat 记住规范 ("Demo project timestamps use UTC.") 到 "projects/demo-onboarding/conventions"。
- 2. 无状态转换：在 GitHub Copilot 中打开新聊天会话或重新加载 VS Code 窗口。
- 3. 带溯源归属的召回：查询 "demo project timestamp format"。确认返回的 Reference 和 Location。
- 4. 修正记忆：使用 update_memory 将规范更新为 ISO 8601 格式。
- 5. 可选清理：验证结束后，通过 forget 软删除规范。

## 功能与配置文件工具

VS Code 中的 GitHub Copilot 可以访问 MCP 文档契约中为 generic-public 配置文件定义的限定工具：

- 核心记忆工具：remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context。
- 工作区工具：get_mcp_identity, get_project_summary, project, todo, open_project_workspace, open_todo_board, ledger, open_ledger。

## 限制与边界

VS Code 中 GitHub Copilot 的操作边界：

- 工作区隔离：操作严格限制在授权用户的工作区内。
- 编辑器/CLI 隔离：VS Code OAuth 会话不会传播到外部终端工具。
- 不混合标头：不要向 mcp.json 中的 servers 条目添加 Authorization 标头。

## 常见错误

VS Code / GitHub Copilot Chat 使用浏览器 OAuth 路径，不应使用 Copilot CLI 令牌设置进行调试：

- invalid_grant — OAuth 授权码无效、已过期或已被使用：重新连接 VS Code MCP 服务器并再次授权。
- invalid_target — OAuth 资源与此 MCP 服务器不匹配：使用 https://xmemo.dev/mcp 重新连接。
- 403 insufficient_scope — 授权不包括 memory:read：批准所需的范围并重新连接。

## 更新与移除

GitHub Copilot 的维护流程：

- 更新：更新配置后重新加载 VS Code 窗口。
- 移除：从 mcp.json 中移除 xmemo 块并重新加载 VS Code 窗口。

## VS Code / GitHub Copilot

OAuth client: keep only the hosted server URL in mcp.json; first tool call opens browser OAuth, so no XMEMO_KEY or Authorization header belongs in this file.

```
{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```