Claude Context 源码级架构解析为 Claude Code 打造基于 Milvus 的语义代码搜索 MCP【免费下载链接】claude-contextCode search MCP for Claude Code. Make entire codebase the context for any coding agent.项目地址: https://gitcode.com/GitHub_Trending/co/claude-contextClaude Context 是一个为 Claude Code 等 AI 编码代理提供语义代码搜索能力的 MCPModel Context Protocol插件代码库被切分为代码块、向量化后存入 Milvus/Zilliz 向量数据库查询时通过稠密向量 稀疏 BM25的混合语义检索直接命中相关代码而非将整个目录塞进模型上下文。本文以仓库根目录的 CLAUDE.md 为骨架结合packages/core、packages/mcp的真实源码逐层拆解其索引引擎、增量同步、忽略规则、环境变量解析与 MCP 服务器实现读完你既能掌握本地编译、测试、运行 MCP 服务器的完整命令链也能理解每个核心模块背后的设计意图。项目定位语义搜索替代全目录加载按 CLAUDE.md 的 Overview 描述Claude Context 解决的是 AI 编码代理面对大型代码库时的上下文瓶颈传统做法是把整个目录读入模型上下文成本高、且单次请求能携带的代码量极其有限。Claude Context 的做法是将代码库切分为 chunk代码块通过 Embedding 模型将 chunk 向量化存入 Milvus / Zilliz 向量数据库查询时执行语义混合 dense sparse搜索把命中的代码块作为上下文返回给代理。这里的关键词是混合检索不只是纯向量相似度而是稠密向量捕捉语义与稀疏向量/BM25捕捉词面匹配并行检索后重排兼顾语义理解与术语精确匹配。对应地在 packages/core/src/context.ts 中Context类的构造与检索逻辑通过HYBRID_MODE环境变量控制默认true关闭后降级为纯稠密向量检索。Monorepo 布局pnpm workspace 下的五层结构项目采用 pnpm workspace 组织packages/*与examples/*共同构成 monorepo要求Node 20 24、pnpm 10。各包职责如下包包名角色packages/corezilliz/claude-context-core索引引擎所有真实逻辑都在这其余包只是它的薄前端packages/mcpzilliz/claude-context-mcpstdio MCP 服务器主要产品使用 ESMtype: modulepackages/vscode-extensionsemanticcodesearchVSCode 扩展webpack 打包在src/stubs/中对 Node 专属依赖Milvus gRPC、原生 AST打桩packages/chrome-extension—浏览器构建将zilliz/milvus2-sdk-node覆写为false浏览器内无 gRPCexamples/basic-usage—可运行的库调用示例这种核心引擎 多端薄壳的分层是理解全仓库的钥匙无论是 MCP 服务器、VSCode 扩展还是浏览器扩展最终都调用packages/core暴露的Context类。环境要求与常用命令CLAUDE.md 给出的完整命令集pnpm install pnpm build # build all packages (examples built last) pnpm build:core # build a single package: also build:mcp, build:vscode pnpm dev # watch all; or dev:core / dev:mcp / dev:vscode pnpm lint # eslint across packages; lint:fix to autofix pnpm typecheck # tsc --noEmit across packages pnpm clean # rimraf dist in every package一个重要提示各包通过workspace:*依赖core因此修改 core 后必须先pnpm build:core再测试 mcp/vscode——它们消费的是core/dist而非源码。这也是从源码结构可直接推断的构建约定。测试策略core 与 mcp 两套 runner测试采用双轨制便于快速定位某条链路的回归core使用 Jest ts-jest测试文件与源码同目录放置*.test.tspnpm --filter zilliz/claude-context-core test # all (runs in band) pnpm --filter zilliz/claude-context-core test -- context.abort # by filename pnpm --filter zilliz/claude-context-core test -- -t pattern # by test namemcp使用 Node 内置测试运行器经 tsx 驱动无 Jestpnpm --filter zilliz/claude-context-mcp test # runs src/**/*.test.ts仓库中实际存在的测试文件与上面对应例如 core 侧的 context.abort.test.ts、context.ignore-patterns.test.ts、context.splitter.test.ts以及 mcp 侧的 handlers.get-indexing-status.test.ts、snapshot.request-options.test.ts。本地运行 MCP 服务器与全部环境变量开发模式下直接运行pnpm --filter zilliz/claude-context-mcp start # tsx src/index.ts配置完全通过环境变量注入不读配置文件主要变量见 packages/mcp/src/config.ts 与仓库根目录 .env.example变量说明默认值EMBEDDING_PROVIDEROpenAI | VoyageAI | Gemini | Ollama | OpenRouterOpenAIOPENAI_API_KEY/VOYAGEAI_API_KEY/GEMINI_API_KEY/OPENROUTER_API_KEY各提供商的 API Key按所选提供商必填无EMBEDDING_MODEL对所有提供商生效的模型名按提供商取默认见下OLLAMA_MODEL/OLLAMA_HOSTOllama 专属模型与主机nomic-embed-text/http://127.0.0.1:11434MILVUS_ADDRESSMilvus 地址可从 Zilliz token 自动解析无MILVUS_TOKENMilvus 认证 token无CODE_CHUNKS_COLLECTION_NAME_OVERRIDE集合名可读前缀覆写见下文无EMBEDDING_BATCH_SIZE分批向量化的批大小100HYBRID_MODE是否启用混合检索dense BM25trueCUSTOM_EXTENSIONS/CUSTOM_IGNORE_PATTERNS额外文件扩展名 / 忽略模式逗号分隔空CLAUDE_CONTEXT_BACKGROUND_SYNC/CLAUDE_CONTEXT_SYNC_INTERVAL_MS后台同步开关与间隔true/300000各提供商默认模型在getDefaultModelForProviderpackages/mcp/src/config.ts中定义OpenAI 为text-embedding-3-smallVoyageAI 为voyage-code-3Gemini 为gemini-embedding-001OpenRouter 为openai/text-embedding-3-smallOllama 为nomic-embed-text。.env.example明确建议将文件复制为~/.context/.env作为全局配置注意不要放在代码库目录内以免与业务项目自身的环境变量冲突。架构总览Context 编排器与三个可插拔接口packages/core/src/context.ts 中的Context是整个系统的编排中枢通过构造函数注入三个可插拔接口ContextConfigEmbeddingpackages/core/src/embedding/接口定义在base-embedding.ts实现包括OpenAIEmbedding、VoyageAIEmbedding、GeminiEmbedding、OllamaEmbedding另有base-embedding.ts统一抽象embedBatch支持批量向量化VectorDatabasepackages/core/src/vectordb/MilvusVectorDatabasegRPC仅 Node与MilvusRestfulVectorDatabaseHTTP浏览器安全zilliz-utils.ts中的ClusterManager可自助开通免费 Zilliz 集群并从 token 解析出 addressSplitterpackages/core/src/splitter/AstCodeSplitter基于 tree-sitter默认 chunk 2500 / overlap 300对不支持的语言或解析失败自动回退到LangChainCodeSplitter。对外公共 API 为indexCodebase、reindexByChange、semanticSearch、clearIndex、hasIndex由 packages/core/src/index.ts 统一 re-export。集合命名规则getCollectionName对代码库绝对路径做 MD5 哈希取前 8 位生成hybrid_code_chunks_pathHash混合模式或code_chunks_pathHash纯向量模式。CODE_CHUNKS_COLLECTION_NAME_OVERRIDE或collectionNameOverride可加可读前缀但源码显示覆写值会被清洗仅保留字母/数字/下划线、总长不超 255且始终保留_pathHash后缀避免同一 MCP 服务器下多个代码库塌缩进同一个集合。索引流水线从文件扫描到向量入库indexCodebasepackages/core/src/context.ts的执行流程计算 ignore 模式loadIgnorePatterns含请求级附加模式准备集合prepareCollection检查/创建集合forceReindextrue时先 drop 再建并通过embedding.detectDimension()探测向量维度递归扫描文件按支持扩展名 ignore 规则过滤得到待索引文件列表流式处理逐文件读取 → 按语言切分 → 攒满EMBEDDING_BATCH_SIZE默认 100一批 → 批量向量化 → upsert 入库进度经progressCallback上报前 10% 留给准备阶段90% 用于实际索引。默认支持扩展名DEFAULT_SUPPORTED_EXTENSIONS覆盖.ts/.tsx/.js/.jsx/.py/.java/.cpp/.c/.h/.hpp/.cs/.go/.rs/.php/.rb/.swift/.kt/.scala/.m/.mm/.dart/.sol以及.md/.markdown/.ipynb。索引单次处理的 chunk 上限为 450000CHUNK_LIMIT达到后以status: limit_reached停止。AST 切分的细节packages/core/src/splitter/ast-splitter.ts按语言维护可切分节点类型表SPLITTABLE_NODE_TYPES例如 JavaScript/TypeScript 切在function_declaration、class_declaration、method_definition、arrow_function、export_statement等节点Python 切在function_definition、class_definition等节点Rust 切在function_item、impl_item、struct_item等。切出的节点若超过chunkSize再按字符二次拆分相邻 chunk 之间追加chunkOverlap300 字符重叠保证跨块上下文不丢失。仓库中tree-sitter的 WASM 版本随 VSCode 扩展打包于 packages/vscode-extension/wasm/。检索参数semanticSearch混合模式下构建两个检索请求——稠密向量字段vectornprobe: 10与稀疏字段sparse_vectordrop_ratio_search: 0.2随后用 RRFReciprocal Rank Fusionk: 100重排合并最终按文件 行号区间做去重同一文件重叠超 50% 保留高分者。搜索前会校验集合是否存在并提示先索引。错误处理语义两个携带控制流的异常CLAUDE.md 特别强调改动流水线时必须保留两个错误类型的控制流语义IndexAbortError通过AbortSignal实现协作式取消。processFileList在每个文件边界检查signal.aborted一旦取消即抛出该异常保证取消后不再发生任何入库/快照写入MCP 的clear_index处理器依赖此机制;EmbeddingError总是被重新抛出以终止整个流水线这与单文件读取/解析错误记录日志后跳过不同。原因是防止静默的部分索引——即 Milvus 一个向量都没写入而快照却把文件标记为完成导致后续检索查不到任何结果。增量同步Merkle DAG 驱动的 reindexByChangeFileSynchronizerpackages/core/src/sync/synchronizer.ts用文件哈希构建 Merkle DAGpackages/core/src/sync/merkle.ts在两次运行之间比较出{added, removed, modified}三类变更使reindexByChange只触碰变更过的文件先删掉被移除/被修改文件的旧 chunk再对新增/修改文件走同一套切分-向量化-入库流程。文件哈希采用 SHA-256DAG 以文件路径 哈希为节点内容父节点哈希再汇总所有子节点。快照持久化到~/.context/merkle/代码库绝对路径MD5.jsonclearIndex在删除集合的同时也会调用FileSynchronizer.deleteSnapshot清理快照。MCP 服务器还可通过环境变量开启后台同步循环CLAUDE_CONTEXT_BACKGROUND_SYNC默认true启动后延迟 5 秒执行首次同步之后按间隔轮询CLAUDE_CONTEXT_SYNC_INTERVAL_MS轮询间隔毫秒数默认 3000005 分钟最小 1000另有CLAUDE_CONTEXT_TRIGGER_WATCHER默认true监控~/.context/.sync-trigger触发文件外部进程如 Claude Code 的 PostToolUse 钩子touch 该文件即可触发一次去抖2 秒的即时重索引且触发式与轮询式共享跨进程全局同步锁~/.context/mcp-sync.lock多实例部署时不会并发写库。这些行为都可在 packages/mcp/src/sync.ts 中逐一找到对应实现。Ignore 模式多层叠加过滤文件过滤是分层叠加的见 packages/core/src/context.ts 与 packages/core/src/utils/ignore-matcher.ts内置DEFAULT_IGNORE_PATTERNSnode_modules/**、dist/**、build/**、.git/**、__pycache__/**、*.min.js、.env、*.map等数十条同时保留目录名形式构造/请求级配置的ignorePatterns/customIgnorePatterns环境变量CUSTOM_IGNORE_PATTERNS磁盘上的 ignore 文件.gitignore、.contextignore、.xxxignore以及全局~/.context/.gitignore。IgnoreMatcher基于ignore库实现完整支持 gitignore 的!取反语义并由 context.ignore-patterns.test.ts 覆盖测试。另外任何路径中包含以.开头的隐藏段如.github、.foo/bar都会被自动忽略。环境变量解析envManager 的优先级packages/core/src/utils/env-manager.ts 中的envManager.get(name)按process.env~/.context/.env文件的优先级解析变量。规范要求凡是读取配置都应使用envManager而非直接读process.env这样才能让~/.context/.env的兜底机制持续生效envManager同时提供set()将变量写入该文件。这也是.env.example建议复制到~/.context/.env的原因——MCP 服务器启动时若进程环境未注入仍能从该文件读到配置。MCP 服务器层stdio 协议与四个工具packages/mcp/src/index.ts 是服务器入口有两个关键设计文件最顶部就把console.log/console.warn重定向到 stderr——因为 stdout 保留给 MCP JSON 协议stdio 传输任何非协议输出污染 stdout 都会破坏协议解析这是该包内不可违背的铁律启动时校验并修复遗留的0/0 completed异常快照条目见validateLegacyZeroEntries避免客户端观测到错误的索引状态。模块划分与 CLAUDE.md 描述一一对应文件职责handlers.tsToolHandlers实现四个工具index_codebase、search_code、clear_index、get_indexing_statussnapshot.tsSnapshotManager跨服务器重启记录每个代码库的索引状态v2 格式含indexing/indexed/indexfailed三态与进度百分比sync.tsSyncManager驱动增量重索引、后台轮询与触发文件监听config.ts从环境变量构建ContextMcpConfig含默认模型选择与配置摘要日志embedding.ts按提供商构造 Embedding 实例工具参数值得注意index_codebase支持path必须绝对路径、force、splitterast/langchain、customExtensions、ignorePatternssearch_code支持path、query、limit默认 10最大 50、extensionFilter。开发约定提交遵循 Conventional Commitsscope 固定为core、vscode、mcp、examples、docs例如fix(core): support gitignore negation patterns全部代码与注释使用英文。贡献相关说明可分别查阅 CONTRIBUTING.md、packages/core/CONTRIBUTING.md、packages/mcp/CONTRIBUTING.md 与 packages/vscode-extension/CONTRIBUTING.md。深入阅读导航端到端使用入门文档见 docs/getting-started/quick-start.md 与 docs/getting-started/environment-variables.md文件包含/排除规则见 docs/dive-deep/file-inclusion-rules.md索引流程的示意图在 docs/dive-deep/indexing-flow-diagram.png异步索引工作流docs/dive-deep/asynchronous-indexing-workflow.md疑难排查docs/troubleshooting/faq.md 与 docs/troubleshooting/troubleshooting-guide.md可运行示例examples/basic-usage/检索质量评估evaluation/目录下包含run_evaluation.py、client.py及案例研究如evaluation/case_study/django_14170/。【免费下载链接】claude-contextCode search MCP for Claude Code. Make entire codebase the context for any coding agent.项目地址: https://gitcode.com/GitHub_Trending/co/claude-context创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
