Claude Code Conversation Search MCP

🚀 Claude Code對話搜索MCP

別再丟失Claude Code的對話記錄啦！ 從此無需再問“我們在哪裡討論過那個bug修復方案？”，也不必在關閉終端後花費數小時找回之前的對話上下文。

🚀 快速開始

安裝後，它會自動與Claude Code進行配置：

npm install -g claude-code-conversation-search-mcp

在任何項目中工作時，都可以跨所有項目進行搜索。

🎯 推薦：增強Claude Code集成

為了獲得最佳搜索結果和更好的Claude Code交互體驗，請將以下指令添加到全局~/.claude/CLAUDE.md文件中：

# 添加到 ~/.claude/CLAUDE.md
echo "- When asked to use conversation-search, you must start searching from very wide queries, narrowing down step by step. When responding based on this mcp results output a human readable text with proper newlines instead of formatting json." >> ~/.claude/CLAUDE.md

為何這樣做有幫助：

• 更好的搜索策略：Claude會從寬泛的查詢開始，逐步縮小範圍，找到更相關的結果。
• 人類可讀的輸出：你將獲得包含項目路徑、日期和恢復命令的格式規範的響應，而不是原始的JSON。
• 改進的用戶體驗：讓Claude Code工作流程中的對話搜索變得自然而直觀。

✨ 主要特性

• 找回丟失的對話：再也不會丟失重要的討論內容。
• 跨所有項目搜索：在項目A中工作，但需要項目B的信息？只需搜索即可。
• 立即恢復：獲取精確的claude --resume命令，從上次中斷的地方繼續。
• 自然語言搜索：像與人交流一樣提問，例如“查找那個Docker對話”。
• 閃電般快速：在毫秒內搜索數千條對話。
• 零設置：安裝後即可立即與現有的Claude Code配合使用。

📦 安裝指南

從源代碼安裝

# 克隆倉庫
git clone https://github.com/TonySimonovsky/claude-code-conversation-search-mcp.git
cd claude-code-conversation-search-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

# 可選：全局鏈接
npm link

配置

自動設置（推薦）

安裝後，MCP服務器會自動與Claude Code進行配置，無需手動配置！

手動配置（可選）

如果你需要自定義配置，可以選擇以下方法之一：

選項1：命令行（推薦）

# 為所有項目全局添加
claude mcp add conversation-search claude-code-conversation-search-mcp

# 僅為當前項目添加（創建.mcp.json）
claude mcp add --scope project conversation-search claude-code-conversation-search-mcp

選項2：直接編輯配置文件

全局配置（所有項目）：

# 編輯全局Claude Code配置（可在任何位置運行）
nano ~/.claude.json
# 或者使用你喜歡的編輯器：code ~/.claude.json

{
  "mcpServers": {
    "conversation-search": {
      "command": "claude-code-conversation-search-mcp",
      "args": []
    }
  }
}

特定項目配置（團隊共享）：

# 創建項目配置文件（從項目根目錄運行）
nano .mcp.json
# 或者：code .mcp.json

{
  "mcpServers": {
    "conversation-search": {
      "command": "claude-code-conversation-search-mcp",
      "args": []
    }
  }
}

配置選項

MCP服務器支持通過環境變量進行廣泛的配置。以下是最常用的選項：

📖 有關完整的配置選項和性能調優，請參閱配置指南

💻 使用示例

基礎用法

# 查找丟失的對話
"where did we discuss the login bug?"
"find that Docker conversation"
"database setup we talked about"

# 根據記憶搜索
"authentication error we fixed"
"API endpoint discussion yesterday"
"performance issue last week"

# 從其他項目中查找解決方案
"how did we solve CORS issues?"
"Redis configuration that worked"
"deployment script we wrote"

每次搜索都會為你提供：

• 對話所在的項目
• 對話發生的時間（日期和時間）
• 討論的內容（對話摘要）
• 恢復對話的智能快捷方式：cd ~/.cs/project-name && claude --resume abc123

高級用法

複雜查詢

我們內置的查詢解析器支持複雜的自然語言模式：

# 查找特定的文件操作
"Where did we create or modify authentication files?"

# 按多個條件搜索
"database migrations in project backend last week"

# 查找特定的錯誤模式
"TypeError or ReferenceError in React components"

# 搜索工具操作
"bash commands containing npm or yarn"

# 查找代碼討論
"Where did we discuss implementing caching?"

搜索運算符

• AND：術語默認是AND關係（"auth login"會查找同時包含這兩個詞的消息）
• OR：在術語之間使用"or"（"auth or login"）
• NOT：使用"-"前綴（"auth -test"排除與測試相關的結果）
• 短語：使用引號表示精確短語（"user authentication"）
• 通配符：使用*進行前綴匹配（"auth*"匹配auth、authentication等）

時間過濾器

支持的時間表達式：

• today，yesterday
• last week，this week
• last month，this month
• last 7 days，last 30 days
• 特定日期："on 2024-01-15"，"since January 1"

