From c24237170dd5992b5868b4b7825e5a84c1b50666 Mon Sep 17 00:00:00 2001 From: Robert M1 <50460704+githubrobbi@users.noreply.github.com> Date: Thu, 18 Jun 2026 10:26:10 -0700 Subject: [PATCH] feat(mcp): read-only freshness signal + honest stale-session messaging MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two coupled changes so version-freshness is surfaced to the audience that can actually act on it — the LLM host — and not as false hope to a human. 1. uffs --status no longer tells a human to `uffs --mcp reload` stale stdio sessions. Those sessions are spawned and OWNED by their AI host (Claude/Cursor/…); a human reload only severs the host's live link. The line now just states the fact: "These run an older binary; the AI host that launched them refreshes on its next start." (The managed HTTP gateway hint is unchanged — that one IS user-restartable.) 2. The MCP surface gains a read-only freshness signal for the agent: - uffs_status structured output adds `server_version` (the running uffsmcp build), and the text output prints it too. - AGENT_INSTRUCTIONS gain a STAYING CURRENT note: UFFS self-updates; `uffs --update` is a quick one-shot the USER runs; if staying current matters, SUGGEST it — never run it (tools stay read-only); a version bump shows up on the agent's next launch, not mid-session. No new mutating tools — the all-read-only contract is intact. No network calls added (server_version is the compiled-in version). Co-Authored-By: Claude Opus 4.8 --- crates/uffs-cli/src/commands/system_status.rs | 9 ++++++++- crates/uffs-mcp/src/handler/instructions.rs | 12 +++++++++++- crates/uffs-mcp/src/schemas.rs | 5 +++++ crates/uffs-mcp/src/tools/status.rs | 7 ++++++- 4 files changed, 30 insertions(+), 3 deletions(-) diff --git a/crates/uffs-cli/src/commands/system_status.rs b/crates/uffs-cli/src/commands/system_status.rs index af51c4835..163f43537 100644 --- a/crates/uffs-cli/src/commands/system_status.rs +++ b/crates/uffs-cli/src/commands/system_status.rs @@ -388,7 +388,14 @@ fn print_mcp_stdio_sessions() { ); } if any_stale { - println!(" Run `uffs --mcp reload` to restart stale sessions."); + // Deliberately NO action hint: these stdio sessions are spawned and + // OWNED by their AI host (Claude/Cursor/…), not by the user. A human + // running `uffs --mcp reload` would only sever the host's live link — + // false hope. The host picks up the new binary when it next relaunches + // the session; the agent is told this via the MCP server instructions. + println!( + " These run an older binary; the AI host that launched them refreshes on its next start." + ); } } diff --git a/crates/uffs-mcp/src/handler/instructions.rs b/crates/uffs-mcp/src/handler/instructions.rs index 5faa4ec83..f5c28f09f 100644 --- a/crates/uffs-mcp/src/handler/instructions.rs +++ b/crates/uffs-mcp/src/handler/instructions.rs @@ -35,7 +35,8 @@ TOOLS (all read-only): what exists. • uffs_info — Full metadata for a single file/directory by path. • uffs_drives — List indexed drives with record counts. -• uffs_status — Daemon health, uptime, memory, loading progress. +• uffs_status — Daemon health, uptime, memory, loading progress, and the \ + running UFFS server version (see STAYING CURRENT). QUERY STRATEGY (minimize round-trips): 1. Start with uffs_aggregate preset='overview' to get the lay of the land. @@ -124,4 +125,13 @@ paths, and metadata. For content search, suggest ripgrep or similar. PROMPTS (guided multi-step workflows): find_large_files, find_by_extension, disk_usage_report, cleanup_report, \ recent_changes, duplicate_investigation, subtree_analysis. + +STAYING CURRENT: +uffs_status reports `server_version` — the UFFS build serving you. UFFS ships \ +frequent improvements and can self-update. Treat `uffs --update` as a quick, \ +safe, one-shot refresh the USER runs themselves (it stops/swaps binaries) — so \ +if it's worth staying current, SUGGEST it to the user; never run it yourself \ +(these tools are read-only). Note: an update refreshes the on-disk binaries, \ +but YOUR session keeps its current `server_version` until its host relaunches \ +the MCP server — so a version bump shows up on your next launch, not mid-session. "; diff --git a/crates/uffs-mcp/src/schemas.rs b/crates/uffs-mcp/src/schemas.rs index f7205a242..5acfb7baf 100644 --- a/crates/uffs-mcp/src/schemas.rs +++ b/crates/uffs-mcp/src/schemas.rs @@ -131,6 +131,11 @@ pub(crate) struct StatusOutput { pub connections: usize, /// Daemon process ID. pub pid: u32, + /// Version of the running `uffsmcp` server binary (e.g. `"0.6.10"`). Lets + /// an agent see which UFFS build is serving it. UFFS can self-update, + /// so an occasional `uffs --update` (run by the user) keeps + /// capabilities current — see the server instructions. + pub server_version: String, } // ── uffs_aggregate ────────────────────────────────────────────────── diff --git a/crates/uffs-mcp/src/tools/status.rs b/crates/uffs-mcp/src/tools/status.rs index d9aa5e8fb..1d4432dfa 100644 --- a/crates/uffs-mcp/src/tools/status.rs +++ b/crates/uffs-mcp/src/tools/status.rs @@ -22,8 +22,12 @@ pub(crate) async fn run(client: &mut UffsClient) -> Result Result