cuemap-mcp

CueMap MCP Server v0.7.5

説明可能で、リポジトリを認識するエージェントメモリを実現するプレミアム MCP ブリッジです。

CueMap の Model Context Protocol（MCP） サーバーです。Claude Desktop、Cursor、Windsurf、Antigravity などの AI コーディングアシスタントが、CueMap エンジンを使ってコードベースのコンテキストをすぐに呼び出せるようにします。

リポジトリへの同意、対応するコンテンツタイプ、呼び出しモード、精度を重視したパラメーターの選択、トラブルシューティングなど、エージェント向けの運用ガイダンスについては、SKILL.md を参照してください。

設定不要のデプロイ

CueMap MCP Server は、インストール後すぐにそのまま使えるよう設計されています。起動すると、CueMap Server の高性能な Rust インスタンスをバックグラウンドで自動的に管理します。v0.7.3 エンジンには、デフォルトで qint8 MiniLM-L3 が、エッジプロファイル用に q4 MiniLM-L3 がバンドルされており、実行時のモデルダウンロードは発生しません。

CueMap CLI を手動でインストールまたは実行する必要はありません。お使いのオペレーティングシステムに対応するコンパイル済みバイナリが、オプションの NPM 依存関係を介して自動的にダウンロードされます。組み込みの起動機能は、Linux x64/ARM64、macOS x64/ARM64、Windows x64 に対応しています。

インストール

# Global installation makes the `cuemap-mcp` command available
npm install -g cuemap-mcp

(注：ローカルの Rust バイナリが含まれるよう、パッケージマネージャーが optionalDependencies をダウンロードする設定になっていることを確認してください。)

エージェントプラグイン

CueMap には、Agent Plugins 対応クライアント用の別パッケージ cuemap-agent-plugin も用意されています。このパッケージには、ポータブルな plugin.json マニフェスト、stdio 用の mcp.json 設定、リポジトリメモリ用のスキルがバンドルされています。このプラグインは同じリリースバージョンの MCP サーバーを起動します。cuemap-mcp とは別にインストールまたはダウンロードする必要があります。

設定（環境変数）

デフォルトでは、組み込みエンジンはポート 8735 で実行されます。MCP 設定で次の環境変数を渡すことで、サーバーの動作をカスタマイズできます。

• CUEMAP_PORT：組み込みエンジンがバインドするポートを上書きします（デフォルト：8735）。
• CUEMAP_CONFIG_PATH：高度なエンジン調整、バックグラウンドジョブ、RAG 検索パラメーターを設定するための、カスタム server_config.toml の絶対パスです。
• CUEMAP_URL：組み込みエンジンを使わず、リモートでホストされている CueMap サーバー、または別途実行中の CueMap サーバーに接続する場合は、その URL を指定します（例：http://localhost:8735）。
• CUEMAP_PROJECT：デフォルトのプロジェクトを上書きします。この設定がない場合、CueMap は現在の Git リモートまたは作業ディレクトリから、リポジトリに紐づく安定したプロジェクトを導出します。
• CUEMAP_LOG_PATH：組み込みエンジンのログパスを上書きします。デフォルトは ~/.cuemap/server.log で、cuemap logs が読み込むファイルです。

サーバーのライフサイクル

Codex がプラグインプロセスを起動すると、CueMap のツールが呼び出される前に、MCP サーバーは EmbeddedCueMap.start() を呼び出します。CUEMAP_URL または設定済みポートで互換性のあるエンジンがすでに待ち受けている場合はそれに接続し、待ち受けていない場合はローカルエンジンを自動的に起動して管理します。cuemap_init はサーバーを起動しません。エンジンの準備が整った後、確認済みのリポジトリスコープをプレビューまたは適用します。MCP プロセスが管理するエンジンは、そのプロセスの終了時に正常に停止します。

AI エージェントでの使用

この MCP サーバーを AI アシスタントで使用するには、アシスタントの MCP 設定ファイルに追加してください。

設定例（Claude Desktop）

{
  "mcpServers": {
    "cuemap": {
      "command": "npx",
      "args": [
        "-y",
        "cuemap-mcp"
      ],
      "env": {
        "CUEMAP_PORT": "8735"
      }
    }
  }
}

利用可能なツール

