itstep-mystat-mcp 0.1.1__tar.gz

itstep_mystat_mcp-0.1.1/.env.example

@@ -0,0 +1,14 @@
+MYSTAT_LOGIN=your_login
+MYSTAT_PASSWORD=your_password
+
+MYSTAT_BASE_URL=https://mapi.itstep.org/v1/mystat
+MYSTAT_LANGUAGE=uk
+MYSTAT_STATUS_FILTER=3
+MYSTAT_SORT=-hw.time
+
+CACHE_DIR=./cache
+DATABASE_PATH=./cache/mystat.db
+
+SYNC_LIMIT=1000
+HTTP_TIMEOUT=30
+MAX_ATTACHMENT_SIZE_MB=100

itstep_mystat_mcp-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: publish
+
+# Trusted Publishing (OIDC): no API token is stored in the repository.
+# PyPI must be configured with:
+#   owner      = stealbe
+#   repository = itstep-mystat-mcp
+#   workflow   = publish.yml
+#   environment= pypi
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - name: Build
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Must match the "Environment name" of the pending publisher on PyPI.
+    environment: pypi
+    permissions:
+      # Required for OIDC: without this the action cannot obtain a token.
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

itstep_mystat_mcp-0.1.1/.gitignore

@@ -0,0 +1,48 @@
+# ---- secrets -------------------------------------------------------------
+.env
+.env.*
+!.env.example
+.token
+.token.*
+
+# ---- local state and caches ---------------------------------------------
+cache/
+logs/
+*.log
+*.db
+*.db-wal
+*.db-shm
+*.part
+
+# ---- python --------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# ---- virtual environments ------------------------------------------------
+.venv/
+.venv*/
+venv/
+
+# ---- editors and OS ------------------------------------------------------
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ---- leftovers -----------------------------------------------------------
+uv.lock.bak
+.tmp-*/
+
+# ---- local test suite (kept on disk, not versioned) ----------------------
+tests/

itstep_mystat_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.5
+Name: itstep-mystat-mcp
+Version: 0.1.1
+Summary: Local MCP server exposing ITStep MyStat homework (list, details, attachments, search)
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pillow>=10.0
+Requires-Dist: pypdf>=5.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: python-pptx>=1.0

itstep_mystat_mcp-0.1.1/README.md

