STARWARCLOUD STARWAR.AI
返回市场
彗星索引器

彗星索引器

作者：CometixAI58 星标更新：2025-10-30
安装使用来源：spider==github.com

项目介绍

Cometix Indexer (MCP Server)

本地索引和检索服务，用于语义代码搜索。该项目实现了一个基于模型上下文协议（MCP）的服务器，封装了Cursor后端RepositoryService的仓库创建、同步和搜索过程。它通过两种类型的MCP工具提供外部能力：项目索引（index_project）和语义搜索（codebase_search）。

待办事项

  • Cursor索引（完成）
  • [ ] Warp嵌入
  • [ ] Trae索引
  • [ ] 增强索引
  • [GitHub索引（来源：Copilot索引）]

功能概述

  • 索引：扫描本地工作区，生成文件清单，批量上传到Cursor服务器，并完成数据库创建标记。
  • 增量同步：监控文件变化，按需进行轻量级同步，确保在搜索前索引是最新的。
  • 语义搜索：调用远程检索接口，自动解密返回的加密路径，直观显示匹配项。
  • 运行模式：作为MCP服务器通过stdio运行，并响应工具调用。

MCP

Claude代码

npx格式

{
  "mcpServers": {
    "cometix-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "--package=git+https://github.com/CometixAI/Cometix-Indexer.git",
        "cometix-indexer",
        "start"
      ],
      "env": {
        "CURSOR_AUTH_TOKEN": "",
        "CURSOR_BASE_URL": "https://api2.cursor.sh"
      }
    }
  }
}

npm格式（本地）

{
  "mcpServers": {
    "cometix-indexer": {
      "command": "npm",
      "args": [
        "--prefix",
        "<path>",
        "run",
        "start"
      ],
      "env": {
        "CURSOR_AUTH_TOKEN": "",
        "CURSOR_BASE_URL": "https://api2.cursor.sh"
      }
    }
  }
}

MCP工具

  • index_project

    • 输入参数：{ workspacePath: string; verbose?: boolean }
    • 操作：初始化/刷新索引，批量全量上传并安排自动同步；当verbose=true时，额外返回此轮上传的相对路径文件列表。
    • 返回：{ codebaseId, uploaded, batches, nextSyncAt }

  • codebase_search

    • 输入参数：{ query: string; paths_include_glob?: string; paths_exclude_glob?: string; max_results?: number }
    • 操作：在“仅已索引”的工作区内执行搜索；支持包含/排除glob过滤（基于工作区相对路径），并在搜索前按需增量同步。
    • 返回：{ total, hits: Array<{ path, score, startLine, endLine }> }

示例（概念性）：

{
  "name": "index_project",
  "arguments": { "workspacePath": "E:/project" }
}

{
  "name": "codebase_search",
  "arguments": { "query": "What is the xxx paper", "paths_include_glob": "src/**/*.rs", "paths_exclude_glob": "**/tests/**", "max_results": 50 }
}

目录结构（核心）

  • src/index.ts处理入口。解析CLI/环境变量，创建MCP Server并连接到stdio传输。
  • src/server.ts注册MCP工具：index_project与codebase_search。
  • src/services/repositoryIndexer.ts索引和同步核心逻辑（初始数据库创建、批量上传、增量同步、计时器）。
  • src/services/codeSearcher.ts搜索逻辑（预同步、远程搜索、结果解密和格式化）。
  • src/services/fileWatcher.ts文件变化监控，标记pendingChanges。
  • src/services/stateManager.ts工作区状态持久化state.json）。
  • src/crypto/pathEncryption.ts路径段加密和解密方案兼容Windows/Posix。
  • src/client/proto.ts加载proto/repository_service.proto并使用protobuf编码和解码发送HTTP请求。
  • src/client/cursorApi.ts封装特定的RepositoryService接口供调用。
  • src/utils/env.ts配置解析，默认参数和请求头。
  • src/utils/fs.ts忽略规则，文件遍历和嵌入文件列表读取。
  • src/utils/semaphore.ts并发控制和重试信号量。

