cursor-rag-tools 1.0.3
RAG indexing and search for Cursor IDE via MCP
License: MIT
Requires Python: >=3.11
Keywords: rag, cursor, mcp, indexing, chromadb, ai

# cursor-rag-tools

**Локальная RAG-индексация кода и семантический поиск для Cursor IDE через MCP**

`cursor-rag-tools` — это утилита и Python-библиотека, которая:
- индексирует ваш репозиторий в **векторную базу** (ChromaDB),
- хранит **эмбеддинги** фрагментов кода/документации,
- поднимает **MCP-сервер**, чтобы Cursor IDE мог делать семантический поиск и получать контекст прямо из вашей локальной БД.

Главная цель — ускорить навигацию по большой кодовой базе и помочь IDE/ассистенту быстро находить **нужные функции/классы/участки логики**, даже если вы не помните точные слова.

## 🚀 Возможности

- **Автоматическая индексация**: Сканирует проект и создает векторные эмбеддинги кода
- **Семантический поиск**: Находит релевантный код по смыслу, а не только по тексту
- **MCP интеграция**: Работает напрямую в Cursor IDE
- **Множественные БД**: Поддержка разных баз данных для разных проектов
- **Гибкая настройка**: Конфигурация через env vars или параметры CLI
- **Простая установка**: Доступен как pip пакет
- **Семантический чанкинг кода**: для Python/JS/TS пытается резать код по структуре (классы/функции/методы), а не по “сырому тексту”

## 🧠 Как это помогает разработчику (практически)

Типовые сценарии:
- **Onboarding**: “где проверяются права доступа?”, “где собирается конфиг?”, “как устроен пайплайн обработки событий?”
- **Рефакторинг**: быстро собрать “все места, где используется X”, даже если названия разные.
- **Поиск “по смыслу”**: запросы вида “rate limit”, “retry logic”, “token refresh”, “как формируется payload”.
- **Быстрые ответы в Cursor**: вместо ручного `ripgrep` и прыжков по файлам — короткие релевантные фрагменты, сразу с указанием файла и диапазона строк.

Что это НЕ делает:
- это не “агент, который пишет код за вас”; библиотека даёт **быстрый поиск контекста** (дальше уже решает LLM/вы).
- это не замена LSP/индекса IDE; это **семантический retrieval** по эмбеддингам.

## 🧩 Как это устроено (вкратце)

1. `cursor-rag index ...` сканирует файлы проекта.
2. Код/тексты режутся на **чанки**:
   - для `.py` — режется по структуре через `ast` (работает без дополнительных зависимостей);
   - для `.js/.ts/.tsx` — если установлены парсеры, режется по структуре (tree-sitter), иначе используется простое разбиение текста;
   - для остальных файлов — использует простое разбиение текста.
3. Для каждого чанка строится эмбеддинг (SentenceTransformers) и сохраняется в ChromaDB.
4. `cursor-rag serve` поднимает MCP-сервер (обычно Cursor запускает его сам по `mcp-config.json`).
5. В Cursor доступны инструменты:
   - `list_rag_projects`
   - `search_codebase` (возвращает файл + строки + найденный фрагмент)

## 📦 Установка

```bash
pip install cursor-rag-tools
```

### Опционально: улучшенный семантический чанкинг для JS/TS

Для `.js/.ts` более качественный структурный чанкинг требует дополнительных парсеров (tree-sitter).
На Python 3.13 пакет `tree_sitter_languages` может быть недоступен (нет wheel’ов), поэтому он сделан опциональным.

Если вы на Python 3.11/3.12, можно поставить extra:

```bash
pip install "cursor-rag-tools[parsers]"
```

## 🧠 Модель эмбеддингов: как выбрать

По умолчанию используется `all-MiniLM-L6-v2` — это быстрый базовый вариант.

Если Cursor/LLM формирует запросы в основном **на английском**, часто имеет смысл перейти на более точную модель:
- `bge-base-en-v1.5` — хороший баланс качества и скорости
- `bge-large-en-v1.5` — максимум качества, но тяжелее по CPU/памяти

Важно:
- модель для индексации и для поиска должна быть **одна и та же**
- после смены модели нужна **переиндексация** (`cursor-rag index ... --force`)

## 🎯 Быстрый старт

### 1. Индексация проекта

```bash
# Индексировать текущий проект (имя определится автоматически)
cursor-rag index .

# Индексировать с указанным именем
cursor-rag index . --name my_project

# Индексировать с custom базой данных
cursor-rag index /path/to/project --db ~/my_databases/code_db

# Переиндексировать (перезаписать существующий)
cursor-rag index . --force
```

### 2. Создание конфигурации для Cursor

```bash
# Создать mcp-config.json в текущей директории
cursor-rag config

# Создать в указанном месте
cursor-rag config --output ~/cursor-settings/mcp-config.json
```

### 3. Настройка Cursor IDE

1. Откройте Cursor IDE
2. Перейдите в **Settings → Features → MCP Servers**
3. Добавьте содержимое созданного `mcp-config.json`
4. Перезапустите Cursor

