克劳德代码对话搜索MCP
别再丢失你的Claude Code对话了。 再也不用问“我们是在哪里讨论的那个bug修复方案?”或者在终端关闭时丢失数小时的上下文信息。```bash
npm install -g claude-code-conversation-search-mcp
在所有项目中查找任何对话:```bash
"where did we discuss the database issue?"
"find that authentication conversation"
"docker configuration we talked about yesterday"
获取确切的项目、日期和命令,以便立即恢复。
为什么你需要这个
问题: Claude Code 没有对话搜索功能。当你关闭终端或切换项目时,就再也找不到那些重要的对话了。你只能浏览那些晦涩难懂的对话标题,希望能认出那个正确的。
解决方案: 搜索所有项目会话中的Claude Code对话。询问“我们是在哪里讨论过身份验证的?”并立即通过“继续”命令获取确切的对话记录。
特点/功能
- 找回丢失的对话再也不用错过任何重要讨论
- 在所有项目中搜索在项目A工作但需要项目B的信息?只需搜索即可
- 立即恢复获取准确结果
claude --resume命令继续从你离开的地方继续 - 自然语言像向人类提问一样提问——“找到那个关于Docker的对话”
- 飞快如闪电在毫秒级时间内搜索数千场对话
- 零设置安装后,它会立即与您现有的Claude代码协同工作
快速入门
安装后,它将自动与Claude代码进行配置:```bash
npm install -g claude-code-conversation-search-mcp
在处理任意项目时,可在所有项目中进行搜索。
### 🎯 推荐:增强版Claude代码集成
为了获得最佳搜索结果和更佳的Claude Code交互体验,请将这些指令添加到您的全局设置中 `~/.claude/CLAUDE.md` 文件:```bash
# Add to ~/.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
为何这会有帮助:
- 更佳的搜索策略克劳德将从广泛的问题开始,然后逐步缩小范围,找到更多相关的结果
- 可读的输出你将获得格式正确的响应,其中包含项目路径、日期和恢复命令,而不是原始的JSON数据
- 提升用户体验(UX)在Claude Code工作流中,使对话搜索感觉自然且直观
用法```bash
Find lost conversations
"where did we discuss the login bug?"
"find that Docker conversation"
"database setup we talked about"
Search by what you remember
"authentication error we fixed"
"API endpoint discussion yesterday"
"performance issue last week"
Find solutions from other projects
"how did we solve CORS issues?"
"Redis configuration that worked"
"deployment script we wrote"
每次搜索都会为您提供:
- **哪个项目** 对话是在
- **当它发生时** (日期和时间)
- **你们讨论了什么** (对话摘要)
- **智能快捷键** 总结来说: `cd ~/.cs/project-name && claude --resume abc123`
## 智能目录快捷方式
搜索会自动创建 **目录快捷方式** 为了更快导航:
- **跨平台**适用于 macOS、Linux 和 Windows 系统
- **短路径**用途 `~/.cs/` 而不是漫长的项目路径
- **真实目录**创建实际的符号链接/连接点,您可以 `cd` 进入
- **基于项目的名称**使用有意义的名称,如 `poc-fbf-v023-1-cc`
- **自动创建**在搜索过程中按需生成
**示例:**```bash
# Instead of:
cd '/Users/username/very/long/path/to/project'
# You get:
cd ~/.cs/project-name
技术
使用TypeScript构建,采用SQLite FTS5进行搜索,通过模型上下文协议进行集成。
系统要求:
- Node.js 18及以上版本
- 带有MCP支持的Claude代码
- macOS、Linux 或 Windows
演出
- 在1万多个对话中进行秒级搜索
- 实时索引与文件监视
- 最小的内存占用(约50MB)
存储:
- SQLite 数据库在
~/.claude/conversation-search/ - 索引对话内容,而非文件内容
- 自动清理已删除的对话
安装
来自源头```bash
Clone the repository
git clone https://github.com/TonySimonovsky/claude-code-conversation-search-mcp.git
cd claude-code-conversation-search-mcp
Install dependencies
npm install
Build the project
npm run build
Optional: Link globally
npm link
## 配置
### 自动设置(推荐)
安装后,MCP服务器会自动使用Claude Code进行配置。无需手动配置!
### 手动配置(可选)
如果您需要自定义配置,请选择以下方法之一:
**选项1:命令行(推荐)**```bash
# Add globally for all projects
claude mcp add conversation-search claude-code-conversation-search-mcp
# Add for current project only (creates .mcp.json)
claude mcp add --scope project conversation-search claude-code-conversation-search-mcp
选项2:直接编辑配置文件
全局配置 (所有项目):```bash
Edit the global Claude Code config (run from anywhere)
nano ~/.claude.json
Or use your preferred editor: code ~/.claude.json
``````json
{
"mcpServers": {
"conversation-search": {
"command": "claude-code-conversation-search-mcp",
"args": []
}
}
}
**项目特定配置** (团队共享):```bash
# Create project config file (run from project root)
nano .mcp.json
# Or: code .mcp.json
``````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 |
📖 如需查看完整的配置选项和性能调优,请参阅 配置指南
用法
一旦配置完成,以下工具将在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) # Last 10 messages
get_conversation_messages("conv_456", limit: 20, startFrom: -10) # 20 messages starting from 10th from end
参数:
conversationId(必需):用于获取消息的对话IDlimit(可选):要返回的消息数量(默认:50)startFrom(可选):起始位置 -0首先,-1最后,-10从末尾数第10个(默认:0)
列出工具
显示所有可用工具及其签名:```
list_tools()
返回自动生成的工具签名和描述。当添加新工具时,会自动更新。
### 刷新索引
手动触发重新索引:```
refresh_index()
在添加新项目后或禁用自动索引时非常有用。
获取服务器信息
显示服务器版本、更改日志和系统信息:```
get_server_info()
显示当前版本、最近更改、系统状态以及可用工具。
## 高级用法
### 复杂查询
我们内置的查询解析器支持复杂的自然语言模式:```
# Find specific file operations
"Where did we create or modify authentication files?"
# Search by multiple criteria
"database migrations in project backend last week"
# Find specific error patterns
"TypeError or ReferenceError in React components"
# Search tool operations
"bash commands containing npm or yarn"
# Find code discussions
"Where did we discuss implementing caching?"
搜索运算符
- 并且默认情况下,术语是通过AND连接的(
"auth login"查找同时包含两者的消息 - 或在术语之间使用“或”(
"auth or login") - 非,不使用“-”前缀(
"auth -test"(排除测试相关结果) - 短语使用引号来表示确切的短语(
"user authentication") - 通配符使用 * 进行前缀匹配(
"auth*"匹配 auth、authentication 等(功能)
时间过滤器
支持的时间表达式:
today,yesterdaylast week,this weeklast month,this monthlast 7 days,last 30 days- 具体日期:
"on 2024-01-15","since January 1"
发展
设置开发环境```bash
Clone and install
git clone
cd claude-code-conversation-search-mcp
npm install
Run in development mode with hot reload
npm run dev
Run tests
npm test
Build for production
npm run build
### 项目结构```
src/
├── index.ts # MCP server entry point
├── indexer/
│ ├── parser.ts # JSONL conversation parser
│ ├── database.ts # SQLite database operations
│ └── indexer.ts # Indexing orchestration
├── search/
│ └── query.ts # Natural language query parser
└── types/
└── index.ts # TypeScript type definitions
贡献
- 为仓库创建分支(或:克隆仓库)
- 创建一个特性分支(
git checkout -b feature/amazing-feature) - 提交你的更改(
git commit -m 'Add amazing feature') - 推送到分支(
git push origin feature/amazing-feature) - 提交拉取请求
故障排除
数据库问题
如果搜索索引损坏:```bash
Remove the database file
rm ~/.claude/conversation-search.db
Restart Claude Code to trigger re-indexing
### 性能优化
对于较长的对话历史:
1. 增加 `INDEX_INTERVAL` 降低索引频率
1. 设定 `MAX_RESULTS` 限制结果大小
1. 在查询中使用特定的项目过滤器
### 调试模式
启用调试日志以排查问题:```json
{
"mcpServers": {
"conversation-search": {
"command": "npx",
"args": ["claude-code-conversation-search-mcp"],
"env": {
"DEBUG": "true"
}
}
}
}
许可证
MIT 许可证 - 详见 许可证 文件详情见附件
致谢
使用(某种方法/技术)构建 模型上下文协议SDK 由Anthropic开发。
功劳/学分
由Tony AI Champ与Claude Code开发,2025年9月
支持
对于问题、功能请求或疑问:
- 在(某平台/项目)上提交一个问题 GitHub
- 检查现有问题以寻找解决方案
- 报告错误时请包含调试日志
