Enhanced semantic codebase search powered by Cursor API with multi-project support and MCP integration

English | 中文

An enhanced fork of cometix-indexer that provides semantic code search capabilities through CLI indexing and MCP server integration. This project separates indexing operations (user-controlled via CLI) from search functionality (AI-controlled via MCP server).

• Multi-Project Index Support - Manage and search across multiple codebases simultaneously
• Progress Visualization - Real-time progress bars during indexing operations
• Separated Operations - CLI handles indexing/activation; MCP server exposes read-only codebase_search tool
• Ignore File Support - Respects .ignore and .cursorignore files for precise index control
• Environment Configuration - .env file support for secure credential management
• Enhanced Search Results - Function/class signatures with code previews in search output
• Bug Fixes - Resolved path decryption errors and ESM import extension issues

# Global installation from GitHub
npm install -g git+https://github.com/Cedriccmh/cursor-codebase-search.git

# Or local development
git clone https://github.com/Cedriccmh/cursor-codebase-search.git
cd cursor-codebase-search
npm install
npm run build
npm link

1. Configure Environment

cp .env.example .env
# Edit .env and add your CURSOR_AUTH_TOKEN

2. Index a Workspace

mcp-cursearch index-activate /path/to/your/project

3. Configure MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "cursor-search": {
      "command": "node",
      "args": ["/path/to/cursor-codebase-search/dist/mcp.js"],
      "env": {
        "CURSOR_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

Parameters:

• query (string, required) - Search query
• paths_include_glob (string, optional) - Include pattern
• paths_exclude_glob (string, optional) - Exclude pattern
• max_results (number, optional) - Max results (default: 10)

Example:

{
  "query": "authentication logic",
  "paths_include_glob": "src/**/*.ts",
  "max_results": 20
}

Environment Variables:

Get CURSOR_AUTH_TOKEN: Visit https://cursor.meteormail.me/ (⚠️ third-party tool)

Semaphore Retry Logging: Automatically retries failed file upload and sync operations with detailed logging. Configure retry behavior via .env to handle network issues or API rate limits gracefully. Set SEMAPHORE_RETRY_COUNT (default: 3) for retry attempts and SEMAPHORE_RETRY_DELAY_MS (default: 200) for base delay between retries.

~/.mcp-cursearch/
├── <workspace-hash>/
│   ├── state.json           # CodebaseId, pathKey, metadata
│   └── embeddable_files.txt # Indexable file list
└── active.json              # Active workspace reference

• ✨ Multi-project management - Index and switch between multiple codebases
• 📊 Progress indicators - Visual feedback during indexing
• 🔧 CLI/MCP separation - Clear separation of concerns for better security
• 📁 Ignore file support - .cursorignore and .ignore integration
• ⚙️ .env configuration - Simplified credential management
• 🐛 Bug fixes - Path decryption and ESM import issues resolved
• 🔍 Enhanced results - Better context in search output

• Node.js >= 18
• Cursor API token

MIT

• CLI Implementation
• Troubleshooting

cometix-indexer 的增强版本，通过 CLI 索引和 MCP 服务器集成提供语义代码搜索功能。本项目将索引操作（用户通过 CLI 控制）与搜索功能（AI 通过 MCP 服务器控制）分离。

• 多项目索引支持 - 同时管理和搜索多个代码库
• 进度可视化 - 索引操作时显示实时进度条
• 操作分离 - CLI 处理索引/激活；MCP 服务器仅暴露只读 codebase_search 工具
• 忽略文件支持 - 支持 .ignore 和 .cursorignore 文件以精确控制索引
• 环境配置 - 支持 .env 文件进行安全凭证管理
• 增强搜索结果 - 搜索输出包含函数/类签名和代码预览
• Bug 修复 - 解决路径解密错误和 ESM 导入扩展问题

# 从 GitHub 全局安装
npm install -g git+https://github.com/Cedriccmh/cursor-codebase-search.git

# 或本地开发
git clone https://github.com/Cedriccmh/cursor-codebase-search.git
cd cursor-codebase-search
npm install
npm run build
npm link

1. 配置环境

cp .env.example .env
# 编辑 .env 文件并添加 CURSOR_AUTH_TOKEN

2. 索引工作区

mcp-cursearch index-activate /path/to/your/project

3. 配置 MCP 服务器

在 MCP 客户端配置中添加（如 Claude Desktop）：

{
  "mcpServers": {
    "cursor-search": {
      "command": "node",
      "args": ["/path/to/cursor-codebase-search/dist/mcp.js"],
      "env": {
        "CURSOR_AUTH_TOKEN": "your-token-here"
      }
    }
  }
}

参数:

• query (字符串, 必需) - 搜索查询
• paths_include_glob (字符串, 可选) - 包含模式
• paths_exclude_glob (字符串, 可选) - 排除模式
• max_results (数字, 可选) - 最大结果数（默认: 10）

示例:

{
  "query": "authentication logic",
  "paths_include_glob": "src/**/*.ts",
  "max_results": 20
}

环境变量:

获取 CURSOR_AUTH_TOKEN: 访问 https://cursor.meteormail.me/ （⚠️ 第三方工具）

信号量重试日志: 自动重试失败的文件上传和同步操作，并提供详细日志记录。通过 .env 配置重试行为，优雅处理网络问题或 API 速率限制。设置 SEMAPHORE_RETRY_COUNT（默认: 3）控制重试次数，SEMAPHORE_RETRY_DELAY_MS（默认: 200）控制重试间隔基础延迟。

~/.mcp-cursearch/
├── <workspace-hash>/
│   ├── state.json           # CodebaseId, pathKey, 元数据
│   └── embeddable_files.txt # 可索引文件列表
└── active.json              # 活动工作区引用

• ✨ 多项目管理 - 索引和切换多个代码库
• 📊 进度指示器 - 索引期间的可视反馈
• 🔧 CLI/MCP 分离 - 更好的安全性关注点分离
• 📁 忽略文件支持 - 集成 .cursorignore 和 .ignore
• ⚙️ .env 配置 - 简化凭证管理
• 🐛 Bug 修复 - 解决路径解密和 ESM 导入问题
• 🔍 增强结果 - 搜索输出提供更好的上下文

• Node.js >= 18
• Cursor API 令牌

MIT

• CLI 实现
• 故障排除

基于 cometix-indexer 增强开发