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. 包含一个 Docker 化的 FastAPI 应用（在此上下文中称为“MCP 服务”），通过简单的 API 端点搜索此 LanceDB 数据库。

✨ 项目目标

主要目标是让 Cursor 聊天历史可搜索，并可用于检索增强生成（RAG）或其他基于大模型的分析，具体方式如下：

• 将用户提示词转换为向量嵌入，并高效地存储在 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）。

⚙️ 设置与配置

该流程包含两个主要步骤：

1. 运行提取脚本，在主机上创建或更新 LanceDB 数据库。
2. 构建并运行 Docker 容器以提供搜索 API，并挂载步骤 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 预期的位置。（即使在 Windows 上使用 Docker 命令，也请使用正斜杠表示路径，或确保正确转义/配置）。
   • -e OLLAMA_HOST="..."：在容器内部设置 OLLAMA_HOST 环境变量。Docker Desktop 通常可通过 http://host.docker.internal:11434 访问主机。对于 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），即可与其交互。

健康检查（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 脚本后，你可以在 Docker 容器外使用 Python 直接检查 LanceDB 数据库文件。 import lancedb import ollama # Required if you want to perform searches

Connect to the DB where the extractor created it

db = lancedb.connect("./cursor_chat_history.lancedb")

try: # Open the table table = db.open_table("chat_history")

# Inspect the table schema and content
print("Table Schema:")
print(table.schema)
print(f"\nTotal rows: {len(table)}")
print("\nFirst 3 rows:")
print(table.limit(3).to_pandas())

# --- Example: Perform a search using this direct connection ---
# Requires Ollama running on the host where this script is executed
# 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("\nSearch Results (Direct Access):")
#     print(search_results)
# except Exception as e:
#     print(f"Error during direct query or search (Is Ollama running?): {e}")

except Exception as e: print(f"Error opening or inspecting LanceDB table: {e}")

这种直接访问方式有助于调试、验证数据库内容，或执行独立于 API 的操作。

⚠️ 故障排除与说明

Ollama 连接：提取脚本和 API 服务都依赖正在运行且可访问的 Ollama 实例，并且该实例已拉取 nomic-embed-text:latest 模型。请确保已为 Docker 环境正确配置 OLLAMA_HOST。 LanceDB 挂载：必须在 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 添加筛选选项（例如按源数据库、日期范围筛选）。