AI Student Developer Assistant — MCP Server

Сервер Model Context Protocol промышленного качества, который предоставляет ИИ-ассистенту унифицированный доступ к вашим задачам на GitHub, академическим дедлайнам (LMS) и персональному трекеру задач — чтобы он мог отвечать на вопросы вроде «Что мне нужно сделать сегодня?» реальным, приоритизированным ответом.

Создано на Python 3.12+, официальном MCP Python SDK (v2), разделении сервисов в стиле FastAPI, SQLite и httpx. Полностью протестировано с моками внешних API — для запуска набора тестов не требуются настоящие учетные данные.

Содержание

• Обзор проекта

• Возможности — инструменты MCP

• Архитектура

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

• Установка

• Настройка

• Запуск сервера

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

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

• Интеграция с API

• База данных

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

• Безопасность

• Ограничения

• Будущие улучшения

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

• Демонстрационный сценарий

• Темы для обсуждения на собеседовании

Обзор проекта

Проблема. Работа студента-разработчика сосредоточена в трёх несвязанных местах: задачи по коду на GitHub, задания и экзамены в университетской LMS и личные дела, разбросанные по заметкам. Приоритеты определяются по памяти, из-за этого что-то упускается.

Решение. Один MCP-сервер, который предоставляет все три источника в виде небольших, хорошо описанных, строго типизированных инструментов. ИИ-ассистент читает и анализирует их все одновременно: он может получить ваши назначенные issues, дедлайны на эту неделю, ожидающие задачи, обнаружить просроченные элементы, составить приоритизированную сводку — и изменять системы (создавать/закрывать issues, создавать задачи, массово импортировать дедлайны) через тот же интерфейс.

Статус. Это реализация личного инструмента продуктивности портфолио-качества. Всё работает от начала до конца; интеграция с LMS намеренно замокана за сменным интерфейсом (см. Ограничения).

Возможности — инструменты MCP

Пятнадцать узконаправленных инструментов. Каждый имеет понятное название, описание, которое ИИ читает, чтобы решить, когда его вызывать, проверенные входные данные и предсказуемый результат:

GitHub (4 инструмента)

LMS / академические дедлайны (3 инструмента)

Трекер задач (8 инструментов)

Все инструменты возвращают одинаковую JSON-структуру, чтобы агент мог надёжно анализировать результаты:

{ "ok": true,  "data": { "...": "..." }, "error": null }
{ "ok": false, "data": null, "error": { "code": "not_found", "message": "..." } }

Архитектура

flowchart TB
    subgraph Host["AI Client (e.g. Claude Desktop)"]
        Agent["Assistant / Agent"]
    end
    subgraph MCP["MCP Protocol (stdio)"]
        S["MCPServer (mcp SDK v2)"]
    end
    subgraph App["app/"]
        Tools["tools/ · 15 thin tool functions"]
        Services["services/ · GitHub · LMS · Task"]
        Repo["TaskRepository"]
        DB[("SQLite")]
        Mock["MockLMSService"]
    end
    Ext["GitHub REST API v3"]
    Agent -->|tools/list · tools/call · server/discover| S
    S --> Tools
    Tools --> Services --> Repo --> DB
    Services --> Ext
    Services --> Mock

Золотое правило в этой кодовой базе: слой MCP — это только адаптеры. Каждая функция инструмента проверяет входные данные через свою сигнатуру типов, вызывает сервис и возвращает результат. Никакой бизнес-логики в функциях инструментов нет.

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

Установка

Требования: Python 3.12+ и git. (MCP SDK сам требует ≥3.10; этот проект нацелен на 3.12.)

Windows (PowerShell)

cd "C:\Users\ASUS\mcp project"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Если Activate.ps1 заблокирован политикой выполнения:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

macOS / Linux

cd mcp-project
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Настройка

Скопируйте файл-заполнитель и заполните свои значения:

cp .env.example .env     # Windows:  copy .env.example .env

Создание токена GitHub → GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token → выберите только нужные репозитории → предоставьте только Issues: Read and Write.

⚠️ .env добавлен в .gitignore. Никогда не коммитьте его. .env.example содержит только заполнители.

Запуск сервера

1. Инициализация базы данных и заполнение демо-данными

python -m scripts.seed_demo

Эта команда создаёт data/tasks.db и вставляет несколько реалистичных демо-задач (одна намеренно просрочена).

2. Запуск MCP-сервера

python -m app.server

Сервер запускается через stdio (по умолчанию для настольных MCP-клиентов) и продолжает работу до остановки.

