适合谁
- 需要长期维护、代码量很大(数百万行以上)的企业级或多语言代码库
- 希望嵌入与索引数据完全留在本机、不外传的隐私敏感团队
- 已在使用 Claude Code、Cursor、VS Code Copilot 或 Gemini CLI,想让 AI 助手更少读文件、更多用语义搜索和依赖图的开发者
- 多个 AI 代理或多人协作、共享同一份代码索引的团队
S
67FMRS · C
SocratiCode 是一个功能较为完整的本地代码库智能 MCP 服务器,提供混合语义搜索、多语言依赖图和符号级影响分析等能力,默认在本机 Docker 容器中运行、无需 API key,适合大型多语言代码库的深度探索场景。使用前需要接受运行本地 Docker 容器、按需配置云端嵌入 API 密钥,以及 AGPL-3.0 许可证的约束;文档明确说明了调用图基于静态分析、对动态派发和框架魔法存在盲区,团队应结合人工审查使用其影响分析结果。
SocratiCode 是一个开源 MCP 服务器,为 AI 助手提供代码库的深度语义理解。它基于 Qdrant 向量数据库和 Ollama(默认本地、也可切换到 OpenAI 或 Google 云端嵌入)构建混合语义+BM25(RRF 融合)搜索,并使用 ast-grep 对 18 种以上语言做 AST 感知分块与多语言依赖关系图分析,支持符号级影响分析(blast radius)、调用流追踪、循环依赖检测、交互式 HTML 图谱查看器,以及跨项目、按分支索引和数据库/API/基础设施等非代码知识的检索。README 声称在 VS Code(245 万行代码)基准测试中比基于 grep 的探索减少 61% 的上下文、减少 84% 的工具调用、快 37 倍。默认在 Docker 中本地运行,不需要 API key,代码不出本机;也可配置云端嵌入服务和外部 Qdrant 实例。项目以 AGPL-3.0 许可发布,并提供尚处私测阶段的付费云端版本(SocratiCode Cloud)。
工具能力
codebase_index
在后台开始对代码库进行完整索引(分块、生成嵌入并写入 Qdrant),可通过 codebase_status 轮询进度。
codebase_stop
安全地停止正在进行的索引任务,当前批次完成并保存检查点,之后可通过 codebase_index 续跑。
codebase_update
增量更新索引,仅重新处理自上次索引以来发生变更的文件。
codebase_remove
删除某个项目的索引,会先停止文件监视器并取消正在进行的索引/更新任务。
codebase_watch
启动或停止文件监视:启动时先追平错过的变更,再持续监听后续文件改动。
codebase_search
混合语义+关键词(稠密向量+BM25,RRF 融合)搜索,支持按文件路径、语言过滤,以及跨项目搜索(includeLinked)。
codebase_status
查看索引状态、已索引文件数与分块数量。
codebase_graph_build
在后台构建多语言依赖关系图,可通过 codebase_graph_status 轮询进度。
codebase_graph_query
查询指定文件的导入(imports)及依赖它的文件(dependents)。
codebase_graph_stats
获取依赖图统计信息,如连接度最高的文件、孤立文件、各语言占比。
codebase_graph_circular
检测代码库中的循环依赖。
codebase_graph_visualize
生成依赖关系图的 Mermaid 图表,或输出可离线使用的交互式 HTML 图谱浏览器(文件/符号视图、影响范围叠加、实时搜索、PNG 导出)。
codebase_graph_status
查看依赖图构建进度或已持久化的图谱元数据。
codebase_graph_remove
删除项目已持久化的依赖关系图(会等待正在进行的图谱构建完成)。
codebase_impact
符号级影响分析(blast radius):通过反向调用边的广度优先搜索,判断修改某个文件/函数会波及哪些文件。
codebase_flow
从入口点正向追踪执行流程;不带参数调用时可自动发现候选入口点(孤立函数、main()、框架路由、测试等)。
codebase_symbol
查看单个符号(函数/方法)的完整信息:定义位置、调用者(callers)与被调用者(callees)。
codebase_symbols
列出某文件中的符号,或按名称在全项目范围内搜索符号。
codebase_context
查看项目中可用的非代码知识产物(数据库结构、API 规范、基础设施配置、架构文档等)。
codebase_context_search
在已索引的上下文产物中搜索特定的数据库表、API 端点或配置项。
codebase_context_index
重新索引/刷新已过期的上下文产物(如数据库结构、API 规范等)。
安装接入
1) 确保本地已安装并启动 Docker,以及 Node.js 18 及以上版本。2) 最简单方式:在支持 MCP 的客户端配置中加入 npx 启动命令 {"command":"npx","args":["-y","socraticode"]}(如 Claude Desktop、Windsurf、Cline、Roo Code 等的 mcpServers 配置,或 VS Code 项目内 .vscode/mcp.json 的 servers 配置)。3) Claude Code 用户推荐安装官方插件以自动获得配套技能:claude plugin marketplace add giancarloerra/socraticode 后 claude plugin install socraticode@socraticode,或在 Claude Code 内执行 /plugin marketplace add giancarloerra/socraticode 与 /plugin install socraticode@socraticode。4) VS Code/Cursor 用户也可在扩展市场搜索 SocratiCode 安装官方扩展或插件。5) 首次使用时服务器会自动拉取 Docker 镜像并启动 Qdrant 与 Ollama 容器、下载嵌入模型,大约耗时 5 分钟;之后启动只需数秒。6) 如需使用云端嵌入(OpenAI/Google)或外部 Qdrant,可在配置的 env 字段中设置 EMBEDDING_PROVIDER、OPENAI_API_KEY、GOOGLE_API_KEY、QDRANT_MODE、QDRANT_URL、QDRANT_API_KEY 等环境变量。7) 首次在项目中使用时,让 AI 执行“索引这个代码库”触发 codebase_index,之后用 codebase_status 查看索引进度。
claude_desktop_config.json
{"mcpServers":{"socraticode":{"command":"npx","args":["-y","socraticode"]}}}
选型与风险
不适合谁
- 无法在本机或 CI 环境运行 Docker(或不允许运行容器)的场景
- 只有几百行代码的小型项目,配置 Docker/Qdrant/Ollama 的成本大于收益
- 需要完全托管、开箱即用的云端共享索引的团队(SocratiCode Cloud 仍处于私测阶段,尚未正式发布)
- 对新增本地容器、后台文件监视进程和第三方 npm 包有严格安全审批限制的环境
所需权限
- 读取本地项目代码库文件系统,用于 AST 分块与索引
- 通过 Docker 启动并管理本地 Qdrant(向量数据库)与 Ollama(嵌入模型)容器
- 本地文件系统写入权限,用于持久化索引、图谱数据及可选的交互式 HTML 图谱文件
- 文件系统监视权限,用于实时检测文件变更并增量更新索引
- 如配置云端嵌入或外部 Qdrant,需要出站网络访问以及对应的 API 密钥(OPENAI_API_KEY、GOOGLE_API_KEY、QDRANT_API_KEY 等)
风险与副作用
- 默认会自动拉取并运行 Docker 镜像(Qdrant、Ollama),需要信任这些容器镜像及其运行时行为
- 若切换到 OpenAI 或 Google 云端嵌入,代码片段会被发送至第三方 API,不再是“完全本地私有”,需评估代码保密性要求
- API 密钥(OPENAI_API_KEY、GOOGLE_API_KEY、QDRANT_API_KEY)以环境变量形式配置,需注意密钥泄露及配置文件的访问权限
- 若使用外部/远程 Qdrant 实例并配置不当,索引内容(可能包含代码片段乃至敏感字符串)存在暴露风险
- 项目采用 AGPL-3.0 许可,与部分商业/闭源软件集成时需评估许可证合规性
- MCP 客户端一旦连接,即拥有对索引、图谱和上下文产物的全部读写与删除权限,缺少细粒度的工具级权限控制
- 依赖静态分析的调用图无法捕获动态派发、反射、框架魔法(如依赖注入、装饰器路由)等,存在“零调用者”误判风险,不能完全替代人工审查
常见排障
- 确保 Docker 正在运行(managed 模式下必需),否则容器化的 Qdrant/Ollama 无法启动
- 若 codebase_search 无结果,先执行 codebase_status 确认项目是否已索引,未索引则运行 codebase_index
- macOS/Windows 上 Docker 容器无法访问 GPU,大中型代码库嵌入较慢,建议原生安装 Ollama 或改用 OpenAI/Google 云端嵌入以提速
- npx 会缓存包版本,如需更新到最新版,执行 `rm -rf ~/.npm/_npx` 并重启 MCP 客户端,或在配置中使用 `socraticode@latest`
- 若此前用 `claude mcp add` 单独注册过服务,再安装插件后应执行 `claude mcp remove socraticode` 避免重复注册
- 索引大型代码库时,建议每隔约 60 秒调用一次 codebase_status,防止部分 MCP 主机因空闲断开连接而中断后台索引
- 若使用外部 Ollama/Qdrant,检查 OLLAMA_MODE/OLLAMA_URL、QDRANT_MODE/QDRANT_URL/QDRANT_API_KEY 等环境变量是否正确指向可达实例
使用场景
在超大型(数千万行级)多语言企业代码库中做语义+关键词混合搜索,快速定位相关代码
重构、重命名或删除代码前,用符号级影响分析(codebase_impact)评估波及范围
通过 codebase_flow 从入口点追踪调用链,理解一段陌生代码到底做了什么
查看和可视化模块间依赖关系图,检测循环依赖等架构问题
跨多个关联仓库或按 Git 分支分别维护和检索索引
检索数据库结构、API 规范、基础设施配置等代码之外的项目知识
支持客户端
Claude Code完整支持
VS Code完整支持
Cursor完整支持
Gemini CLI完整支持
Claude Desktop部分支持
Windsurf部分支持
Cline部分支持
Roo Code部分支持
Zed部分支持
OpenAI Codex CLI部分支持
OpenCode部分支持