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

@ -1,15 +1,15 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu · **Last updated:** 2026-10-19
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server · **Last updated:** 2026-10-19
## Overview
```
apps/lutra-desktop (L6) Tauri 2 shell: windows, menus, IPC bridge to the engine
ui/ (L6) Vue 3 + TypeScript + Vite frontend, Pinia, CodeMirror 6
apps/lutra-cli (L6) the `lutra` command: open, --wait; later diff, mcp, perf, bench
apps/lutra-cli (L6) the `lutra` command: open, --wait, mcp; later diff, perf, bench
crates/control (L5) JSON-lines control channel (--control PORT)
crates/mcp (L5) MCP server over stdio
crates/mcp (L5) MCP server over stdio (the CLI supplies the connection)
crates/engine (L4) command registry, workspace state, guard, recovery journal, theme tokens
crates/lsp (L3) LSP client (Phpactor first), later DAP client
crates/terminal (L3) pseudo-terminal sessions (portable-pty)
@ -78,7 +78,25 @@ As built in M0:
- **Starting Lutra:** if no instance answers, the CLI starts the desktop detached (`LUTRA_DESKTOP`, else `lutra-desktop` next to `lutra`, else on `PATH`) and polls the rendezvous file for up to 60 s.
- **`--wait`:** subscribes before opening, then blocks until every opened file's `bufferClosed` arrived (or `projectClosed`, or the connection ends because Lutra quit). A `subscriptionLost` renews the subscription and checks the remaining ids with `buffer.get`. Folders are not waited for.
- **Exit codes:** 0 ok, 1 error (cannot start, open failed, missing path), 2 bad usage (unknown option, line or column 0 or too big, two folders, a positioned folder, non-Unicode argument). Arguments are untrusted; parsing is property-tested.
- **Rendezvous API for M3.8 (`lutra mcp`):** `lutra_control::client::connect_live(&rendezvous::dir()?, timeout)` returns the `Instance` and an authenticated `Client`; `Client::request(method, params)`, `execute(command, params)`, `subscribe()`, `next_event(timeout)` (events read while waiting for a response are queued, at most 4096), `open_folder`, `open_file`, `reveal`, `focus`. To start Lutra when none runs, reuse the CLI's `launch` logic (move it into the client if MCP needs it outside the CLI binary). Response lines are capped at 64 MiB.
- **Rendezvous API for M3.8 (`lutra mcp`):** `lutra_control::client::connect_live(&rendezvous::dir()?, timeout)` returns the `Instance` and an authenticated `Client`; `Client::request(method, params)`, `execute(command, params)`, `subscribe()`, `next_event(timeout)` (events read while waiting for a response are queued, at most 4096), `open_folder`, `open_file`, `reveal`, `focus`. Response lines are capped at 64 MiB. `lutra mcp` (M3.8) uses this API from the CLI, so the CLI's `launch` logic stayed in the CLI.
### MCP server (M3.8)
- **Shape:** `crates/mcp` (L5) holds the protocol, the tools and the event buffer but opens no sockets and starts no processes; it reaches Lutra through the `lutra_mcp::Connector` / `Connection` traits (`request(method, params)`, `next_event(timeout)`). `lutra mcp` in `apps/lutra-cli` (L6) implements them with `lutra_control::client`: the rendezvous file and token by default (starting Lutra like `lutra PATH` when none runs), `--port PORT` for an open `--control` channel, `--no-start` to never start Lutra. Register it with `claude mcp add lutra -- lutra mcp`. No SDK: the official Rust SDK brings an async runtime and schema generators, and the protocol needed here is small.
- **Transport:** stdio, one JSON-RPC 2.0 message per line (UTF-8, at most 16 MiB; a longer or non-UTF-8 line gets a parse error and the next line is read). Batches are rejected. stdout carries only MCP messages; the server exits 0 when stdin closes. Every request runs under `lutra_engine::guard`.
- **Protocol versions (dual era):** modern **2026-07-28** (stateless: each request carries `_meta` `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`; `server/discover`; results get `resultType: "complete"` and `_meta` `io.modelcontextprotocol/serverInfo`; another version gets `-32022` with `data {supported, requested}`, missing capabilities `-32602`) and legacy **2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05** through `initialize` (the client's version if known, else 2025-11-25). Only the handshake and the result decoration differ; both eras share every method and tool. A request with neither `_meta` nor a prior `initialize` is served with legacy shapes.
- **Methods:** `server/discover`, `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `resources/templates/list` (empty). Notifications are accepted silently; any other method is `-32601`. Capabilities: `tools {listChanged: false}`, `resources {}` (no subscriptions yet). Lists come whole (a cursor is ignored).
- **Tools (D16):**
- `list_commands {filter?, enabledOnly?}`: `engine.listCommands` (id, label, menu path, shortcut, params doc, enabled, ui).
- `execute_command {command, params?, confirm?}`: `engine.execute` for every engine and UI command. **`app.quit` is refused with `confirmation_required` unless `confirm: true`.**
- `screenshot {path?}`: `ui.screenshot` into a temporary file (deleted afterwards) or `path`, returned as `image/png` content; at most 32 MiB, PNG signature checked.
- `read_buffer {path | id}`: the current text with unsaved changes plus `{id, path, version, dirty, lineEnding, truncated}`; a project-relative or absolute path inside the project; cut at 4 MiB.
- `get_events {since?, max?, kinds?, waitMs?}`: see Events below.
- Results carry `structuredContent` and the same JSON as text. Bad arguments, engine errors and an unreachable Lutra are tool errors (`isError: true`, text `code: message`, `structuredContent.error {code, message}`) with the engine's code, or `invalid_params`, `confirmation_required`, `not_open`, `screenshot_failed`, `unavailable`. An unknown tool is `-32602`.
- **Events:** the first connection starts a pump thread with its own subscribed connection (`events.subscribe`). It keeps the last 1000 events in a ring, numbered by a growing `seq`, each capped at 16 KiB (a bigger one keeps only `kind` and `truncated: true`). `get_events` returns the events after `since` (default 100, at most 1000, optionally only `kinds`, optionally waiting up to `waitMs` ≤ 30 s), `latest` to pass as `since` next time, `missed` when the ring dropped events after `since` or the subscription was down, and `subscribed`. A lost subscription reconnects every 0.5 s without starting Lutra. Events from before the first connection are not seen.
- **Resources:** one per open buffer (`buffer.list`), URI `lutra://buffer/<project-relative path>` with every byte outside the RFC 3986 unreserved set (except `/`) percent-encoded, a MIME type from the extension, and a description for unsaved changes. `resources/read` returns the text with unsaved changes; an unknown or closed buffer is `-32602` with `data {uri}`, an unreachable Lutra `-32603`.
- **Connection:** made on the first call that needs Lutra (listing tools never starts it) and pinged (`app.ping`) before each use; a dead one is replaced, which starts Lutra again if it quit.
- **Tests:** JSON-RPC and protocol units, a proptest fuzz of message lines and tool arguments (no panic, exactly one valid response line), integration against `lutra_testkit::EngineBackend` behind a real token listener (`crates/mcp/tests/tcp.rs`), and the `lutra mcp` binary on stdio (`apps/lutra-cli/tests/mcp.rs`).
## Frontend ↔ engine
@ -89,7 +107,7 @@ Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS cus
### Workspace (M1.3)
- `State` holds `project: Option<Workspace>` (the `lutra_vfs::Project`, its watcher and the watched directories) and `buffers` (id → `OpenBuffer { buffer: lutra_text::Buffer, path, version, saved_version, bom }`). A buffer is dirty when `version != saved_version`. Ids are never reused.
- Commands: `project.open {path, force?}`, `project.close {force?}`, `project.children {dir?}`, `file.open {path}` (returns the existing buffer if the file is already open), `buffer.get {id}`, `buffer.edit {id, baseVersion, edits}`, `file.save {id}` (`Mod+S`), `file.saveAll` (`Mod+Alt+S`), `buffer.close {id, force?}`. Everything except `project.open` is disabled without a project. Paths are project-relative with `/`; absolute paths are accepted when they lie inside the project; `..` escapes are rejected by the VFS.
- Commands: `project.open {path, force?}`, `project.close {force?}`, `project.children {dir?}`, `file.open {path}` (returns the existing buffer if the file is already open), `buffer.get {id}`, `buffer.edit {id, baseVersion, edits}`, `file.save {id}` (`Mod+S`), `file.saveAll` (`Mod+Alt+S`), `buffer.close {id, force?}`, `buffer.list` (M3.8: `[{id, path, version, dirty}]` without text, empty without a project). Everything except `project.open` and `buffer.list` is disabled without a project. Paths are project-relative with `/`; absolute paths are accepted when they lie inside the project; `..` escapes are rejected by the VFS.
- Edit protocol: `edits` are `{from, to, insert}` in UTF-16 code units, all relative to the text at `baseVersion` (CodeMirror change-set semantics), non-overlapping, applied atomically. A `baseVersion` other than the current version fails with `stale_version` and changes nothing; the client refetches with `buffer.get` and reapplies its pending changes. Each successful batch increments the version by one. Limits: 100,000 edits and 64 MiB inserted per call.
- Saving writes `Buffer::save_text` (the file's dominant line ending) atomically through the VFS and keeps a UTF-8 byte order mark.
@ -343,6 +361,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-19 | minor | M3.8: MCP server (`lutra mcp`, dual era 2026-07-28 + legacy `initialize`), tools, resources, event buffer; `buffer.list` |
| 2026-10-19 | minor | M3.9: app menu (header bar, `menu.open`, grouping by `menuPath`, launcher under the modal rule); menu paths for user commands |
| 2026-10-18 | minor | M3.1: toolchain (PHP detection, pinned Phpactor download with SHA-256 check, network access note, D15), `toolchain.status`/`toolchain.downloadPhpactor`, `toolchainChanged`, bool and string settings |
| 2026-10-18 | minor | M3.2: LSP client library (`crates/lsp`: framing, supervision and restart, initialize, requests with timeout and cancel, server requests, document sync, fake server tests) |

View file

@ -1,6 +1,6 @@
# Gaps
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal); G3 M1 part done (project tree, palette, settings dialog, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download); G7 under way (`lutra` CLI and single instance); G14 English UI catalog in place · **Last updated:** 2026-10-19
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal); G3 M1 part done (project tree, palette, settings dialog, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download); G7 under way (`lutra` CLI and single instance, MCP server); G14 English UI catalog in place · **Last updated:** 2026-10-19
Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated.
@ -12,7 +12,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t
| G4 | Syntax and structure: tree-sitter PHP, ~~Lezer highlighting~~ (M2.2: PHP with embedded HTML plus HTML, CSS, JS/TS, JSON, YAML, Markdown; `--lt-syntax-*` tokens; `editor.reveal`), ~~file structure~~ (M2.7: Structure tool window, `syntax.outline`), semantic highlighting, folding in the editor | M2 | ~8 h |
| G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h |
| G6 | Language server: completion, diagnostics, definition, hover, rename via Phpactor (~~PHP detection and Phpactor download~~, M3.1) | M3 | ~43 h |
| G7 | Terminal, ~~`lutra` CLI and single instance~~ (M3.7: open folders and files at a line, `--wait`, forwarding a second start, token-protected rendezvous), MCP server, files outside the open project (the CLI refuses them; needs out-of-project buffers or a second window), `lutra diff` | M3 | ~30 h |
| G7 | Terminal, ~~`lutra` CLI and single instance~~ (M3.7: open folders and files at a line, `--wait`, forwarding a second start, token-protected rendezvous), ~~MCP server~~ (M3.8: `lutra mcp` with list/execute every command, screenshot, read buffer, recent events, open buffers as resources; still missing: resource and tool change notifications, progress for long commands), files outside the open project (the CLI refuses them; needs out-of-project buffers or a second window), `lutra diff` | M3 | ~26 h |
| G8 | Git integration | M4 | ~150 h |
| G9 | Debugger, test runner, Composer, run configurations | M5 | ~300 h |
| G10 | Own indexer, type inference, inspections, refactorings | M6 | ~800 h |
@ -50,6 +50,7 @@ G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framin
| Date | Change | Summary |
|---|---|---|
| 2026-10-19 | minor | G7: MCP server (M3.8) |
| 2026-10-19 | minor | G3: app menu (M3.9) |
| 2026-10-18 | minor | G6: PHP detection and pinned Phpactor download (M3.1) |
| 2026-10-18 | minor | G6: LSP client library (M3.2) |

View file

@ -1,6 +1,6 @@
# Milestones
> **Status:** M0 done, M1 done, M2 in progress · **Last updated:** 2026-10-17
> **Status:** M0 done, M1 done, M2 in progress · **Last updated:** 2026-10-19
Hours are agent wall-clock hours for one agent; M0 and M1 so far are measured, the rest estimated. Since cycle C1 (factor 0.07) M1–M3 are scaled ×0.1; M4–M6 keep their first raw estimates (multiply by ~0.1 for the calibrated value).
@ -9,7 +9,7 @@ Hours are agent wall-clock hours for one agent; M0 and M1 so far are measured, t
| M0 | Foundation: workspace, lints, quality gate, command registry, control channel, empty window | done 2026-10-14 (CI workflow written, not yet run: hosted on Forgejo, runners unknown) | ~2 (measured) |
| M1 | Editor and project: open folder, tree, tabs, editor, save, recovery, palette, settings, themes | done 2026-10-16 (M1.1 text, M1.2 VFS, M1.5 tree UI, M1.3 engine workspace, M1.4 desktop bridge, M1.6 tabs and editor, M1.11 message catalog, M1.9a settings backend, M1.10 themes, M1.7 recovery journal, M1.12 notifications, M1.13 C1 follow-ups, M1.8 command palette and keymap, M1.14 app icon, M1.9b settings dialog; C2 live checks pending, gaming mode) | ~5.6 (measured: C1 2.5, C2 3.1) |
| M2 | Syntax and search: highlighting, structure, find in files, go to file/class/symbol | done 2026-10-17 (C3: M2.1 tree-sitter syntax, M2.2 highlighting + `editor.reveal`, M2.3 search backend, M2.4 Find tool window, M2.5 symbol index + go-to commands, M2.6 go-to popup, M2.7 Structure tool window) | ~6.1 (measured) |
| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | in progress (M3.7 CLI and single instance done) | ~12 |
| M3 | LSP, terminal, CLI: completion, diagnostics, go to definition, hover, rename; terminal; `lutra` CLI and MCP — **MVP** | in progress (M3.7 CLI and single instance, M3.8 MCP server done) | ~12 |
| M4 | Git: status, diff, commit, branches, log, blame, conflicts | not started | ~150 |
| M5 | Debugger (Xdebug via DAP), PHPUnit/Pest runner, Composer, run configurations | not started | ~300 |
| M6 | Own indexer and inspections; Symfony, Laravel, Shopware, WordPress support | not started | ~1,100 |
@ -35,6 +35,7 @@ By the raw estimates the alpha gate needs M1–M4 plus cross-platform verificati
| Date | Change | Summary |
|---|---|---|
| 2026-10-18 | minor | M7–M9 added from the full PhpStorm help inventory (155 feature units); raw hours, calibrate ×0.15 |
| 2026-10-19 | minor | M3.8 MCP server |
| 2026-10-17 | minor | M3.7 CLI and single instance |
| 2026-10-17 | minor | M2 done (C3 review), M3 ~12 h at ×0.15 |
| 2026-10-17 | minor | M2.6 go-to popup |