Content
# DevBoost MCP Server 🚀
## Что делает MCP-сервер
**Какую боль решает:**
Сервер `DevBoost` решает две классические проблемы локальной разработки, отнимающие часы времени:
1. **Проблемы с окружением:** залипшие порты (`EADDRINUSE`) и рассинхрон системных версий (Node/Python) между разработчиками.
2. **Проблемы с базами данных:** медленные SQL-запросы, сложность профилирования (чтение "простыней" `EXPLAIN ANALYZE`) и непонимание того, где конкретно не хватает индексов.
**Для кого полезен:**
Fullstack-разработчики, джуниор/мидл бэкендеры и AI-агенты, так как сервер превращает любую LLM в локального DevOps-инженера и DBA (Database Administrator).
**Какие инструменты реализованы (4 инструмента):**
- `check_versions` — проверка версий установленного локального софта.
- `kill_port_hog` — устранение зависших процессов по порту.
- `explain_query` — профилирование SQL-запросов (поиск узких мест типа Seq Scan).
- `suggest_index` — выявление отсутствующих индексов для оптимизации таблиц.
---
## Быстрый старт (Запуск для Жюри)
Мы максимально упростили запуск проекта, автоматизировав установку зависимостей, сборку и запуск БД.
### 1. Требования к окружению
Для запуска проекта вам понадобится:
* Установленный **Docker** и **Docker Compose** (для запуска сервера и базы данных).
* Установленный **Node.js** (npm/npx) (для интерфейса Inspector).
* Установленный **Python 3.10+** (для локальной установки пакетов).
### 2. Запуск в один клик (Автоматизированный стенд)
Для проверяющих жюри и быстрого тестирования в корне проекта лежат исполняемые файлы.
Просто запустите нужный файл **двойным кликом** (на Windows) или через терминал (на Mac/Linux):
- **Windows:** Двойной клик по `1_Запустить_Сервер.bat`
- **Mac/Linux:** `bash 1_start_server.sh`
**Что произойдет автоматически:**
1. Скрипт создаст чистое локальное окружение и установит зависимости.
2. Соберет Docker-образ MCP-сервера DevBoost.
3. Поднимет тестовую базу данных на 100 000 строк и сам сервер.
4. Автоматически скачает и **откроет MCP Inspector** в вашем браузере!
После запуска скрипта вам останется лишь перейти по предоставленной браузерной ссылке (обычно `http://localhost:5173`) и начать работать с ИИ во вкладке **Chat**!
---
### (Опционально) Ручная установка и запуск
Если вы хотите запустить проект вручную:
**Создание окружения и локальная установка пакета:**
> **⚠️ Важно для Windows:** Пакет `asyncpg` может выдавать ошибку компиляции на **Python 3.13**. Рекомендуем использовать **Python 3.10-3.12**.
```bash
python3 -m venv .venv
# Mac/Linux: source .venv/bin/activate
# Windows: .venv\Scripts\activate
pip install -e .
```
**Сборка образа и запуск (без базы данных):**
```bash
docker build -t devboost-mcp .
docker run -p 8080:8000 devboost-mcp serve
```
### Как проверить /health
Для быстрой проверки работоспособности образа (Smoke Test), который запустится, проверит собственный `/health` и моментально завершится:
```bash
docker run --rm devboost-mcp smoke
```
Также вы можете вручную проверить эндпоинт, если сервер запущен через команду `server`:
```bash
curl http://localhost:8080/health
```
### Как подключиться через MCP Inspector/клиент
**Тестирование через Inspector браузера (локально):**
Для проверки всего функционала руками подготовлена папка `demo_project/` с тестовой БД. Подробная инструкция по запуску Inspector описана в файле **[DEMO.md](DEMO.md)**.
**Подключение реального ИИ (Claude Desktop):**
Добавьте этот блок в конфиг `claude_desktop_config.json` и перезапустите приложение:
```json
{
"mcpServers": {
"devboost": {
"command": "/АБСОЛЮТНЫЙ_ПУТЬ_ДО_ВЕНВ_ПРОЕКТА/bin/python",
"args": ["/АБСОЛЮТНЫЙ_ПУТЬ_ДО_ПРОЕКТА/run_stdio.py"],
"env": {
"DATABASE_URL": "postgresql://testuser:testpass@localhost:54322/testdb"
}
}
}
}
```
---
## Как использовать
Сервер предоставляет ИИ-ассистентам следующие функции (Tools):
### 1. `check_versions`
- **Что делает:** Проверяет установленные в системе версии утилит (например, node, docker).
- **Входные параметры:** `tools: array of strings` (список имен бинарников, например `["node", "docker"]`).
- **Ожидаемый результат:** Текст с найденным путем до бинарника и его версией, либо сообщение об отсутствии.
### 2. `kill_port_hog`
- **Что делает:** Находит и завершает процесс (PID), который занимает указанный порт. Безопасен, так как убивает только процессы текущего пользователя.
- **Входные параметры:** `port: integer` (например, `8080`).
- **Ожидаемый результат:** Имя и PID убитого процесса, либо уведомление, что порт свободен.
### 3. `explain_query`
- **Что делает:** Выполняет `EXPLAIN ANALYZE` для переданного SQL-запроса в подключенной PostgreSQL базе.
- **Входные параметры:** `query: string` (валидный SQL SELECT запрос).
- **Ожидаемый результат:** JSON-структура плана выполнения запроса (показывает реальное время и методы сканирования, например Seq Scan).
### 4. `suggest_index`
- **Что делает:** Читает схему базы данных PostgreSQL, находя все существующие индексы для заданных таблиц.
- **Входные параметры:** `tables: array of strings` (список таблиц, например `["users"]`).
- **Ожидаемый результат:** Список существующих индексов. ИИ использует эту информацию для генерации команды `CREATE INDEX`, если выявил проблему шагом ранее.
---
## Ограничения / допущения
**Что поддерживается:**
- Мониторинг портов и завершение процессов работает на **macOS** и **Linux**.
- Инструменты для работы с базами данных строго завязаны на **PostgreSQL**.
- Работа по протоколу MCP через потоки `stdio` (Python) или `SSE` эндпоинты (Docker).
**Что не поддерживается:**
- Windows-специфичные сетевые команды (инструмент `kill_port_hog` использует `lsof` под капотом).
- Другие СУБД (MySQL, SQLite, MongoDB).
- Выполнение мутирующих SQL-запросов клиентом напрямую в обход `explain` (сервер спроектирован для анализа, а не для удаления данных).
**На каком тестовом проекте проверялось:**
Сервер проверялся на проекте из папки `demo_project/`. Внутри находится классическая проблема: конфигурация `docker-compose`, поднимающая базу данных PostgreSQL 15, в которой развернута таблица `users` на **100 000 строк**. Присутствует скрипт инициализации `init-db.sql`. Эта конфигурация гарантированно воспроизводит проблемы долгого `Seq Scan` без индексов.
---
## (Опционально) Расширенный режим
Данный MCP-сервер является автономным и не требует внешних платных сервисов (OpenAI, Anthropic API) на своей стороне.
Единственная "интеграция" — подключение к вашей локальной базе данных.
**Как включить:**
При запуске сервера необходимо передать строку подключения через переменную окружения `DATABASE_URL`.
В репозитории лежит шаблон `.env.example`, который вы можете использовать для локального тестирования. Секретов в репозитории нет.
