Skip to main content
Glama
README.md
# mcp-guap

MCP-сервер для личного кабинета ГУАП ([pro.guap.ru](https://pro.guap.ru)).
Позволяет ИИ-агентам (Claude и другим) работать с заданиями, материалами и отчётами студента.

## Что умеет

### MCP Mode (для ИИ-ассистентов)

| Инструмент | Описание |
|---|---|
| `authenticate` | 🔐 Авторизация через браузер (открывает окно, ждёт входа, сохраняет cookies) |
| `check_auth_status` | Проверить, валидны ли сохранённые cookies |
| `list_tasks` | Список всех заданий текущего семестра (дедлайны, баллы, статусы) |
| `get_task` | Детали задания: описание, доп. материалы, сданные отчёты |
| `list_materials` | Учебные материалы семестра (файлы и внешние ссылки) |
| `download_material` | Скачать учебный материал (с pro.guap.ru, Google Drive или любой ссылке) |
| `submit_report` | Загрузить файл отчёта к заданию |
| `get_my_profile` | Профиль студента: ФИО, группа, номер зачётки |
| `get_teacher_info` | Информация о преподавателе |
| `get_subject_info` | Информация о дисциплине |
| `get_my_group_order` | Порядковый номер в группе |

### CLI Mode (автономный терминал)

| Команда | Описание |
|---|---|
| `guap pro auth` | 🔐 Авторизация через браузер |
| `guap pro check` | Проверить авторизацию |
| `guap pro tasks` | Список заданий с фильтрами |
| `guap pro task <id>` | Детали задания |
| `guap pro materials` | Учебные материалы |
| `guap pro profile` | Профиль студента |
| `guap skill` | Установить Agent Skill в `agents/skills/` |

## Требования

- [uv](https://docs.astral.sh/uv/getting-started/installation/) — менеджер пакетов Python
- [Claude Desktop](https://claude.ai/download) (или любой другой MCP-клиент)
- Аккаунт ГУАП на [pro.guap.ru](https://pro.guap.ru)

## Установка

Клонировать репозиторий не нужно — достаточно `uv`.

### Вариант 1: Автоматическая авторизация (рекомендуется)

**1. Установить Playwright browsers**

При первом запуске автоматической авторизации, Claude установит необходимые браузеры автоматически. Это может занять 1-2 минуты.

Или установите вручную:
```bash
uvx playwright install chromium
```

**2. Добавить сервер в Claude Desktop**

Откройте файл конфигурации Claude Desktop:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

Добавьте секцию `mcpServers`:

```json
{
  "mcpServers": {
    "guap": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ehlvg/mcp-guap", "mcp-guap"]
    }
  }
}
```

**2. Перезапустить Claude Desktop**

**3. Выполнить авторизацию**

Просто скажите Claude:
> "Выполни авторизацию в ГУАП"

Claude откроет браузер, вам нужно будет ввести логин и пароль. Cookies сохранятся автоматически.

### Вариант 2: Ручная настройка (без браузера)

Если не хотите использовать автоматическую авторизацию:

1. Войдите в [pro.guap.ru](https://pro.guap.ru) в браузере
2. Откройте DevTools → вкладка **Network**
3. Обновите страницу, кликните на любой запрос к `pro.guap.ru`
4. В заголовках запроса найдите **Cookie** и скопируйте всё значение
5. Добавьте в конфигурацию Claude Desktop:

```json
{
  "mcpServers": {
    "guap": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ehlvg/mcp-guap", "mcp-guap"],
      "env": {
        "GUAP_COOKIE": "YOUR_COOKIE_STRING_HERE"
      }
    }
  }
}
```

> Куки живут несколько часов. Когда перестанет работать — выполните `authenticate` снова или обновите `GUAP_COOKIE`.

### Вариант 3: Agent Skill (для AI-агентов с поддержкой Agent Skills)

Если ваш AI-агент поддерживает [Agent Skills](https://agentskills.io/):

```bash
# Установить skill в agents/skills/
uvx --from git+https://github.com/ehlvg/mcp-guap guap skill

# Или в кастомную директорию
uvx --from git+https://github.com/ehlvg/mcp-guap guap skill --path ./my-agents/skills
```

Skill будет автоматически обнаружен агентом. Просто спросите:
> "Помоги мне с заданиями в ГУАП"

### Вариант 4: CLI режим (терминал)

Если предпочитаете работать в терминале:

```bash
# Использование
uvx --from git+https://github.com/ehlvg/mcp-guap guap pro auth
guap pro tasks
guap pro task 181395
guap pro materials
guap pro profile
```

#### Форматы вывода

Поддерживаются форматы `table` (по умолчанию), `json` и `csv`:

```bash
# JSON формат
guap pro tasks --format json
guap pro profile --format json
guap pro task 181395 --format json

# CSV формат
guap pro tasks --format csv > tasks.csv
guap pro materials --format csv > materials.csv
```

## Использование

### MCP режим

Просто общайтесь с Claude на естественном языке:

> «Покажи все мои задания»
> «Что нужно сдать по вычислительной математике?»
> «Загрузи файл ~/Documents/report.pdf как отчёт к заданию 181395»

## Запуск вручную (для отладки)

```bash
GUAP_COOKIE="..." uvx --from git+https://github.com/ehlvg/mcp-guap mcp-guap
```

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

```
mcp-guap/
├── mcp_guap/
│   ├── server.py        # MCP-сервер
│   ├── cli.py           # CLI инструмент (guap)
│   ├── auth.py          # Авторизация через браузер
│   ├── guap_client.py   # HTTP-клиент
│   └── skill/           # Agent Skill (agentskills.io)
│       ├── SKILL.md     # Skill metadata + instructions
│       ├── scripts/     # Helper scripts
│       └── references/  # Documentation
├── pyproject.toml       # Зависимости проекта
└── cookie.json          # Cookies (автосоздается)
```

TDQS

A4.3/5.0

Scored across 11 tools

Disambiguation5/5

Each tool targets a distinct resource and action: profile, teacher, subject, group order, task list, task detail, material list, authentication, download, submission, and auth check. Even related tools like get_my_profile and get_my_group_order are clearly separated by their specific purposes, with no overlap.

Naming Consistency5/5

All tool names follow the verb_noun pattern with snake_case (get_, list_, download_, submit_, check_, authenticate). The verbs are consistently used: 'list' for collections, 'get' for single items, and action verbs for operations. This provides a predictable and coherent naming scheme.

Tool Count5/5

With 11 tools, the set is well-scoped for a student portal. Each tool covers a necessary operation for managing tasks, materials, and submissions, without unnecessary duplication or bloat. The count falls squarely in the ideal range for a focused MCP server.

Completeness5/5

The tool surface covers the full student workflow: authentication, viewing profile, listing and viewing tasks, listing and downloading materials, submitting reports, and checking auth status. While minor gaps like a logout or listing all subjects exist, they are not essential for the core purpose and can be worked around. The lifecycle is complete for the domain.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues