arthur-s · Sep 30, 2026 · Sep 29, 2026 · Sep 29, 2026 · Sep 29, 2026 · Sep 30, 2026
diff --git a/README.md b/README.md
@@ -42,25 +42,27 @@ Download the starter project for your current practicum:
 softpractice starter
 ```
 
-Open the created directory and check the current lesson:
+Open the created directory, check the project state, and read the assignment:
 
 ```bash
 cd <project-directory>
 softpractice status
+softpractice task
+softpractice material
 ```
 
 Work on the project and commit your changes with Git. When the solution is
-ready, submit the current commit:
+ready, submit the current commit and wait for the result:
 
 ```bash
-softpractice submit
+softpractice submit --wait
 ```
 
-Check the submission and open its result:
+Read the result again at any time, or open it in the browser:
 
 ```bash
-softpractice submission show
-softpractice open
+softpractice result
+softpractice open result
 ```
 
 After an accepted solution, apply the transition to the next available lesson:
@@ -69,18 +71,25 @@ After an accepted solution, apply the transition to the next available lesson:
 softpractice update
 ```
 
+`softpractice status` always ends with the next step.
+
 ## Common commands
 
 | Command | Description |
 | --- | --- |
 | `softpractice login` | Sign in through the browser |
 | `softpractice starter` | Download the first lesson project |
-| `softpractice status` | Show the current lesson and local project state |
+| `softpractice status` | Show the project state and the next step |
+| `softpractice task` | Show the assignment |
+| `softpractice material` | Show the theory material; `--lesson ID` for another lesson |
+| `softpractice hint` | Show the hints you have opened; the next one is opened on the assignment page |
 | `softpractice check` | Run public checks against the current working tree |
-| `softpractice submit` | Submit the current committed Git revision |
-| `softpractice submission show` | Show the latest submission and review result |
+| `softpractice submit` | Submit the current committed Git revision; `--wait` waits for the result |
+| `softpractice result` | Show the evaluation result; `--wait` waits for it, `--directions` adds the reviewer's recommendations |
+| `softpractice submissions` | Show the recent submissions of the lesson |
 | `softpractice update` | Apply the transition to the next lesson, or move to a newer version of the current lesson (replaces only lesson files, never yours; optional until the lesson ends) |
-| `softpractice open` | Open the workspace or latest result in the browser |
+| `softpractice open` | Open the task, material, or latest result in the browser |
+| `softpractice mcp` | Run the MCP server for Claude Code, Codex, Claude Desktop, and other agents |
 | `softpractice project restore` | Restore a project from the latest usable revision |
 
 Run `softpractice help <command>` for detailed help.
@@ -108,6 +117,112 @@ softpractice set auto-checks true
 run. Unlike `softpractice check`, submission checks require a clean working
 tree and run in an isolated snapshot of `HEAD`.
 
