SocratiCode -- Codebase Intelligence Engine

Hybrid search, polyglot dependency graphs, context artifacts, and AI code exploration for AI assistants via the Model Context Protocol.

Quick Start

# 1. Install dependencies
npm install

# 2. Set up Convex backend
npx convex dev

# 3. Build the MCP server
npm run build

# 4. Configure your MCP host (Claude Code example)
# Add to ~/.claude.json:

{
  "mcpServers": {
    "socraticode": {
      "command": "node",
      "args": ["dist/src/index.js"],
      "cwd": "/path/to/socraticode",
      "env": {
        "CONVEX_URL": "https://your-deployment.convex.cloud",
        "CONVEX_DEPLOY_KEY": "prod:your-deploy-key",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

See docs/setup.md for full setup instructions including Google OAuth configuration.

Configuration

| Variable | Required | Description | |---|---|---| | CONVEX_URL | Yes | Convex deployment URL | | CONVEX_DEPLOY_KEY | Yes | Deploy key for server-side auth | | OPENAI_API_KEY | Yes | OpenAI key for embeddings (text-embedding-3-small) and AI agent (GPT-4o) | | AUTH_GOOGLE_ID | Yes | Google OAuth Client ID | | AUTH_GOOGLE_SECRET | Yes | Google OAuth Client Secret | | SITE_URL | Yes | Convex HTTP actions URL (e.g., https://your-deployment.convex.site) |

See docs/setup.md for the complete environment variable reference.

MCP Host Configuration

SocratiCode works with any MCP-compatible AI assistant:

• Claude Code -- ~/.claude.json or .mcp.json
• Cursor -- Settings > MCP Servers
• Windsurf -- ~/.windsurf/mcp.json
• Generic MCP host -- stdio transport

See docs/mcp-hosts.md for complete configuration examples.

MCP Tools

SocratiCode exposes 22 MCP tools across four categories. See docs/tool-reference.md for full parameter details and examples.

Indexing & Lifecycle

| Tool | Description | |---|---| | codebase_index | Index a codebase into searchable chunks with embeddings | | codebase_update | Incrementally update changed files | | codebase_stop | Stop an in-progress indexing operation | | codebase_remove | Remove a project and all its data | | codebase_status | Real-time indexing progress | | codebase_watch | Watch filesystem for changes and auto-update | | codebase_health | Backend health check | | codebase_list_projects | List all indexed projects | | codebase_about | Server version and capabilities |

Search

| Tool | Description | |---|---| | codebase_search | Hybrid search (dense vector + BM25 full-text, RRF-fused) | | codebase_explore | AI-powered code exploration agent (GPT-4o) |

Dependency Graph

| Tool | Description | |---|---| | codebase_graph_build | Build dependency graph via AST import extraction | | codebase_graph_query | Query imports and dependents for a file | | codebase_graph_circular | Detect circular dependencies | | codebase_graph_stats | Graph statistics and metrics | | codebase_graph_visualize | Generate Mermaid dependency diagrams | | codebase_graph_status | Graph metadata (edge count, languages) | | codebase_graph_remove | Remove graph data for a project |

Context Artifacts

| Tool | Description | |---|---| | codebase_context | List context artifacts for a project | | codebase_context_search | Full-text search over context artifacts | | codebase_context_index | Index a context artifact (schema, spec, doc) | | codebase_context_remove | Remove a context artifact |

Architecture

SocratiCode runs as a local MCP server (stdio transport) that communicates with a Convex cloud backend via HTTP.

• Local: MCP protocol handling, AST parsing (ast-grep), file watching, graph analysis (cycle detection, stats, Mermaid visualization)
• Cloud (Convex): Document storage, vector search (1536d cosine), full-text search (BM25/Tantivy), real-time subscriptions, AI agent (@convex-dev/agent)

Authentication is handled by Google OAuth via @convex-dev/auth.

Privacy

SocratiCode stores only code chunks (5-50 lines each), never full files. Source files are read locally for AST parsing and chunking, then only the resulting chunks and their embeddings are sent to Convex.

Documentation

| Document | Description | |---|---| | docs/setup.md | Full setup guide (OAuth, env vars, Convex deployment) | | docs/mcp-hosts.md | MCP host configuration (Claude Code, Cursor, Windsurf) | | docs/tool-reference.md | Complete reference for all 22 tools |

Development

# Run tests
npm test

# Start Convex dev server
npx convex dev

# Build
npm run build

License

MIT