# Copilot CLI

XMEMO_KEY と安定したインスタンス帰属を使用して、直接ベアラートークンの Copilot CLI MCP クライアントを構成します。

- Canonical: https://docs.xmemo.dev/ja/docs/mcp/copilot-cli
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 3d18b1df6bc7de8f1e1af14a294640eb5bf7a2d0176a2523f2f62b790b975e99
- Edition-Digest: 972d02c10fdcda8fae98ec621e15bd7ae42f069526341618f27af4536161a0e5
- Source-Revision: sha256:96e19501d8a5b0d1cc66043cdcd452344580fd7ffafd84f8562409ac6df29e12

## 前提条件

MCP 構成をサポートする GitHub Copilot CLI を使用します。このルートは、VS Code / GitHub Copilot Chat の OAuth ルートとは意図的に分離されています。Copilot CLI は、~/.copilot/mcp-config.json でのカスタム HTTP ヘッダー、または memory-os-cli を介したローカルプロキシ接続をサポートしています。

- エンドポイント: https://xmemo.dev/mcp。
- トランスポート: Streamable HTTP (構成内の type: "http") またはローカルプロキシ (xmemo mcp proxy)。
- 認証モード: Copilot の公式 MCP UI/CLI またはサポートされているシークレット参照を介して Authorization を適用します。ヘッダー値での環境変数の展開 (${env:…}) を想定しないでください。
- 構成ファイル: ~/.copilot/mcp-config.json。
- 準備状況: Copilot CLI ヘッダーでの直接的な環境変数の展開は not-tested です。ローカルプロキシパスは memory-os-cli の MCP-SETUP-GUIDE.md 経由で検証されています。

## インストール / セットアップ

XMemo サーバーブロックを ~/.copilot/mcp-config.json の mcpServers の下に追加するか、memory-os-cli ローカルプロキシ経由で実行します。VS Code の servers キーエントリを再利用しないでください。Copilot CLI は異なるクライアントパスです。

- ダイレクトリモート HTTP: ~/.copilot/mcp-config.json に type: "http", url: "https://xmemo.dev/mcp", timeout: 30000, および tools: ["*"] を指定して XMemo ブロックを追加します。
- ローカルプロキシパス: xmemo setup copilot を実行し、バックグラウンドターミナルで xmemo mcp proxy を実行し続けます (memory-os-cli MCP-SETUP-GUIDE.md に準拠)。
- ヘッダー内の直接環境変数展開 (${env:XMEMO_KEY}) は not-tested であり、Core テンプレートではサポートされていません。

```bash
# Local proxy path (recommended if direct remote HTTP is unsupported):
xmemo login
xmemo setup copilot
xmemo mcp proxy  # keep running in a background terminal
```

## 認証情報を設定する

Copilot の公式 MCP UI/CLI またはサポートされているシークレット参照を使用して Authorization ヘッダー値を設定します (<replace-with-XMEMO_KEY-or-supported-secret-reference> を実際のトークンに置き換えます)。ローカルプロキシを使用する場合、xmemo login が認証情報を自動的に管理します。

```bash
# For local proxy:
xmemo login
# For direct configuration, apply token through Copilot CLI or supported secret reference
```

## XMEMO_AGENT_INSTANCE_IDを生成 / 確認する

ローカルのCopilot CLI installごとに秘密ではない値を1つ生成し、gitの外に保存して再起動後も再利用します。これによりattributionが安定します。

```bash
export XMEMO_AGENT_INSTANCE_ID='<stable-local-copilot-cli-instance-id>'
# Persist and reuse this value for the same local install
```

## 既存の構成ブロックを保持する

Core のテンプレート (mcp_config.py:267) に一致する正規の Copilot CLI XMemo 構成ブロックを使用します。Copilot の公式 MCP UI/CLI またはサポートされているシークレット参照を介して実際の Authorization 値を適用します。未検証の ${env:XMEMO_KEY} ヘッダー展開に依存しないでください。

```json
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp",
      "tools": [
        "*"
      ],
      "timeout": 30000,
      "headers": {
        "Authorization": "Bearer <replace-with-XMEMO_KEY-or-supported-secret-reference>",
        "X-Memory-OS-Agent-ID": "copilot-cli",
        "X-Memory-OS-Agent-Instance-ID": "<stable-local-copilot-cli-instance-id>"
      }
    }
  }
}
```

## クライアントを再起動する

mcp-config.json を変更した後に Copilot CLI を再起動します。ローカルプロキシを使用している場合は、Copilot CLI を再起動する前に 'xmemo mcp proxy' がバックグラウンドターミナルで実行され続けていることを確認してください。

## 実際のrecall callでテストする

最初のMCP callはread-onlyにします。これはhealth-check placeholderではなく実際のrecall invocationであり、memoryを書き込みません。

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

## 期待されるresponse（literal shape）

成功したcallは、次の公開ranked text shapeを返します。referenceとcontentは認証済みmemory spaceから得られる実際の値です。

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

## よくあるエラー

Copilot CLI は直接トークンまたはプロキシクライアントです。一般的なエラーは、認証トークン、プロキシのライフサイクル、またはスコープの承認に関連しています。

- 401 invalid_token — XMEMO_KEY が見つからない、期限切れ、取り消された、または展開されていません: アクティブなシークレット参照を確認するか、ローカルプロキシ用に xmemo login を再実行してください。
- 403 insufficient_scope — トークンが付与する権限に memory:read が含まれていません: 必要なスコープを持つトークンを発行してください。
- Connection refused — ローカルプロキシを使用している場合は、xmemo mcp proxy がバックグラウンドターミナルで実行されていることを確認してください。
- ヘッダーでリテラル '${env:XMEMO_KEY}' が送信される — Copilot CLI はヘッダー値内の環境変数を展開しない場合があります。シークレット参照またはローカルプロキシを使用してください。
- 無効な XMEMO_AGENT_INSTANCE_ID の値は、認証エラーを発生させるのではなく、インスタンス帰属なしとして正規化されます。

## Copilot CLI

Direct client: set XMEMO_KEY in the user environment or a supported secret reference, then replace the stable instance placeholder before applying the reviewed config.

```
{
  "mcpServers": {
    "XMemo": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}
```