+## Reviewer questions
+
+When the reviewer asks questions about your solution, `softpractice result`
+and `softpractice status` say so and give the link to the result page, where
+you answer them.
+
+## Machine-readable output
+
+`status`, `task`, `material`, `hint`, `result`, `submissions`, and `submit`
+accept `--json`. Each document has a `kind`; on an error the command prints a
+`softpractice.error` document, also for an invalid command line (code
+`usage`) and for a declined `submit` confirmation (code `declined`).
+
+```bash
+softpractice result --wait --timeout 10m --json
+```
+
+Exit codes: `0` done, `1` error, `2` invalid arguments, `3` the evaluation is
+not ready yet, `4` the evaluation was superseded and will have no result.
+
+## MCP server
+
+`softpractice mcp` is a local MCP server on stdio. It lets Claude Code, Codex,
+Claude Desktop, and other MCP clients work through the lesson with you, using
+the same operations as the commands above. Sign in first with
+`softpractice login`: the server never starts a sign-in itself.
+
+The server works on the lesson project in the directory the client starts it
+in. When the client starts it elsewhere, as Claude Desktop does, pass the
+project folder with `--project`.
+
+**Claude Code**, from the project folder:
+
+```bash
+claude mcp add softpractice -- softpractice mcp
+```
+
+**Codex**, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.softpractice]
+command = "softpractice"
+args = ["mcp"]
+# Allow result and submit to wait for an evaluation.
+tool_timeout_sec = 180
+```
+
+**Claude Desktop**, in `claude_desktop_config.json`. Use the full path of the
+`softpractice` executable if the app does not find it on `PATH`:
+
+```json
+{
+  "mcpServers": {
+    "softpractice": {
+      "command": "softpractice",
+      "args": ["mcp", "--project", "/path/to/your/lesson-project"]
+    }
+  }
+}
+```
+
+| Tool | What it does |
+| --- | --- |
+| `status` | Project state and `next_actions`, each naming the tool to call next or a page for you |
+| `task` | The assignment of the lesson in this folder |
+| `material` | The theory material; `lesson_id` for another lesson |
+| `hints` | The hints you have already opened |
+| `check` | Run the public checks on the working tree |
+| `submit` | Submit the committed `HEAD`, after you confirm; `wait_seconds` waits for the result |
+| `result` | The evaluation result; `wait_seconds` waits for it |
+| `submissions` | The recent submissions of the lesson |
+| `update` | Apply the lesson update, after you confirm the list of files it changes |
+
+The task and the material are also available as the resources
+`softpractice://lesson/task` and `softpractice://lesson/material`.
+
+What the server leaves to you:
+
+- `submit` and `update` ask you to confirm in the client, with the commit or
+  the list of files. If the client cannot ask (it does not support MCP
+  elicitation), they do nothing and return `confirmation_unavailable`; run
+  `softpractice submit` or `softpractice update` in a terminal instead.
+- Results never include the reviewer's recommendations (`--directions`) or
+  the text of the reviewer's questions. You answer the questions on the result
+  page; the agent gets their number and the link.
+- The agent sees only the hints you have opened; you open the next one on the
+  assignment page.
+- `check` runs only the checks the server publishes for the lesson. If
+  `.softpractice/checks.json` differs, it returns `checks_not_published`:
+  review the commands and run `softpractice check` in a terminal.
+- `login`, `logout`, `starter`, `project restore`, `set`, and `open` are not
+  available through MCP.
+
+These limits apply to the MCP tools. An agent that can run shell commands can
+also run the `softpractice` commands themselves.
+
+Errors are tool results with `isError` and a JSON body
+`{"error": {"code", "message", "action"}}`; `action` says what you have to do,
+for example `login_required` asks you to run `softpractice login`.
+
+Tool names and descriptions are in English, for the model. Messages meant for
+you, such as the confirmation and error messages, use the CLI language (see
+below); when no language is configured, the MCP server uses Russian, the
+language of the course. To change it, set `SOFTPRACTICE_LANGUAGE` in the
+server's `env` in the client configuration, or pass `--lang en` before `mcp`.
+
 ## Language
 
 SoftPractice CLI supports English and Russian and selects a language from the

diff --git a/README_RU.md b/README_RU.md
@@ -42,25 +42,27 @@ softpractice login
 softpractice starter
 ```
 
-Перейди в созданный каталог и проверь текущий урок:
+Перейди в созданный каталог, проверь состояние проекта и прочитай задание:
 
 ```bash
 cd <каталог-проекта>
 softpractice status
+softpractice task
+softpractice material
 ```
 
 Работай над проектом и фиксируй изменения в Git. Когда решение будет готово,
-отправь текущий коммит:
+отправь текущий коммит и дождись результата:
 
 ```bash
-softpractice submit
+softpractice submit --wait
 ```
 
-Проверь состояние отправки и открой результат:
+Результат можно посмотреть снова в любой момент или открыть в браузере:
 
 ```bash
-softpractice submission show
-softpractice open
+softpractice result
+softpractice open result
 ```
 
 После принятия решения примени переход к следующему доступному уроку:
@@ -69,18 +71,25 @@ softpractice open
 softpractice update
 ```
 