@@ -0,0 +1,235 @@
+# itstep-mystat-mcp
+
+Локальный MCP-сервер (stdio) для доступа к домашним заданиям ITStep MyStat:
+синхронизация списка заданий, загрузка вложений, извлечение текста, поиск.
+
+Ставится одной командой `uv tool install`, настраивается мастером `setup`:
+логин и пароль вводятся в терминале, сервер сам прописывается в локальные
+клиенты (OpenCode, Claude Code, Claude Desktop, Codex).
+
+## Быстрый старт
+
+```powershell
+uv tool install itstep-mystat-mcp          # из индекса (когда опубликован)
+# или из локальной папки проекта:
+uv tool install .
+
+itstep-mystat-mcp setup                    # логин/пароль + авто-регистрация в клиентах
+```
+
+`setup` задаёт три вопроса (если значения не переданы флагами) и делает всё сам:
+
+1. спрашивает логин MyStat (`MYSTAT_LOGIN`);
+2. спрашивает пароль (ввод скрыт, просит повторить);
+3. проверяет пару реальным `POST /auth/login`;
+4. пишет конфиг в `%APPDATA%\itstep-mystat-mcp\.env`;
+5. регистрирует MCP-сервер в найденных клиентах.
+
+После этого достаточно перезапустить клиент.
+
+## Что умеет
+
+| Инструмент | Назначение |
+|---|---|
+| `mystat_login` | принудительный login, замена сохранённого токена |
+| `mystat_auth_status` | есть ли токен, когда получен, известен ли срок (токен не раскрывается) |
+| `mystat_logout` | удалить токен из локального кеша |
+| `homework_sync` | синхронизация списка + деталей + вложений |
+| `homework_list` | список заданий из кеша (краткие сведения) |
+| `homework_get` | одно задание: текст, вложения, статусы |
+| `homework_search` | полнотекстовый поиск (FTS5) |
+| `homework_read_file` | чтение вложения или извлечённого текста |
+| `homework_cache_status` | статистика кеша |
+
+## Команды CLI
+
+```powershell
+itstep-mystat-mcp setup     # мастер настройки (логин/пароль + клиенты)
+itstep-mystat-mcp run       # MCP-сервер по stdio (это вызывают клиенты)
+itstep-mystat-mcp status    # пути конфига/кеша, наличие кредов, токен, размер кеша
+itstep-mystat-mcp sync      # разовая синхронизация из терминала
+itstep-mystat-mcp login     # принудительный login, токен в кеш
+itstep-mystat-mcp logout    # удалить токен
+```
+
+`itstep-mystat-mcp run` без аргументов — поведение по умолчанию (так его
+запускают MCP-клиенты).
+
+### Флаги `setup`
+
+| Флаг | Смысл |
+|---|---|
+| `--login <login>` | логин без интерактивного вопроса |
+| `--env-file <path>` | куда писать конфиг (по умолчанию `%APPDATA%\itstep-mystat-mcp\.env`) |
+| `--cache-dir <path>` | каталог кеша (по умолчанию рядом с конфигом) |
+| `--client auto\|all\|none\|<name>` | целевые клиенты; можно повторять. `auto` — найденные на машине (по умолчанию) |
+| `--verify` / `--no-verify` | проверять ли креды реальным login (по умолчанию проверяет) |
+| `-y`, `--yes` | не задавать вопросов: брать значения из флагов, `.env` или окружения |
+
+Пароль можно передать через переменную окружения `MYSTAT_PASSWORD` — тогда
+мастер не спрашивает его в интерактиве (удобно для скриптов и CI):
+
+```powershell
+$env:MYSTAT_PASSWORD = "..."      # останется в истории шелла — учитывайте это
+itstep-mystat-mcp setup --login my_login --client none --no-verify
+```
+
+### Куда ставится конфиг и клиенты
+
+| Клиент | Путь / способ |
+|---|---|
+| конфиг сервера | `%APPDATA%\itstep-mystat-mcp\.env` (кеш — `%APPDATA%\itstep-mystat-mcp\cache`) |
+| OpenCode | `~/.config/opencode/opencode.jsonc` (или `opencode.json`) |
+| Claude Code | `claude mcp add --scope user` (используется CLI, если он в `PATH`) |
+| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Codex | `~/.codex/config.toml` (`$CODEX_HOME` учитывается) |
+
+Перед изменением существующего файла создаётся резервная копия
+`<имя>.bak-YYYYMMDD-HHMMSS`. Если файл не парсится, он **не** перезаписывается —
+вместо этого выводится сниппет для ручной вставки.
+
+## Ручное подключение (если авто-регистрация не сработала)
+
+OpenCode, `~/.config/opencode/opencode.jsonc`:
+
+```jsonc
+"mcp": {
+  "itstep-mystat": {
+    "type": "local",
+    "command": ["C:\\Users\\<you>\\AppData\\Local\\uv\\tools\\itstep-mystat-mcp\\Scripts\\python.exe", "-m", "mystat"],
+    "environment": { "PYTHONUTF8": "1" },
+    "enabled": true,
+    "timeout": 180000
+  }
+}
+```
+
+Claude Desktop / общий JSON-формат:
+
+```json
+{
+  "mcpServers": {
+    "itstep-mystat": {
+      "command": "itstep-mystat-mcp",
+      "args": ["run"],
+      "env": { "PYTHONUTF8": "1" }
+    }
+  }
+}
+```
+
+Codex, `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.itstep-mystat]
+command = "itstep-mystat-mcp"
+args = ["run"]
+env = { PYTHONUTF8 = "1" }
+```
+
+Таймаут увеличен: первая синхронизация скачивает десятки файлов.
+
+## Разработка (из исходников)
+
+```powershell
+uv sync
+uv run python -m mystat status
+uv run python -m mystat sync --no-attachments
+```
+
+`python server.py` оставлен как тонкая обёртка над `mystat.server:main`.
+
+Сервер общается по stdio. `stdout` занят протоколом; все логи идут в `stderr`
+и в `cache/logs/mystat.log`.
+
+## Структура
+
+```text
+server.py              тонкая обёртка (совместимость)
+mystat/__main__.py     python -m mystat
+mystat/cli.py          setup / run / status / sync / login / logout
+mystat/clients.py      регистрация MCP в opencode, claude*, codex
+mystat/server.py       MCP-сервер (mcp 2.x MCPServer, stdio, 9 инструментов)
+mystat/config.py       .env, пути, лимиты
+mystat/cache.py        SQLite (WAL), миграции, FTS5
+mystat/auth.py         login / refresh / хранение токена
+mystat/api.py          единый HTTP-клиент, 401-recovery, ретраи
+mystat/homework.py     нормализация, sync, read model
+mystat/attachments.py  валидация URL, скачивание, имена, MIME
+mystat/extraction.py   PDF/DOCX/PPTX/XLSX/TXT/HTML
+mystat/search.py       безопасные FTS5-запросы
+docs/api-findings.md   подтверждённый контракт API
+scripts/               разведочные скрипты (не входят в поставку)
+```
+
+## Ключевые решения (по фактам API)
+
+- Токен — JWT, живёт 30 дней; `expires_at` берётся из `exp`.
+- `401` → `POST /auth/refresh` с текущим токеном; при неудаче — `POST /auth/login`.
+  Один повтор запроса, не более.
+- Текст задания есть **только** в `GET /od/homework/{id}` (`comment` в списке пуст).
+- Детали приходят объектом с ключом `"0"`, а не массивом — нормализатор
+  поддерживает оба варианта.
+- Имя файла — из `Content-Disposition` (`filename*`, UTF-8); MIME проверяется
+  по magic bytes; `ETag` у файлового хранилища недостоверен, поэтому изменения
+  определяются по SHA-256.
+- Скачиваются только `https://*.itstep.org/api/v1/files/...`; проверяется
+  разрешённый IP (private/loopback/link-local запрещены), размер ограничен,
+  редиректы проверяются.
+- ZIP не распаковывается, OCR не выполняется (первая версия).
+
+## Безопасность
+
+- Логин и пароль хранятся только в локальном конфиге, который не попадает
+  в репозиторий (`.env` в `.gitignore`).
+- Пароль никогда не выводится: `setup` читает его скрытым вводом, `status`
+  показывает только `configured` / `MISSING`.
+- Токен никогда не возвращается MCP-инструментами и не пишется в логи;
+  заголовок `Authorization` в лог не попадает.
+- Регистрация клиентов не удаляет чужие записи: изменяется только ключ
+  `itstep-mystat`.
+
+## Тесты
+
+Набор тестов есть локально, но не входит в репозиторий (см. `.gitignore`):
+
+```powershell
+.venv\Scripts\python.exe -m pytest -q
+```
+
+82 теста: авторизация и refresh, ретраи, нормализация, sync, пометка
+исчезнувших заданий, безопасность URL и имён, скачивание, FTS5, CLI,
+регистрация клиентов и кодирование значений `.env`. Тесты не ходят в сеть:
+`httpx.MockTransport` и обезличенные фикстуры в `tests/fixtures/`.
+
+## Формат `.env`
+
+`setup` пишет значение без кавычек, когда это безопасно (логин, Windows-пути),
+и в двойных кавычках с экранированием — когда внутри есть пробелы, `#`,
+кавычки или обрамляющие пробелы:
+
+```dotenv
+MYSTAT_LOGIN=student_login
+MYSTAT_PASSWORD="pa ss#1 \"x\""
+CACHE_DIR=C:\Users\you\AppData\Roaming\itstep-mystat-mcp\cache
+```
+
+Читается файл с `interpolate=False`: `python-dotenv` подставляет `${VAR}`
+даже внутри кавычек, и без этого пароль вида `${...}` молча превращался бы в
+пустую строку. После записи значения сверяются обратным чтением — при
+расхождении `setup` сообщает об ошибке, не печатая сами значения.
+
+`--cache-dir` всегда сохраняется абсолютным: MCP-клиент запускает сервер из
+произвольного рабочего каталога, относительный путь разрешился бы не там.
+
+## Ограничения
+
+- Первый запуск `homework_sync` требует действующих учётных данных
+  (мастер `setup` или `.env`).
+- Токен хранится в SQLite открытым текстом (как в ТЗ). Шифрование через
+  Windows DPAPI можно добавить отдельным этапом.
+- Если пароль не принимается, API отвечает одинаковым `401` и для неверного
+  пароля, и для несуществующего логина — поэтому «неверный пароль» и
+  «неизвестный логин» неразличимы.
+- Проектный `.env` в папке разработки имеет приоритет над
+  `%APPDATA%\itstep-mystat-mcp\.env`; `setup` предупреждает об этом.

