QUICKSTART.md

MCP Code RAG Server - Быстрый старт

Что это такое?

MCP Code RAG Server — это сервер для интеллектуального поиска и анализа кода с использованием векторного поиска. Он позволяет задавать вопросы на естественном языке о вашей кодобазе и получать релевантные фрагменты кода.

Основные возможности

• Векторный поиск по кодебазе на основе семантической схожести
• Инкрементальная индексация для быстрого обновления при изменениях
• Различные стратегии чанкинга: truncate, fixed-size, AST-based
• Локальное хранение данных в LanceDB
• Мультязычная поддержка (Go, Python, JavaScript и др.)

Быстрый старт за 5 шагов

Шаг 1: Установка Go

Убедитесь, что у вас установлен Go 1.21 или выше:

go version

Если нет, установите с https://go.dev/dl/

Шаг 2: Клонируйте репозиторий

git clone https://github.com/yourusername/mcp-code-rag.git
cd mcp-code-rag

Шаг 3: Установите зависимости

go mod download
go mod tidy

Шаг 4: Соберите проект

make build

Это создаст бинарный файл в build/mcp-code-rag-server

Шаг 5: Запустите сервер

./build/mcp-code-rag-server -config=config/test-config.yaml

Сервер запустится и будет готов к приему запросов.

Использование с MCP клиентами

Пример 1: Подключение через stdio

{
  "extensions": [
    {
      "name": "mcp-code-rag",
      "type": "stdio",
      "command": "/path/to/mcp-code-rag-server"
    }
  ]
}

Пример 2: Использование с Continue

В конфигурации Continue добавьте:

{
  "extensions": [
    {
      "name": "code-rag",
      "type": "stdio",
      "command": "/path/to/mcp-code-rag-server"
    }
  ]
}

Примеры запросов

После индексации вы можете задавать вопросы:

1. "как работает аутентификация" - покажет код JWT токенов
2. "структура пользователя" - покажет модель User
3. "помощники и утилиты" - вернет функции из helpers.go

Конфигурация

Создайте файл config.yaml:

codebase_path: "./my-repo"           # Путь к вашему кодебазе
database_path: "./data/index.lance"  # Путь к базе данных

embedding:
  model_name: "sentence-transformers/all-MiniLM-L6-v2"
  use_ollama: false                  # true для использования Ollama

chunking:
  strategy: "fixed-size"             # truncate, fixed-size, ast-based
  max_chunk_size: 2048               # Максимальный размер чанка (символы)
  overlap_size: 256                  # Перекрытие между чанками

search:
  default_limit: 10                  # Количество результатов по умолчанию
  similarity_threshold: 0.3          # Порог схожести (0.0-1.0)

Команды Makefile

Команда	Описание
make build	Собрать проект для текущей платформы
make cross-build	Собрать бинарники для всех платформ (Linux, macOS, Windows)
make run	Запустить сервер локально
make test	Запустить все тесты
make fmt	Отформатировать код
make lint	Проверить код линтером
make clean	Очистить бинарники и временные файлы

Сборка для разных платформ

Linux AMD64

GOOS=linux GOARCH=amd64 go build -o mcp-code-rag-server-linux ./cmd/server

macOS ARM64 (Apple Silicon)

GOOS=darwin GOARCH=arm64 go build -o mcp-code-rag-server-macos-arm64 ./cmd/server

Windows AMD64

GOOS=windows GOARCH=amd64 go build -o mcp-code-rag-server-windows.exe ./cmd/server

Или используйте готовую команду:

make cross-build

Это создаст все бинарники в директории dist/.

Структура проекта

mcp-code-rag/
├── cmd/server/          # Точка входа приложения
│   └── main.go
├── internal/            # Приватный код
│   ├── chunking/        # Стратегии чанкинга
│   │   ├── chunker.go   # Интерфейс
│   │   ├── truncate.go  # Truncate стратегия
│   │   └── fixed_size.go# Fixed-size стратегия
│   ├── embedding/       # Генерация эмбеддингов
│   │   ├── embedder.go  # Интерфейс
│   │   └── mock.go      # Mock реализация для тестов
│   ├── db/              # Работа с базой данных
│   │   ├── database.go  # Интерфейс БД
│   │   └── mock.go      # Mock реализация
│   └── mcp/             # MCP протокол
│       ├── types.go     # Типы данных
│       └── server.go    # Серверная логика
├── config/              # Конфигурация
│   ├── config.go        # Загрузка конфигурации
│   ├── config.yaml      # Основной конфиг
│   └── test-config.yaml # Тестовый конфиг
├── example-repo/        # Пример кодебазы для тестирования
├── docs/                # Документация
├── build/               # Собранные бинарники (генерируется)
├── dist/                # Релизные бинарники (генерируется)
└── data/                # Данные LanceDB (генерируется)

Разработка и тестирование

Запуск тестов

go test -v ./...
# Или
make test

Форматирование кода

go fmt ./...
# Или
make fmt

Линтинг (требует golangci-lint)

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
golangci-lint run
# Или
make lint

Отладка

Включение подробного логирования

export LOG_LEVEL=debug
./build/mcp-code-rag-server

Проверка здоровья базы данных

Используйте встроенную проверку:

if err := db.HealthCheck(ctx); err != nil {
    log.Printf("Database health check failed: %v", err)
}

Решение проблем

Ошибка "module not found"

Убедитесь, что все зависимости установлены:

go mod download
go mod tidy

Проблемы с LanceDB

Если база данных повреждена:

rm -rf ./data/index.lance
# Перезапустите сервер для создания новой базы
./build/mcp-code-rag-server

Сервер не запускается

Проверьте права на выполнение:

chmod +x build/mcp-code-rag-server

Используйте go run вместо бинарника:

go run ./cmd/server

Следующие шаги

1. Изучите документацию в директории docs/
2. Попробуйте разные стратегии чанкинга и модели эмбеддингов
3. Интегрируйте с MCP клиентом вашей IDE
4. Настройте автоматическую индексацию при изменениях кода

Полезные ресурсы

• MCP Protocol Documentation
• LanceDB Documentation
• Go Effective Programs

Поддержка

Если у вас возникли проблемы:

1. Проверьте документацию в docs/
2. Откройте issue на GitHub с описанием проблемы
3. Изучите логи сервера при включенном debug режиме

---

Удачной работы с вашим кодом! 🚀