🛠️ McBuddy Server

Язык: 🇷🇺 Русский | 🇺🇸 English | 🇨🇳 中文

🛠️⚡ Бэкенд для AI-ассистента MCBuddy — быстрый сервер на Bun с интеграцией OpenRouter, обработкой запросов из Minecraft серверов и Telegram ботов. Предоставляет REST API для получения AI-ответов на вопросы о Minecraft с контекстом и историей чата.

Сборка и деплой

Docker Compose (рекомендуется для продакшена)

1. Подготовка конфигурации:

   # Клонируйте репозиторий
   git clone https://github.com/mcbuddy-ai/mcbuddy-server
   cd mcbuddy-server
   
   # Скопируйте пример переменных окружения
   cp .env.sample .env
   
   # Отредактируйте .env файл с вашими настройками
   nano .env

2. Настройка домена:

   # Отредактируйте Caddyfile и замените mcbuddy.ru на ваш домен
   nano configurations/caddy/Caddyfile

3. Запуск:

   docker compose up -d

4. Проверьте статус:

   docker compose logs -f mcbuddy-server

Docker Compose с готовым образом

Если хотите использовать готовый образ и управлять MongoDB/Redis самостоятельно:

1. Задекларируйте сервис mcbuddy-server в docker-compose.yml:

services:
  mcbuddy-server:
    image: ghcr.io/mcbuddy-ai/mcbuddy-server:1.3.3
    env_file: .env
    environment:
      MONGODB_URI: ${MONGODB_URI}
      REDIS_URL: ${REDIS_URL}
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
      # ... другие переменные окружения

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

2. Задекларируйте сервисы MongoDB и Redis в docker-compose.yml.

Важно, версия MongoDB должна быть 5.0+, а Redis должна быть 6.0+.

3. Запустите сервисы:

docker compose up -d

Bare Metal

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

   # Установите Bun.js
   curl -fsSL https://bun.sh/install | bash
   
   # Установите пакеты
   bun install

Важно! Не забудьте развернуть зависимые сервисы: Redis, MongoDB и Caddy при надобности.

2. Настройка переменных окружения:

   cp .env.sample .env
   # Отредактируйте .env с настройками для MongoDB, Redis и OpenRouter

3. Запуск:

   # Разработка
   bun run dev
   
   # Продакшен
   bun run build
   bun run start

⚠️ Важно: Обязательно настройте переменные окружения из файла .env.sample перед запуском. Особое внимание уделите OPENROUTER_API_KEY, MONGODB_URI и REDIS_URL и промптам.

Рантайм конфигурация

У пользователей бэкэнда есть возможность переопределить токен от openrouter.ai на свой, чтобы мониторить свои траты и иметь свои правила для роутинга AI моделей.

Для этого достаточно в запросах на этот бэкэнд отправить заголовок X-OpenRouter-Token: sk-xxxx-xxxx

Это позволит вам использовать свой биллинг и тарификацию.

Стек

• TypeScript — основной язык разработки
• Bun.js — быстрый JS runtime и пакетный менеджер
• MongoDB — основная база данных для пользователей и метрики
• Redis — кэширование и хранение истории чата
• Docker & Docker Compose — контейнеризация и оркестрация
• Caddy — реверс-прокси и SSL-терминация
• OpenRouter — API для доступа к различным AI моделям
• fp-ts — фп тс :)
• Mongoose — ODM для MongoDB
• BullMQ — система очередей и фоновых задач
• tslog — структурированное логирование (которое я благополучно не использую trollface.png)

Участие AI

AI-инструменты использовались точечно для решения специфических задач: оптимизация промптов для OpenRouter, генерация части документации и рефакторинг некоторых TypeScript типов. Основная архитектура, бизнес-логика и критические компоненты разработаны вручную. Коммиты полностью написаны AI агентом, по возможности участие ИИ сведено к минимуму.

Ссылки на связанные проекты

McBuddy Spigot — плагин для Minecraft серверов с командой /ask и /askx

McBuddy Telegram — Telegram бот для общения с MCBuddy

Из серии "от того же автора"

Xi Manager — 🀄️ Telegram-бот с ИИ, стилизованный под личного помощника Xi. Личный помощник великого лидера, готовый отвечать на вопросы простого народа.

Dickobrazz — 🌶️ Дикобраз бот, он же дикобот, способен в точности до сантиметра выдать размер вашего агрегата, краника или валыны, не обижайтесь, если не удалось понтануться большим прибором, это всего лишь шутка.

Louisepizdon — 🥀 Луипиздон, Telegram-бот с ИИ, который честнее чем твоя бабушка. Оценит тебя по достоинству, разборка ценообразования твоих шмоток с фотографии!

Mo'Bosses — 🏆 Mo'Bosses — это лучший RPG плагин, который превращает обычных мобов в эпических боссов с продвинутой системой прогрессии игрока. В отличие от других плагинов, здесь каждый бой имеет значение, а каждый уровень открывает новые возможности! ⚔

Mo'Joins — 🎉 Кастомные входы/выходы: сообщения, звуки, частицы, фейерверки и защита после входа. Все для PaperMC.

Mo'Afks — 🛡️ Пауза в онлайне — теперь возможна. Плагин для PaperMC, который даёт игроку безопасный режим AFK: иммунитет к урону, отсутствие коллизий, игнор мобами, авто-детект неактивности и аккуратные визуальные эффекты.

---

🇷🇺 Сделано в России с любовью. ❤️

MCBuddy — это результат любви к игре Minecraft и современным технологиям. Проект создан для русскоязычного сообщества игроков, с заботой о качестве кода и пользовательском опыте.

🫡 Made by Pavel Erokhin (Павел Ерохин), aka mairwunnx.