# Stepik Courses Retrieval MCP

Read-only MCP-сервер: агент собирает учебный контекст из **started courses** Stepik (только **text steps**).

Сервер даёт тонкие GET-примитивы. Оркестрацию (decompose → select → fetch → gap-fill) держит host/skill, не один «толстый» tool.

Репозиторий: [https://github.com/lifefucky/mcp_read_stepik](https://github.com/lifefucky/mcp_read_stepik)

Нужен [uv](https://docs.astral.sh/uv/) в PATH (MCP стартует через `uvx`, Python 3.11+ подтянется сам). Skill ставится отдельно и **не** запускает Python-сервер.

## Установка в агент

Это git-marketplace репозитория, не official catalog (Cursor Marketplace / `claude-plugins-official` / `openai-curated`).

```text
# Cursor
/add-plugin https://github.com/lifefucky/mcp_read_stepik
# либо Customize → Plugins → Import marketplace → тот же URL, затем Install plugin stepik-courses

# Claude Code
/plugin marketplace add lifefucky/mcp_read_stepik
/plugin install stepik-courses@stepik-courses

# Codex
codex plugin marketplace add lifefucky/mcp_read_stepik

# OpenCode (только skill; MCP — в вашем opencode.json)
npx skills add lifefucky/mcp_read_stepik -a opencode

# fallback: skill во все обнаруженные агенты (без MCP)
npx skills add lifefucky/mcp_read_stepik
```

После установки plugin введите `CLIENT_ID` и `CLIENT_SECRET` в UI хоста (**Plugins → Configure** / MCP settings). Не правьте файлы проекта и не вставляйте секреты в чат.

## Учётные данные Stepik

Приложение OAuth, grant **client-credentials**. Создайте его так:

1. Откройте [https://stepik.org/oauth2/applications/](https://stepik.org/oauth2/applications/) — страница **«Ваши приложения»**.
2. Нажмите **«Новое приложение»**.
3. **Client type:** `confidential`.
4. **Authorization Grant Type:** `client-credentials`.
5. Остальные поля заполняются сами; сохраните приложение и скопируйте `CLIENT_ID` / `CLIENT_SECRET`.

Справка Stepik: [OAuth applications](https://help.stepik.org/article/64188).

## MCP одной командой

Пока пакет не на PyPI:

```bash
uvx --from git+https://github.com/lifefucky/mcp_read_stepik stepik-mcp
```

После публикации на PyPI: `uvx stepik-courses-mcp` (тот же entry point).

Транспорт v1: **stdio**. При старте preflight проверяет `/api/user-courses` и завершает процесс, если started courses недоступны.

Локальный FTS-индекс: user-dir (`%LOCALAPPDATA%/stepik-mcp/` или XDG `stepik-mcp/`) либо `STEPIK_INDEX_DB`. Fingerprint — `STEPIK_INDEX_IDENTITY` или hash `CLIENT_ID`, не bearer-токен.

## Host config

Креды задаются полями `env` в UI хоста (не JSON в git). Пример формы, которую хост сохраняет у себя:

```json
{
  "mcpServers": {
    "stepik-courses": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/lifefucky/mcp_read_stepik",
        "stepik-mcp"
      ],
      "env": {
        "CLIENT_ID": "${CLIENT_ID}",
        "CLIENT_SECRET": "${CLIENT_SECRET}"
      }
    }
  }
}
```

`${CLIENT_ID}` / `${CLIENT_SECRET}` — плейсхолдеры plugin variables, не shell `${env:...}`.

OpenCode: skill через `npx skills add lifefucky/mcp_read_stepik -a opencode`. MCP в **вашем** `opencode.json` (не в этом репозитории), те же `command` / `args` / `env`.

## Tools

| Tool | Назначение |
|------|------------|
| `list_started_courses` | started courses; fail-fast если пусто |
| `get_course_structure` | sections → units → lessons; только started |
| `get_lesson_steps_meta` | step id / position / type / `text_capable`; только started |
| `get_step_content` | text-only + metadata + `lesson_url`; только started |
| `refresh_search_index` | явное обновление локального FTS-индекса |
| `search_lessons` | weighted lexical search: `score` / `matched_fields` / `snippet` |

Рекомендуемый путь: `refresh_search_index` → `search_lessons` → `get_step_content`. Browse-fallback: `list_started_courses` → `get_course_structure` → `get_lesson_steps_meta` → `get_step_content`.

Resources: `stepik://course/{id}/outline`, `stepik://lesson/{id}/step/{position}`, `stepik://guide/retrieval`.  
Prompts: `gather_course_context`, `gap_fill_pass` (тонкие шаблоны; процедура в `skills/stepik-course-retrieval/SKILL.md`).

Ограничения v1: только started courses под текущими кредами; только text steps; course/lesson вне allowlist → отказ.

## Inspector и разработка из исходников

Inspector — для локального checkout (креды в env процесса или корневой `.env`; перечень имён — [`.env.example`](.env.example)):

```bash
HOST=127.0.0.1 npx @modelcontextprotocol/inspector@latest --web mcp_server/run_inspector.cmd
```

Launcher: [`mcp_server/run_inspector.cmd`](mcp_server/run_inspector.cmd) (`python -m mcp_server.server`, preflight отключён). На Windows, если `localhost` уходит в IPv6, задайте `$env:HOST="127.0.0.1"`.

Из исходников (не основной UX): `pip install -e .`, затем `stepik-mcp` или `python -m mcp_server.server`. Креды — env процесса (`CLIENT_ID` / `CLIENT_SECRET` или `STEPIK_*`), иначе fallback корневой `.env`.