Cursor Chat History Vectorizer & Dockerized Search MCP

Cursor チャット履歴のベクトル化と Docker 化された検索 MCP

Cursor のチャット履歴をベクトル化し、シンプルな検索 API を通じて提供します。

このプロジェクトでは、次のツールを提供します。

1. ローカルの Cursor IDE データ（ワークスペースストレージ内の state.vscdb ファイル）からチャット履歴を抽出します。
2. ローカルの Ollama インスタンス（nomic-embed-text）を使用して、ユーザープロンプトのテキスト埋め込みを生成します。
3. 抽出したプロンプトとその埋め込みを LanceDB ベクトルデータベースに保存します。
4. シンプルな API エンドポイント経由でこの LanceDB データベースを検索する、Docker 化された FastAPI アプリケーション（このコンテキストでは「MCP サーバー」と呼びます） を含みます。

✨ プロジェクトの目標

主な目標は、次の方法により、Cursor のチャット履歴を検索可能にし、検索拡張生成（RAG）やその他の LLM ベースの分析に利用できるようにすることです。

• ユーザープロンプトをベクトル埋め込みに変換し、LanceDB に効率よく保存します。
• ベクトル化した履歴に対してベクトル類似度検索を実行する、シンプルで使いやすい API サーバーを提供します。

🚀 主な機能

• データの抽出： 指定された Cursor のワークスペースストレージパスから state.vscdb SQLite ファイルをスキャンします。
• プロンプトの抽出： データベースファイル内の aiService.prompts キーからユーザープロンプトを抽出します。
• 埋め込みの生成： ローカルで実行中の Ollama インスタンスを使用して、抽出したプロンプトの埋め込みを生成します。
  • 埋め込みモデル： nomic-embed-embed-text:latest（デフォルトの次元数は 768）。
• ベクトルデータベースへの保存： 元のテキスト、ソースファイル、ロール、ベクトル埋め込みを LanceDB データベースに保存します。
  • LanceDB URI： ./cursor_chat_history.lancedb（抽出スクリプト用）／/data/cursor_chat_history.lancedb（Docker コンテナ内）
  • テーブル名： chat_history
• Docker 化された検索： 高速検索サーバーのコンテナをビルドするための Dockerfile を含みます。
• 高速サーバー（main.py）： 検索リクエストを処理する「MCP サーバー」として機能します。
• エンドポイント：
  • /search_chat_history（POST）：ベクトル類似度検索を実行します。
  • /health（GET）：サーバーの状態と接続（Ollama、LanceDB）を確認します。

📋 必要条件

抽出スクリプト（cursor_history_extractor.py）を実行する場合：

• Python 3.7 以降
• Ollama： Ollama がローカルマシンにインストールされ、実行中であることを確認してください。nomic-embed-text モデルをダウンロードします。

  ollama pull nomic-embed-text:latest
  

• Python パッケージ： 必要なパッケージをインストールします。

  pip install ollama lancedb pyarrow pandas python-dotenv
  

• ファイルアクセス： Cursor のワークスペースストレージディレクトリへの読み取りアクセス（デフォルト：C:\Users\<name>\AppData\Roaming\Cursor\User\workspaceStorage）。

Docker 経由で検索 API（main.py）を実行する場合：

• Docker Desktop（Windows／Mac）または Docker Engine（Linux）。
• Docker コンテナのネットワークからアクセス可能な Ollama インスタンス。
• 抽出スクリプトによって作成済みの LanceDB データベースディレクトリ（./cursor_chat_history.lancedb）。

⚙️ セットアップと設定

処理は次の 2 つの手順で構成されます。

1. 抽出スクリプトを実行して、ホストマシン上に LanceDB データベースを作成または更新します。
2. 検索 API 用の Docker コンテナをビルドして実行し、 手順 1 で作成したデータベースをマウントします。

ステップ 1：データベースの抽出と作成（ホストマシン）