+`softpractice status` всегда заканчивается следующим шагом.
+
 ## Основные команды
 
 | Команда | Описание |
 | --- | --- |
 | `softpractice login` | Войти через браузер |
 | `softpractice starter` | Скачать проект первого урока |
-| `softpractice status` | Показать текущий урок и состояние локального проекта |
+| `softpractice status` | Показать состояние проекта и следующий шаг |
+| `softpractice task` | Показать задание |
+| `softpractice material` | Показать теоретический материал; `--lesson ID` — другого урока |
+| `softpractice hint` | Показать открытые подсказки; следующая открывается на странице задания |
 | `softpractice check` | Запустить публичные проверки текущего рабочего дерева |
-| `softpractice submit` | Отправить текущую зафиксированную Git-ревизию |
-| `softpractice submission show` | Показать последнюю отправку и результат проверки |
+| `softpractice submit` | Отправить текущую зафиксированную Git-ревизию; `--wait` дожидается результата |
+| `softpractice result` | Показать результат проверки; `--wait` дожидается его, `--directions` добавляет рекомендации рецензента |
+| `softpractice submissions` | Показать последние отправки урока |
 | `softpractice update` | Применить переход к следующему уроку или перейти на новую версию текущего урока (заменяет только файлы урока, ваши файлы не трогает; до конца урока необязательно) |
-| `softpractice open` | Открыть workspace или последний результат в браузере |
+| `softpractice open` | Открыть задание, материал или последний результат в браузере |
+| `softpractice mcp` | Запустить MCP-сервер для Claude Code, Codex, Claude Desktop и других агентов |
 | `softpractice project restore` | Восстановить проект из последней подходящей ревизии |
 
 Подробную справку можно получить командой `softpractice help <команда>`.
@@ -109,6 +118,113 @@ softpractice set auto-checks true
 отличие от `softpractice check`, проверка перед отправкой требует чистое рабочее
 дерево и запускается в изолированном снимке `HEAD`.
 