• cuemap_init_preview：リポジトリのメタデータを読み取り専用でスキャンし、対応しているトップレベルフォルダー／ルートファイル、件数、安定したリポジトリのプロジェクト ID、既存の保存済みスコープを返します。取り込みの前に、このプレビューをユーザーに提示します。

  • path (string)：リポジトリのルートへの絶対パスです。
  • projectName (string, optional)：プロジェクト ID の上書き指定です。デフォルトでは、リポジトリに紐づく安定した ID が使用されます。
  • includedPaths (string[], optional)：プレビューする、リポジトリ相対のファイルまたはフォルダーです。空の場合は、無視ルールで許可されたすべての対応ファイルが対象になります。
  • ignoredPatterns (string[], optional)：追加の gitignore 形式の除外パターンです。
  • ignoredExtensions (string[], optional)：追加の除外対象拡張子です。

• cuemap_init：ユーザーが確認したリポジトリの取り込みスコープを適用し、初回スキャンを開始します。また、新規、変更、削除されたファイル、および新たに無視対象となったファイルや無視対象でなくなった対応ファイルを、そのスコープについて継続的に監視します。取り込み処理のアクティビティを確認し、ジョブが終端フェーズに達し、意図のアノテーションが完了した後にのみ、確認済みの完了を報告します。初期状態が idle で書き込みが 0/0 の場合は、完了とみなしません。

  • path (string)：リポジトリのルートへの絶対パスです。
  • projectName (string, optional)：プロジェクト ID の上書き指定です。デフォルトでは、リポジトリに紐づく安定した ID が使用されます。
  • includedPaths (string[], optional)：ユーザーが承認した、リポジトリ相対のファイルまたはフォルダーです。空の場合は、無視ルールで許可されたすべての対応ファイルが対象になります。
  • ignoredPatterns (string[], optional)：追加の gitignore 形式の除外パターンです。
  • ignoredExtensions (string[], optional)：追加の除外対象拡張子です。
  • confirmed (boolean)：プレビューされたスコープについてユーザーが明示的に確認した後にのみ、true にする必要があります。

• cuemap_status：プロジェクトごとのバックグラウンド取り込みの進行状況と、そこから導出された監視フィールドを返します。verified_complete が true になるまで、cuemap_init の後にポーリングしてください。

  • project (string, optional)：プロジェクト ID の上書き指定です。デフォルトでは、リポジトリに紐づく安定した ID が使用されます。
  • active：現在のフェーズが終端フェーズではない、または保留中の書き込み／意図のアノテーションが残っているかどうかを示します。
  • observed_activity：この MCP プロセスが、プロジェクトについてアクティブなフェーズ、または正の書き込み数／意図数を確認したかどうかを示します。
  • pending_writes：最新の合計値に基づく、残りの書き込み数です。
  • pending_intents：残りのメモリー意図アノテーション数です。
  • verified_complete：アクティビティが確認され、プロジェクトが done または idle に達し、失敗した作業や保留中の作業がなく、intent_ready が false ではない場合にのみ true になります。

プロジェクトの確認とメモリのライフサイクル

• cuemap_projects：各プロジェクトが現在 RAM にロードされているかどうかを含む、プロジェクトの一覧と概要メタデータを表示します。
• cuemap_project_load：レイテンシが重視される操作の前に、永続化されたプロジェクトを明示的にウォームアップします。通常のプロジェクトリクエストでは、必要に応じてオンデマンドでロードされます。
• cuemap_project_save：プロジェクトをアンロードせずに、現在のスナップショットを永続化します。
• cuemap_project_unload：プロジェクトを永続化してアンロードし、メモリ使用量を削減します。作業が進行中の場合、再試行可能なビジー応答が返されることがあります。
• cuemap_project_pack / cuemap_project_package_load：クエリですぐに利用できるローカルの .cuemap パッケージを書き出す、またはロードします。
• cuemap_project_push / cuemap_project_pull：エンジンホストに設定された AWS CLI を使用して、S3 経由でパッケージを転送します。
• cuemap_project_sync：不変の S3 履歴をファストフォワードで同期し、履歴の分岐を拒否します。
• cuemap_stats：リポジトリプロジェクトの統計情報を取得します。global: true を指定すると、エンジン全体の統計情報を取得します。
• cuemap_memory_get：数値の memory_id と所有する project を指定して、1 つのメモリをデコード済みテキストおよび出所情報とともに取得します。GET /memories/:id?decoded=true に対応したエンジンが必要です。古いエンジンでは、このツールからアップグレードエラーが返されます。
• cuemap_memory_reinforce：1 つのメモリを強化します。任意で cues を明示的に指定できます。
• cuemap_memory_delete：1 つのメモリを完全に削除します。ユーザーによる明示的な確認の後、confirmed: true が必要です。
• cuemap_project_export：コンテンツ、キュー、メタデータの含有を設定し、カーソルベースのページネーションでプロジェクトのページをエクスポートします。
• cuemap_project_artifacts：再ロードせずに CueBridge アーティファクトのメタデータを確認します。

