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:
parent
51eba0b3cb
commit
0e56c22b66
24 changed files with 3055 additions and 18 deletions
|
|
@ -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) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue