{
  "markdown": "# Claude Code Conversation Search MCP\n\n**Stop losing your Claude Code conversations.** Never again ask \"where did we discuss that bug fix?\" or lose hours of context when your terminal closes.\n\n```bash\nnpm install -g claude-code-conversation-search-mcp\n```\n\nFind any conversation across all projects:\n```bash\n\"where did we discuss the database issue?\"\n\"find that authentication conversation\"\n\"docker configuration we talked about yesterday\"\n```\n\nGet the exact project, date, and command to resume instantly.\n\n## Why You Need This\n\n**The Problem:** Claude Code has no conversation search. When you close a terminal or switch projects, finding that important discussion becomes impossible. You're left scrolling through cryptic conversation titles hoping to recognize the right one.\n\n**The Solution:** Search all your Claude Code conversations from any project session. Ask \"where did we discuss authentication?\" and instantly get the exact conversation with a resume command.\n\n## Features\n\n- **Find lost conversations**: Never lose track of important discussions again\n- **Search across all projects**: Working in Project A but need info from Project B? Just search\n- **Resume instantly**: Get exact `claude --resume` commands to continue where you left off  \n- **Natural language**: Ask questions like you would a human - \"find that Docker conversation\"\n- **Lightning fast**: Search thousands of conversations in milliseconds\n- **Zero setup**: Install and it works immediately with your existing Claude Code\n\n## Quick Start\n\nInstall and it auto-configures with Claude Code:\n\n```bash\nnpm install -g claude-code-conversation-search-mcp\n```\n\nSearch across all projects while working in any project.\n\n### 🎯 Recommended: Enhanced Claude Code Integration\n\nFor optimal search results and better Claude Code interaction, add these instructions to your global `~/.claude/CLAUDE.md` file:\n\n```bash\n# Add to ~/.claude/CLAUDE.md\necho \"- 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\n```\n\n**Why this helps:**\n- **Better search strategy**: Claude will start with broad queries and progressively narrow down, finding more relevant results\n- **Human-readable output**: Instead of raw JSON, you'll get properly formatted responses with project paths, dates, and resume commands\n- **Improved UX**: Makes conversation search feel natural and intuitive within Claude Code workflows\n\n## Usage\n\n```bash\n# Find lost conversations\n\"where did we discuss the login bug?\"\n\"find that Docker conversation\"\n\"database setup we talked about\"\n\n# Search by what you remember\n\"authentication error we fixed\"\n\"API endpoint discussion yesterday\"\n\"performance issue last week\"\n\n# Find solutions from other projects  \n\"how did we solve CORS issues?\"\n\"Redis configuration that worked\"\n\"deployment script we wrote\"\n```\n\nEvery search gives you:\n- **Which project** the conversation was in\n- **When it happened** (date and time)\n- **What you discussed** (conversation summary)\n- **Smart shortcuts** to resume: `cd ~/.cs/project-name && claude --resume abc123`\n\n## Smart Directory Shortcuts\n\nThe search automatically creates **directory shortcuts** for faster navigation:\n\n- **Cross-platform**: Works on macOS, Linux, and Windows\n- **Short paths**: Uses `~/.cs/` instead of long project paths\n- **Real directories**: Creates actual symlinks/junctions you can `cd` into\n- **Project-based names**: Uses meaningful names like `poc-fbf-v023-1-cc`\n- **Automatic creation**: Generated on-demand during search\n\n**Example:**\n```bash\n# Instead of:\ncd '/Users/username/very/long/path/to/project'\n\n# You get:\ncd ~/.cs/project-name\n```\n\n## Technical\n\nBuilt with TypeScript, uses SQLite FTS5 for search, integrates via Model Context Protocol.\n\n**System requirements:**\n- Node.js 18+\n- Claude Code with MCP support\n- macOS, Linux, or Windows\n\n**Performance:**\n- Sub-second search across 10k+ conversations\n- Real-time indexing with file watching\n- Minimal memory footprint (~50MB)\n\n**Storage:**\n- SQLite database in `~/.claude/conversation-search/`\n- Indexes conversation content, not file contents\n- Automatic cleanup of deleted conversations\n\n## Installation\n\n### From source\n\n```bash\n# Clone the repository\ngit clone https://github.com/TonySimonovsky/claude-code-conversation-search-mcp.git\ncd claude-code-conversation-search-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n\n# Optional: Link globally\nnpm link\n```\n\n## Configuration\n\n### Automatic Setup (Recommended)\n\nAfter installation, the MCP server auto-configures with Claude Code. No manual configuration needed!\n\n### Manual Configuration (Optional)\n\nIf you need custom configuration, choose one of these approaches:\n\n**Option 1: Command Line (Recommended)**\n```bash\n# Add globally for all projects\nclaude mcp add conversation-search claude-code-conversation-search-mcp\n\n# Add for current project only (creates .mcp.json)\nclaude mcp add --scope project conversation-search claude-code-conversation-search-mcp\n```\n\n**Option 2: Edit Configuration Files Directly**\n\n**Global configuration** (all projects):\n```bash\n# Edit the global Claude Code config (run from anywhere)\nnano ~/.claude.json\n# Or use your preferred editor: code ~/.claude.json\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"conversation-search\": {\n      \"command\": \"claude-code-conversation-search-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n**Project-specific configuration** (team-shared):\n```bash\n# Create project config file (run from project root)\nnano .mcp.json\n# Or: code .mcp.json\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"conversation-search\": {\n      \"command\": \"claude-code-conversation-search-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n### Configuration Options\n\nThe MCP server supports extensive configuration through environment variables. Here are the most commonly used options:\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `CONVERSATION_DB_PATH` | Path to SQLite database | `~/.claude/conversation-search.db` |\n| `CLAUDE_PROJECTS_DIR` | Path to Claude projects directory | `~/.claude/projects` |\n| `INDEX_INTERVAL` | Auto-index interval in milliseconds | `300000` (5 minutes) |\n| `MAX_RESULTS` | Maximum search results to return | `20` |\n| `DEFAULT_CONTEXT_SIZE` | Default context messages before/after | `2` |\n| `AUTO_INDEXING` | Enable automatic indexing | `true` |\n| `DEBUG` | Enable debug logging | `false` |\n\n**📖 For complete configuration options and performance tuning, see [Configuration Guide](docs/configuration.md)**\n\n## Usage\n\nOnce configured, the following tools are available in Claude Code:\n\n### Search Conversations\n\nSearch through your conversation history with natural language:\n\n```\nsearch_conversations(\"Where did we create auth.js?\")\nsearch_conversations(\"database optimization last week\")\nsearch_conversations(\"TypeError in index.ts\")\n```\n\n**Query Examples:**\n- **File operations**: `\"created auth.js\"`, `\"edited config.json\"`, `\"modified database.ts\"`\n- **Topics**: `\"discuss React hooks\"`, `\"security review\"`, `\"performance optimization\"`\n- **Errors**: `\"TypeError\"`, `\"CORS error\"`, `\"undefined variable\"`\n- **Commands**: `\"npm install lodash\"`, `\"git commit\"`, `\"database migration\"`\n- **Time filters**: `\"today\"`, `\"yesterday\"`, `\"last week\"`, `\"this month\"`\n- **Project filters**: `\"in project myapp\"`, `\"from backend-api\"`\n\n**Parameters:**\n- `query` (required): Natural language search query\n- `limit` (optional): Maximum results to return (default: 10)\n- `includeContext` (optional): Include surrounding messages (default: true)\n\n### List Projects\n\nGet all indexed projects with statistics:\n\n```\nlist_projects()\n```\n\nReturns project names, message counts, and last activity dates.\n\n### Get Message Context\n\nRetrieve full context around a specific message:\n\n```\nget_message_context(\"msg_abc123\", contextSize: 5)\n```\n\n**Parameters:**\n- `messageId` (required): The message ID to get context for\n- `contextSize` (optional): Number of messages before/after (default: 5)\n\n### Get Conversation Messages\n\nRetrieve messages from a specific conversation:\n\n```\nget_conversation_messages(\"conv_456\", limit: 50, startFrom: 0)\nget_conversation_messages(\"conv_456\", limit: 10, startFrom: -1)  # Last 10 messages\nget_conversation_messages(\"conv_456\", limit: 20, startFrom: -10) # 20 messages starting from 10th from end\n```\n\n**Parameters:**\n- `conversationId` (required): The conversation ID to get messages from\n- `limit` (optional): Number of messages to return (default: 50)\n- `startFrom` (optional): Starting position - `0`=first, `-1`=last, `-10`=10th from end (default: 0)\n\n### List Tools\n\nShow all available tools with their signatures:\n\n```\nlist_tools()\n```\n\nReturns automatically generated tool signatures and descriptions. Updates automatically when new tools are added.\n\n### Refresh Index\n\nManually trigger re-indexing:\n\n```\nrefresh_index()\n```\n\nUseful after adding new projects or when auto-indexing is disabled.\n\n### Get Server Information\n\nShow server version, changelog, and system information:\n\n```\nget_server_info()\n```\n\nDisplays current version, recent changes, system status, and available tools.\n\n## Advanced Usage\n\n### Complex Queries\n\nOur built-in query parser supports sophisticated natural language patterns:\n\n```\n# Find specific file operations\n\"Where did we create or modify authentication files?\"\n\n# Search by multiple criteria\n\"database migrations in project backend last week\"\n\n# Find specific error patterns\n\"TypeError or ReferenceError in React components\"\n\n# Search tool operations\n\"bash commands containing npm or yarn\"\n\n# Find code discussions\n\"Where did we discuss implementing caching?\"\n```\n\n### Search Operators\n\n- **AND**: Terms are ANDed by default (`\"auth login\"` finds messages with both)\n- **OR**: Use \"or\" between terms (`\"auth or login\"`)\n- **NOT**: Use \"-\" prefix (`\"auth -test\"` excludes test-related results)\n- **Phrase**: Use quotes for exact phrases (`\"user authentication\"`)\n- **Wildcard**: Use * for prefix matching (`\"auth*\"` matches auth, authentication, etc.)\n\n### Time Filters\n\nSupported time expressions:\n- `today`, `yesterday`\n- `last week`, `this week`\n- `last month`, `this month`\n- `last 7 days`, `last 30 days`\n- Specific dates: `\"on 2024-01-15\"`, `\"since January 1\"`\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone and install\ngit clone <repository>\ncd claude-code-conversation-search-mcp\nnpm install\n\n# Run in development mode with hot reload\nnpm run dev\n\n# Run tests\nnpm test\n\n# Build for production\nnpm run build\n```\n\n### Project Structure\n\n```\nsrc/\n├── index.ts              # MCP server entry point\n├── indexer/\n│   ├── parser.ts        # JSONL conversation parser\n│   ├── database.ts      # SQLite database operations\n│   └── indexer.ts       # Indexing orchestration\n├── search/\n│   └── query.ts         # Natural language query parser\n└── types/\n    └── index.ts         # TypeScript type definitions\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## Troubleshooting\n\n### Database Issues\n\nIf the search index becomes corrupted:\n\n```bash\n# Remove the database file\nrm ~/.claude/conversation-search.db\n\n# Restart Claude Code to trigger re-indexing\n```\n\n### Performance Optimization\n\nFor large conversation histories:\n\n1. Increase `INDEX_INTERVAL` to reduce indexing frequency\n2. Set `MAX_RESULTS` to limit result size\n3. Use specific project filters in queries\n\n### Debug Mode\n\nEnable debug logging to troubleshoot issues:\n\n```json\n{\n  \"mcpServers\": {\n    \"conversation-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"claude-code-conversation-search-mcp\"],\n      \"env\": {\n        \"DEBUG\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details\n\n## Acknowledgments\n\nBuilt using the [Model Context Protocol SDK](https://github.com/anthropics/model-context-protocol) by Anthropic.\n\n## Credits\n\nDeveloped by Tony AI Champ & Claude Code, 09-2025\n\n## Support\n\nFor issues, feature requests, or questions:\n- Open an issue on [GitHub](https://github.com/TonySimonovsky/claude-code-conversation-search-mcp/issues)\n- Check existing issues for solutions\n- Include debug logs when reporting bugs",
  "bytes": 12514,
  "sha": "93c1bd0805d53eff4a80e7a95eddf2bdc8833e0b0d520d377412e4f7ad726571",
  "repo_slug": "tonysimonovsky/claude-code-conversation-search-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tonysimonovsky_claude_code_con_0fc1d003/readme"
}