Metadata-Version: 2.4
Name: leindex
Version: 1.6.1
Summary: LeIndex MCP bootstrap wrapper for the Rust LeIndex binary
Author: LeIndex Contributors
License-Expression: MIT OR Apache-2.0
Project-URL: Homepage, https://github.com/scooter-lacroix/LeIndex
Project-URL: Repository, https://github.com/scooter-lacroix/LeIndex.git
Project-URL: Issues, https://github.com/scooter-lacroix/LeIndex/issues
Project-URL: Documentation, https://docs.rs/leindex
Keywords: search,code,semantic,indexing,mcp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

<div align="center">

<img src="leindex.jpeg" alt="LeIndex" width="500"/>

[![Rust](https://img.shields.io/badge/Rust-1.75%2B-orange?style=flat-square&logo=rust)](https://www.rust-lang.org/)
[![License](https://img.shields.io/badge/License-MIT%20%7C%20Apache--2.0-blue?style=flat-square)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Server-purple?style=flat-square)](https://modelcontextprotocol.io)

</div>

# LeIndex

**Understand large codebases instantly.**

LeIndex is a semantic code search engine that lets you search code by **meaning**, not just keywords.

Instead of hunting through files with grep or hoping variable names match your query, you can ask things like:

- *"Where is authentication enforced?"*
- *"Where are API tokens validated?"*
- *"How does session management work?"*

LeIndex surfaces the actual implementation — even if the words you're searching for never appear in the code.

Built in Rust. Built for developers and AI coding tools.

---

## Demo: finding logic that grep and LLMs miss

Imagine a codebase where authentication is implemented like this:

```rust
fn validate_session(req: Request) -> Result<User> { ... }
fn verify_token(token: &str) -> bool { ... }
fn authorize_user(user: &User, action: Action) -> bool { ... }
```

None of these functions contain the word **"authentication"**.

### grep

```bash
grep -r "authentication" src/
# (no matches)
```

### LeIndex

```bash
leindex search "where is authentication enforced"
```

```
src/security/session_validator.rs    validate_session    (0.92)
src/auth/token_verifier.rs           verify_token        (0.87)
src/middleware/auth_gate.rs           authorize_user      (0.84)
```

LeIndex finds the correct logic because it searches by **semantic intent**, not string matches.

It works across multiple repositories too:

```bash
leindex search "where are API rate limits enforced"
```

```
gateway/middleware/rate_limit.rs      throttle_request     (0.91)
api/server/request_throttle.go        limit_handler        (0.88)
auth/session_policy.rs                enforce_policy       (0.83)
```

---

## 90%+ Token Savings for AI Coding Tools

When an LLM reads your code with standard tools, it burns tokens on entire files just to understand one function. LeIndex returns **only what matters** — structured, context-aware results instead of raw file dumps.

| Task | Standard Tools | LeIndex | Savings |
|------|---------------:|--------:|--------:|
| Understand a 500-line file | ~2,000 tokens | ~380 tokens | **81%** |
| Find all callers of a function | ~5,800 tokens | ~420 tokens | **93%** |
| Navigate project structure | ~8,500 tokens | ~650 tokens | **92%** |
| Cross-file symbol rename | ~12,000 tokens | ~340 tokens | **97%** |

Every tool call is **context-aware** — not atomic. When you look up a symbol, you don't just get its definition. You get its callers, callees, data dependencies, and impact radius. When you summarize a file, you get cross-file relationships that `Read` can never provide at any token cost. One LeIndex call replaces chains of `Grep → Read → Read → Read`.

> See [full benchmarks](docs/TOOL_SUPREMACY_BENCHMARKS.md) for methodology and detailed comparisons.

---

## Quick Start (2 minutes)

### Install

**Via cargo (recommended):**

```bash
cargo install leindex
```

**Via install script:**

```bash
curl -fsSL https://raw.githubusercontent.com/scooter-lacroix/LeIndex/master/install.sh -o install-leindex.sh
bash install-leindex.sh
```

**Via PyPI bootstrap wrapper:**

```bash
pip install leindex
leindex --version
```

The PyPI package installs a small Python launcher. On first run it installs or updates
the real Rust `leindex` binary in `~/.cargo/bin` via `cargo install leindex`. If Cargo
is missing, the launcher explains the requirement and prompts to install Rust/Cargo when
automatic setup is supported on the current platform.

**Via npm MCP wrapper (recommended for AI tools):**

```bash
npm install -g @leindex/mcp
```

**Environment Variables:**

| Name | Required | Description | Default |
|------|----------|-------------|---------|
| `LEINDEX_HOME` | No | Override storage/index home directory | `~/.leindex` |
| `LEINDEX_PORT` | No | Override HTTP server port | `47268` |

### Index and search

```bash
# Index your project
leindex index /path/to/project

# Search by meaning
leindex search "authentication flow"

# Deep structural analysis
leindex analyze "how authorization is enforced"
```

That's it. You're searching by meaning.

---

## What LeIndex Is Useful For

- **Understanding unfamiliar codebases** — ask questions instead of reading every file
- **Onboarding new engineers** — find relevant code without tribal knowledge
- **Exploring legacy systems** — surface logic buried in decades of code
- **AI coding assistants** — give LLMs real structural context via MCP
- **Cross-project search** — query across multiple repositories simultaneously

---

## Built for AI-Assisted Development

Modern AI coding tools struggle with large codebases because they lack global structural context.

LeIndex provides that missing layer.

It builds a semantic index of your repository that both developers and AI assistants can query to understand:

- where logic lives
- how components interact
- what code paths enforce behavior

LeIndex runs as an **MCP server**, allowing tools like **Claude Code**, **Cursor**, and other MCP-compatible agents to explore your codebase with semantic understanding.

```bash
# Start MCP stdio mode (for Claude Code / Cursor)
leindex mcp

# Or run the HTTP MCP server
leindex serve --host 127.0.0.1 --port 47268
```

```text
Claude: "Where is request validation implemented?"

LeIndex MCP → src/http/request_validator.rs
              src/middleware/input_guard.rs
```

---

## How It Works

LeIndex builds a semantic index of your codebase using embeddings and structural analysis (tree-sitter parsing + program dependence graphs).

This allows queries to match:

- **code intent** — what the code does, not what it's named
- **related logic paths** — follow data flow and control flow
- **implementation patterns** — structural similarity across files

Indexes can span multiple repositories, enabling cross-project search.

```
Codebase → Tree-sitter Parser → PDG Builder → Semantic Index → Query Engine → Results
```

---

## Features

- **Semantic search** — find code by meaning, not keywords
- **PDG analysis** — program dependence graph for structural understanding
- **5-phase analysis** — additive multi-pass codebase analysis pipeline
- **Cross-project indexing** — search across multiple repos at once
- **16 MCP tools** — read, analyze, edit preview/apply, rename, impact analysis
- **HTTP + WebSocket server** — available through the unified `leindex` server modules and commands
- **Dashboard** — Bun + React operational UI with project metrics and graph telemetry
- **Low resource mode** — works on constrained hardware
- **Built in Rust** — fast indexing, low memory, safe concurrency

---

## Other Install Options

### crates.io

```bash
cargo install leindex
```

### PyPI

```bash
pip install leindex
```

This package is a bootstrap wrapper for the Rust release. It keeps using the unified
`leindex` command, installs the binary into `~/.cargo/bin`, and then forwards all CLI
arguments to the real Rust executable.

### From source

```bash
git clone https://github.com/scooter-lacroix/LeIndex.git
cd leindex
cargo build --release
```

**Feature flags:** Use `--features` to customize the build:
- `full` (default) — Full library plus the `leindex` CLI binary
- `minimal` — Library-focused parse/search build slice; does not produce the `leindex` binary by itself
- `cli` — Required feature for the `leindex` binary target
- `server` — Enables the HTTP/WebSocket server library modules; combine with `cli` for a runnable binary

### MCP Server Integration

For AI coding tools, the recommended integration path is the npm MCP wrapper so the client
resolves the published MCP entrypoint directly:

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```

If you intentionally installed the full Rust binary via `cargo install leindex`,
`install.sh`, or the PyPI bootstrapper, you can replace `npx -y @leindex/mcp`
with `leindex mcp`.

Every MCP tool is also available from the CLI bridge:

```bash
leindex tools list
leindex tools help leindex_project_map
leindex tools run leindex_project_map --args '{"path":"src","depth":2}'
```

<details>
<summary><b>Zed IDE</b></summary>

Add to `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "leindex": {
      "command": {
        "path": "npx",
        "args": ["-y", "@leindex/mcp"]
      }
    }
  }
}
```
</details>

<details>
<summary><b>Cursor IDE</b></summary>

Add to Cursor settings (`settings.json`):

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"],
      "env": {}
    }
  }
}
```
</details>

<details>
<summary><b>VS Code</b></summary>

Requires the [Model Context Protocol](https://marketplace.visualstudio.com/items?itemName=modelcontextprotocol.vscode-mcp) extension.

Configure in `settings.json`:

```json
{
  "mcp.mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Claude Code</b></summary>

Add to `~/.claude/settings.json` or project-local `.claude/settings.json`:

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"],
      "type": "stdio"
    }
  }
}
```

Optional guidance pack:
- Install the shared skill from `integrations/skills/leindex-toolkit/` into `~/.claude/skills/leindex-toolkit/`
- Merge `integrations/claude-code/settings.example.json` to add the LeIndex reminder hook
</details>

<details>
<summary><b>Amp CLI (Sourcegraph)</b></summary>

Add to `~/.config/amp/settings.json`:

```json
{
  "amp.mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>OpenCode</b></summary>

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "leindex": {
      "command": ["npx", "-y", "@leindex/mcp"],
      "type": "local"
    }
  }
}
```
</details>

<details>
<summary><b>Qwen CLI</b></summary>

Add to `~/.qwen/settings.json`:

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>iFlow CLI</b></summary>

Add to `~/.iflow/settings.json`:

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Droid (Factory)</b></summary>

Add to `~/.factory/mcp.json` (note: requires `type: "stdio"`):

```json
{
  "mcpServers": {
    "leindex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Gemini CLI</b></summary>

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

Agent guidance packs:
- Claude Code: shared skill plus reminder hook
- Codex: install `integrations/skills/leindex-toolkit/` into `~/.codex/skills/leindex-toolkit/`
- Gemini CLI, Amp, OpenCode, Qwen, and iFlow: reuse the shared skill text as project instructions or agent rules
- Full instructions: `docs/AGENT_GUIDANCE.md`

<details>
<summary><b>Claude Desktop</b></summary>

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "leindex": {
      "command": "npx",
      "args": ["-y", "@leindex/mcp"]
    }
  }
}
```
</details>

### Dashboard (optional)

```bash
cd dashboard
bun install
bun run build
leindex dashboard
```

---

## CLI Reference

```bash
leindex index /path/to/project       # Index a project
leindex search "query"                # Semantic search
leindex analyze "query"               # Deep structural analysis
leindex phase --all --path /path      # 5-phase additive analysis
leindex diagnostics                   # System health check
leindex mcp                           # MCP stdio mode
leindex serve                         # HTTP/WebSocket server
leindex dashboard                     # Launch dashboard UI
```

---

## MCP Tools (16)

| Tool | Purpose |
|------|---------|
| `leindex_index` | Index a project |
| `leindex_search` | Semantic code search |
| `leindex_deep_analyze` | Deep analysis with PDG traversal |
| `leindex_context` | Expand context around a symbol |
| `leindex_phase_analysis` | 5-phase additive analysis |
| `leindex_file_summary` | Structural file analysis |
| `leindex_symbol_lookup` | Symbol definition + callers/callees |
| `leindex_project_map` | Annotated project structure |
| `leindex_grep_symbols` | Structural symbol search |
| `leindex_read_symbol` | Read symbol source with deps |
| `leindex_edit_preview` | Preview edits with impact report |
| `leindex_edit_apply` | Apply code edits |
| `leindex_rename_symbol` | Rename across all references |
| `leindex_impact_analysis` | Blast radius analysis |
| `leindex_diagnostics` | Index health and stats |
| `phase_analysis` | Alias for phase analysis |

---

## Unified Module Layout

LeIndex is now a single crate with feature-gated modules:

| Module | Role |
|-------|------|
| `parse` | Language parsing and signature extraction |
| `graph` | Graph construction and traversal |
| `search` | Retrieval, scoring, vector search |
| `storage` | SQLite persistence + storage |
| `phase` | Additive phase analysis pipeline |
| `cli` | CLI + MCP protocol handlers |
| `global` | Cross-project discovery/registry |
| `server` | HTTP/WebSocket API server |
| `edit` | Edit preview/apply support |
| `validation` | Validation and guardrails |

Legacy crate-style aliases remain available from `leindex::leparse`, `leindex::legraphe`, and similar compatibility re-exports.

---

## Security

Database discovery (`LEINDEX_DISCOVERY_ROOTS`) is **opt-in only**. Sensitive directories (`.ssh`, `.aws`, `.gnupg`, etc.) are automatically excluded. All SQL operations use parameterized queries. See [ARCHITECTURE.md](ARCHITECTURE.md) for details.

---

## Docs

- [ARCHITECTURE.md](ARCHITECTURE.md) — system design and internals
- [API.md](API.md) — HTTP API reference
- [docs/MCP.md](docs/MCP.md) — MCP server documentation
- [dashboard/README.md](dashboard/README.md) — dashboard setup

---

## License

MIT
