Claude Context MCP 服务器开发指南工具设计、stdio 协议规范与多客户端联调实践【免费下载链接】claude-contextCode search MCP for Claude Code. Make entire codebase the context for any coding agent.项目地址: https://gitcode.com/GitHub_Trending/co/claude-context导读本文是zilliz/claude-context-mcp包Claude Context 项目的 MCP 服务器的完整开发指南。它面向想要为本包贡献代码、修复缺陷或深入理解其内部机制的开发者覆盖从构建命令、环境变量、启动流程、MCP 协议纪律、四个工具的入参设计到 Cursor / Claude Code / Claude Desktop 等客户端开发模式联调的全过程。读完本文你将掌握该 MCP 服务器的开发工作流、index_codebase/search_code/clear_index/get_indexing_status四个工具的准确参数契约以及如何在不污染 MCP 协议的前提下调试与验证你的改动。MCP 服务器在项目中的定位Claude Context 是一个代码语义搜索项目核心思路是把整个代码库切片、向量化后存入 Milvus / Zilliz Cloud从而让任何编码 Agent 都能用自然语言检索代码上下文。zilliz/claude-context-mcp是该项目面向 Agent 生态的 MCP 集成层——它把底层索引与检索能力包装成标准的 MCP 工具使 Claude Code、Cursor、Gemini CLI、Qwen Code 等一切支持 Model Context Protocol 的客户端都能直接使用。从仓库结构看本包是 monorepopnpm-workspace.yaml中的一个独立包packages/mcp —— 本文主角MCP 服务器实现TypeScript入口 src/index.tspackages/core —— 被 MCP 服务器依赖的核心索引引擎切片、向量化、同步packages/vscode-extension —— 同一能力的 VSCode 集成形态。packages/mcp/package.json显示其依赖zilliz/claude-context-coreworkspace 链接与官方modelcontextprotocol/sdk并使用zod做参数校验bin指向dist/index.js意味着构建后的产物可以直接作为 MCP 服务器命令执行。首次参与贡献的开发者请先阅读仓库根目录的 CONTRIBUTING.md其中包含 monorepo 的通用设置、分支与提交流程本文只聚焦 MCP 服务器本身的开发细节。开发环境与快速命令本包的所有开发命令定义在 packages/mcp/package.json 的scripts中。先安装依赖仓库根目录使用 pnpm workspacepnpm install然后即可使用下列核心命令命令实际执行的脚本用途pnpm build:mcp构建 MCP 服务器等价于本包目录下的pnpm build即tsc --build --force产出dist/index.js供 MCP 客户端加载pnpm dev:mcptsx --watch src/index.ts监听模式开发源码变更自动重启pnpm starttsx src/index.ts直接以 TypeScript 源码启动服务器不经构建pnpm start:with-envOPENAI_API_KEY${OPENAI_API_KEY:your-api-key-here} MILVUS_ADDRESS${MILVUS_ADDRESS:localhost:19530} tsx src/index.ts携带示例环境变量启动适合本地冒烟测试除上述命令外包内还有pnpm linteslint、pnpm typechecktsc --noEmit、pnpm testNode 原生 test runner tsx执行src/**/*.test.ts。开发时建议至少通过pnpm typecheck与pnpm lint再提交。启动服务器从构建到连接官方文档给出的运行路径是pnpm build # 1. 构建tsc 输出 dist/index.js pnpm start # 2. 运行服务器tsx 直跑源码或对 dist/index.js 执行 nodepnpm start直接执行 src/index.ts其main()流程为解析命令行参数--help/-h时输出帮助并退出帮助文本定义在 src/config.ts 的showHelpMessage()包含全部环境变量与启动示例调用createMcpConfig()从环境变量装配配置并打印摘要实例化ContextMcpServer依次初始化 embedding provider、MilvusVectorDatabase、核心Context对象以及SnapshotManager、SyncManager、ToolHandlers三个管理器启动时先执行validateLegacyZeroEntries()修复历史遗留的异常快照条目详见下文「快照机制」一节再通过StdioServerTransport连接 MCP 客户端服务器连接建立后调用syncManager.startBackgroundSync()启动后台同步启动延迟 5 秒 周期轮询监听SIGINT/SIGTERM实现优雅退出。必需环境变量MCP 服务器本质上是「embedding 提供方 Milvus/Zilliz 向量库」的适配层因此两个必需项缺一不可Embedding Provider 的 API Key按所选 provider 不同而不同Milvus 向量数据库本地 Milvus 或 Zilliz Cloud。环境变量的完整清单与说明见 packages/mcp/README.md 的「Prepare Environment Variables」一节与仓库 docs/getting-started/environment-variables.md。Embedding Provider 选择默认 provider 是 OpenAI通过EMBEDDING_PROVIDER切换# 支持的 providerOpenAI, VoyageAI, Gemini, Ollama源码中另有 OpenRouter EMBEDDING_PROVIDEROpenAI各 provider 的最小配置如下来自 packages/mcp/README.md1. OpenAI默认OPENAI_API_KEYsk-your-openai-api-key # 必需 EMBEDDING_MODELtext-embedding-3-small # 可选默认 text-embedding-3-small OPENAI_BASE_URLhttps://api.openai.com/v1 # 可选兼容 Azure OpenAI 等自定义端点2. VoyageAIVOYAGEAI_API_KEYpa-your-voyageai-api-key # 必需 EMBEDDING_MODELvoyage-code-3 # 可选默认 voyage-code-33. GeminiGEMINI_API_KEYyour-gemini-api-key # 必需 EMBEDDING_MODELgemini-embedding-001 # 可选默认 gemini-embedding-001支持 gemini-embedding-2 GEMINI_BASE_URLhttps://generativelanguage.googleapis.com/v1beta # 可选4. Ollama本地/自托管EMBEDDING_MODELnomic-embed-text # 必需指定本地模型 OLLAMA_HOSThttp://127.0.0.1:11434 # 可选默认 http://127.0.0.1:11434 EMBEDDING_DIMENSION768 # 可选跳过运行时维度探测Ollama 使用前需先拉取模型并启动服务ollama pull nomic-embed-text、ollama serve。模型选择逻辑可以在 src/config.ts 的getDefaultModelForProvider()/getEmbeddingModelForProvider()中得到源码级印证各 provider 的默认模型硬编码在getDefaultModelForProvider()中OpenAI→text-embedding-3-small、VoyageAI→voyage-code-3、Gemini→gemini-embedding-001、Ollama→nomic-embed-text而getEmbeddingModelForProvider()会优先读取EMBEDDING_MODEL环境变量对 Ollama 还额外兼容旧的OLLAMA_MODEL变量优先级OLLAMA_MODELEMBEDDING_MODEL 默认值。EMBEDDING_DIMENSION则经getPositiveIntegerFromEnv()校验非正整数会被忽略并告警。embedding 实例的创建逻辑在 src/embedding.ts按 provider 分发到OpenAIEmbedding/VoyageAIEmbedding/GeminiEmbedding/OllamaEmbedding缺少对应 API Key 时直接抛出明确错误OpenRouter 则复用OpenAIEmbedding并固定指向其 OpenAI 兼容端点。Milvus / Zilliz Cloud向量库只需一个 tokenZilliz Cloud 的 Personal KeyMILVUS_TOKENyour-zilliz-cloud-api-key # 可选慢集群上增大 collection 上限预检查超时默认 15000 毫秒 MILVUS_COLLECTION_LIMIT_CHECK_TIMEOUT_MS30000注意 src/config.ts 中milvusAddress是可选的——createMcpConfig()将其置为「可以从 token 自动解析」的状态即只配MILVUS_TOKEN时地址会自动推导本地部署时也可显式给出MILVUS_ADDRESSlocalhost:19530。其余可选环境变量以下变量同样是开发与部署中常见的调优项全部出自 packages/mcp/README.md并被 src/config.ts 的showHelpMessage()收录# 1. Embedding 批大小默认 100按模型吞吐调整 EMBEDDING_BATCH_SIZE512 # 2. 全局自定义文件扩展名与忽略规则与工具参数中的自定义项会合并生效 CUSTOM_EXTENSIONS.vue,.svelte,.astro,.twig CUSTOM_IGNORE_PATTERNStemp/**,*.backup,private/**,uploads/** # 3. 集合名可读前缀保留 per-codebase 的 pathHash 后缀避免多仓库塌缩到一个集合 CODE_CHUNKS_COLLECTION_NAME_OVERRIDEmy_project # 4. 触发文件监听器默认 true只读文件系统/沙箱环境可关 CLAUDE_CONTEXT_TRIGGER_WATCHERtrue # 5. 后台同步开关与周期默认 true / 300000ms CLAUDE_CONTEXT_BACKGROUND_SYNCfalse CLAUDE_CONTEXT_SYNC_INTERVAL_MS60000CODE_CHUNKS_COLLECTION_NAME_OVERRIDE的命名规则在文档中有精确描述覆盖值会被清洗为字母、数字、下划线并截断以保证完整集合名不超过 Milvus 的 255 字符上限取消该变量后自动回退到code_chunks_pathHash命名。CLAUDE_CONTEXT_BACKGROUND_SYNC/CLAUDE_CONTEXT_SYNC_INTERVAL_MS的解析在 src/sync.ts 的isBackgroundSyncEnabled()/getBackgroundSyncIntervalMs()中实现布尔解析接受1/true/yes/on与0/false/no/off非法值回退默认间隔低于 1000ms 的最小值会被拒绝并回退到 5 分钟。MCP 协议纪律三条硬性要求CONTRIBUTING.md 明确要求遵循 MCP 规范核心有四点使用 stdio 传输保证与所有 MCP 客户端的兼容性优雅处理错误并以正确的 MCP 响应格式返回isError: true 文本内容而不是让进程崩溃日志必须重定向到 stderr绝不能污染 stdout——因为 stdout 是 MCP JSON-RPC 协议数据的唯一通道工具接口保持简单直观、错误信息清晰、所有用户输入都要校验。第 3 点在 src/index.ts 顶部有最直接的实现证据文件开头的注释写着 CRITICAL: Redirect console outputs to stderr IMMEDIATELY随后把console.log与console.warn整体重写为向process.stderr写入带[LOG]/[WARN]前缀的内容console.error本身就走 stderr。这意味着你在 MCP 服务器内打印的任何日志都不会干扰协议帧。错误处理方面src/handlers.ts 中每个 handler 都用 try/catch 包裹且 catch 分支永远返回 MCP 响应对象而非抛出异常例如handleIndexCodebase的注释明确写着 Ensure we always return a proper MCP response, never throw。输入校验的典型例子包括ensureAbsolutePath()强制绝对路径、路径必须存在且为目录、splitter参数必须匹配ast|langchainisRequestSplitterType()、extensionFilter必须以.开头且不含空白字符。工具参数详解通过ListToolsRequestSchema服务器共注册四个工具src/index.ts 的setupTools()。开发指南中重点介绍了前三个第四个get_indexing_status在源码与 README 中同样存在。index_codebase—— 索引代码库对指定目录做混合检索BM25 稠密向量索引。参数类型必填默认值说明pathstring✅—目标代码库目录的绝对路径forceboolean否false已索引时强制重建索引splitterstring否astast语法感知切片失败自动回退或langchain字符切片customExtensionsstring[]否[]追加的文件扩展名如[.vue, .svelte, .astro]缺省点号会自动补上ignorePatternsstring[]否[]额外忽略规则如[static/**, *.tmp, private/**, docs/generated/**]与默认规则node_modules、.git等合并splitters的工厂实现在 src/splitter.tsast对应AstCodeSplitter(2500, 300)langchain对应LangChainCodeSplitter(1000, 200)。索引是后台执行的handleIndexCodebase在完成路径校验、collection 上限预检查checkCollectionLimit()命中上限时返回COLLECTION_LIMIT_MESSAGE、快照状态写入后会立即返回「已在后台开始索引」的提示并借助AbortController跟踪后台任务使clear_index能够取消并等待其结束解决 issue #199 中「清空后后台任务仍向空集合写数据」的问题。索引期间的进度会每 2 秒持久化一次到快照见 src/handlers.ts 的startBackgroundIndexing()。search_code—— 自然语言搜索参数类型必填默认值说明pathstring✅—已索引代码库的绝对路径querystring✅—自然语言查询limitnumber否10返回结果条数最大50extensionFilterstring[]否[]按扩展名过滤结果如[.ts, .py]搜索实现src/handlers.ts 的handleSearchCode会先把extensionFilter组装成 Milvus 过滤表达式fileExtension in [...]再以Math.min(resultLimit, 50)截断上限、0.3作为分数阈值调用context.semanticSearch()。结果按相对路径:起始行-结束行格式化代码片段会截断到 5000 字符truncateContent()见 src/utils.ts。搜索前还会做快照与向量库的一致性检查快照缺失但 Milvus 有索引时自动恢复快照再继续。clear_index—— 清除索引参数类型必填说明pathstring✅要清除索引的代码库绝对路径handleClearIndex会先取消并等待该路径上仍在运行的后台索引任务再调用context.clearIndex()最后把该代码库从快照中完全移除removeCodebaseCompletely()并汇报剩余索引数量。get_indexing_status—— 查询索引状态参数类型必填说明pathstring✅要查询状态的代码库绝对路径返回indexed/indexing/indexfailed/not_found四种状态getCodebaseStatus()见 src/snapshot.ts。解读该工具输出时需注意出自 packages/mcp/README.md进度是基于阶段的collection 准备、文件扫描、文件处理/embedding不是文件计数比——大仓库上百分比可能跳变长 embedding 批次期间可能长时间不动文件数与 chunk 数只在索引成功结束时写入索引进行中刻意只报进度代码库以绝对路径为键索引/repo、其符号链接路径、以及另一个克隆会被视为独立条目已完成条目显示0 files, 0 chunks通常是本地快照元数据过期而非向量库真为空对该绝对路径重新索引或清除后重索引即可刷新统计。后台索引与进度上报的完整机理可进一步阅读 docs/dive-deep/asynchronous-indexing-workflow.md常见问题见 docs/troubleshooting/faq.md。后台同步与触发式重建索引MCP 服务器默认在启动后 5 秒执行一次初始同步此后按CLAUDE_CONTEXT_SYNC_INTERVAL_MS默认 5 分钟周期性同步。每个同步周期会对快照中所有已索引代码库调用context.reindexByChange()用 Merkle 树做增量变更检测added/removed/modified三组统计实现只重索引变更文件的增量同步。两个值得注意的机制全部实现在 src/sync.ts跨进程全局同步锁锁文件位于~/.context/mcp-sync.lock。acquireGlobalSyncLock()通过原子mkdir竞争锁并在owner.json中记录 pid、token、获取时间超过CLAUDE_CONTEXT_SYNC_LOCK_STALE_MS默认 10 分钟的陈旧锁会被回收。这样即使多个 MCP 进程共享同一个$HOME同一时刻也只有一个进程执行同步周期。触发文件监听器服务器监听~/.context/.sync-trigger哨兵文件外部工具touch该文件即可立即触发一次重建索引。触发事件有2 秒防抖窗口快速连续 touch 会合并为一次同步且触发同步与后台同步走同一个全局锁。触发文件的内容被忽略只有修改事件有意义。典型用法是 Claude Code 的PostToolUsehook{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: touch ~/.context/.sync-trigger } ]} ] } }对多实例本地 stdio 部署文档建议设置CLAUDE_CONTEXT_BACKGROUND_SYNCfalse并保留触发监听器既避免空闲轮询又保留按需立即重建的能力。CLAUDE_CONTEXT_TRIGGER_WATCHERfalse则可在只读文件系统或沙箱环境中彻底关闭文件系统监听。快照机制与故障恢复快照文件位于~/.context/mcp-codebase-snapshot.json由 src/snapshot.ts 的SnapshotManager管理。开发时需要了解几个关键事实双版本兼容旧版 v1indexedCodebases数组会被迁移为 v2formatVersion: v2codebases映射表v2 中每个代码库条目记录状态indexed/indexing/indexfailed、进度百分比、文件数、chunk 数、上次请求的 splitter/扩展名/忽略规则以及时间戳v1 迁移时中断的 indexing 条目会被重置为indexfailed并发写保护快照写操作通过snapshotFilePath .lock目录锁串行化超过 10 秒视为陈旧锁读-合并read-merge机制把磁盘上其它进程写入的条目合并进内存避免多进程互相覆盖0/0 毒化防护setCodebaseIndexed()会拒绝持久化indexedFiles0, totalChunks0, statuscompleted的组合——因为客户端会把 0/0completed 误读为未索引并触发强制重建删除真实数据后再写回 0/0形成死循环issue #295启动自愈服务器启动时validateLegacyZeroEntries()会扫描历史遗留的 0/0completed 条目查询 Milvus 真实行数后修复行数 0 则回填、集合不存在或为空则移除且在传输层接受请求之前完成客户端永远不会观察到异常状态。如何修改代码建议流程为你的 feature/fix创建独立分支分支与提交流程遵循根目录 CONTRIBUTING.md编辑 src/index.ts——这是 MCP 服务器的主实现工具注册、请求分发、启动流程都在这里config.ts/embedding.ts/snapshot.ts/sync.ts/handlers.ts/splitter.ts/utils.ts是按职责拆分的模块用pnpm typecheck、pnpm lint做静态检查用pnpm test运行包内测试如handlers.get-indexing-status.test.ts、snapshot.request-options.test.ts、sync-lock-e2e.mjs、path-resolution-e2e.mjs覆盖了状态查询、请求选项持久化、同步锁与路径解析等关键行为用真实 MCP 客户端验证Claude Desktop、Cursor 等见下节联调配置按根目录 CONTRIBUTING.md 的提交规范提交。与 MCP 客户端联调开发模式配置Cursor / Claude Desktop 开发模式将以下配置写入客户端的 MCP 配置Cursor 为~/.cursor/mcp.json或项目级.cursor/mcp.jsonClaude Desktop 为其claude_desktop_config.json。与生产环境用npx拉取发布包不同开发模式直接指向本仓库构建产物dist/index.js{ mcpServers: { claude-context-local: { command: node, args: [PATH_TO_CLAUDECONTEXT/packages/mcp/dist/index.js], env: { OPENAI_API_KEY: sk-your-openai-api-key, MILVUS_TOKEN: your-zilliz-cloud-api-key } } } }注意先执行pnpm build确保dist/index.js存在且PATH_TO_CLAUDECONTEXT需替换为仓库在本机的绝对路径。Claude Code 开发模式用 CLI 添加服务器并通过-e逐个注入环境变量claude mcp add claude-context -e OPENAI_API_KEYsk-your-openai-api-key -e MILVUS_ADDRESSyour-zilliz-cloud-public-endpoint -e MILVUS_TOKENyour-zilliz-cloud-api-key -- node PATH_TO_CLAUDECONTEXT/packages/mcp/dist/index.js随后以claude --debug启动 Claude Code 即可看到 MCP 服务器日志——由于日志全部重定向到 stderr它们会出现在调试输出中而不会破坏协议。手动验证三个核心工具配置完成后即可手动调用工具验证端到端链路index_codebase索引仓库并测试自定义忽略规则例如{path: /repo/path, ignorePatterns: [static/**, *.tmp]}search_code用不同查询验证语义检索质量未索引时工具会返回明确的请先索引错误clear_index清除后重新索引验证幂等性。小结开发zilliz/claude-context-mcp的关键纪律可以浓缩为四点stdout 只属于协议一切日志走 stderr、工具参数小而明确绝对路径 显式默认值 全量校验、索引与同步异步化后台任务 快照持久化 跨进程锁、错误永远以 MCP 响应返回而不是让进程崩溃。理解这些约束后无论是新增工具、修复缺陷还是接入新的 MCP 客户端都能沿着 src/index.ts → 各模块 → 测试 → 客户端联调这条链路高效推进。【免费下载链接】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），仅供参考