明示的な取り込み

• cuemap_ingest_url：1 つの URL を取り込みます。または、depth と same_domain_only で制御しながら再帰的にクロールします。
• cuemap_ingest_content：ファイル名、ソースキー、メタデータ、構造キュー、セグメンテーション、および生成された各チャンクに 1 つずつ対応する任意の embeddings を指定して、提供されたテキストを取り込みます。
• cuemap_ingest_file：ユーザーが承認したローカルファイルのパスを 1 つ取り込みます。

これらのツールは、明示的な取り込みリクエストに使用します。リポジトリの初期化では、引き続き上記のプレビュー、確認、ウォッチャーのワークフローが使用されます。

エイリアスとレキシコンの管理

• cuemap_alias_list、cuemap_alias_add、cuemap_alias_merge：手動のキューエイリアスを確認および管理します。統合には confirmed: true が必要です。

• cuemap_lexicon_inspect、cuemap_lexicon_graph、cuemap_lexicon_wire、cuemap_lexicon_delete：レキシコンの関係を確認および管理します。削除には confirmed: true が必要です。

• cuemap_add：自然言語のメモリを 1 つ保存します。プロジェクトが存在しない場合は自動的に作成されます。

  • content（string）：保存するメモリの内容です。
  • project（string、任意）：メモリを所有するプロジェクト ID です。デフォルトは、現在のリポジトリを対象とするプロジェクトです。
  • cues（string[]、任意）：メモリに関連付ける明示的なキュー／タグです。
  • metadata（object、任意）：メモリとともに保存する JSON メタデータです。
  • source_key（string、任意）：決定的なアップサート／重複排除に使用する安定したソースキーです。
  • event_time（number、任意）：元のイベントのタイムスタンプを Unix 秒で指定します。デフォルトは取り込み時刻です。
  • embedding（number[]、任意）：事前計算されたメモリの埋め込み表現です。
  • disable_temporal_chunking（boolean、任意）：このメモリの時間的チャンク分割を無効にします。
  • async_ingest（boolean、任意）：取り込みをバックグラウンドで処理し、すぐに応答を返します。

• cuemap_intent_classify：エンジンのローカルなインテントモデルを使用してテキストを分類します。target: "query" または "memory" を受け取り、相対的なインテントスコア、想起／メモリの適格性、信頼度の重み、モデル／分類体系のバージョンを返します。スコアは順位付けのためのシグナルであり、確率として調整された値ではありません。

