cursor-rag-tools 1.0.0

RAG indexing and search for Cursor IDE via MCP

cursor-rag-tools

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

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

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

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

📦 Установка

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

cd cursor-rag-tools
pip install -e .

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

pip install cursor-rag-tools

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

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

# Индексировать текущий проект (имя определится автоматически)
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

# Создать 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

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

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

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

cursor-rag list [OPTIONS]

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

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

cursor-rag delete

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

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.

cursor-rag serve [OPTIONS]

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

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

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

cursor-rag config

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

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

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

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	Кастомные разрешенные расширения	-

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

# Использовать 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 коде:

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: Индексация нескольких проектов

# Проект 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: Разные базы для работы и личных проектов

# Рабочие проекты
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: Работа с проектами на кириллице

# Автоматическая транслитерация
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. Используйте более легкую модель эмбеддингов

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

# Обновите 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 - векторная база данных
• Sentence Transformers - модели для эмбеддингов
• MCP - Model Context Protocol

---

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

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