getstack-mcp

GetStack Templates MCP Server

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

Особенности

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

Архитектура

MCP сервер работает через API фронтенда для генерации эмбеддингов, что обеспечивает:

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

Установка

cd mcp
uv sync

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

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

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

Запуск

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 шаблонов

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

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

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

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

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

Все функции возвращают структурированные ответы с полем success:

• success: true - операция выполнена успешно
• success: false - произошла ошибка, детали в поле error

Fallback механизмы

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

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

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

Логирование

Сервер ведет подробные логи всех операций:

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

Лицензия

MIT