MCP Server for persistent code indexing. Gives AI assistants (Claude, Gemini, Copilot, Cursor) instant access to your codebase. 50x less context than grep.
npm install aidex-mcp
Before: grep flooding your context
AI: grep "PlayerHealth" → 200 hits in 40 files
AI: read File1.cs, File2.cs, File3.cs...
→ 2000+ tokens consumed, 5+ tool calls
After: precise results, minimal context
AI: aidex_query({ term: "PlayerHealth" })
→ Engine.cs:45, Player.cs:23, UI.cs:156
→ ~50 tokens, 1 tool call
`
Result: 50-80% less context used for code navigation.
Why Not Just Grep?
| | Grep/Ripgrep | AiDex |
|---|---|---|
| Context usage | 2000+ tokens per search | ~50 tokens |
| Results | All text matches | Only identifiers |
| Precision | log matches catalog, logarithm | log finds only log |
| Persistence | Starts fresh every time | Index survives sessions |
| Structure | Flat text search | Knows methods, classes, types |
The real cost of grep: Every grep result includes surrounding context. Search for User in a large project and you'll get hundreds of hits - comments, strings, partial matches. Your AI reads through all of them, burning context tokens on noise.
AiDex indexes identifiers: It uses Tree-sitter to actually parse your code. When you search for User, you get the class definition, the method parameters, the variable declarations - not every comment that mentions "user".
How It Works
1. Index your project once (~1 second per 1000 files)
`
aidex_init({ path: "/path/to/project" })
`
2. AI searches the index instead of grepping
`
aidex_query({ term: "Calculate", mode: "starts_with" })
→ All functions starting with "Calculate" + exact line numbers
aidex_query({ term: "Player", modified_since: "2h" })
→ Only matches changed in the last 2 hours
`
3. Get file overviews without reading entire files
`
aidex_signature({ file: "src/Engine.cs" })
→ All classes, methods, and their signatures
`
The index lives in .aidex/index.db (SQLite) - fast, portable, no external dependencies.
Features
- Screenshots: Cross-platform screenshot capture (fullscreen, window, region) with auto-path for instant AI viewing
- Smart Extraction: Uses Tree-sitter to parse code properly - indexes identifiers, not keywords
- Method Signatures: Get function prototypes without reading implementations
- Project Summary: Auto-detected entry points, main classes, language breakdown
- Incremental Updates: Re-index single files after changes
- Cross-Project Links: Query across multiple related projects
- Time-based Filtering: Find what changed in the last hour, day, or week
- Project Structure: Query all files (code, config, docs, assets) without filesystem access
- Session Notes: Leave reminders for the next session - persists in the database
- Task Backlog: Built-in task management that lives with your code index - no external tools needed
- Auto-Cleanup: Excluded files (e.g., build outputs) are automatically removed from index
Supported Languages
| Language | Extensions |
|----------|------------|
| C# | .cs |
| TypeScript | .ts, .tsx |
| JavaScript | .js, .jsx, .mjs, .cjs |
| Rust | .rs |
| Python | .py, .pyw |
| C | .c, .h |
| C++ | .cpp, .cc, .cxx, .hpp, .hxx |
| Java | .java |
| Go | .go |
| PHP | .php |
| Ruby | .rb, .rake |
Quick Start
$3
`bash
npm install -g aidex-mcp
aidex setup
`
aidex setup automatically detects and registers AiDex with your installed AI clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot). To unregister: aidex unsetup.
$3
For Claude Code (~/.claude/settings.json or ~/.claude.json):
`json
{
"mcpServers": {
"aidex": {
"type": "stdio",
"command": "aidex",
"env": {}
}
}
}
`
For Claude Desktop (%APPDATA%/Claude/claude_desktop_config.json on Windows):
`json
{
"mcpServers": {
"aidex": {
"command": "aidex"
}
}
}
`
> Note: Both aidex and aidex-mcp work as command names.
> Important: The server name in your config determines the MCP tool prefix. Use "aidex" as shown above — this gives you tool names like aidex_query, aidex_signature, etc. Using a different name (e.g., "codegraph") would change the prefix accordingly.
For Gemini CLI (~/.gemini/settings.json):
`json
{
"mcpServers": {
"aidex": {
"command": "aidex"
}
}
}
`
For VS Code Copilot (run MCP: Open User Configuration in Command Palette):
`json
{
"servers": {
"aidex": {
"type": "stdio",
"command": "aidex"
}
}
}
`
For other MCP clients: See your client's documentation for MCP server configuration.
$3
Add to your AI's instructions (e.g., ~/.claude/CLAUDE.md for Claude Code):
`markdown
AiDex - Use for ALL code searches!
Before using Grep/Glob, check if .aidex/ exists in the project.
If yes, use AiDex instead:
- aidex_query - Find functions, classes, variables by name
- aidex_signature - Get all methods in a file with line numbers
- aidex_signatures - Get methods from multiple files (glob pattern)
- aidex_summary - Project overview with entry points
If no .aidex/ exists, offer to run aidex_init first.
`
$3
Ask your AI: "Index this project with AiDex"
Or manually in the AI chat:
`
aidex_init({ path: "/path/to/your/project" })
`
Available Tools
| Tool | Description |
|------|-------------|
| aidex_init | Index a project (creates .aidex/) |
| aidex_query | Search by term (exact/contains/starts_with) |
| aidex_signature | Get one file's classes + methods |
| aidex_signatures | Get signatures for multiple files (glob) |
| aidex_update | Re-index a single changed file |
| aidex_remove | Remove a deleted file from index |
| aidex_summary | Project overview |
| aidex_tree | File tree with statistics |
| aidex_describe | Add documentation to summary |
| aidex_link | Link another indexed project |
| aidex_unlink | Remove linked project |
| aidex_links | List linked projects |
| aidex_status | Index statistics |
| aidex_scan | Find indexed projects in directory tree |
| aidex_files | List project files by type (code/config/doc/asset) |
| aidex_note | Read/write session notes (persists between sessions) |
| aidex_session | Start session, detect external changes, auto-reindex |
| aidex_viewer | Open interactive project tree in browser |
| aidex_task | Create, read, update, delete tasks with priority and tags |
| aidex_tasks | List and filter tasks by status, priority, or tag |
| aidex_screenshot | Take a screenshot (fullscreen, window, region) |
| aidex_windows | List open windows for screenshot targeting |
Time-based Filtering
Track what changed recently with modified_since and modified_before:
`
aidex_query({ term: "render", modified_since: "2h" }) # Last 2 hours
aidex_query({ term: "User", modified_since: "1d" }) # Last day
aidex_query({ term: "API", modified_since: "1w" }) # Last week
`
Supported formats:
- Relative: 30m (minutes), 2h (hours), 1d (days), 1w (weeks)
- ISO date: 2026-01-27 or 2026-01-27T14:30:00
Perfect for questions like "What did I change in the last hour?"
Project Structure
AiDex indexes ALL files in your project (not just code), letting you query the structure:
`
aidex_files({ path: ".", type: "config" }) # All config files
aidex_files({ path: ".", type: "test" }) # All test files
aidex_files({ path: ".", pattern: "*/.md" }) # All markdown files
aidex_files({ path: ".", modified_since: "30m" }) # Changed this session
`
File types: code, config, doc, asset, test, other, dir
Use modified_since to find files changed in this session - perfect for "What did I edit?"
Session Notes
Leave reminders for the next session - no more losing context between chats:
`
aidex_note({ path: ".", note: "Test the glob fix after restart" }) # Write
aidex_note({ path: ".", note: "Also check edge cases", append: true }) # Append
aidex_note({ path: "." }) # Read
aidex_note({ path: ".", clear: true }) # Clear
`
Use cases:
- Before ending a session: "Remember to test X next time"
- AI auto-reminder: Save what to verify after a restart
- Handover notes: Context for the next session without editing config files
Notes are stored in the SQLite database (.aidex/index.db) and persist indefinitely.
Task Backlog
Keep your project tasks right next to your code index - no Jira, no Trello, no context switching:
`
aidex_task({ path: ".", action: "create", title: "Fix parser bug", priority: 1, tags: "bug" })
aidex_task({ path: ".", action: "update", id: 1, status: "done" })
aidex_task({ path: ".", action: "log", id: 1, note: "Root cause: unbounded buffer" })
aidex_tasks({ path: ".", status: "active" })
`
Features:
- Priorities: 🔴 high, 🟡 medium, ⚪ low
- Statuses: backlog → active → done | cancelled
- Tags: Categorize tasks (bug, feature, docs, etc.)
- History log: Every status change is auto-logged, plus manual notes
- Viewer integration: Tasks tab in the browser viewer with live updates
- Persistent: Tasks survive between sessions, stored in .aidex/index.db
Your AI assistant can create tasks while working ("found a bug in the parser, add it to the backlog"), track progress, and pick up where you left off next session.
Screenshots
Take cross-platform screenshots directly from your AI assistant - no manual file paths needed:
`
aidex_screenshot() # Full screen
aidex_screenshot({ mode: "active_window" }) # Active window
aidex_screenshot({ mode: "window", window_title: "VS Code" }) # Specific window
aidex_screenshot({ mode: "region" }) # Interactive selection
aidex_windows({ filter: "chrome" }) # Find window titles
`
Features:
- 4 capture modes: Fullscreen, active window, specific window (by title), interactive region selection
- Cross-platform: Windows (PowerShell), macOS (screencapture), Linux (maim/scrot)
- Multi-monitor: Select which monitor to capture
- Delay: Wait N seconds before capturing (e.g., to open a menu first)
- Auto-path: Default saves to temp directory with fixed filename - your AI reads it immediately
- No index required: Works standalone, no .aidex/ needed
Use aidex_windows to find the exact window title, then aidex_screenshot with mode: "window" to capture it.
Future: Screenshots will be storable in the AiDex database - attach them to tasks for bug documentation, capture before/after states for refactoring, or persist GUI evidence across sessions.
Interactive Viewer
Explore your indexed project visually in the browser:
`
aidex_viewer({ path: "." })
`
Opens http://localhost:3333 with:
- Interactive file tree - Click to expand directories
- File signatures - Click any file to see its types and methods
- Live reload - Changes detected automatically while you code
- Git status icons - See which files are modified, staged, or untracked
!AiDex Viewer - Signatures
!AiDex Viewer - Code
Close with aidex_viewer({ path: ".", action: "close" })
CLI Usage
`bash
aidex scan Q:/develop # Find all indexed projects
aidex init ./myproject # Index a project from command line
`
> aidex-mcp works as an alias for aidex.
Performance
| Project | Files | Items | Index Time | Query Time |
|---------|-------|-------|------------|------------|
| Small (AiDex) | 19 | 1,200 | <1s | 1-5ms |
| Medium (RemoteDebug) | 10 | 1,900 | <1s | 1-5ms |
| Large (LibPyramid3D) | 18 | 3,000 | <1s | 1-5ms |
| XL (MeloTTS) | 56 | 4,100 | ~2s | 1-10ms |
Technology
- Parser: Tree-sitter - Real parsing, not regex
- Database: SQLite with WAL mode - Fast, single file, zero config
- Protocol: MCP - Works with any compatible AI
Project Structure
`
.aidex/ ← Created in YOUR project
├── index.db ← SQLite database
└── summary.md ← Optional documentation
AiDex/ ← This repository
├── src/
│ ├── commands/ ← Tool implementations
│ ├── db/ ← SQLite wrapper
│ ├── parser/ ← Tree-sitter integration
│ └── server/ ← MCP protocol handler
└── build/ ← Compiled output
``