SocratiCode

环境要求

• Node.js 18.17 或更新版本，且 npx 在 PATH 中可用
• Docker 正在运行（默认本地 Qdrant 与 Ollama 栈依赖它）
• 一个支持 MCP 的宿主：Claude Code、OpenAI Codex、VS Code 或 Cursor 等
• 可选：本机原生安装 Ollama，用于外部嵌入服务模式

安装与启动步骤

1. 1检查运行环境

   先确认 Node.js 版本不低于 18.17、npx 可用，并让 Docker Desktop 处于运行状态，默认本地栈才能启动。

   node -v
   npx --version
   docker info

   复制

2. 2添加 MCP 配置

   在支持 mcpServers JSON 对象的宿主配置文件中加入该对象，npx 会拉取最新引擎。

   {
     "mcpServers": {
       "socraticode": {
         "command": "npx",
         "args": ["-y", "--prefer-online", "socraticode@latest"]
       }
     }
   }

   复制

3. 3Claude Code 安装

   用户级安装且不带内置技能；装完新建会话，或运行 /mcp 选择 Reconnect。

   claude mcp add --scope user socraticode -- npx -y --prefer-online socraticode@latest
   claude mcp list

   复制

4. 4Codex 安装

   该命令把用户配置写入 ~/.codex/config.toml，安装后需新建任务或 CLI 会话。

   codex mcp add socraticode -- npx -y --prefer-online socraticode@latest
   codex mcp list

   复制

5. 5VS Code 配置

   在项目级 .vscode/mcp.json 写入 servers 对象，并在 VS Code 中选择用户或工作区范围。

   {
     "servers": {
       "socraticode": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "--prefer-online", "socraticode@latest"]
       }
     }
   }

   复制

6. 6接入外部 Ollama

   本机已原生安装 Ollama 时，设置 OLLAMA_MODE 为 external 并指向实例地址，嵌入模型首次使用会自动拉取。

   ollama pull nomic-embed-text

   复制

7. 7配置关联项目

   在项目根创建 .socraticode.json，或用环境变量指定关联项目；两个来源会合并并去重。

   {
     "linkedProjects": [
       "../shared-lib",
       "/absolute/path/to/other-project"
     ]
   }

   复制

8. 8声明上下文产物

   在项目根创建 .socraticodecontextartifacts.json，把数据库、API、基础设施等资料登记进来。

   {
     "artifacts": [
       {
         "name": "database-schema",
         "path": "./docs/schema.sql",
         "description": "Complete PostgreSQL schema — all tables, indexes, constraints, foreign keys."
       },
       {
         "name": "api-spec",
         "path": "./docs/openapi.yaml",
         "description": "OpenAPI 3.0 spec for the REST API."
       }
     ]
   }

   复制

关键配置

如何确认成功

运行 claude mcp list 或 VS Code 的 MCP: List Servers 能列出 socraticode，新建会话即可调用。

常见问题

注意事项

• 本项目是 MCP 服务，本身不带界面，必须通过 Claude Code、Codex、VS Code、Cursor 等宿主调用。
• 使用 @latest 时，每次服务器启动都会检查并拉取最新发布版本。
• 关联项目路径中的相对路径以项目根为基准解析，不存在的路径会被静默跳过。
• 不同嵌入模型可能产生相同维度向量，回退逻辑无法识别，因此关联项目应统一使用同一个嵌入模型。