# Code-Memory MCP (Rust Version)

> **Semantic code search for your local repositories, powered by SQLite Vector Search, AST-based chunking, and Parallel AI Cascading.**
>
> Find functions, classes, and logic across your codebase using natural language — 100% local, accurate, and resilient.

---

## ✨ Key Features

- 🔍 **Hybrid Search (Vector + FTS5)** — Fast local semantic retrieval using **sqlite-vec** combined with Full-Text Search (FTS5) and **Reciprocal Rank Fusion (RRF)** for maximum accuracy.
- 📦 **AST-based Smart Chunking** — Language-aware splitting (Python, JS, TS, Rust, Go, Java, Markdown) that preserves functional context using Tree-sitter.
- ⚡ **Parallel AI Collaboration (Async Planning)** — Support for non-blocking, asynchronous planning tasks that allow Worker and Mahaguru (planner) models to work in parallel.
- 🔄 **Background Indexing** — High-performance, non-blocking indexing of large folders with job monitoring and status tracking.
- 🧠 **Session-based Chat Context** — Automatically preserves and restores chat summaries per project to maintain context across sessions.
- 📏 **Agent Rules Sync** — Synchronizes specialized Antigravity/Cursor rules based on the detected project stack.
- 🛡️ **Path Sandboxing** — Secure file access with environment-based path validation.
- 🔌 **MCP Protocol** — Native integration as an MCP server for Claude Desktop, Cursor, Antigravity, and more.

---

## 🔌 MCP Tools Overview

The server exposes 13 powerful tools for AI agents to interact with your codebase:

| Tool | Description |
| --- | --- |
| `semantic_code_search` | Hybrid search (Vector + FTS5 + RRF) with heuristic re-ranking. |
| `index_folder` | Initiates background indexing for a local project folder. |
| `get_index_stats` | Monitors active indexing and planning (Mahaguru) jobs. |
| `list_indexed_projects` | Lists all projects currently available in the index. |
| `delete_project` | Removes a project and its chat context from the index. |
| `request_mahaguru_refinement` | Synchronous escalation to a high-level planner (Mahaguru) model. |
| `request_async_mahaguru_refinement` | Non-blocking escalation; returns a Job ID for parallel workflows. |
| `get_planning_job_result` | Polls the result of an asynchronous planning/refinement job. |
| `save_project_chat_context` | Persists a summary of the current session context. |
| `get_project_chat_context` | Retrieves the last saved session context for a project. |
| `sync_agent_rules` | Updates `.agents/rules` based on the project's detected stack. |
| `maintenance_prune` | Removes stale entries for files that no longer exist on disk. |
| `rebuild_index_database` | Factory Reset: Clears the entire database (use with caution). |

---

## 🚀 Quick Start

### 1. Requirements

- **Rust 1.80+** (Stable toolchain via `rustup`).
- **sqlite-vec** (Binary `vec0.dylib` for macOS or equivalent for your OS must be in the binary directory).

### 2. Build

```bash
git clone <your-repo-url> mcp-code-search
cd mcp-code-search
cargo build --release
```

### 3. Run

**Mode A: MCP Server (Stdin/Stdout)**
Best for Claude Desktop, Cursor, and other IDE integrations.
```bash
cargo run --release -- --mcp
```

**Mode B: HTTP Management API**
Runs a REST API (default on port 8000) for managing the server.
```bash
cargo run --release -- --port 8000
```

**Mode C: CLI Indexer**
One-off indexing without running a server.
```bash
cargo run --release -- --index /path/to/project
```

---

## 🔌 IDE & Client Integration

### Claude Desktop / Cursor / Antigravity

Add the following configuration to your MCP settings. Using the provided `run_mcp.sh` is highly recommended as it ensures the binary is built and run from the correct root with all environment variables.

#### macOS / Linux
```json
{
  "mcpServers": {
    "code-memory-rs": {
      "command": "/absolute/path/to/mcp-code-search-rs/run_mcp.sh"
    }
  }
}
```

> [!TIP]
> **Petunjuk Integrasi (Bahasa Indonesia):**
> Gunakan file `run_mcp.sh` untuk memastikan server berjalan stabil di Claude/Cursor. Skrip ini akan otomatis menjalankan `cargo build` jika ada perubahan kode, memastikan binary terbaru selalu digunakan. Pastikan path yang Anda masukkan adalah **path absolut**.

---

## 🏗️ Architecture

- **Engine**: Pure Rust with `tokio` for async orchestration.
- **Storage**: SQLite (WAL mode) for reliable persistence.
- **Search**: `sqlite-vec` for vector embeddings + FTS5 for keyword matching, merged via Reciprocal Rank Fusion (RRF).
- **Chunking**: AST-aware logic using `tree-sitter` to preserve logical boundaries (functions, classes).
- **Hardening**: State-machine based `balanced-brace` JSON extraction for reliable processing of unpredictable AI outputs.
- **Safety**: Environment-variable driven path sandboxing (`ALLOWED_PATHS`).
- **Observability**: Integrated `tracing` spans and instrumented futures for deep visibility into async/sync execution boundaries.
- **Resilience**: Robust API retry logic with exponential backoff and circuit breaking for all LLM interactions.

---

## 📁 Project Structure

```
mcp-code-search/
├── src/                 # Rust source (Core, API, Indexer)
├── data/                # Database and persistent state
├── docs/                # Extended documentation suite
├── bin/                 # Helper scripts and utilities
└── Cargo.toml           # Package metadata
```

---

## 📄 License

MIT