+## Вопросы рецензента
+
+Если у рецензента есть вопросы к решению, `softpractice result` и
+`softpractice status` сообщают об этом и дают ссылку на страницу результата:
+отвечать нужно там.
+
+## Машиночитаемый вывод
+
+`status`, `task`, `material`, `hint`, `result`, `submissions` и `submit`
+принимают `--json`. У каждого документа есть поле `kind`; при ошибке команда
+выводит документ `softpractice.error`, в том числе при неверных аргументах
+(код `usage`) и при отказе в подтверждении `submit` (код `declined`).
+
+```bash
+softpractice result --wait --timeout 10m --json
+```
+
+Коды выхода: `0` — готово, `1` — ошибка, `2` — неверные аргументы, `3` —
+проверка ещё не готова, `4` — проверка заменена, результата не будет.
+
+## MCP-сервер
+
+`softpractice mcp` — локальный MCP-сервер на stdio. Через него Claude Code,
+Codex, Claude Desktop и другие MCP-клиенты проходят урок вместе с тобой теми же
+операциями, что и команды выше. Сначала войди: `softpractice login`. Сам сервер
+вход никогда не запускает.
+
+Сервер работает с проектом урока в папке, в которой его запустил клиент. Если
+клиент запускает его в другом месте, как Claude Desktop, передай папку
+проекта флагом `--project`.
+
+**Claude Code**, из папки проекта:
+
+```bash
+claude mcp add softpractice -- softpractice mcp
+```
+
+**Codex**, в `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.softpractice]
+command = "softpractice"
+args = ["mcp"]
+# Чтобы result и submit успевали дождаться проверки.
+tool_timeout_sec = 180
+```
+
+**Claude Desktop**, в `claude_desktop_config.json`. Если приложение не находит
+`softpractice` в `PATH`, укажи полный путь к исполняемому файлу:
+
+```json
+{
+  "mcpServers": {
+    "softpractice": {
+      "command": "softpractice",
+      "args": ["mcp", "--project", "/path/to/your/lesson-project"]
+    }
+  }
+}
+```
+
+| Инструмент | Что делает |
+| --- | --- |
+| `status` | Состояние проекта и `next_actions`: какой инструмент вызвать дальше или какая страница нужна тебе |
+| `task` | Задание урока в этой папке |
+| `material` | Теоретический материал; `lesson_id` — для другого урока |
+| `hints` | Подсказки, которые ты уже открыл |
+| `check` | Запустить публичные проверки для рабочего дерева |
+| `submit` | Отправить закоммиченный `HEAD` после твоего подтверждения; `wait_seconds` — дождаться результата |
+| `result` | Результат проверки; `wait_seconds` — дождаться его |
+| `submissions` | Последние отправки урока |
+| `update` | Применить обновление урока после того, как ты подтвердишь список файлов |
+
+Задание и материал доступны также как resources
+`softpractice://lesson/task` и `softpractice://lesson/material`.
+
+Что сервер оставляет тебе:
+
+- `submit` и `update` просят подтверждения в клиенте и показывают commit или
+  список файлов. Если клиент не умеет спрашивать (не поддерживает MCP
+  elicitation), они ничего не делают и возвращают `confirmation_unavailable`;
+  тогда выполни `softpractice submit` или `softpractice update` в терминале.
+- В результатах никогда нет рекомендаций рецензента (`--directions`) и текста
+  его вопросов. На вопросы ты отвечаешь на странице результата; агент получает
+  только их число и ссылку.
+- Агент видит только подсказки, которые ты уже открыл; следующую ты открываешь
+  на странице задания.
+- `check` запускает только проверки, которые сервер публикует для урока. Если
+  `.softpractice/checks.json` отличается, он возвращает
+  `checks_not_published`: посмотри команды и запусти `softpractice check` в
+  терминале.
+- `login`, `logout`, `starter`, `project restore`, `set` и `open` через MCP
+  недоступны.
+
+Эти ограничения относятся к инструментам MCP. Агент, который может выполнять
+команды в терминале, может вызвать и сами команды `softpractice`.
+
+Ошибки приходят как результаты инструментов с `isError` и JSON
+`{"error": {"code", "message", "action"}}`; в `action` написано, что сделать
+тебе, например при `login_required` — выполнить `softpractice login`.
+
+Имена и описания инструментов — на английском, их читает модель. Сообщения для
+тебя — подтверждение и ошибки — на языке CLI (см. ниже); если язык нигде не
+задан, MCP-сервер говорит по-русски, на языке курса. Чтобы сменить язык, задай
+`SOFTPRACTICE_LANGUAGE` в `env` сервера в настройках клиента или передай
+`--lang en` перед `mcp`.
+
 ## Язык
 
 SoftPractice CLI поддерживает английский и русский языки и по возможности

diff --git a/cmd/softpractice/coursebase_test.go b/cmd/softpractice/coursebase_test.go
@@ -123,7 +123,7 @@ func TestStatusReportsAPendingTransitionAndScopesTheSubmissionLine(t *testing.T)
 
 	var machineOutput bytes.Buffer
 	if err := status(
-		context.Background(), client, root, []string{"--format", "json"}, &machineOutput, &errorOutput,
+		context.Background(), client, root, []string{"--json"}, &machineOutput, &errorOutput,
 	); err != nil {
 		t.Fatal(err)
 	}
@@ -161,7 +161,7 @@ func TestMachineStatusOmitsTransitionWhenTheProjectIsOnTheCurrentLesson(t *testi
 
 	var output, errorOutput bytes.Buffer
 	if err := status(
-		context.Background(), client, root, []string{"--format", "json"}, &output, &errorOutput,
+		context.Background(), client, root, []string{"--json"}, &output, &errorOutput,
 	); err != nil {
 		t.Fatal(err)
 	}