配置完成後，Claude Code中提供以下工具：

搜索對話

使用自然語言搜索你的對話歷史：

search_conversations("Where did we create auth.js?")
search_conversations("database optimization last week")
search_conversations("TypeError in index.ts")

查詢示例：

• 文件操作："created auth.js"，"edited config.json"，"modified database.ts"
• 主題："discuss React hooks"，"security review"，"performance optimization"
• 錯誤："TypeError"，"CORS error"，"undefined variable"
• 命令："npm install lodash"，"git commit"，"database migration"
• 時間過濾器："today"，"yesterday"，"last week"，"this month"
• 項目過濾器："in project myapp"，"from backend-api"

參數：

• query（必需）：自然語言搜索查詢
• limit（可選）：要返回的最大結果數（默認值：10）
• includeContext（可選）：是否包含周圍的消息（默認值：true）

列出項目

獲取所有已索引項目的統計信息：

list_projects()

返回項目名稱、消息數量和最後活動日期。

獲取消息上下文

檢索特定消息的完整上下文：

get_message_context("msg_abc123", contextSize: 5)

參數：

• messageId（必需）：要獲取上下文的消息ID
• contextSize（可選）：前後的消息數量（默認值：5）

獲取對話消息

從特定對話中檢索消息：

get_conversation_messages("conv_456", limit: 50, startFrom: 0)
get_conversation_messages("conv_456", limit: 10, startFrom: -1)  # 最後10條消息
get_conversation_messages("conv_456", limit: 20, startFrom: -10) # 從倒數第10條開始的20條消息

參數：

• conversationId（必需）：要獲取消息的對話ID
• limit（可選）：要返回的消息數量（默認值：50）
• startFrom（可選）：起始位置 - 0表示第一條，-1表示最後一條，-10表示倒數第10條（默認值：0）

列出工具

顯示所有可用工具及其簽名：

list_tools()

返回自動生成的工具簽名和描述。當添加新工具時，會自動更新。

刷新索引

手動觸發重新索引：

refresh_index()

在添加新項目或禁用自動索引時很有用。

獲取服務器信息

顯示服務器版本、更新日誌和系統信息：

get_server_info()

顯示當前版本、最近的更改、系統狀態和可用工具。

🔧 技術細節

該項目使用TypeScript構建，使用SQLite FTS5進行搜索，並通過模型上下文協議進行集成。

系統要求：

• Node.js 18+
• 支持MCP的Claude Code
• macOS、Linux或Windows

性能：

• 對10000+條對話的搜索可在亞秒級完成。
• 通過文件監控實現即時索引。
• 最小的內存佔用（約50MB）。

存儲：

• SQLite數據庫位於~/.claude/conversation-search/。
• 對對話內容進行索引，而不是文件內容。
• 自動清理已刪除的對話。

智能目錄快捷方式

搜索會自動創建目錄快捷方式，以便更快地導航：

• 跨平臺：適用於macOS、Linux和Windows。
• 短路徑：使用~/.cs/代替長項目路徑。
• 真實目錄：創建實際的符號鏈接/連接點，你可以使用cd進入。
• 基於項目的名稱：使用有意義的名稱，如poc-fbf-v023-1-cc。
• 自動創建：在搜索時按需生成。

示例：

# 代替
cd '/Users/username/very/long/path/to/project'

# 你可以使用
cd ~/.cs/project-name

開發

設置開發環境

# 克隆並安裝
git clone <repository>
cd claude-code-conversation-search-mcp
npm install

# 以熱重載模式運行開發環境
npm run dev

# 運行測試
npm test

# 構建生產版本
npm run build

項目結構

src/
├── index.ts              # MCP服務器入口點
├── indexer/
│   ├── parser.ts        # JSONL對話解析器
│   ├── database.ts      # SQLite數據庫操作
│   └── indexer.ts       # 索引編排
├── search/
│   └── query.ts         # 自然語言查詢解析器
└── types/
    └── index.ts         # TypeScript類型定義

貢獻

1. 分叉倉庫
2. 創建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打開拉取請求

故障排除

數據庫問題

如果搜索索引損壞：

# 刪除數據庫文件
rm ~/.claude/conversation-search.db

# 重啟Claude Code以觸發重新索引

性能優化

對於大型對話歷史：

1. 增加INDEX_INTERVAL以減少索引頻率
2. 設置MAX_RESULTS以限制結果大小
3. 在查詢中使用特定的項目過濾器

調試模式

啟用調試日誌以解決問題：

{
  "mcpServers": {
    "conversation-search": {
      "command": "npx",
      "args": ["claude-code-conversation-search-mcp"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

致謝

本項目使用了由Anthropic開發的模型上下文協議SDK構建。

版權信息

由Tony AI Champ和Claude Code於2025年9月開發。

支持

如果你遇到問題、有功能請求或疑問，請：

• 在GitHub上打開一個問題
• 查看現有問題以尋找解決方案
• 在報告錯誤時包含調試日誌