M3.8: MCP server lutra mcp

- crates/mcp (L5): JSON-RPC 2.0 over stdio, dual era: MCP 2026-07-28
  (per-request _meta, server/discover, -32022) and legacy initialize
  (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05). Tools list_commands,
  execute_command (app.quit only with confirm: true), screenshot (image
  content), read_buffer, get_events (ring of 1000 events via
  events.subscribe); resources lutra://buffer/<path> for open buffers.
  Engine errors become tool errors with the engine code. Lines capped at
  16 MiB, guard around every request, parser and tool args fuzzed.
- lutra mcp [--port PORT] [--no-start] in apps/lutra-cli: connects through
  the rendezvous file and token, or starts Lutra.
- Engine: read-only buffer.list command.
- Tests: protocol units + proptest fuzz, integration over the token
  listener, stdio end to end. Docs: architecture (MCP), G7, ROADMAP.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-19 18:20:57 +02:00
parent 51eba0b3cb
commit 0e56c22b66
24 changed files with 3055 additions and 18 deletions

View file

@ -2,7 +2,7 @@
**Stage: pre-alpha (M2 done)** · next: M3 language server, terminal, CLI and MCP (the MVP); alpha when the six core workflows work end to end (see [docs/roadmap.md › Alpha gate](docs/roadmap.md#alpha-gate))
> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-17 · **Change:** minor (M3.7: `lutra` CLI and single instance) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only
> **Last reviewed:** 2026-10-15 · **Last updated:** 2026-10-19 · **Change:** minor (M3.8: MCP server) · **Target:** JetBrains PhpStorm 2026.x, described from public documentation only
Lutra is a clean-room, open-source PHP IDE with a Rust core and a Tauri + Vue interface, targeting the PhpStorm workflow. Agents can drive all of it over MCP, the `lutra` CLI and a JSON control channel. This page is the summary; the evidence is in [`docs/target-app-parity.md`](docs/target-app-parity.md) and the work list in [`docs/gaps.md`](docs/gaps.md).
@ -33,9 +33,9 @@ Dimension hours overlap: language, framework and tooling hours are part of the f
| Localization (en, de) | 5% | ~38 | [localization-parity.md](docs/localization-parity.md) |
| Performance | 0% | ~100 | [gaps.md › G12](docs/gaps.md) |
| Stability | 8% | ~95 | [gaps.md › G11](docs/gaps.md) |
| Agent automation | 18% (est.) | ~52 | AGENTS.md |
| Agent automation | 26% (est.) | ~44 | AGENTS.md |
Stability 8%: no-panic lints, the engine guard, a fuzzed control protocol and a crash-recovery journal for unsaved buffers (property-tested: random edits, crash, restore) exist; the journal is not yet checked in the running app. Agent automation 10%: the control channel (ping, execute, listCommands, screenshot) works, and since M1.8 it also reaches the frontend's UI commands (opening the palette, toggling the project tree) through the `uiCommand` event; since M3.7 the `lutra` CLI opens folders and files at a line in the running instance (or starts it), `--wait` blocks until the tabs close (usable as `core.editor`), and a token-protected rendezvous file lets local tools find the instance; MCP does not exist yet. Both are estimated. Localization 5% (estimated): every UI string comes from an English catalog enforced by lint; engine messages, the language switch and German are missing. UI/UX fidelity 1% (estimated): light and dark themes switch live and pass a WCAG AA contrast test; the rest of the ui-parity checklist is open.
Stability 8%: no-panic lints, the engine guard, a fuzzed control protocol and a crash-recovery journal for unsaved buffers (property-tested: random edits, crash, restore) exist; the journal is not yet checked in the running app. Agent automation 26%: the control channel (ping, execute, listCommands, screenshot) works, and since M1.8 it also reaches the frontend's UI commands (opening the palette, toggling the project tree) through the `uiCommand` event; since M3.7 the `lutra` CLI opens folders and files at a line in the running instance (or starts it), `--wait` blocks until the tabs close (usable as `core.editor`), and a token-protected rendezvous file lets local tools find the instance; since M3.8 `lutra mcp` gives MCP clients such as Claude Code every command (with params docs and the enabled state), screenshots, the text of open buffers (also as resources) and the recent events, with `app.quit` only on explicit confirmation. Missing: change notifications, progress for long commands, the perf and diff subcommands. Both are estimated. Localization 5% (estimated): every UI string comes from an English catalog enforced by lint; engine messages, the language switch and German are missing. UI/UX fidelity 1% (estimated): light and dark themes switch live and pass a WCAG AA contrast test; the rest of the ui-parity checklist is open.
## Features
@ -75,6 +75,7 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a
| Date | What landed |
|---|---|
| 2026-10-19 | M3.8: agents can drive Lutra over MCP: `claude mcp add lutra -- lutra mcp`, then Claude can list and run every command, look at the window, read open files including unsaved changes and follow what happens. Closing Lutra needs an explicit confirmation. |
| 2026-10-17 | M3.7: the `lutra` command: `lutra src/Kernel.php:42` opens the file at line 42 in the running Lutra or starts it, `lutra .` opens a folder, `lutra --wait FILE` returns when the tab is closed (for `git commit`). Starting Lutra a second time hands the path to the first window. Only your user account can talk to the running instance. |
| 2026-10-17 | M2.6: go to any file, class or symbol by name: `Mod+P`, `Mod+Alt+C` and `Mod+T` open one popup with Files, Classes and Symbols tabs (Tab switches); results update as you type with the matched letters marked, library code is labelled, a hint shows while the index is still building, and Enter jumps there. Agents can open it with a query. |
| 2026-10-17 | M2.7: a Structure tool window next to Project (new left stripe, `Mod+2`) shows the classes, functions, methods, properties and constants of the active PHP file as a tree that follows tabs and edits; click or Enter jumps to the declaration. The file is reparsed in the background, so big files never stall typing. |
@ -96,6 +97,7 @@ All hours estimated. Weights, evidence and the missing items per area: [target-a
| Date | Change | Summary |
|---|---|---|
| 2026-10-18 | minor | Feature breadth measured against the full PhpStorm help inventory (155 units); M7–M9 added |
| 2026-10-19 | minor | M3.8: MCP server; agent automation 18% → 26% (est.) |
| 2026-10-17 | minor | M3.7: `lutra` CLI and single instance; agent automation 10% → 18% (est.) |
| 2026-10-17 | minor | Cycle C3 review: M2 done (~6.1 h measured), factor 0.14, MVP ~12 h left |
| 2026-10-17 | minor | M2.6: Navigation 4% → 10%, feature depth ~3.2% |