# socraticode

Indexes codebases locally, builds dependency graphs, and runs hybrid semantic search via Qdrant.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 3354
- Author: giancarloerra
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/giancarloerra/SocratiCode
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/socraticode

## What it does

The server parses local repositories to feed deep codebase context directly to AI coding assistants. It combines AST-aware code chunking with hybrid search, fusing BM25 keyword matching and vector embeddings via reciprocal rank fusion. It also computes call flows and symbol-level impact across 18 programming languages.

Local execution relies on Docker to run Qdrant, keeping the index entirely on the local machine without sending code off-device. External embedding providers like OpenAI, Google Gemini, or Ollama can be plugged in when cloud embeddings are needed. Without Docker running locally or explicit remote credentials, the indexing engine cannot start.

A built-in file watcher monitors changes to keep the index fresh across sessions. Checkpoints ensure large indexing jobs resume cleanly after interruptions, while multiple agents can share the same repository index simultaneously.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `EMBEDDING_PROVIDER`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, `OLLAMA_URL`, `EMBEDDING_MODEL`, `EMBEDDING_DIMENSIONS`, `OLLAMA_MODE`, `OLLAMA_API_KEY`, `LMSTUDIO_URL`, `LMSTUDIO_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add socraticode -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OLLAMA_API_KEY=<OLLAMA_API_KEY> -e LMSTUDIO_API_KEY=<LMSTUDIO_API_KEY> -e LITELLM_API_KEY=<LITELLM_API_KEY> -e QDRANT_API_KEY=<QDRANT_API_KEY> -- npx -y socraticode
```
Replace <…> with your own values. 12 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add socraticode --env EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> --env OPENAI_API_KEY=<OPENAI_API_KEY> --env GOOGLE_API_KEY=<GOOGLE_API_KEY> --env OLLAMA_URL=<OLLAMA_URL> --env EMBEDDING_MODEL=<EMBEDDING_MODEL> -- npx -y socraticode
```
Replace <…> with your own values. 12 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "socraticode": {
            "command": "npx",
            "args": [
                "-y",
                "socraticode"
            ],
            "env": {
                "EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
                "OPENAI_API_KEY": "<OPENAI_API_KEY>",
                "GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
                "OLLAMA_URL": "<OLLAMA_URL>",
                "EMBEDDING_MODEL": "<EMBEDDING_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. 12 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "socraticode": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "socraticode"
            ],
            "env": {
                "EMBEDDING_PROVIDER": "<EMBEDDING_PROVIDER>",
                "OPENAI_API_KEY": "<OPENAI_API_KEY>",
                "GOOGLE_API_KEY": "<GOOGLE_API_KEY>",
                "OLLAMA_URL": "<OLLAMA_URL>",
                "EMBEDDING_MODEL": "<EMBEDDING_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. 12 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e EMBEDDING_PROVIDER=<EMBEDDING_PROVIDER> -e OPENAI_API_KEY=<OPENAI_API_KEY> -e GOOGLE_API_KEY=<GOOGLE_API_KEY> -e OLLAMA_URL=<OLLAMA_URL> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> socraticode npx -y socraticode
```
Replace <…> with your own values. 12 more environment variables are in the server README

## When to use it
- locate relevant functions using combined semantic and keyword search
- trace blast radius and symbol dependencies across 18 languages
- visualize module architecture and pinpoint circular dependencies
- index API schemas, database migrations, and infrastructure configurations

## Example prompts
- Find all authentication handlers and map their database dependencies
- Trace the blast radius of modifying calculateBilling across the project
- Check the codebase for circular dependencies between modules

## Similar
- [qdrant-performance-optimization](https://affpapa.org/en/nevibecode/skills/qdrant-qdrant-performance-optimization.md) — skill · 1700 installs
- [ctx-index](https://affpapa.org/en/nevibecode/skills/ctx-index.md) — skill · 1100 installs
- [qdrant-advisor](https://affpapa.org/en/nevibecode/skills/qdrant-advisor.md) — skill · 682 installs
- [qdrant-search-quality](https://affpapa.org/en/nevibecode/skills/qdrant-search-quality.md) — skill · 61 installs
- [ast-grep-outline](https://affpapa.org/en/nevibecode/skills/ast-grep-outline.md) — skill · 2400 installs
- [gitnexus-guide](https://affpapa.org/en/nevibecode/skills/gitnexus-guide.md) — skill · 809 installs

From the same set: [giancarloerra/socraticode](https://affpapa.org/en/nevibecode/by/giancarloerra/socraticode.md) — 2 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md