🤖 MCP AI Assistant

Персональный AI-ассистент с MCP-архитектурой, способный управлять файлами, GitHub и Google Sheets через естественный язык.

🎯 Что это?

MCP AI Assistant — это терминальный AI-помощник, который не просто отвечает на вопросы, а совершает действия в реальном мире. Он умеет читать и писать файлы, управлять GitHub-репозиториями, создавать issues и pull requests, работать с Google Sheets — и всё это через обычный диалог.

Проект построен на Model Context Protocol (MCP) — открытом стандарте для подключения AI-моделей к внешним инструментам.

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

Пользователь → Терминал → LLM (DeepSeek) → MCP Server → Внешний сервис
                                                  ├── Файловая система
                                                  ├── GitHub API
                                                  └── Google Sheets API

1. Вы пишете запрос на естественном языке
2. LLM анализирует запрос и решает, какие инструменты нужны
3. MCP-сервер выполняет вызов API
4. Результат возвращается в диалог

🛠 Возможности (24 инструмента)

📁 Файловая система (4 инструмента)

• Чтение файлов — прочитать любой файл в рабочей директории
• Запись файлов — создать или перезаписать файл
• Просмотр директории — список файлов и папок
• Поиск по маске — рекурсивный поиск (например, *.py)
• 🔒 Sandbox-безопасность — нельзя выйти за пределы WORKSPACE_DIR

🐙 GitHub (17 инструментов)

• Репозитории: просмотр списка, детальная информация, создание новых
• Файлы: чтение, создание/обновление (с коммитом), просмотр директорий
• Issues: создание, просмотр списка, обновление (включая закрытие)
• Pull Requests: создание, просмотр списка, слияние (merge/squash/rebase)
• Ветки: просмотр списка, создание новых от любой существующей
• Коммиты: просмотр истории
• Поиск: поиск кода и репозиториев на GitHub

📊 Google Sheets (3 инструмента)

• Создание таблиц — новая таблица в вашем Google-аккаунте
• Чтение данных — любая таблица по ID, с указанием диапазона
• Запись данных — заполнение ячеек значениями
• 🔑 Авторизация через личный OAuth-токен (без сервисного аккаунта)

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

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

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

Требования

• Python 3.12+
• Yandex Cloud API ключ (для LLM)
• GitHub Personal Access Token
• Google OAuth Access Token (для Google Sheets)

Установка

git clone https://github.com/Artem-Kornilov-pro/mcp-ai-assistant.git
cd mcp-ai-assistant
make install

Настройка

cp .env.example .env
# Заполни .env своими ключами

Запуск

make run

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

mcp-ai-assistant/
├── src/
│   ├── __init__.py          # Пакет
│   ├── config.py            # Загрузка конфигурации из .env
│   ├── llm.py               # LLM-клиент (Yandex Cloud / OpenAI SDK)
│   ├── mcp_manager.py       # Менеджер MCP-инструментов
│   └── main.py              # Терминальный чат-интерфейс
├── servers/
│   ├── __init__.py
│   ├── filesystem.py        # MCP-сервер файловой системы
│   ├── github.py            # MCP-сервер GitHub (17 инструментов)
│   └── google_sheets.py     # MCP-сервер Google Sheets
├── tests/
│   ├── unit/
│   │   ├── test_llm.py
│   │   ├── test_cli.py
│   │   ├── test_filesystem.py
│   │   ├── test_github.py
│   │   └── test_google_sheets.py
├── docs/
│   └── screenshots/         # Скриншоты работы
├── .github/workflows/
│   └── ci.yml               # CI/CD: ruff + pytest + mypy
├── pyproject.toml
├── Makefile
└── README.md

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

make test        # pytest с покрытием (56+ тестов)
make lint        # ruff check + format check
make type-check  # mypy strict mode

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

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

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

| Категория | Технология | |-----------|-----------| | Язык | Python 3.12 | | LLM | Yandex Cloud / DeepSeek (OpenAI-совместимый API) | | MCP | FastMCP | | HTTP | httpx (асинхронный) | | Конфигурация | python-dotenv, Pydantic | | Тестирование | pytest, pytest-cov, pytest-asyncio | | Линтер | ruff | | Типизация | mypy (strict mode) | | CI/CD | GitHub Actions |

📋 Примеры запросов

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

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

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

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

• [ ] MCP-сервер для Telegram (отправка сообщений)
• [ ] MCP-сервер для работы с браузером (Playwright)
• [ ] Веб-интерфейс (FastAPI + WebSocket)
• [ ] Поддержка нескольких LLM-провайдеров (Ollama, Anthropic)
• [ ] RAG (Retrieval-Augmented Generation) для работы с документами
• [ ] Агентные цепочки (Agent Chains) для сложных сценариев

📄 Лицензия

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

👤 Автор

Artem Kornilov — GitHub