工作原理

  1. 初始索引
  • 扫描工作区（忽略node_modules/``.git/``dist/并生成默认清单embeddable_files.txt（每个工作区独立存储）。
  • 根据@anysphere/file-service中的MerkleClient构建目录Merkle树，获取rootHash使用simhash。
  • 生成路径加密密钥（pathKey），并使用V1MasterKeyedEncryptionScheme分段加密相对路径。
  • 按批次分组文件（INITIAL_UPLOAD_MAX_FILES执行完整流程：
    • FastRepoInitHandshakeV2握手（返回codebaseId）。
    • 上传这批文件（FastUpdateFileV2）。
    • EnsureIndexCreated与FastRepoSyncComplete标记索引完成。
  • 将codebaseId``pathKey``orthogonalTransformSeed等待持久化到工作区状态state.json。
  1. 增量同步
  • 使用chokidar监控文件变化，仅标记pendingChanges = true轻量级。
  • 当触发搜索或计时器时，如果有变化：
    • 使用SyncMerkleSubtreeV2比较目录节点以定位不匹配的子树和文件。
    • 对更改的文件执行批量上传，并执行EnsureIndexCreated/FastRepoSyncComplete。
    • 清除pendingChanges标记并持久化。
  1. 语义搜索
  • 在搜索前触发按需增量同步，确保结果是新鲜的。
  • 调用SearchRepositoryV2，并使用本地返回的加密路径pathKey解密为Posix相对路径，输出{ path, score, startLine, endLine }。

系统需求

  • Node.js >= 18
  • proto/repository_service.proto必须存在（仓库附带）。

启动（npx）

npx -y --package=git+https://github.com/CometixAI/Cometix-Indexer.git cometix-indexer -- --auth-token "$CURSOR_AUTH_TOKEN" --base-url https://api2.cursor.sh

启动（npm脚本）

# 安装依赖并构建
npm install
npm run build

# 方式一：通过环境变量（PowerShell示例）
$env:CURSOR_AUTH_TOKEN="你的Token"; npm run start

# 方式二：通过参数传递（-- 之后的参数会透传给脚本）
npm run start -- --auth-token 你的Token --base-url https://api2.cursor.sh --log-level info

# 开发模式（监听编译；运行需要另开终端执行 start）
npm run dev
# 另开一个终端
npm run start -- --auth-token 你的Token

可用环境变量：

  • CURSOR_AUTH_TOKEN(必需)
  • CURSOR_BASE_URL(默认https://api2.cursor.sh)
  • LOG_LEVEL(debug | info | warning | error默认info)

环境变量和默认值（可调）

  • SYNC_CONCURRENCY(默认4)
  • SYNC_MAX_NODES(默认2000)
  • SYNC_MAX_ITERATIONS(默认10000)
  • SYNC_LIST_LIMIT(默认1000)
  • FILE_SIZE_LIMIT_BYTES(默认2MB，超过将被跳过)
  • INITIAL_UPLOAD_MAX_FILES(默认10，初始索引批处理大小)
  • PROTO_TIMEOUT_MS(默认30000)
  • PROTO_SEARCH_TIMEOUT_MS(默认60000)
  • AUTO_SYNC_INTERVAL_MS(默认5分钟)

开发、安装和构建

npm install
npm run build

状态和数据持久化

  • 工作区独占数据目录：%USERPROFILE%/.cometix/cursor-indexer/<safeName>-<hash>/
    • state.json保存codebaseId``pathKey``orthogonalTransformSeed等待。
    • embeddable_files.txt首次索引生成的可嵌入文件列表可以手动编辑，精确控制索引范围。

路径加密和兼容性

  • 采用分段对称加密aes-256-ctr）和Windows相对路径（以./或.\开头），在初始级别进行，避免暴露实际目录结构。
  • 搜索结果将自动尝试使用本地pathKey解密为Posix相对路径，失败时回退到原始加密字符串。

忽略和限制

  • 默认忽略：node_modules/``.git/``.cursor/``dist/``build/``coverage/等待。
  • 超过FILE_SIZE_LIMIT_BYTES的文件将被跳过。

常见问题

  • 报错repository_service.proto not found请确认项目根目录下存在proto/repository_service.proto。
  • Missing CURSOR_AUTH_TOKEN通过--auth-token传递参数或设置环境变量CURSOR_AUTH_TOKEN。

许可证

MIT