shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

claude-code-conversation-search-mcp

Claude Code对话搜索MCP工具，帮助用户跨项目搜索和恢复Claude Code的对话历史，解决对话丢失和难以查找的问题。

article

README

🚀 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服务器支持通过环境变量进行广泛的配置。以下是最常用的选项： | 环境变量 | 描述 | 默认值 | |---------------------|-------------|---------| | CONVERSATION_DB_PATH | SQLite数据库的路径 | ~/.claude/conversation-search.db | | CLAUDE_PROJECTS_DIR | Claude项目目录的路径 | ~/.claude/projects | | INDEX_INTERVAL | 自动索引的时间间隔（毫秒） | 300000（5分钟） | | MAX_RESULTS | 要返回的最大搜索结果数 | 20 | | DEFAULT_CONTEXT_SIZE | 前后默认的上下文消息数 | 2 | | AUTO_INDEXING | 启用自动索引 | true | | DEBUG | 启用调试日志 | false |

📖 有关完整的配置选项和性能调优，请参阅配置指南

💻 使用示例

基础用法

# 查找丢失的对话
"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上打开一个问题
  • 查看现有问题以寻找解决方案
  • 在报告错误时包含调试日志
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端