SocratiCode

社区

本地私有的企业级代码库智能引擎:混合语义搜索与依赖影响分析

分类: 开发工具第 26 / 438
Stars: ★ 3.4k 非常热门
传输方式: stdio（本地进程）
运行环境: Node.js 18+ · Docker
凭据: 无需凭据
许可证: AGPL-3.0
最近提交: 1 天前
工具数: 21

67FMRS · C

SocratiCode 是一个功能较为完整的本地代码库智能 MCP 服务器,提供混合语义搜索、多语言依赖图和符号级影响分析等能力,默认在本机 Docker 容器中运行、无需 API key,适合大型多语言代码库的深度探索场景。使用前需要接受运行本地 Docker 容器、按需配置云端嵌入 API 密钥,以及 AGPL-3.0 许可证的约束;文档明确说明了调用图基于静态分析、对动态派发和框架魔法存在盲区,团队应结合人工审查使用其影响分析结果。

最强项 · 文档质量 18/20 最弱项 · 可靠性 9/20

可靠性

9/20

安全与权限

14/20

维护活跃度

13/20

文档质量

18/20

安装易用性

13/20

查看各项评分依据

可靠性 9/20: README 展示了一个 CI 徽章（github actions ci.yml）以及一个“Testing”目录锚点，但提供的材料中未包含实际工作流内容或测试用例，也没有任何 MCP 初始化/工具列表握手的可复现日志或输出。manifest 声明通过 npm 包以 stdio 传输运行，21 个工具的行为描述详尽，但“生产级”“battle-tested on ~40M LOC”等说法均为未经证实的营销性陈述，缺乏可验证的执行证据。根据静态校准规则，在没有已提交测试证明关键路径的情况下评分不得超过 12 分；因此给出 9 分，体现路径合理但完全未经验证的状态。
安全与权限 14/20: manifest 正确地将 OPENAI_API_KEY、GOOGLE_API_KEY、QDRANT_API_KEY 标记为 isSecret，且默认模式（Ollama + 托管 Qdrant）无需任何密钥，云端 embedding 提供商需要显式设置环境变量才会启用，体现了较好的最小权限设计。未发现明显的红线风险（无凭据窃取、无隐蔽外泄迹象）。但该服务器在首次使用时会自动拉取 Docker 镜像并启动容器、下载模型，属于有一定副作用的自动化操作，README 中未描述任何用户确认步骤；“本地私有、数据不出机器”等隐私声明仅见于文档，源码层面无法在本次静态审阅中验证。缺乏可验证证据导致扣分，故未给满分。
维护活跃度 13/20: 仓库有 3203 星、0 个未解决 issue、未归档，使用 AGPL-3.0 许可证，npm 包版本为 1.0.1 并附带 CI 徽章，同时维护 Discord 社区频道用于用户交流，显示出一定的活跃度和治理迹象。但 0 个未解决 issue 对于 3000+ 星的项目而言略显异常（可能是 issue 被关闭/限制或项目较新），且未提供提交历史、发布频率或版本演进的直接证据，无法充分判断长期维护节奏，因此不给更高分。
文档质量 18/20: README 内容异常详尽：为十余种 MCP 主机/编辑器提供了具体安装示例，逐一列出全部 21 个工具及用途，针对多种 embedding 提供商（Ollama/OpenAI/Google/LM Studio/LiteLLM）分别说明必需与可选环境变量及默认值，还包含“Accepted limits”一节坦诚披露静态调用图分析对动态分发、反射、框架魔法（DI、装饰器路由等）的盲区，以及跨项目搜索评分机制中三种边界情况的详细说明。这种主动披露局限性的做法达到了高质量文档的标准，因此给出接近满分的分数，仅因缺少独立可核实的第三方评测或troubleshooting实录而未给满分。
安装易用性 13/20: 提供了 npx 一键配置、Claude Code 插件市场安装、VS Code/Open VSX 扩展、Cursor 深链接、Codex/Gemini CLI 等多种主流客户端的具体配置示例，步骤描述清晰。但前提条件较重：需要预先安装并运行 Docker，首次启动需自动拉取镜像、下载 embedding 模型（README 称约 5 分钟），且默认依赖后台索引与文件监听等复杂运行时行为。依据静态校准规则，在没有实际执行验证的情况下安装易用性不得超过 15 分，加之 Docker 依赖增加了脆弱性，故评为 13 分。

静态评测 · 未实际运行收录于 2026-08-06

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件访问网络

适合谁

需要长期维护、代码量很大(数百万行以上)的企业级或多语言代码库
希望嵌入与索引数据完全留在本机、不外传的隐私敏感团队
已在使用 Claude Code、Cursor、VS Code Copilot 或 Gemini CLI,想让 AI 助手更少读文件、更多用语义搜索和依赖图的开发者
多个 AI 代理或多人协作、共享同一份代码索引的团队

不适合谁

