🤖 MCP AI Assistant

🇷🇺 Русский | 🇬🇧 English

Dockerized MCP-сервер со 134 инструментами (файлы, GitHub, Google Sheets, погода, изображения, QR/штрихкоды, математика, валюты и др.), доступный по HTTP или stdio — подключается из Claude Desktop, Claude Code, Cursor или любого другого MCP-клиента.

---

🎯 Что это?

MCP AI Assistant — это библиотека готовых MCP-инструментов, упакованная в один Docker-образ. Внутри — 24 тематических сервера (файловая система, GitHub, погода, изображения, QR-коды, математика, валюты и т.д.), которые можно подключить целиком или частично к любому MCP-совместимому клиенту через обычный сетевой запрос, без установки Python или самого проекта.

Проект построен на Model Context Protocol (MCP) — открытом стандарте для подключения AI-моделей к внешним инструментам. Помимо самого MCP-сервера, в examples/terminal_chat.py есть готовый пример клиента — терминальный AI-ассистент, который использует эти же инструменты напрямую через диалог на естественном языке.

---

🧠 Как это работает

MCP-клиент → HTTP / stdio → MCP-гейтвей (src/gateway.py) → выбранные servers/*.py → внешний сервис
(Claude Desktop,                                                  ├── Файловая система
 Claude Code, Cursor,                                              ├── GitHub / Google Sheets API
 ваше приложение...)                                               └── погода, валюты, QR и т.д.

1. При старте контейнера переменная MCP_SERVERS определяет, какие домены инструментов включить (по умолчанию — все 24)
2. src/gateway.py монтирует выбранные servers/*.py в один MCP-эндпоинт
3. Любой MCP-клиент подключается по HTTP (или stdio) и видит список доступных инструментов
4. Клиент вызывает инструмент напрямую — без LLM в середине, если он не нужен вашему приложению

---

🛠 Возможности (140 инструментов)

---

📸 Демонстрация

Скриншоты ниже — из терминального примера клиента (examples/terminal_chat.py).

🚀 Быстрый старт

Требования

• Docker и Docker Compose (рекомендуемый способ)
• Или Python 3.12+ для запуска без контейнера
• GitHub Personal Access Token и Google OAuth Access Token — только если используете домены github/google_sheets
• Yandex Cloud API ключ — только для примера с терминальным чатом (examples/terminal_chat.py)

Docker (рекомендуется)

git clone https://github.com/Artem-Kornilov-pro/mcp-ai-assistant.git
cd mcp-ai-assistant
cp .env.example .env   # нужен только доменам, которым требуются токены (github, google_sheets)
docker compose up --build

Сервер поднимется на http://localhost:8000/mcp (транспорт Streamable HTTP). По умолчанию доступны все 24 домена и 134 инструмента.

Выбор доменов инструментов

Какие домены включены, определяет переменная MCP_SERVERS (список ключей через запятую; по умолчанию или при all — включены все):

MCP_SERVERS=weather,currency,qr docker compose up --build

Доступные ключи: filesystem, github, google_sheets, weather, datetime, sqlite, excel, csv, pdf, archive, text, random, math, linalg, validate, image, chart, qr, barcode, translate, equation, currency, units, holidays, color.

Авторизация (опционально)

Если контейнер доступен не только с localhost, задайте MCP_API_KEY — тогда все HTTP-запросы к /mcp без заголовка Authorization: Bearer будут отклонены с 401. Без этой переменной сервер работает как раньше, без авторизации (удобно для локальной разработки).

MCP_API_KEY=your-secret-key docker compose up --build

Подключение MCP-клиента

• Claude Desktop / Claude Code / Cursor и другие MCP-клиенты: укажите HTTP-эндпоинт http://localhost:8000/mcp в конфигурации MCP-серверов клиента.
• Напрямую (без Docker, для локальной интеграции по stdio): MCP_TRANSPORT=stdio python -m src.gateway — подходит для конфигов вида "command": "python", "args": ["-m", "src.gateway"].

Без Docker

make install
make run                 # эквивалент MCP_TRANSPORT=http PORT=8000 MCP_SERVERS=all

Пример клиента: терминальный чат

examples/terminal_chat.py — самостоятельный терминальный AI-ассистент (Yandex Cloud/DeepSeek), который вызывает инструменты из servers/*.py напрямую по естественноязыковому диалогу, без MCP-транспорта. Демонстрирует, как использовать эту библиотеку инструментов внутри своего приложения.

make install
cp .env.example .env     # заполните YANDEX_CLOUD_API_KEY и YANDEX_CLOUD_FOLDER_ID
make run-chat

---

🏗 Архитектура проекта

mcp-ai-assistant/
├── src/
│   ├── __init__.py          # Пакет
│   ├── config.py            # Загрузка конфигурации из .env
│   ├── llm.py               # LLM-клиент (Yandex Cloud / DeepSeek)
│   ├── mcp_manager.py       # Прямой вызов инструментов (используется примером-чатом)
│   └── gateway.py           # MCP-гейтвей: реестр доменов, монтирование, HTTP/stdio-сервер
├── servers/
│   ├── __init__.py
│   ├── filesystem.py        # Файловая система (4)
│   ├── github.py            # GitHub API (17)
│   ├── google_sheets.py     # Google Sheets (3)
│   ├── weather.py           # Погода wttr.in (8)
│   ├── datetime_tools.py    # Дата и время (8)
│   ├── sqlite_server.py     # Локальная SQLite БД (3)
│   ├── excel_server.py      # Excel (4)
│   ├── csv_server.py        # CSV (3)
│   ├── pdf_server.py        # PDF (3)
│   ├── archive_server.py    # ZIP-архивы (3)
│   ├── text_server.py       # Текстовые утилиты (5)
│   ├── random_server.py     # Случайные числа (5)
│   ├── math_server.py       # Математика (5)
│   ├── linalg_server.py     # Линейная алгебра (8)
│   ├── validate_server.py   # Валидация текста (5)
│   ├── image_server.py      # Изображения (7)
│   ├── chart_server.py      # Графики (10)
│   ├── qr_server.py         # QR-коды (10)
│   ├── barcode_server.py    # Штрихкоды (4)
│   ├── translate_server.py  # Перевод (2)
│   ├── equation_server.py   # Уравнения и неравенства (5)
│   ├── currency_server.py   # Валюты (3)
│   ├── units_server.py      # Единицы измерения (5)
│   ├── holidays_server.py   # Праздники (4)
│   └── color_server.py      # Цвет (6)
├── examples/
│   └── terminal_chat.py     # Пример клиента: терминальный AI-ассистент
├── tests/
│   └── unit/                # По одному файлу тестов на каждый модуль выше + test_gateway.py
├── screenshots/             # Скриншоты работы (пример-чат)
├── .github/workflows/
│   └── ci.yml               # CI/CD: ruff + pytest + mypy + docker build
├── workspace/                # Рабочая директория (файлы, БД)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── Makefile
├── LICENSE
├── README.md
└── README.en.md

---

🧪 Тестирование и качество кода

make test         # pytest с покрытием (325+ тестов)
make lint         # ruff check + format check
make type-check   # mypy strict mode
make docker-build # сборка Docker-образа

CI/CD: GitHub Actions автоматически проверяет каждый PR и push в master:

• ✅ Ruff — линтер
• ✅ Pytest — юнит-тесты с coverage
• ✅ Mypy — строгая типизация
• ✅ Docker build — образ должен собираться

---

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

---

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

Вызов инструмента напрямую (MCP-клиент)

После подключения к http://localhost:8000/mcp инструменты доступны под именами _, например weather_get_weather, currency_convert_currency, qr_generate_qr_code — так, как они появляются в списке tools/list.

Через пример-чат на естественном языке (examples/terminal_chat.py)

# Файлы
"покажи содержимое корневой папки workspace"
"найди все Python файлы в src/"
"создай файл notes.md с текстом ..."

# GitHub
"покажи список моих репозиториев на GitHub"
"создай issue в user/repo с заголовком 'Баг'"
"создай PR из ветки feature в main"

# Google Sheets
"создай таблицу 'Мои заметки'"
"запиши в  в ячейку A1 значение 'Привет'"
"прочитай таблицу "

---

🔮 Планы развития

• [x] Dockerized MCP-сервер с выбором доменов инструментов (MCP_SERVERS)
• [ ] Публикация образа в GitHub Container Registry при релизных тегах
• [ ] MCP-сервер для Telegram (отправка сообщений)
• [ ] MCP-сервер для работы с браузером (Playwright)
• [ ] RAG (Retrieval-Augmented Generation) для работы с документами

---

📄 Лицензия

MIT — используйте, модифицируйте, распространяйте.

---

👤 Автор

Artem Kornilov — GitHub