itstep_mystat_mcp-0.1.1/docs/api-findings.md

@@ -0,0 +1,138 @@
+# MyStat API — подтверждённые факты (discovery)
+
+**Дата:** 12.11.2026
+**Источник:** реальные запросы к `https://mapi.itstep.org/v1/mystat` + JS-бандл веб-клиента `https://mystat.itstep.org/main-PTSNAXV7.js`.
+**Статус:** всё ниже — наблюдённые факты, кроме явно помеченных INFERENCE.
+
+Закрывает неизвестные из раздела 18 ТЗ.
+
+---
+
+## 1. Авторизация
+
+**`POST /auth/login`**
+
+```http
+Content-Type: application/json
+X-Language: uk
+
+{"login": "<login>", "password": "<password>"}
+```
+
+- `200` → тело **plain text JWT** (не JSON). `Content-Type: text/html; charset=UTF-8`, длина 604.
+- `401` → `Unauthorized: error_unauthorized` (одинаково для неверного логина и пароля).
+- `422` → `Validation error. The Password is required` (без пароля) / `validation_custom_email_required_without` (без логина).
+- Имена полей: только `login` + `password`. `username`, `email` не принимаются (`500`/`422`).
+- `X-Language`, `Origin`, `Referer`, `User-Agent`, `X-Userid` на результат **не влияют**.
+
+**JWT claims (payload):** `iss, iat, exp, nbf, jti, sub, id, id_user_storage, email, username, name, branch_id, project_id, lang, profile, module, branch_alias`.
+`exp - iat = 2 592 000 c` = **30 дней** → `expires_at` можно заполнять из токена без верификации подписи.
+
+**`POST /auth/refresh`** (в ТЗ помечен как неизвестный — теперь известно)
+
+```http
+Authorization: Bearer <access_token>
+Content-Type: application/json
+
+{}
+```
+
+- `200` → новый JWT тем же plain-text форматом. **Refresh token не нужен** — сам access token выступает основанием для refresh.
+- `401` без заголовка → `Unauthorized: Token is empty`.
+
+Веб-клиент после логина вызывает `/auth/me` (`accountService.getAccountForce$`), но для MCP-потока он не требуется: `list` и `homework/{id}` работают сразу с Bearer-токеном.
+
+---
+
+## 2. Список заданий
+
+**`GET /od/homework/list?sort=-hw.time&status=3&limit=1000`**
+
+Заголовки: `Authorization: Bearer <token>`, `X-Language: uk`. **`X-Userid` не требуется** (проверено: без него `200`).
+
+Форма ответа:
+
+```json
+{ "data": [ ... 60 элементов ... ], "_meta": { "currentPage": 1, "totalPages": 1, "totalCount": 60 } }
+```
+
+Поля элемента списка:
+
+| Поле | Тип | Пример / смысл |
+|---|---|---|
+| `id` | int | `502719` — ID задания |
+| `id_spec` | int | ID предмета |
+| `id_teach` | int | ID преподавателя |
+| `id_group` | int | ID группы |
+| `fio_teach` | str | ФИО преподавателя |
+| `theme` | str | тема задания |
+| `name_spec` | str | название предмета |
+| `comment` | str | **всегда пустой в списке** (см. п.3) |
+| `creation_time` / `completion_time` / `overdue_time` | str | `YYYY-MM-DD` |
+| `file_path` | str \| null | URL основного вложения |
+| `cover_image` | str \| null | URL картинки-обложки |
+| `status` | int | наблюдалось только `3` при фильтре `status=3` |
+| `homework_stud` | obj | данные сдачи: `id, file_path, mark, creation_time, stud_answer, auto_mark, status, photo_pas, fio_stud, related_homeworks, related_materials, unlock_expire, communication_history, is_retake` |
+| `homework_comment` | obj | `text_comment, attachment, attachment_path, date_updated` |
+| `is_autotest`, `autotest_status`, `autotest_result`, `ospr`, `default_deadline_days`, `coins_to_close_deadline`, `completion_days`, `is_academic_holiday` | mixed | служебные |
+
+Заголовков `X-Pagination-*` сервер **не отдаёт** — пагинация только через `_meta`.
+
+---
+
+## 3. Детали задания
+
+**`GET /od/homework/{id}`**
+
+Форма ответа — **не массив**, а объект с ключом-строкой `"0"`:
+
+```json
+{ "0": { ...поля задания... }, "relatedHomeworks": [ ... ] }
+```
+
+Парсер обязан корректно принимать: объект с ключом `"0"`, массив из одного элемента и (на всякий случай) одиночный объект.
+
+Поля внутри `"0"` совпадают с полями списка, **но `comment` здесь содержит реальный текст задания** (проверено на 10 заданиях: в списке пусто, в деталях 9–539 символов). Значит `homework_sync` обязан запрашивать детали — иначе текст задания теряется.
+
+`relatedHomeworks[]`: `id_domzadstud, id_teach, id_stud, status, time, id_domzad, ospr, mark, nlenta, date_vizit, is_retake, auto_test_status, auto_test_response, unlock_expire, moved_from_inactive_teacher, created_at, updated_at, domZad{ id_domzad, material_link, id_teach, id_tgroups, id_spec, time, id_schedule, nlenta, date, ospr, dz_theme, deadline, is_autotest, public_material_uuid, spec{...} }`.
+
+`updated_at` в `relatedHomeworks` — единственный кандидат на «время изменения», но относится к связанным сдачам, не к самому заданию. **Для самого задания поля изменения нет** → определение изменений по SHA-256 нормализованного JSON деталей (как в ТЗ).
+
+---
+
+## 4. Вложения
+
+В JSON **нет** имени, MIME и размера файла — только URL.
+
+| Поле | Смысл |
+|---|---|
+| `file_path` | основное вложение задания (есть у 53 из 60 заданий) |
+| `cover_image` | картинка-обложка задания (не вложение) |
+| `homework_stud.file_path` | файл, загруженный студентом (в наблюдённых данных `null`) |
+| `homework_comment.attachment` / `attachment_path` | вложение к комментарию преподавателя |
+
+Наблюдённые домены: `fs1.itstep.org`, `fs3.itstep.org`, `fsx1.itstep.org`.
+Шаблон пути: `/api/v1/files/<opaque-token>`.
+
+Скачивание **открытое, без авторизации**:
+
+- `200`, `access-control-allow-origin: *`, `server: nginx`;
+- `Content-Disposition: attachment; filename="DZ_2026_11_09.pdf"; filename*=utf-8''ДЗ_2026_11_09.pdf` → отсюда берём исходное имя (декодировать `filename*` по RFC 5987);
+- `Content-Type` и `Content-Length` корректны (проверено: `application/pdf`, `...wordprocessingml.document`, `video/mp4`, `image/png`, `text/html`);
+- `Last-Modified` присутствует не всегда;
+- **`ETag` непригоден**: у разных файлов одинаковый sha1 пустой строки. Условные запросы по ETag использовать нельзя → только SHA-256 содержимого.
+
+Вложение может быть **HTML-документом** (сгенерированная страница задания `Домашнє_завдання_...html`) — извлечение текста обязано это поддерживать.
+
+---
+
+## 5. Следствия для реализации
+
+1. Токен хранить как plain text JWT + `expires_at` из `exp` (30 дней).
+2. На `401`: сначала `POST /auth/refresh` с Bearer, при неудаче — `POST /auth/login`; один повтор исходного запроса.
+3. `homework_sync` всегда тянет `homework/{id}` (в списке нет текста задания).
+4. Allowlist файлов: HTTPS + host заканчивается на `.itstep.org` + path начинается с `/api/v1/files/`.
+5. Имя файла: `Content-Disposition` → `filename*` (UTF-8) → `filename` → имя из URL → `attachment_<n>`.
+6. MIME: доверять `Content-Type`, но проверять magic bytes (PK\x03\x04, %PDF, \x89PNG, ftyp, <!DOCTYPE).
+7. Change detection: SHA-256 нормализованного JSON деталей и SHA-256 содержимого файла; ETag игнорировать.
+8. `status=3` — единственное наблюдённое значение; вынести в конфиг.

itstep_mystat_mcp-0.1.1/mystat/__init__.py

@@ -0,0 +1,3 @@
+"""itstep-mystat-mcp --- MyStat homework access for MCP clients."""
+
+__version__ = "0.1.0"

itstep_mystat_mcp-0.1.1/mystat/__main__.py

@@ -0,0 +1,10 @@
+"""Allows ``python -m mystat`` (used by MCP client configs)."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())