getstack-mcp 2.4.0
MCP server for managing getstack templates from Supabase database with RAG search
License: MIT
Requires Python: >=3.10
Keywords: claude, embeddings, mcp, rag, supabase, templates

# GetStack Templates MCP Server

MCP сервер для управления шаблонами GetStack из базы данных Supabase с поддержкой RAG поиска.

## Особенности

- 📋 Получение списка всех доступных шаблонов
- 🔍 RAG поиск шаблонов с использованием векторных эмбеддингов
- 🔄 Fallback на поиск по ключевым словам
- 📦 Клонирование шаблонов в указанную папку
- 🔐 Безопасная архитектура без прямого доступа к OpenAI API

## Архитектура

MCP сервер работает через API фронтенда для генерации эмбеддингов, что обеспечивает:
- Безопасность: OpenAI API ключ хранится только на сервере фронтенда
- Централизованную логику: Вся логика поиска и обработки в одном месте
- Fallback механизмы: Автоматический переход на поиск по ключевым словам

## Установка

```bash
cd mcp
uv sync
```

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

Установите переменные окружения:

```bash
# URL фронтенд API (по умолчанию http://localhost:3000)
export FRONTEND_API_URL="http://localhost:3000"
```

## Запуск

```bash
cd mcp
uv run python server.py
```

## Доступные функции

### get_templates()

Получает список всех доступных шаблонов из базы данных Supabase.

**Возвращает:**
- `success`: Статус операции
- `templates`: Список шаблонов с базовой информацией
- `count`: Количество найденных шаблонов

### search_templates(query, limit=10, similarity_threshold=0.7, auth_token=None)

Выполняет RAG поиск шаблонов с использованием векторных эмбеддингов.

**Параметры:**
- `query`: Поисковый запрос
- `limit`: Максимальное количество результатов (по умолчанию 10)
- `similarity_threshold`: Минимальный порог сходства от 0 до 1 (по умолчанию 0.7)
- `auth_token`: Токен авторизации для доступа к API (опционально)

**Возвращает:**
- `success`: Статус операции
- `templates`: Список шаблонов отсортированных по релевантности
- `search_type`: Тип поиска ("rag" или "keyword")
- `message`: Дополнительная информация

### search_templates_via_frontend_api(query, auth_token=None)

Выполняет поиск шаблонов используя готовую логику фронтенда.

**Параметры:**
- `query`: Поисковый запрос
- `auth_token`: Токен авторизации для доступа к API (опционально)

**Возвращает:**
- `success`: Статус операции
- `templates`: Список шаблонов отсортированных по релевантности
- `search_type`: Тип поиска ("rag" или "keyword")
- `message`: Информация о результатах поиска

### use_template(template_id, current_folder)

Клонирует указанный шаблон в заданную папку.

**Параметры:**
- `template_id`: ID шаблона в базе данных Supabase
- `current_folder`: Целевая папка для копирования шаблона (полный абсолютный путь)

**Возвращает:**
- `success`: Статус операции
- `template_name`: Название шаблона
- `files_copied`: Количество скопированных файлов
- `target_folder`: Путь к целевой папке

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

### Поиск React шаблонов

```python
# Поиск с использованием RAG
result = search_templates("React TypeScript components")

# Поиск через фронтенд API
result = search_templates_via_frontend_api("React TypeScript components")
```

### Использование шаблона

```python
# Клонирование шаблона в текущую папку
result = use_template("template-id-123", "/path/to/project")
```

## Обработка ошибок

Все функции возвращают структурированные ответы с полем `success`:
- `success: true` - операция выполнена успешно
- `success: false` - произошла ошибка, детали в поле `error`

## Fallback механизмы

1. **RAG поиск недоступен**: Автоматический переход на поиск по ключевым словам
2. **Фронтенд API недоступен**: Прямой поиск в базе данных Supabase
3. **Сетевые ошибки**: Подробные сообщения об ошибках с рекомендациями

## Безопасность

- OpenAI API ключ никогда не передается в MCP сервер
- Все запросы к внешним API проходят через фронтенд
- Поддержка токенов авторизации для защищенных эндпоинтов
- Валидация всех входных параметров

## Логирование

Сервер ведет подробные логи всех операций:
- Успешные операции: INFO уровень
- Ошибки: ERROR уровень с полными трассировками
- Предупреждения: WARNING уровень для fallback операций

## Лицензия

MIT