AI导哈

对话搜索工具

一个用于搜索和检索Claude Code历史对话的工具，支持关键词、项目和日期筛选，并提供使用统计和MCP集成功能。

  • by prassanna-ravishankar
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 prassanna-ravishankar/cc-search

使用说明

cc-search 翻译为中文是“内容分发网络搜索”或简化为“CDN搜索”，其中“cc”通常代表“内容分发”（Content Delivery）的缩写，而“search”则表示搜索。不过，具体翻译可能根据上下文有所调整，以更贴合实际应用场景

搜索并检索过去的Claude Code对话记录。

特点/特性

  • 搜索对话 按关键词、项目或日期
  • 查看完整对话 格式化输出的历史记录
  • 统计 关于您使用Claude代码的情况
  • MCP集成 用于Claude Code会话内部使用
  • CLI（Command Line Interface）的中文翻译是“命令行界面” 用于独立测试和探索

安装

# Clone the repo
git clone <your-repo>
cd cc-search

# Install with uv
uv sync

# Or install in development mode
uv pip install -e .

CLI 使用方法

搜索对话

# Basic search
cc-search search "authentication"

# Search with filters
cc-search search "database" --project sgp --since "7 days ago" --limit 5

# List all conversations
cc-search --list --project myproject

查看完整对话

# Show conversation by session ID (full or prefix)
cc-search show 4af530fc

查看统计数据

# Show conversation statistics
cc-search stats

MCP集成

设置

在您的Claude Code MCP设置文件中添加：

macOS/Linux（可译为“苹果操作系统/类Unix操作系统”或直接保留原英文，根据上下文决定是否需要具体翻译）： ~/.config/claude-code/mcp_settings.json Windows: %APPDATA%\claude-code\mcp_settings.json

选项1：使用uv（推荐）

{
  "mcpServers": {
    "cc-search": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/full/path/to/cc-search/run_mcp_server.py"
      ],
      "cwd": "/full/path/to/cc-search"
    }
  }
}

选项2：直接使用Python

{
  "mcpServers": {
    "cc-search": {
      "command": "/full/path/to/cc-search/.venv/bin/python",
      "args": [
        "-m",
        "cc_search.mcp.server"
      ],
      "cwd": "/full/path/to/cc-search"
    }
  }
}

注使用绝对路径（不要使用 ~ 或相对路径。

验证安装

  1. 重启 Claude Code CLI
  2. 测试方法是询问：“在我的过往对话中搜索有关身份验证的讨论”

可用的MCP工具

search_conversations_tool

使用筛选器搜索过去的对话。

参数：

  • query （可选）：搜索查询字符串
  • project （可选）：按项目路径筛选
  • since （可选）：日期过滤器（例如，“7天前”）
  • limit （默认：10）：最大结果数

get_conversation

通过会话ID检索完整对话。

参数：

  • session_id会话 UUID 或前缀

list_recent_conversations

列出最近的对话。

参数：

  • limit （默认：20）：结果数量
  • project （可选）：按项目过滤

get_conversation_stats

显示所有对话的统计数据。

使用示例

向Claude询问诸如：

  1. 寻找类似的解决方案：

    • “在我的过往对话中搜索我是如何处理身份验证的”
    • “我有没有讨论过速率限制？”

  2. 参考过去的决定：

    • “我们上周决定好数据库架构了吗？”
    • “给我看看关于API设计的对话”

  3. 审查历史:

    • “列出我在sgp项目中的最近对话”
    • “给我看看我使用Claude Code的统计数据”

  4. 从以往工作中学习:

    • “查找我参与测试策略工作的对话”
    • “我之前讨论过关于Docker配置的内容是什么？”

它是如何工作的

  1. 你向克劳德·科德（Claude Code）提出一个问题，需要过去的对话上下文
  2. 克劳德决定使用哪种MCP工具
  3. MCP服务器（cc-search）读取本地JSONL文件
  4. 结果返回给克劳德，由他进行解读并展示
  5. 克劳德执行语义排序以查找最相关的对话

故障排除

MCP服务器无法启动：

# Test the server manually
uv run python run_mcp_server.py

工具未显示：

  1. 验证配置文件的位置和语法（有效的JSON）
  2. 重启 Claude Code CLI
  3. 检查路径是否为绝对路径（而非相对路径或 ~）

运行缓慢：

  • 首次扫描所有对话可能会较慢
  • 考虑按项目或日期进行筛选以缩小范围
  • 大型对话文件（100+条消息）解析时间较长

它是如何运作的

Claude Code 将对话本地存储在 ~/.claude/projects/ 作为JSONL文件。此工具：

  1. 扫描（图像/文件等） 对话文件的项目目录
  2. 解析 使用 Pydantic 模型的 JSONL 格式
  3. 过滤器 按关键字、项目路径或日期范围
  4. 格式 为CLI或MCP消费的输出

搜索使用 关键词匹配 默认情况下。当通过MCP（多客户端协议）使用时，Claude Code本身会执行语义相关性排序。

项目结构

cc-search/
├── src/cc_search/
│   ├── cli.py              # Typer CLI interface
│   ├── core/
│   │   ├── models.py       # Pydantic data models
│   │   ├── parser.py       # JSONL parsing logic
│   │   ├── scanner.py      # File system scanning
│   │   └── search.py       # Search and filtering
│   └── mcp/
│       └── server.py       # FastMCP server
├── tests/
│   └── test_mcp_server.py  # Unit tests
├── pyproject.toml
└── README.md

发展

# Install dev dependencies
uv sync --dev

# Run tests
pytest

# Lint/format
ruff check .
ruff format .

已知的限制

  • 一些对话文件可能包含消息类型（system， summary（那些）被跳过的
  • 在显示时，较长的对话（>1000行）会被截断
  • 搜索是基于关键词的，而非语义的（不过通过MCP使用时，Claude会进行语义排序）

许可证

麻省理工学院（MIT）

相关 MCP