# Cursor

推奨パスとして Browser OAuth を使用し、サポートされているヘッドレス代替手段としてダイレクト MCP を使用して Cursor IDE を接続します。

- Canonical: https://docs.xmemo.dev/ja/docs/mcp/cursor
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 7fd7191e1dc893d17ccc57d383768ec709f689feebde935e92cbec85252ab1df
- Edition-Digest: d9bf4a5dcdb7ddd47d3b7206787eaedba921ec7cd51457c044b8bb7c5eb04e56
- Source-Revision: sha256:5900c57d4a9131e42571635160707dd33bcf4854c638661503d89ccec7e4bdeb

## 前提条件

設定 -> 機能 -> MCP またはマーケットプレイスサポートを備えた Cursor IDE を使用します。インターフェースと前提条件：

- 具体的なインターフェース: Cursor IDE (~/.cursor/mcp.json または 設定 -> 機能 -> MCP)。
- エンドポイント: https://xmemo.dev/mcp。
- 推奨される認証モード: Browser OAuth。
- フォールバック認証モード: ヘッドレスおよびコンテナ環境用の直接ベアラートークン。
- アカウント: https://xmemo.dev の有効な XMemo アカウント。

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

Cursor 設定 -> 機能 -> MCP を開くか、~/.cursor/mcp.json を構成します。ヘッドレス操作の場合は、ブラウザフローの代わりに環境トークン参照を含む直接構成ブロックを使用します：

- OAuth パス: ホストされた URL のみを構成し、初回使用時にブラウザの同意をトリガーさせます。
- ダイレクトフォールバック: トークンは XMEMO_KEY に保持し、設定ファイルに直接配置しないでください。
- 同じエントリ内で OAuth URL 構成と Authorization ヘッダーを混在させないでください。

## 認証情報を設定する

OAuth パスにはキーは不要です — 初回プロンプトで Browser OAuth を完了します。ダイレクトヘッドレスフォールバックの場合は、シェル環境に XMEMO_KEY を設定し、Cursor 設定にトークン値を貼り付けないでください：

```bash
# OAuth path: no XMEMO_KEY needed (browser prompt)
# Direct fallback:
export XMEMO_KEY='<your-xmemo-token>'
```

## XMEMO_AGENT_INSTANCE_ID を生成 / 確認する

レビュー済みの Cursor OAuth およびダイレクトスニペットは、クライアント側のインスタンスヘッダーを必要としません。ヘッドレスラッパーが XMEMO_AGENT_INSTANCE_ID を提供する場合は、ローカルプロファイルごとに 1 回生成して再利用します。

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

推奨される OAuth パス: ブラウザベースの OAuth 認証には、~/.cursor/mcp.json でレビュー済みの URL のみの Cursor 構成を使用します：

```json
{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## ダイレクトフォールバック構成ブロック

ダイレクトヘッドレスフォールバック: ヘッドレスまたは非対話型環境で Cursor を実行する場合、ローカル環境から ${env:XMEMO_KEY} を参照する Authorization ヘッダーを構成します：

```json
{
  "mcpServers": {
    "xmemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}"
      }
    }
  }
}
```

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

構成を編集した後、変更を有効にするために Cursor を再起動するか、設定 -> 機能 -> MCP で MCP サーバーをオフにしてからオンに切り替えます。

## 実際の recall 呼び出しでテストする

最初の MCP 呼び出しは読み取り専用にします。これはヘルスチェック用のプレースホルダーではなく実際のリコール呼び出しであり、メモリへの書き込みは行いません。

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

## 期待される応答（リテラル形式）

呼び出しが成功すると、以下の公開ランク付けテキスト形式が返されます。参照とコンテンツは、承認されたメモリ空間からの実際の値です。

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

## 最初の有用なタスク：合成メモリライフサイクル

Cursor Composer または Agent モード内で完全な合成メモリタスクを実行します：

- 1. 合成事実の保存: 規則 ("Demo project timestamps use UTC.") を "projects/demo-onboarding/conventions" に記憶するよう Cursor に依頼します。
- 2. ステートレス移行: 新しい Cursor Composer チャットを開始するか、プロジェクトワークスペースを再度開きます。
- 3. 出所帰属付きリコール: "demo project timestamp format" をクエリします。返された Reference と Location を確認します。
- 4. メモリの修正: アクティブな ID を指定して update_memory を呼び出し、タイムスタンプを ISO 8601 でフォーマットします。
- 5. オプションのクリーンアップ: オンボーディングテストが完了したら、メモリ ID を指定して forget を呼び出します。

## 機能とプロファイルツール

Cursor は、cursor-plugin プロファイルの MCP ドキュメント規約で定義されているプロファイル修飾ツールにアクセスできます：

- コアメモリツール: remember, recall, update_memory, forget, read_memory, explain_memory, search_memory, recall_context, search_knowledge。
- スナップショットと競合ツール: create_restart_snapshot, restore_restart_snapshot, list_memory_versions, list_memory_conflicts, resolve_memory_conflict。
- プロジェクトおよび計画ツール: get_mcp_identity, get_project_context, get_timeline, list_memory_todos, complete_memory_todo, create_memory_todo, update_project_decision, update_project_todo, update_state。
- クラウドスキルとガバナンス: recall_cloud_skill, save_cloud_skill, propose_write, propose_todo_mutation, propose_profile_mutation, query_audit, record_event, memory_stats。

## 制限事項と境界

Cursor の運用上の境界と制約：

- 構成の純粋性: 同じサーバーブロック内で OAuth URL のみの構成と Authorization ヘッダーを混在させないでください。
- ワークスペース境界: メモリアクセスは認証されたユーザーのワークスペースに厳密に制限されます。
- ヘッドレストークンの要件: ダイレクト MCP フォールバックには、明示的な環境トークンのプロビジョニングが必要です。

## よくあるエラー

Cursor は、OAuth パスまたはダイレクトヘッドレスフォールバックのいずれかで失敗する可能性があります：

- invalid_grant — OAuth 認可コードが無効、期限切れ、または既に使用されています: Cursor を再接続して再認可してください。
- 401 invalid_token — ダイレクトフォールバックトークンが欠落、期限切れ、または無効です: ヘッドレス環境で XMEMO_KEY を確認してください。
- 403 insufficient_scope — 認証情報が memory:read を許可していません: 必要なスコープを承認するか、そのスコープを持つトークンを発行してください。

## 更新と削除

Cursor のメンテナンス手順：

- 更新: スキーマを再読み込みするには、Cursor MCP 設定でサーバーをオフにしてからオンに切り替えます。
- 削除: ~/.cursor/mcp.json から xmemo エントリを削除するか、Cursor MCP 設定から削除します。

## Cursor

Direct client: configure in ~/.cursor/mcp.json with XMEMO_KEY in the environment. Run npx @xmemo/client mcp add cursor to install automatically.

```
{
  "mcpServers": {
    "XMemo": {
      "url": "https://xmemo.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:XMEMO_KEY}",
        "X-Memory-OS-Agent-ID": "cursor",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}
```