MCP Developer Tools

Современное FastAPI приложение для разработчиков с полным набором инструментов для разработки, тестирования и мониторинга.

🚀 Технологический стек

• Python 3.12
• FastAPI - современный веб-фреймворк
• SQLAlchemy - ORM для работы с базой данных
• Alembic - система миграций
• Pydantic - валидация данных
• Poetry - управление зависимостями
• Docker - контейнеризация
• Prometheus - мониторинг
• OpenTelemetry - трассировка
• Sphinx - документация

📋 Требования

• Python 3.12+
• Poetry
• Docker и Docker Compose
• Make или Just

🛠 Установка

1. Клонируйте репозиторий:

git clone https://github.com/your-username/mcp-developer.git
cd mcp-developer

2. Установите зависимости через Poetry:

poetry install

3. Создайте файл .env на основе .env.example:

cp .env.example .env

4. Настройте переменные окружения в файле .env

🚀 Запуск

Локальный запуск

# Активация виртуального окружения
poetry shell

# Запуск приложения
uvicorn src.app.main:app --reload

Запуск через Docker

docker-compose up -d

📚 Документация

После запуска приложения документация доступна по адресам:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🧪 Тестирование

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

# Запуск тестов с покрытием
pytest --cov=src

# Запуск линтеров
poetry run pre-commit run --all-files

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

src/
├── app/
│   ├── api/          # API эндпоинты
│   ├── core/         # Базовая логика
│   ├── db/           # Работа с БД
│   ├── models/       # SQLAlchemy модели
│   ├── repositories/ # Репозитории
│   ├── schemas/      # Pydantic модели
│   ├── services/     # Бизнес-логика
│   └── main.py       # Точка входа
├── tests/            # Тесты
└── docs/             # Документация

🔧 Инструменты разработки

• Black - форматирование кода
• isort - сортировка импортов
• mypy - статическая типизация
• ruff - линтер
• pre-commit - git хуки
• commitizen - стандартизация коммитов

📊 Мониторинг

• Prometheus метрики доступны по адресу: http://localhost:8000/metrics
• Jaeger UI для просмотра трейсов: http://localhost:16686

🤝 Вклад в проект

1. Создайте ветку для новой функциональности
2. Внесите изменения
3. Запустите тесты и линтеры
4. Создайте Pull Request

🛠 Команды Just

Проект использует just для автоматизации задач разработки. Все команды логируются в файл justfile.log.

�� Основные команды

Просмотр доступных команд

just

Установка зависимостей

just install

• Проверяет версию Python
• Устанавливает Poetry
• Устанавливает зависимости
• Настраивает pre-commit хуки

Обновление зависимостей

just update

• Обновляет poetry.lock
• Переустанавливает зависимости

Запуск приложения

just run

• Автоматическая перезагрузка при изменениях
• Логирование в консоль

Тестирование

just test

• Запускает pytest
• Генерирует отчет о покрытии

Тестирование с покрытием

just test-cov

• Запускает pytest с coverage
• Минимальное покрытие: 95%

Проверка покрытия

just coverage

• Генерирует HTML отчет
• Открывает отчет в браузере

🧹 Очистка и форматирование

Очистка кэшей

just clean

• Удаляет pycache
• Удаляет .pytest_cache
• Удаляет .coverage
• Удаляет .ruff_cache

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

just fmt

• Запускает isort для сортировки импортов
• Запускает black для форматирования
• Запускает ruff format
• Создает бэкап перед форматированием

Проверка типов

just typecheck

• Запускает mypy в строгом режиме
• Проверяет все Python файлы
• Генерирует отчет об ошибках

Линтинг

just lint

• Запускает ruff check
• Проверяет стиль кода
• Проверяет безопасность

🐳 Docker команды

Сборка образа

just docker-build

• Собирает multi-stage образ
• Оптимизирует размер
• Использует кэширование слоев

Запуск контейнеров

just docker-up

• Запускает все сервисы
• Настраивает сети
• Проверяет здоровье

Остановка контейнеров

just docker-down

• Останавливает все сервисы
• Удаляет сети
• Очищает тома

Просмотр логов

just docker-logs

• Показывает логи всех сервисов
• Поддерживает фильтрацию
• Автоматическое обновление

📚 Документация

Сборка документации

just docs-build

• Генерирует HTML из RST
• Собирает API документацию
• Проверяет ссылки

Запуск сервера документации

just docs-serve

• Запускает локальный сервер
• Автоматическая перезагрузка
• Поддержка поиска

🔍 Проверки безопасности

Проверка зависимостей

just security-check

• Проверяет уязвимости в пакетах
• Обновляет базу данных уязвимостей
• Генерирует отчет

Проверка кода

just security-scan

• Запускает bandit
• Проверяет безопасность кода
• Генерирует отчет

🧪 Тестирование

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

just test

• Запускает pytest
• Использует pytest-xdist
• Генерирует отчет

Тестирование с покрытием

just test-cov

• Запускает pytest с coverage
• Проверяет минимальное покрытие
• Генерирует HTML отчет

Запуск конкретного теста

just test-one TEST_PATH=path/to/test.py

• Запускает указанный тест
• Поддерживает отладку
• Показывает подробный вывод

Отладочное тестирование

just test-debug

• Включает подробный вывод
• Останавливается на ошибках
• Показывает переменные

🔄 Миграции базы данных

Создание миграции

just db-migrate MESSAGE="описание миграции"

• Генерирует миграцию из моделей
• Добавляет описание
• Проверяет корректность

Применение миграций

just db-upgrade

• Применяет все миграции
• Проверяет статус
• Логирует изменения

Откат миграции

just db-downgrade

• Откатывает последнюю миграцию
• Проверяет статус
• Логирует изменения

📝 Лицензия

MIT