### 4. Использование в Cursor

Теперь в Cursor доступны следующие MCP инструменты:

- **search_codebase** - поиск по проиндексированному коду
- **list_rag_projects** - список всех проектов

Пример использования в чате Cursor:
```
@mcp search_codebase project=my_project query="authentication logic"
```

## 📚 Команды CLI

### `cursor-rag help`

Показывает справку по CLI или по конкретной команде.

```bash
cursor-rag help
cursor-rag help index
cursor-rag help serve
```

### `cursor-rag model`

Управление моделью эмбеддингов **глобально** (сохранение в `~/.cursor_rag/config.json`).

Команды:

```bash
cursor-rag model list
cursor-rag model show
cursor-rag model set mini
cursor-rag model set bge-base
cursor-rag model set bge-large
```

Примечания:
- `CURSOR_RAG_MODEL` (env) имеет приоритет над `~/.cursor_rag/config.json`.
- После смены модели нужно **переиндексировать** проект, иначе эмбеддинги в БД останутся от старой модели.

Формат `~/.cursor_rag/config.json` (минимально):

```json
{
  "model": "BAAI/bge-base-en-v1.5"
}
```

### `cursor-rag index`

Индексирует проект в векторную базу данных.

```bash
cursor-rag index [PATH] [OPTIONS]

Опции:
  --name, -n NAME    Имя проекта (автоопределение если не указано)
  --db PATH          Путь к базе данных (по умолчанию ~/.cursor_rag)
  --force, -f        Перезаписать существующий индекс

Примеры:
  cursor-rag index .
  cursor-rag index /home/user/my-project --name awesome_project
  cursor-rag index . --force --db ~/databases/work_db
```

### `cursor-rag list`

Показывает список проиндексированных проектов.

```bash
cursor-rag list [OPTIONS]

Опции:
  --db PATH          Путь к базе данных

Примеры:
  cursor-rag list
  cursor-rag list --db ~/databases/work_db
```

### `cursor-rag delete`

Удаляет проект из индекса.

```bash
cursor-rag delete NAME [OPTIONS]

Опции:
  --db PATH          Путь к базе данных

Примеры:
  cursor-rag delete old_project
  cursor-rag delete temp_project --db ~/databases/test_db
```

### `cursor-rag serve`

Запускает MCP сервер для Cursor IDE.

```bash
cursor-rag serve [OPTIONS]

Опции:
  --db PATH          Путь к базе данных

Примеры:
  cursor-rag serve
  cursor-rag serve --db ~/databases/work_db
```

**Примечание**: Обычно эту команду не нужно запускать вручную, она используется в конфигурации MCP.

### `cursor-rag config`

Генерирует конфигурацию MCP для Cursor IDE.

```bash
cursor-rag config [OPTIONS]

Опции:
  --output, -o PATH  Путь для сохранения (по умолчанию ./mcp-config.json)
  --db PATH          Путь к базе данных

Примеры:
  cursor-rag config
  cursor-rag config --output ~/mcp-cursor.json
  cursor-rag config --db ~/databases/work_db --output ~/config.json
```

### `cursor-rag info`

Показывает текущую конфигурацию.

```bash
cursor-rag info

Выводит:
  - Путь к базе данных
  - Используемая модель
  - Параметры чанкинга
  - Игнорируемые директории и расширения
```

## ⚙️ Конфигурация

### Переменные окружения

Вы можете настроить поведение через переменные окружения:

| Переменная | Описание | Значение по умолчанию |
|-----------|----------|----------------------|
| `CURSOR_RAG_DB_PATH` | Путь к базе данных | `~/.cursor_rag` |
| `CURSOR_RAG_MODEL` | Модель для эмбеддингов | `all-MiniLM-L6-v2` |
| `CURSOR_RAG_CHUNK_SIZE` | Размер чанка в символах | `500` |
| `CURSOR_RAG_CHUNK_OVERLAP` | Перекрытие чанков | `50` |
| `CURSOR_RAG_MIN_CHUNK_SIZE` | Минимальный размер чанка (маленькие объединяются) | `200` |
| `CURSOR_RAG_SEMANTIC_CHUNKING` | Семантический чанкинг кода (true/false) | `true` |
| `CURSOR_RAG_IGNORE_DIRS` | Доп. игнорируемые папки | - |
| `CURSOR_RAG_IGNORE_EXT` | Доп. игнорируемые расширения | - |
| `CURSOR_RAG_ALLOWED_EXT` | Кастомные разрешенные расширения | - |

Пример использования:

```bash
# Использовать custom базу данных
export CURSOR_RAG_DB_PATH=~/my_project_db
cursor-rag index .

# Изменить модель эмбеддингов
export CURSOR_RAG_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
cursor-rag index .

# Добавить игнорируемые директории
export CURSOR_RAG_IGNORE_DIRS="temp,cache,backup"
cursor-rag index .
```

### Игнорируемые по умолчанию