1. プロジェクトをクローン／ダウンロードします：

   git clone https://github.com/markelaugust74/Cursor-history-MCP.git
   cd Cursor-history-API
   

2. 抽出ツールの Python 依存関係をインストールします：

   pip install -r requirements.txt
   

3. パスを確認します（必要な場合）：
   • Cursor のデータがデフォルトの場所にない場合は、cursor_history_extractor.py の WORKSPACE_STORAGE_PATH 変数を更新します。
   • スクリプトを実行するディレクトリへの書き込み権限があることを確認します。./cursor_chat_history.lancedb はここに作成されます。
4. Ollama が実行中であることを確認します： Ollama サーバーを起動し、nomic-embed-text:latest が利用可能であることを確認します（ollama list）。
5. 抽出スクリプトを実行します：

   python cursor_history_extractor.py
   

   このスクリプトは進行状況を表示し、成功すると、ベクトル化された履歴を含む ./cursor_chat_history.lancedb ディレクトリを作成します。

ステップ 2：API の Docker コンテナをビルドして実行する

1. Dockerfile、main.py、およびステップ 1 で作成した ./cursor_chat_history.lancedb ディレクトリがあるプロジェクトディレクトリに 移動します。
2. Docker イメージをビルドします：

   docker build -t cursor-chat-search-api .
   

3. Docker コンテナを実行します：

   docker run -p 8001:8001 \
       -v /path/to/your/cursor_chat_history.lancedb:/data/cursor_chat_history.lancedb \
       -e OLLAMA_HOST="http://host.docker.internal:11434" \
       cursor-chat-search-api
   

   • -p 8001:8001：ホストマシンのポート 8001 を、コンテナ内のポート 8001（FastAPI アプリが実行されるポート）にマッピングします。
   • -v /path/to/your/cursor_chat_history.lancedb:/data/cursor_chat_history.lancedb：これは非常に重要です。 /path/to/your/cursor_chat_history.lancedb を、抽出スクリプトで作成された cursor_chat_history.lancedb ディレクトリのホストマシン上の 絶対パス に置き換えます。これにより、ホスト上のデータベースがコンテナ内の /data/cursor_chat_history.lancedb にマウントされます。この場所は main.py が想定しているパスです。（Docker コマンドでは、Windows でもパスにスラッシュを使用するか、適切にエスケープ／設定してください）。
   • -e OLLAMA_HOST="..."：コンテナ内の OLLAMA_HOST 環境変数を設定します。http://host.docker.internal:11434 は、Docker Desktop からホストに接続する場合によく使用されます。Linux では、別の方法（ホストネットワークモードや、コンテナからアクセスできるホストの IP アドレスの使用など）が必要になる場合があります。
4. FastAPI アプリケーション（「MCP サーバー」）が起動し、http://localhost:8001 からアクセスできるようになります。

▶️ 実行方法

全体的なワークフローは次のとおりです。

1. ホストマシンで python cursor_history_extractor.py を定期的に実行し、./cursor_chat_history.lancedb を作成／更新します。
2. プロジェクトのルート（.lancedb ディレクトリがある場所）から docker run コマンドを実行して、API サーバーを起動します。このサーバーは、ボリュームマウントを通じて LanceDB データベースにアクセスします。

📁 出力

• ./cursor_chat_history.lancedb：抽出スクリプトによって作成される、LanceDB ベクトルデータベースを含むディレクトリです。スキーマには vector（浮動小数点数のリスト）、text（文字列）、source_db（文字列）、role（文字列）が含まれます。
• Docker コンテナ内で実行中の API サーバー。マッピングされたポート（デフォルトは 8001）を通じて外部からアクセスでき、定義済みの API エンドポイントを提供します。

🔌 API の使用方法

Docker コンテナが実行中で、API にアクセスできる状態（例：http://localhost:8001）になったら、API を利用できます。

ヘルスチェック（GET /health）

サーバーの状態と、Ollama および LanceDB への接続を確認します。

curl http://localhost:8001/health

応答例：

