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 (возвращает файл + строки + найденный фрагмент)

📦 Установка

pip install cursor-rag-tools

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

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

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

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. Индексация проекта

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

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

cursor-rag help
cursor-rag help index
cursor-rag help serve

cursor-rag model

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

Команды:

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 (минимально):

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

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_MIN_CHUNK_SIZE	Минимальный размер чанка (маленькие объединяются)	200
CURSOR_RAG_SEMANTIC_CHUNKING	Семантический чанкинг кода (true/false)	true
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 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 - векторная база данных
• Sentence Transformers - модели для эмбеддингов
• MCP - Model Context Protocol

---

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

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