**Директории**:
- `node_modules`, `venv`, `.venv`, `env`
- `.git`, `.idea`, `.vscode`
- `__pycache__`, `dist`, `build`, `coverage`
- `.next`, `.nuxt`, `target`
- `.pytest_cache`, `.mypy_cache`, `.ruff_cache`

**Расширения файлов**:
- Бинарные: `.pyc`, `.so`, `.dll`, `.exe`, `.class`
- Изображения: `.jpg`, `.png`, `.gif`, `.svg`, `.ico`
- Архивы: `.zip`, `.tar`, `.gz`, `.7z`, `.rar`
- Шрифты: `.woff`, `.woff2`, `.ttf`, `.eot`

**Разрешенные расширения**:
- Языки: `.py`, `.js`, `.ts`, `.go`, `.rs`, `.java`, `.cpp`, `.c`, `.rb`, `.php`, `.swift`
- Разметка: `.md`, `.html`, `.css`, `.scss`, `.json`, `.yaml`, `.xml`
- Конфиги: `.toml`, `.ini`, `.cfg`, `.env`
- SQL: `.sql`, `.graphql`

## 🔧 Использование как библиотека

Вы можете использовать cursor-rag-tools программно в вашем Python коде:

```python
from cursor_rag import Indexer, auto_detect_project_name, get_db_path
from pathlib import Path

# Создать индексатор
indexer = Indexer()

# Индексировать проект
project_path = Path("/path/to/project")
project_name = auto_detect_project_name(project_path)
files_count, chunks_count = indexer.index_project(
    project_path=project_path,
    project_name=project_name,
    force=True
)

print(f"Indexed {files_count} files, {chunks_count} chunks")

# Получить список проектов
projects = indexer.list_projects()
for name, count in projects:
    print(f"{name}: {count} chunks")

# Удалить проект
indexer.delete_project("old_project")

# Custom база данных
custom_indexer = Indexer(db_path=Path("~/my_db"))
```

## 🎨 Примеры использования

### Пример 1: Индексация нескольких проектов

```bash
# Проект 1: backend
cd ~/projects/my-backend
cursor-rag index . --name backend_api

# Проект 2: frontend
cd ~/projects/my-frontend
cursor-rag index . --name frontend_app

# Проект 3: ML модели
cd ~/projects/ml-models
cursor-rag index . --name ml_research

# Посмотреть все проекты
cursor-rag list
```

### Пример 2: Разные базы для работы и личных проектов

```bash
# Рабочие проекты
export CURSOR_RAG_DB_PATH=~/databases/work
cursor-rag index ~/work/project1 --name work_api
cursor-rag index ~/work/project2 --name work_frontend

# Личные проекты
export CURSOR_RAG_DB_PATH=~/databases/personal
cursor-rag index ~/personal/hobby-app --name hobby_project

# Создать отдельные конфиги
cursor-rag config --db ~/databases/work --output ~/mcp-work.json
cursor-rag config --db ~/databases/personal --output ~/mcp-personal.json
```

### Пример 3: Работа с проектами на кириллице

```bash
# Автоматическая транслитерация
cd ~/проекты/мой_сайт
cursor-rag index .
# Создаст проект с именем "moy_sayt"

# Или явно указать имя
cursor-rag index . --name my_website
```

## 🐛 Устранение неполадок

### База данных заблокирована

Если вы видите ошибку "database is locked":

1. Закройте все процессы `cursor-rag serve`
2. Закройте Cursor IDE
3. Подождите несколько секунд
4. Попробуйте снова

### Проект не найден в Cursor

1. Убедитесь, что проект проиндексирован: `cursor-rag list`
2. Проверьте имя проекта (используйте точное имя из списка)
3. Убедитесь, что в `mcp-config.json` указан правильный путь к БД
4. Перезапустите Cursor IDE

### Медленная индексация

1. Проверьте размер проекта: `cursor-rag info`
2. Добавьте большие директории в игнорируемые через env vars
3. Используйте более легкую модель эмбеддингов

### Ошибки при установке

```bash
# Обновите pip
pip install --upgrade pip

# Установите зависимости вручную (если нужно)
pip install chromadb sentence-transformers mcp tree-sitter tree_sitter_languages

# Потом установите пакет
pip install -e .
```

## 📖 Дополнительная документация

- `QUICK_START.md` - подробное руководство для начинающих
- `TROUBLESHOOTING.md` - решение распространенных проблем

## 🤝 Вклад в проект

Приветствуются pull requests! Перед началом работы:

1. Fork репозитория
2. Создайте ветку для вашей фичи
3. Внесите изменения
4. Напишите тесты (если применимо)
5. Создайте pull request

## 📄 Лицензия

MIT License

## 🙏 Благодарности

- [ChromaDB](https://www.trychroma.com/) - векторная база данных
- [Sentence Transformers](https://www.sbert.net/) - модели для эмбеддингов
- [MCP](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol

---

**Приятного использования! 🎉**

Если у вас есть вопросы или предложения, создайте issue в репозитории.