{ "status": "healthy", "ollama_connection": "Connected", "lancedb_connection": "Connected and table open" }

検索履歴（POST /search_chat_history）

LanceDB のチャット履歴に対してベクトル類似度検索を実行します。

curl -X POST http://localhost:8001/search_chat_history \
-H "Content-Type: application/json" \
-d '{"query_text": "How do I use Python with data analysis?", "top_k": 5}'

🔍 データベースの直接確認

cursor_history_extractor.py スクリプトの実行後、Python を使用して LanceDB データベースファイルを直接確認できます（Docker コンテナの外部から）。

import lancedb
import ollama # 検索を実行する場合に必要です

# 抽出スクリプトがデータベースを作成した場所に接続します
db = lancedb.connect("./cursor_chat_history.lancedb")

try:
    # テーブルを開きます
    table = db.open_table("chat_history")

    # テーブルのスキーマと内容を確認します
    print("テーブルスキーマ:")
    print(table.schema)
    print(f"\n合計行数: {len(table)}")
    print("\n先頭の3行:")
    print(table.limit(3).to_pandas())

    # --- 例：この直接接続を使用して検索を実行します ---
    # このスクリプトを実行するホストで Ollama が起動している必要があります
    # try:
    #     query_text = "How do I use Python with data analysis?"
    #     ollama_model_name = "nomic-embed-text:latest"
    #     response = ollama.embeddings(model=ollama_model_name, prompt=query_text)
    #     query_vector = response["embedding"]
    #     search_results = table.search(query_vector).limit(5).to_pandas()
    #     print("\n検索結果（直接アクセス）:")
    #     print(search_results)
    # except Exception as e:
    #     print(f"直接クエリまたは検索中にエラーが発生しました（Ollama は起動していますか？）: {e}")

except Exception as e:
    print(f"LanceDB テーブルを開く、または確認する際にエラーが発生しました: {e}")

この直接アクセス方法は、デバッグ、データベースの内容の検証、または API とは別の操作を実行する際に役立ちます。

⚠️ トラブルシューティングと注意事項

Ollama の接続性：抽出スクリプトと API サーバーはどちらも、nomic-embed-text:latest モデルを取得済みの、起動中でアクセス可能な Ollama インスタンスに依存します。Docker 環境で OLLAMA_HOST が正しく設定されていることを確認してください。 LanceDB のマウント：Docker コンテナには、docker run の -v フラグを使って LanceDB データベースディレクトリを正しくマウントする必要があります。ホストパスが正しいことを確認し、必要に応じてコンテナユーザーに読み取り／書き込み権限があることを確認してください（書き込み権限は主に抽出スクリプトで必要で、API 検索には読み取り権限で十分です）。 データベースのパス：抽出スクリプトは、スクリプトを実行した場所を基準に ./cursor_chat_history.lancedb にデータベースを作成します。Docker コンテナでは、これが /data/cursor_chat_history.lancedb にマウントされていることを想定しています。これらのパスは重要です。 空のプロンプト：抽出スクリプトは、ベクトル列のサイズの一貫性を保つため、空または空白文字のみのプロンプトにプレースホルダーのゼロベクトルを追加します。 AI モデルの応答：このプロジェクトでは現在、aiService.prompts からユーザープロンプトのみを抽出します。AI モデルの応答やその他の会話の詳細は、現在抽出または保存されません。 Windows のパス：Windows で docker run の -v フラグにホストパスを指定する際は、パス形式に注意してください。絶対パスを使用してください。 ✨ 今後の機能拡張（案） AI モデルの応答を抽出して保存し、ユーザープロンプトと関連付けます。 会話を並べ替えるためのタイムスタンプを抽出して保存します。 保存するドキュメントにメタデータ（ワークスペース ID、会話 ID など）を追加します。 抽出スクリプトと API サーバーの両方で、.env ファイルによる設定に対応します。 検索 API にフィルタリングオプションを追加します（例：ソースデータベース、日付範囲での絞り込み）。