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

Нужен uv в PATH (MCP стартует через uvx, Python 3.11+ подтянется сам). Skill ставится отдельно и не запускает Python-сервер.

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

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

# 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/ — страница «Ваши приложения».
2. Нажмите «Новое приложение».
3. Client type: confidential.
4. Authorization Grant Type: client-credentials.
5. Остальные поля заполняются сами; сохраните приложение и скопируйте CLIENT_ID / CLIENT_SECRET.

Справка Stepik: OAuth applications.

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

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

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). Пример формы, которую хост сохраняет у себя:

{
  "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):

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

Launcher: 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.