npm package: @socraticode-cloud/socraticode
Description: Codebase intelligence engine — hybrid search, polyglot dependency graphs, context artifacts via MCP
Author: Mediatique Press
Latest version: 1.0.1

# SocratiCode -- Codebase Intelligence Engine

Hybrid search, polyglot dependency graphs, context artifacts, and AI code exploration for AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io/).

## Quick Start

```bash
# 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:
```

```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](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](docs/setup.md) for the complete environment variable reference.

## MCP Host Configuration

SocratiCode works with any MCP-compatible AI assistant:

- **[Claude Code](docs/mcp-hosts.md#claude-code)** -- `~/.claude.json` or `.mcp.json`
- **[Cursor](docs/mcp-hosts.md#cursor)** -- Settings > MCP Servers
- **[Windsurf](docs/mcp-hosts.md#windsurf)** -- `~/.windsurf/mcp.json`
- **[Generic MCP host](docs/mcp-hosts.md#generic-mcp-host)** -- stdio transport

See [docs/mcp-hosts.md](docs/mcp-hosts.md) for complete configuration examples.

## MCP Tools

SocratiCode exposes 22 MCP tools across four categories. See [docs/tool-reference.md](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](docs/setup.md) | Full setup guide (OAuth, env vars, Convex deployment) |
| [docs/mcp-hosts.md](docs/mcp-hosts.md) | MCP host configuration (Claude Code, Cursor, Windsurf) |
| [docs/tool-reference.md](docs/tool-reference.md) | Complete reference for all 22 tools |

## Development

```bash
# Run tests
npm test

# Start Convex dev server
npx convex dev

# Build
npm run build
```

## License

MIT