Expand shared Sprinter MCP with managed launch, raw reads and key input

docs/sdbg-mcp.md

@@ -44,8 +44,38 @@ pyenv exec python -m venv /tmp/sprinter-sdbg-mcp-venv
 MCP-сервер заново вместе с новой DAP-сессией. Альтернатива параметру
 `--socket` — переменная окружения `SDBG_SOCKET`.
 
+Для работы **без VS Code** запустите тот же MCP-сервер с `--build`:
+
+```json
+{
+  "command": "/tmp/sprinter-sdbg-mcp-venv/bin/python",
+  "args": [
+    "/ABS/PATH/C-Compiler/toolchain/sdbg_mcp.py",
+    "--build", "/ABS/PATH/C-Compiler/tests/hello/.sprinter-cc-hello",
+    "--socket", "/tmp/sprinter-hello-agent.sock",
+    "--mame-home", "/ABS/PATH/MAME/runtime",
+    "--mame-bin", "/ABS/PATH/MAME.HT/sprinter"
+  ]
+}
+```
+
+MCP handshake не ждёт загрузку DSS. `start_session` сразу возвращает socket и
+launch ID; `session_status` показывает `starting`, затем `ready` с build ID,
+session ID, PC и PID MAME либо `failed` с диагностикой. Повторный start при
+активном сеансе отклоняется. `stop_session` завершает только запущенный этим
+MCP-сервером MAME и удаляет socket. Закрытие самого MCP-процесса также
+завершает его автономный MAME. DAP/VS Code может подключиться к тому же socket;
+его disconnect не завершает MCP-owned MAME. Конфигурация VS Code — в
+[разделе attach](vscode-sprinter-debug.md#ручной-attach).
+Доступны также `--mame-rompath`, `--mame-dss-image`,
+`--mame-system-hdd-image`, `--mame-bios`, `--app-hdd`, `--launch-path`,
+`--data`, `--debugger`, `--launch-at`, `--dss-timeout`.
+Живой stdio MCP→DSS→`main`→DAP attach→stop прогон прошёл; подключение
+непосредственно из UI Codex и Claude ещё не проверено.
+
 Доступные инструменты: `session_status`, `where`, `read_registers`,
-`read_memory`, `list_variables`, `read_variable`, `recent_events`,
+`read_memory`, `read_program_memory`, `list_ports`, `list_shares`, `read_share`, `read_vram`,
+`read_screen_pixels`, `screenshot`, `press_key`, `list_variables`, `read_variable`, `recent_events`,
 `mame_console_tail`, `set_line_breakpoint`, `set_function_breakpoint`,
 `clear_breakpoint`, `clear_my_breakpoints`, `claim_control`, `release_control`,
 `continue_execution`,
@@ -55,7 +85,8 @@ MCP-сервер заново вместе с новой DAP-сессией. А
 `recent_events` с курсором `last`. Логи `SDBG_LOG` приходят как события
 `output`; журнал ограничен 1024 событиями и сообщает `first`/`last`/`lost`.
 
-Число 16 не означает удаление возможностей более нового `-plugin mamebridge`:
+Число 26 в attach-режиме (28 в автономном с `start_session`/`stop_session`)
+не означает полного переноса более нового `-plugin mamebridge`:
 его `src/mame_mcp.py` публикует 30 raw-инструментов, ориентированных на
 машину MAME. Здесь инструменты сгруппированы по операциям C-сессии, а
 некоторые функции (C-позиция, typed global/static, журнал с generation)
@@ -64,15 +95,16 @@ MCP-сервер заново вместе с новой DAP-сессией. А
 | Группа raw MCP | Что требуется перед переносом в общую сессию |
 |---|---|
 | `setmem`, raw `debugger_command`, watchpoints | Проверка прав, банка, диапазона и согласование с DAP-точками; произвольная debugger-команда может нарушить состояние сессии |
-| VRAM/shares, screen pixels, screenshot | Явные адресные пространства, лимиты, формат ответа и изолированный каталог снимков |
-| Клавиатура, мышь, type/press | Один владелец ввода, корректное отпускание клавиш, ожидание running CPU и проверка прямого ввода с клавиатуры |
+| VRAM/shares, screen pixels, screenshot | Реализованы через общий `sdbgbridge`; точный tag, пределы 4096 байт/8192 пикселя, PNG только в каталоге сессии |
+| Клавиатура, мышь, type/press | `list_ports` и одиночный `press_key` уже перенесены; набор строки, произвольные поля портов и мышь требуют отдельного контракта ввода |
 | Raw disassembly | Связать адрес/банк с проверенной C-картой; не выдавать физический адрес за logical |
 
 Это следующий этап, а не запрет на функции raw MCP. Нельзя просто загрузить
 `mamebridge` рядом с `sdbgbridge`: два независимых обработчика начнут менять
 CPU и точки без общего owner ID и журнала.
 Результаты удаления legacy Lua и этапы переноса всех 30 возможностей в общую
-C-сессию описаны в [плане сведения MCP](mcp-convergence-plan.md).
+C-сессию описаны в [плане сведения MCP](mcp-convergence-plan.md) и
+[матрице покрытия](mcp-capability-matrix.md).
 
 Чтение памяти принимает десятичный адрес или `0xHEX`, 1–256 байт logical
 Z80 memory, только при остановленном CPU, без side effects. Ответ содержит
@@ -81,6 +113,37 @@ generation и страницы банков; диапазон не может п
 байта, только когда нужный банк отображён. Локальные, стек, watchpoints,
 запись переменных и произвольные выражения пока не поддерживаются.
 
+`read_program_memory` читает raw program space 0..0x3ffff без side effects,
+до 4096 байт при остановленном CPU; это отдельный инструмент, так как
+`read_memory` означает logical Z80. `list_ports` возвращает tag, имена полей
+и битовые маски; результат ограничен 512 портами/4096 полями и помечает
+`truncated`, если достигнут предел. Оба инструмента проверены в живом MAME.
+
+`list_shares` возвращает точные tag/размеры. `read_share` требует полный tag,
+`read_vram` выбирает единственный VRAM share; обе операции читают до 4096
+байт без Z80 bank mapping. `read_screen_pixels` возвращает pen16-значения
+в hex и номер кадра. `screenshot` сохраняет PNG до 8 МиБ в каталоге текущей
+сессии и возвращает путь; после завершения сессии временный каталог удаляется.
+Для обоих экранных инструментов `stale_frame=true` означает, что CPU
+остановлен и показан последний нарисованный кадр. Экран работающего `hello`
+во время `getchar()` проверен живым MCP-прогоном.
+
+`press_key` принимает один символ раскладки PC или `enter`, `space`, `tab`
+и `frames` от 1 до 60 (по умолчанию 3). Он доступен только при работающем
+CPU, после запуска EXE; применяется общий control lease. Shift удерживается
+автоматически для заглавных букв и соответствующих символов. После нужного
+числа кадров или остановки CPU клавиша отпускается, включая путь ошибки.
+Ответ сообщает число прошедших кадров и признак остановки. Живой автономный
+MCP-прогон ввёл `x` в ожидающий `getchar()` и дошёл до следующей C-строки.
+Прямой физический ввод в MAME проверялся отдельно; `press_key` не заменяет
+его. Набор строки, произвольные имена клавиш, мышь и порты ввода ещё не
+публичны в C-MCP.
+
+После первого `session_status` клиент отправляет session ID и build ID в
+каждом RPC; команды, меняющие CPU/точки, дополнительно сверяют generation.
+При замене сеанса или устаревшей generation команда отклоняется без
+автоматического повтора.
+
 У каждой MCP-копии свой owner ID. Она может удалить только свои точки; при
 обычном закрытии stdio они очищаются. Живой тест подтвердил, что попытка
 удалить DAP-точку отвергается и точка VS Code срабатывает после выхода MCP.