Разработка и отладка

SDK включает CLI и интерактивный инспектор:

mcp dev app/server.py        # launch + open the MCP Inspector in a browser
mcp run app/server.py        # run the server (same behavior as python -m app.server)

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

Локальные MCP-серверы работают через stdio: ИИ-клиент запускает процесс вашего сервера и общается с ним через stdin/stdout. Формат конфигурации находится в блоке mcpServers клиента.

Claude Desktop (Windows)

Отредактируйте %APPDATA%\Claude\claude_desktop_config.json (откройте через Settings → Developer → Edit Config), полностью закройте и перезапустите:

{
  "mcpServers": {
    "ai-student-assistant": {
      "command": "C:\\Users\\ASUS\\mcp project\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\ASUS\\mcp project\\app\\server.py"]
    }
  }
}

Требования:

• Абсолютные пути — Claude Desktop не наследует ваши PATH или рабочую директорию.

• Используйте where python / where git, чтобы определить точный путь к интерпретатору.

• После сохранения полностью перезапустите Claude Desktop, затем найдите сервер и его инструменты в меню коннекторов/сообщений.

• Логи при сбое: %APPDATA%\Claude\logs\mcp*.log.

Альтернативы

• MCP Inspector (без конфигурации): mcp dev app/server.py предоставляет графический интерфейс для вызова каждого инструмента вручную — идеально для демонстраций.

• Cursor — .cursor/mcp.json использует ту же структуру mcpServers.

• Сервер не привязан к транспорту: тот же MCPServer можно впоследствии обслуживать через Streamable HTTP (см. Будущие улучшения).

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

Пользователь: Какие issues на GitHub сейчас открыты?

Агент вызывает get_open_issues (без репозитория → issues, назначенные вам), затем обобщает:

У вас 2 открытых issues: «Исправить ошибку входа» (#1, bug) и «Добавить CI-пайплайн» (#2).

Пользователь: Какие задания должны быть сданы в ближайшие 7 дней?

Агент вызывает get_upcoming_deadlines с start/end, вычисленными от сегодняшней даты:

На этой неделе: Тест 3 (Математика, 12 авг.), Черновик проектного предложения (ENG101, 11 авг.), Задание по обходу графов (CS101, 13 авг.).

Пользователь: Создай задачи для этих заданий.

Агент вызывает create_tasks_from_deadlines (сервер уже учитывает дедупликацию по source/source_id, поэтому повторный запуск не создаёт дубликатов):

Создано 3 задачи. Пропущено 0 (нет дубликатов).

Пользователь: Над какими задачами мне работать в первую очередь?

Агент вызывает get_workload_summary и get_overdue_tasks, затем анализирует приоритеты и сроки:

Сначала: «Исправить нестабильный тест в CI-пайплайне» (ПРОСРОЧЕНО, высокий). Затем: Черновик проектного предложения (срок завтра), Викторина 3 (срок через 2 дня)...

Интеграция API

GitHub

• Эндпоинты: GET /issues (назначенные вам), GET|POST /repos/{owner}/{repo}/issues, GET|PATCH /repos/{owner}/{repo}/issues/{number}.

• Аутентификация: Authorization: Bearer <GITHUB_TOKEN>. Анонимный доступ разрешён для публичных репозиториев; при 401 возвращается понятная ошибка «требуется аутентификация».

• Лимиты запросов: 403 с x-ratelimit-remaining: 0 и 429 преобразуются в ошибку rate_limited.

• Pull requests: эндпоинт issues также возвращает PR; они отфильтровываются по ключу pull_request.

• Все состояния сети/таймаута/ошибок преобразуются в доменные исключения (см. Безопасность).

LMS

Для этого проекта не предполагалось наличие легитимного/доступного API колледжеской LMS, поэтому LMS реализована через небольшой интерфейс (LMSService) с реалистичной моковой реализацией (MockLMSService), которая:

• заполняет каталог курсов сроками относительно сегодняшней даты,

• проверяет курсы (неизвестный курс → not_found),

• проверяет даты и диапазоны (некорректный ввод → invalid_input).

Добавление реального провайдера позже = реализовать тот же интерфейс + установить LMS_PROVIDER=real. Никакие защищённые страницы не парсились; аутентификация не обходится. Мок ведёт себя как реальный сервис, поэтому остальная часть приложения тестируется без изменений.

База данных

Файл SQLite по пути DATABASE_PATH (по умолчанию data/tasks.db), одна таблица в MVP:

CREATE TABLE tasks (
    id          INTEGER PRIMARY KEY AUTOINCREMENT,
    title       TEXT    NOT NULL,
    description TEXT,
    status      TEXT    NOT NULL DEFAULT 'pending'
                    CHECK (status IN ('pending','completed')),
    priority    TEXT    NOT NULL DEFAULT 'medium'
                    CHECK (priority IN ('low','medium','high','urgent')),
    due_date    TEXT,                      -- ISO-8601 (date or timestamp)
    source      TEXT,                      -- 'github' | 'lms' | NULL
    source_id   TEXT,                      -- e.g. GitHub issue number
    source_url  TEXT,
    created_at  TEXT NOT NULL,
    updated_at  TEXT NOT NULL
);

CREATE INDEX idx_tasks_status    ON tasks(status);
CREATE INDEX idx_tasks_due_date  ON tasks(due_date);
CREATE INDEX idx_tasks_priority  ON tasks(priority, due_date);

CREATE UNIQUE INDEX uq_tasks_source ON tasks(source, source_id)
    WHERE source IS NOT NULL AND source_id IS NOT NULL;

Почему каждое решение имеет значение:

• Частичный уникальный индекс на (source, source_id) — SQLite считает NULL-значения различными в обычном UNIQUE, что позволило бы дубликатам импорта проскальзывать и запретило бы несколько «личных» (без source) задач. Частичный индекс с WHERE source IS NOT NULL делает импорт идемпотентным на уровне базы данных, где это и должно быть. Именно это делает create_task_from_issue / create_tasks_from_deadlines безопасными для многократного вызова.

• status/priority как TEXT + CHECK — в SQLite нет перечислений; CHECK обеспечивает целостность, а Python enum.Enum отражают значения для типобезопасности.

• ISO-8601 временные метки UTC как сортируемые строки — лексикографический порядок == хронологический порядок, без неоднозначности часовых поясов, удобно для JSON.

• source + source_id + source_url сохраняют происхождение, чтобы задачу всегда можно было отследить до исходного issue или задания.

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

pytest          # runs the whole suite: mocked GitHub, mock LMS, SQLite tasks, MCP client

Область (tests/):

Инструменты MCP тестируются через реальное соединение по протоколу с использованием in-memory клиента SDK (async with Client(server)) — тот же паттерн, что и TestClient у FastAPI. Никаких подпроцессов, портов или учётных данных.

Безопасность

• Секреты хранятся только в переменных окружения (.env игнорируется git; .env.example содержит заполнители).

• Минимальные привилегии: детализированный PAT GitHub с ограничением Чтение и Запись для Issues на конкретных репозиториях — никогда не полная область repo.

• Без логирования секретов: фильтр редактирования очищает значения Authorization из логов; а поскольку сервер ничего не выводит в stdout (логирование идёт в stderr), поток stdio-протокола остаётся чистым.

• Валидация входных данных: Pydantic на границе инструментов + доменная валидация в сервисах.

• Параметризованные SQL-запросы через SQLAlchemy — никаких строковых запросов.

• Контролируемое раскрытие ошибок: ИИ получает структурированные ошибки (code, message); сырые стектрейсы попадают только в логи сервера.

• Минимальное раскрытие клиенту: токен из .env читается процессом сервера, а не передаётся через конфигурацию клиента.

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

Ограничения

Честные оговорки, намеренно:

• LMS замокана. LMS_PROVIDER=mock — единственный провайдер. Необходимо добавить реальный адаптер API, экспортированный календарь или другой авторизованный источник данных для замены (взаимозаменяемо, через интерфейс LMSService).

• SQLite однопользовательский. Нет гарантий конкурентности, сетевого доступа, репликации бэкенда. Преднамеренно для личного ассистента.

• Пока нет OAuth / HTTP-транспорта. Токен GitHub — статический секрет; сервер работает через stdio. Подходит для локального личного использования; удалённое/хостированное использование потребует OAuth и Streamable HTTP.

• Создание issue не поддерживает назначение или явное указание markdown в теле — оставлено намеренно небольшим.

• Одночасовая гранулярность сроков — без преобразования часовых поясов; даты сравниваются в форме ISO-8601, предоставленной пользователем.

• Импорты описывают изменяемые исходные элементы как снимки: если issue GitHub впоследствии редактируется, уже созданная задача не обновляется (это спроектированное поведение, а не ошибка).

Будущие улучшения

• Реальный адаптер LMSService (официальный API или экспорт календаря .ics)

• Интеграция с Google Calendar для сроков

• Уведомления Slack/Teams о просроченных задачах

• Бэкенд PostgreSQL (репозиторий уже абстрагирован)

• OAuth для GitHub + Streamable HTTP транспорт + развёртывание в Docker

• Таблица истории/аудита задач; обновления issue синхронизируются с задачами

• Более богатые рабочие процессы агента (авто-триаж, еженедельный отчёт «стендап»)

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

Слои, в порядке зависимостей:

app/tools       MCP adapters — type-hinted params, docstrings as descriptions, guard() → {ok, data, error}
app/services    GitHubService · LMSService (mock) · TaskService — business logic + cross-service workflows
app/database    Database (engine/session) · TaskRepository (all SQL)
app/models      SQLAlchemy ORM (Task) · Pydantic schemas (TaskCreate/Out, GitHubIssue, Deadline)
app/config.py   validated env config
app/exceptions  domain error hierarchy → AI-readable codes

Внедрение зависимостей: app/server.py — корень композиции: он строит config → база данных → сервисы → MCPServer и регистрирует функции-инструменты с необходимыми им сервисами. Ничего не является глобальным; тесты собирают тот же граф с подделками.

Поток ошибок: инструмент → сервис → репозиторий/API выбрасывает StudentAssistantError → guard() возвращает {ok: false, error: {code, message}}. Неожиданные исключения логируются (stderr) и возвращаются как общее сообщение internal_error.

Демо-сценарий

1. Создайте детализированный токен GitHub и установите GITHUB_TOKEN в вашем .env.

2. Заполните базу задач: python -m scripts.seed_demo (создаёт несколько задач, одну просроченную).

3. Запустите сервер: python -m app.server (или mcp dev app/server.py для запуска Inspector).

4. Подключите Claude Desktop / Inspector к серверу.

5. Спросите: «Что мне нужно сделать на этой неделе?» → агент вызывает get_workload_summary, объединяет открытые issues GitHub + предстоящие сроки + ожидающие/просроченные задачи и даёт ответ с приоритетами.

6. Спросите: «Создай задачи для всех заданий со сроками на этой неделе.» → агент вызывает create_tasks_from_deadlines.

7. Проверьте в базе данных:

   sqlite3 data/tasks.db "SELECT title, due_date, source FROM tasks ORDER BY due_date;"

   → новые строки появляются с source = 'lms', по одной на каждый срок. Повторите тот же вопрос — инструмент сообщит skipped вместо дублирования.

Вопросы для собеседования

Будьте готовы защищать эти решения:

1. Почему MCP? Это стандартизированный протокол, поэтому один сервер работает с любым AI-клиентом; инструменты обнаруживаются (tools/list), вызываются (tools/call) и описываются модели — именование и описания — это UX-контракт для LLM.

2. Почему текущий MCP SDK v2? SDK переименовал FastMCP → MCPServer и теперь обслуживает обе версии протокола (2025 и 2026-07-28) из одного процесса; pip install mcp устанавливает v2. Строить на поддерживаемой ветке (а не на v1 с обслуживанием) — обоснованный выбор.

3. Тонкий слой MCP / сервисный слой. Функции-инструменты — это адаптеры; логика живёт в сервисах за интерфейсами. Именно это делает GitHub, LMS и задачи подключаемыми и тестируемыми без сети.

4. Частичный уникальный индекс для идемпотентности. Объясните, почему SQLite нужен частичный индекс для (source, source_id) и как он делает create_task_from_issue/create_tasks_from_deadlines безопасными — как небольшая, обоснованная демонстрация глубины знаний SQL.

5. Неоднозначность 403 в GitHub. Запрещено vs. ограничение по лимиту различается через заголовок ответа x-ratelimit-remaining — реальная тонкость интеграции API, а не фольклор.

6. Токены с минимальными привилегиями. Детализированный PAT с только Issues: Read & Write против классического токена с областью repo. Знайте «почему» наизусть.

7. Таксономия ошибок. Одна иерархия исключений, отображаемая на стабильные AI-читаемые коды, с стектрейсами, ограниченными логами. Надёжность — это цель проектирования, а не запоздалая мысль.

8. Тестирование протокольного слоя. In-memory Client(server) означает, что проводка MCP тестируется именно так, как её использует клиент.

9. Честное определение области. LMS явно замокана; SQLite однопользовательский — «личный инструмент продуктивности», а не заявка на корпоративный многопользовательский продукт.

Лицензия

MIT — см. LICENSE. Copyright (c) 2026 Mahendra Vattikuti.