# Study Projects MCP

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

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

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

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

- найти все проекты с Docker или SQLite;
- выбрать завершённые Telegram-боты для портфолио;
- получить карточку проекта вместе с технологиями и результатами проверки;
- увидеть наиболее часто используемые технологии;
- найти завершённые работы, которые ещё не опубликованы на GitHub;
- добавить новую работу и позже изменить её статус.

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

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

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

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

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

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

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

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

| Инструмент | Назначение | Пример применения |
|---|---|---|
| `list_projects` | Выводит проекты с фильтрами по статусу и категории | Показать завершённые проекты по мониторингу |
| `get_project` | Возвращает полную карточку по ID или точному названию | Получить сведения о `Loki_Grafana_test` |
| `search_projects` | Ищет текст в названии, описании и ключевых функциях | Найти работы, в которых упоминается Grafana |
| `find_projects_by_technology` | Ищет по точному названию технологии без учёта регистра | Показать проекты с Docker |
| `add_project` | Проверяет и добавляет новую запись без дублей названий | Добавить очередную учебную работу |
| `update_project_status` | Меняет статус и при необходимости дату завершения | Перевести проект в состояние `completed` |
| `get_project_statistics` | Группирует проекты по статусам, категориям и технологиям | Получить общую картину портфолио |
| `list_technologies` | Показывает технологии и количество связанных проектов | Узнать, какие технологии используются чаще всего |
| `get_projects_without_github` | Находит завершённые работы без GitHub-ссылки | Составить список проектов для публикации |

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

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

```powershell
python demo_client.py
```

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

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

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

```text
Найдено проектов: 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 после установки следует запустить тесты.

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

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

```powershell
python -m mcp_server.server
```

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

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

```powershell
python -m mcp_server.seed_loader
```

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

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

```powershell
python -m unittest discover -s tests -v
```

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

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

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

```text
Ran 3 tests
OK
```

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

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

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

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

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

```powershell
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:

```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;
- дату завершения;
- результат и замечания преподавателя;
- подтверждения тестирования;
- уровень уверенности и неизвестные поля.

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

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

```text
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-хосту.