• cuemap_recall：CueMap 統合ブレインからコードベースに関するコンテキストを想起します。自然言語とセマンティック検索を使用して、関連情報を見つけます。

  • query（string）：検索する自然言語のクエリです。
  • limit（number、任意）：返す結果の最大数です（デフォルト：10）。
  • response_mode（full | preview、任意）：デフォルトは full です。幅広く情報を探す場合は preview を使用します。各ヒットでは、完全な内容ではなく先頭の抜粋が返され、ID とメタデータは保持されます。
  • preview_chars（integer、任意）：プレビューの長さの上限です。100～2000 UTF-16 コード単位（デフォルト：200）です。full モードでは無視されます。メタデータと診断情報には上限が適用されません。
  • projects（string[]、任意）：検索対象を限定するプロジェクト ID のリストです。複数指定すると、プロジェクト横断クエリが可能になります。
  • cues（string[]、任意）：検索対象を絞り込む特定のキュータグです。
  • query_time（string、任意）：v0.7 の時間指定クエリ用のタイムスタンプ、または自然言語による時間指定です。
  • depth（number、任意）：複数ホップ想起の展開深度です（デフォルト：1）。
  • expansion_depth（number または "conversation_round"、任意）：周辺コンテキストの展開方法です（デフォルト："conversation_round"）。1 を超える値を指定すると、関連付けが存在する場合に、近くの親チャンクやソース順のコンテキストが含まれます。展開範囲は expansion_depth - 1 です。"conversation_round" は、メモリにセッション、ターン、ロールのメタデータが含まれる場合（たとえば segmenter: "conversation" を指定して取り込んだ場合）、各結果への返信元のメッセージを先頭に追加します（アシスタントの返信の場合は、そのきっかけとなったユーザーメッセージです）。最上位の結果には、その結果への返信も追加されます（ユーザーメッセージの場合は、アシスタントの回答です）。会話メタデータのないメモリはそのまま返されます。マッチしたメモリだけを返す場合は 1 を指定してください。結果の下位にも表示されるメッセージは重複させずに上位へ移動するため、返される結果が limit より少なくなることがあります。
  • auto_reinforce（boolean、任意）：取得したメモリを自動的に強化します（デフォルト：false）。
  • min_intersection（number、任意）：必要なキューの最小交差数です（デフォルト：0）。
  • explain（boolean、任意）：結果にスコアリングの説明データを含めます（デフォルト：false）。
  • trace_timing（boolean、任意）：v0.7 のタイミング診断情報を含めます。
  • disable_salience_bias（boolean、任意）：顕著性スコアのバイアスを無効にします。
  • disable_alias_expansion（boolean、任意）：クエリ実行時の辞書による同義語の追加を無効にします（デフォルト：true）。
  • parent_fusion（off | auto | force、任意）：チャンクと親の融合モードです。
  • ordered_reconstruction（off | auto | force、任意）：セッションの順序付き再構成モードです。
  • evidence_coverage（off | auto | force、任意）：複数の証拠による網羅モードです。
  • disable_cuebridge_artifacts（boolean、任意）：CueBridge アーティファクトの展開を無効にします。
  • cuebridge_gap_limit（number、任意）：CueBridge のギャップ展開の最大数です。
  • semantic_mode（lexical、semantic、または hybrid、任意）：キューのみの想起、ベクトルによる候補の検出、または語彙候補のローカルなセマンティック再ランキングから選択します。エンジンのデフォルトは hybrid です。

• query_embedding（number[]、任意）：呼び出し元のアプリケーションが埋め込みプロバイダーを管理する場合に、事前計算したクエリベクトルを指定します。

Recall の応答と追加調査

Recall は、MCP の structuredContent と、それに一致する JSON テキストブロックの両方でエンジンの JSON を返します。これは従来の文章のみの形式に代わるものです。特定された各メモリには project_id と memory_id が付与され、メタデータ、ソースの位置情報、要求された診断情報は、エンジンから提供された内容のまま保持されます。明示的なプロジェクトクエリでは、それぞれ独自の results または error を含むプロジェクトブロックが返されることがあり、空のグループも含まれます。スコープを指定しない通常のクエリでは、メモリレコードが results に直接返されます。

保存されたレコードが必要な場合は、ヒットのプロジェクトと ID を cuemap_memory_get で指定します。このツールは、ベクトルや圧縮されたストレージバイトを含まない、読みやすい内容を返します。隣接するチャンクを展開したり、ライブファイルを読み取ったりはしません。Recall がすでに関連するテキストを返している場合は、引用元を開くことを優先してください。追加の Recall では、新たな根拠の不足に対応してください。コーディング調査のワークフローと範囲を限定した Recall の制御については、SKILL.md を参照してください。

幅広く調べる場合は、response_mode: "preview" を渡します。ヒットの content は preview、content_truncated、content_length（UTF-16 コード単位）に置き換えられます。これは先頭部分の抜粋であり、生成された要約やクエリに応じて選択されたスニペットではありません。MCP のどちらの出力形式でも、完全な内容は省略されます。有望なメモリは、プロジェクトと ID を指定して取得するか、ライブソースを読み取ってください。デフォルトは引き続きフルモードです。エンジンは応答を送信する前にプレビューを整形します。これはランキングや検索処理を変更せず、メタデータや診断情報も制限しません。

ライセンス

MCP サーバーパッケージは MIT ライセンスです。オプションのネイティブエンジン依存パッケージは別パッケージです。v0.7.3 以降のエンジンパッケージは Apache-2.0 ライセンスですが、v0.7.3 より前のエンジンパッケージは引き続き BSL-1.1 ライセンスです。MCP サーバーのライセンスについては、LICENSE を参照してください。