# SymDex

Universal code-indexer MCP server for AI coding agents — Claude, Codex, Gemini, Cursor, and any agent that speaks MCP.

**The problem:** Reading a full file to find one function costs ~7,500 tokens. SymDex pre-indexes your codebase once, then returns precise byte-offset locations. The same lookup costs ~200 tokens — a **97% reduction**.

## Installation

```bash
pip install symdex
```

## Quickstart

### 1. Index a project

```bash
symdex index ./myproject --name myproject
```

### 2. Search for a symbol

```bash
symdex search "validate email"
```

### 3. Start the MCP server

```bash
symdex serve          # stdio mode (for local agents)
symdex serve --port 8080  # HTTP mode
```

## MCP Tool Reference

| Tool | Description |
|------|-------------|
| `index_folder` | Index a local folder (run once per session) |
| `search_symbols` | Find function/class by name (~200 tokens) |
| `get_symbol` | Get one function's full source by byte offset |
| `get_file_outline` | All symbols in a file, no full content |
| `get_repo_outline` | Directory structure + symbol stats |
| `search_text` | Text search, returns matching lines only |
| `get_file_tree` | Directory tree without content |
| `list_repos` | List all indexed repos |
| `get_symbols` | Bulk symbol retrieval |
| `index_repo` | Index a named repo |
| `invalidate_cache` | Force re-index on next request |
| `semantic_search` | Find symbols by meaning (embedding similarity) |
| `get_callers` | Who calls this function |
| `get_callees` | What this function calls |

## CLI Commands

```bash
symdex index ./myproject              # Index a folder
symdex search "validate email"        # Search symbols
symdex find MyClass                   # Exact name lookup
symdex outline myproject/module.py --repo myproject   # File outline
symdex text "TODO" --repo myproject   # Text search
symdex semantic "parse authentication token" --repo myproject  # Semantic search
symdex callers my_function --repo myproject   # Call graph: who calls this
symdex callees my_function --repo myproject   # Call graph: what this calls
symdex repos                          # List indexed repos
symdex serve                          # Start MCP server
```

## Supported Languages

Python, JavaScript, TypeScript, Go, Rust, Java, PHP, C#, C, C++, Elixir, Ruby (13 languages via tree-sitter)

## Agent Configuration

Add to your agent's MCP config:

```json
{
  "mcpServers": {
    "symdex": {
      "command": "symdex",
      "args": ["serve"]
    }
  }
}
```

## License

MIT — see [LICENSE](LICENSE)
