Study Projects MCP

Локальный MCP-сервер для работы с каталогом учебных проектов. Он позволяет MCP-клиенту или ИИ-ассистенту искать работы, фильтровать их, получать статистику, добавлять новые проекты и контролировать готовность портфолио к публикации.

В каталоге находятся 24 реальные учебные работы по Python, API, базам данных, Telegram-ботам, AI, Docker, CI/CD и мониторингу. Данные были собраны, очищены от дублей и сверены с локальными проектами перед загрузкой в базу.

Практическая польза

Без такого каталога сведения о проектах находятся в разных папках, README и репозиториях. Study Projects MCP предоставляет единый интерфейс, через который можно, например:

• найти все проекты с Docker или SQLite;

• выбрать завершённые Telegram-боты для портфолио;

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

• увидеть наиболее часто используемые технологии;

• найти завершённые работы, которые ещё не опубликованы на GitHub;

• добавить новую работу и позже изменить её статус.

Сервер не использует внешние API, ключи и авторизацию. Все данные обрабатываются локально.

Related MCP server: mdgraph

Как устроен проект

Пользователь
    ↓ обычный запрос
MCP-хост или демонстрационный клиент
    ↓ вызов инструмента по протоколу MCP
Study Projects MCP
    ↓ чтение или изменение данных
SQLite

Исходный каталог хранится в study_projects_seed.json. При первом запуске сервер создаёт data/study_projects.db и загружает в неё 24 проекта. Повторный запуск не создаёт дубли и не перезаписывает уже существующую базу.

Данные каталога

Все исходные данные входят в репозиторий в файле study_projects_seed.json. SQLite-база не публикуется, потому что является автоматически создаваемой копией этих данных.

Полный терминальный пример работы человекочитаемого MCP-клиента сохранён в DEMO_CLIENT_EXAMPLE.md.

Девять MCP-инструментов

Человекочитаемая демонстрация

Интерактивный клиент вызывает те же MCP-инструменты, но показывает результаты в удобном виде вместо служебного JSON:

python demo_client.py

После запуска появится меню:

1 — показать проекты
2 — получить один проект
3 — найти проекты по тексту
4 — найти проекты по технологии
5 — добавить проект
6 — изменить статус проекта
7 — показать статистику
8 — показать технологии
9 — найти завершённые проекты без GitHub
0 — завершить работу

Например, в пункте 1 можно указать статус completed и категорию monitoring. Клиент вызовет list_projects и выведет:

Найдено проектов: 1

1. Loki_Grafana_test
   ID: 13
   Категория: monitoring
   Статус: завершён
   Технологии: Docker, Docker Compose, Loki, Grafana, HTTP API, Git, GitHub
   GitHub: https://github.com/Denis-Zag/Loki_Grafana_test.git

Пункты 5 и 6 изменяют рабочую базу. Остальные пункты безопасны для просмотра.

Установка

Требуется Python 3.10 или новее. Рекомендуемая и проверенная версия — Python 3.12.9. Python 3.9 и более ранние версии не поддерживаются используемой версией MCP SDK. На более новых версиях Python после установки следует запустить тесты.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

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

python -m mcp_server.server

Сервер использует официальный MCP Python SDK и транспорт stdio. Обычно его запускает MCP-хост, поэтому в терминале сервер ожидает протокольные команды и не показывает пользовательское меню.

Отдельная загрузка базы

python -m mcp_server.seed_loader

Команда создаёт базу при необходимости и показывает количество исходных, добавленных и сохранённых записей.

Автоматические тесты

python -m unittest discover -s tests -v

Тесты проверяют:

• структуру и уникальность 24 исходных записей;

• однократную загрузку данных без дублей;

• регистрацию всех девяти инструментов;

• вызов каждого инструмента через настоящий MCP-клиент;

• добавление проекта и изменение статуса во временной тестовой базе.

Ожидаемый итог:

Ran 3 tests
OK

Проверка через MCP Inspector

MCP Inspector нужен для технической проверки сервера независимым клиентом. Для него требуются Node.js и npx; для обычного запуска проекта они не нужны.

Получить список зарегистрированных инструментов:

npx.cmd --yes @modelcontextprotocol/inspector@latest --cli --config mcp.json --server study-projects --method tools/list

Выполнить инструмент статистики без параметров:

npx.cmd --yes @modelcontextprotocol/inspector@latest --cli --config mcp.json --server study-projects --method tools/call --tool-name get_project_statistics --tool-args-json "{}"

Вызвать list_projects с фильтрами из PowerShell:

npx.cmd --yes @modelcontextprotocol/inspector@latest --cli --config mcp.json --server study-projects --method tools/call --tool-name list_projects --tool-args-json '{\"status\":\"completed\",\"category\":\"monitoring\"}'

Успешный ответ содержит найденный проект и "isError": false. Inspector выводит служебный JSON, поэтому для наглядной работы предназначен demo_client.py.

Состав записи проекта

Каталог хранит не только название, но и:

• категорию и текущий статус;

• технологии и основные функции;

• ссылку на GitHub;

• дату завершения;

• результат и замечания преподавателя;

• подтверждения тестирования;

• уровень уверенности и неизвестные поля.

При добавлении данных проверяются обязательные поля, допустимые статусы, формат даты и уникальность названия.

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

Study_Projects_MCP/
├── mcp_server/
│   ├── __init__.py
│   ├── database.py          # схема SQLite и операции с данными
│   ├── seed_loader.py       # проверка JSON и начальная загрузка
│   └── server.py            # MCP-сервер и девять инструментов
├── tests/
│   ├── test_seed_loader.py
│   └── test_server.py
├── data/                    # локальная база создаётся автоматически
├── demo_client.py           # интерактивная MCP-демонстрация
├── DEMO_CLIENT_EXAMPLE.md   # полный пример работы клиента
├── mcp.json                 # конфигурация MCP Inspector
├── study_projects_seed.json # 24 проверенные записи
├── requirements.txt
└── README.md

Локальная SQLite-база, виртуальное окружение, кэш и внутренние рабочие материалы не включаются в репозиторий.

Результат

Проект представляет собой готовый локальный MCP-сервер с постоянным хранилищем, девятью инструментами, человекочитаемой демонстрацией и сквозными тестами через MCP-клиент. Текущее состояние: готов к публикации и подключению к совместимому MCP-хосту.