无法在本机或 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 客户端一旦连接,即拥有对索引、图谱和上下文产物的全部读写与删除权限,缺少细粒度的工具级权限控制
依赖静态分析的调用图无法捕获动态派发、反射、框架魔法(如依赖注入、装饰器路由)等,存在“零调用者”误判风险,不能完全替代人工审查

安装接入

准备工作

运行环境：Node.js 18+ · Docker

OPENAI_API_KEY 可选密钥仅当 EMBEDDING_PROVIDER=openai 时需要，在 platform.openai.com 获取。

GOOGLE_API_KEY 可选密钥仅当 EMBEDDING_PROVIDER=google 时需要，在 aistudio.google.com/apikey 获取。

QDRANT_API_KEY 可选密钥 external 模式下远程 Qdrant 的 API 密钥。

LMSTUDIO_API_KEY 可选密钥 LM Studio 启用鉴权时使用的 API 密钥。

LITELLM_API_KEY 可选密钥 LiteLLM 代理的 master/虚拟密钥，LiteLLM 模式下必填。

其他可选配置项（19 个）

EMBEDDING_PROVIDER 可选嵌入提供方：ollama（默认）、openai、google、lmstudio 或 litellm；可选。

OLLAMA_URL 可选外部 Ollama 服务地址（默认自动检测，如 http://localhost:11434）。

OLLAMA_MODE 可选设为 external 可使用本机原生或远程 Ollama，默认 auto。

EMBEDDING_MODEL 可选嵌入模型名，各提供方有默认值；LM Studio/LiteLLM 模式下必填。

EMBEDDING_DIMENSIONS 可选嵌入向量维度；LM Studio/LiteLLM 模式下必填。

QDRANT_MODE 可选 managed（默认 Docker 托管）或 external（用户自建实例）。

QDRANT_URL 可选 external 模式下远程/云端 Qdrant 的完整地址。

LMSTUDIO_URL 可选 LM Studio 本地服务器地址，默认 http://localhost:1234/v1。

LITELLM_URL 可选 LiteLLM 代理地址，默认 http://localhost:4000/v1。

LITELLM_SEND_DIMENSIONS 可选是否向代理转发 dimensions 参数，仅对 Matryoshka 感知的后端安全。

SOCRATICODE_LOG_LEVEL 可选结构化日志的日志级别。

SOCRATICODE_PROJECT_ID 可选跨目录/git worktree 共享同一索引的项目 ID。

SOCRATICODE_LINKED_PROJECTS 可选逗号分隔的关联项目路径，用于跨项目搜索。

SOCRATICODE_BRANCH_AWARE 可选设为 true 时按 git 分支维护独立索引。

RESPECT_GITIGNORE 可选设为 false 可禁用 .gitignore 处理。

INCLUDE_DOT_FILES 可选设为 true 可包含点目录（如 .agent）。

EXTRA_EXTENSIONS 可选包含非标准文件扩展名（如 .tpl），按纯文本索引。

EXTENSION_LANGUAGE_MAP 可选把自定义扩展名映射为真实语言（如 .inc:php）以启用 AST 处理。

SEARCH_MIN_SCORE 可选搜索结果最低分数阈值（默认 0.10），跨项目搜索时可能需调低。

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 查看索引进度。

.mcp.json

{"mcpServers":{"socraticode":{"command":"npx","args":["-y","socraticode"]}}}

以 Claude Code 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "socraticode": {
      "command": "npx",
      "args": [
        "-y",
        "socraticode"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add socraticode -- npx -y socraticode

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

启动后查看 MCP 客户端的工具列表，应出现 codebase_index、codebase_search 等工具；首次运行时对项目说“索引这个代码库”，然后用 codebase_status 确认索引完成，即证明连接成功。

常见排障

确保 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 等环境变量是否正确指向可达实例

试试这样问

连接成功后，可以直接对 AI 助手这样说：

索引这个代码库
搜索这个项目中身份验证是如何处理的
有哪些文件依赖 src/middleware/auth.ts？如果我重命名 validateUser 会影响什么？
检测一下项目里有没有循环依赖并展示依赖图

工具能力 21

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 轮询进度。

展开其余 13 个工具

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 规范等)。

使用场景

在超大型(数千万行级)多语言企业代码库中做语义+关键词混合搜索,快速定位相关代码

重构、重命名或删除代码前,用符号级影响分析(codebase_impact)评估波及范围

通过 codebase_flow 从入口点追踪调用链,理解一段陌生代码到底做了什么

查看和可视化模块间依赖关系图,检测循环依赖等架构问题

跨多个关联仓库或按 Git 分支分别维护和检索索引

检索数据库结构、API 规范、基础设施配置等代码之外的项目知识

支持客户端

Claude Code

VS Code

Cursor

Gemini CLI

Claude Desktop部分支持

Windsurf部分支持

Cline部分支持

Roo Code部分支持

Zed部分支持

OpenAI Codex CLI部分支持

OpenCode部分支持

依据项目文档列出，未经本站实测。

详细介绍

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)。