Metadata-Version: 2.4
Name: cursor-rag-tools
Version: 1.0.0
Summary: RAG indexing and search for Cursor IDE via MCP
Author: Cursor RAG Tools Contributors
License: MIT
Project-URL: Homepage, https://github.com/your-org/cursor-rag-tools
Project-URL: Repository, https://github.com/your-org/cursor-rag-tools
Project-URL: Issues, https://github.com/your-org/cursor-rag-tools/issues
Keywords: rag,cursor,mcp,indexing,chromadb,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chromadb>=0.4.0
Requires-Dist: sentence-transformers>=2.0.0
Requires-Dist: mcp>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# cursor-rag-tools

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

Этот инструмент позволяет индексировать вашу кодовую базу в векторную базу данных (ChromaDB) и использовать семантический поиск прямо в Cursor IDE через MCP (Model Context Protocol).

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

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

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

### Из локального источника

```bash
cd cursor-rag-tools
pip install -e .
```

### Из PyPI (когда будет опубликован)

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

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

### 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 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_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

# Потом установите пакет
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 в репозитории.

