Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

feat(mcp): tell the agent when a newer OpenScreen is out

EtienneLescot201d52950206
diff --git a/electron/cli/cliMain.ts b/electron/cli/cliMain.ts
index 410ba9745..3c23e5323 100644
--- a/electron/cli/cliMain.ts
+++ b/electron/cli/cliMain.ts
@@ -5,14 +5,15 @@
import fs from "node:fs/promises";
import path from "node:path";
import readline from "node:readline";
-import { app, BrowserWindow, ipcMain, Menu, session, systemPreferences } from "electron";
+import { app, BrowserWindow, ipcMain, Menu, net, session, systemPreferences } from "electron";
import type { CliProgressEvent, CliSourcesResult } from "../../src/lib/cliContracts";
import { renameWithRetry } from "../atomic-rename";
import { isDiagnosticModeEnabled } from "../diagnostics/main-log-buffer";
-import { getInstallChannel } from "../install-channel";
+import { getInstallChannel, ownsItsUpdates } from "../install-channel";
import { getSelectedDesktopSource, registerIpcHandlers } from "../ipc/handlers";
import { openVideoInHiddenWindow } from "../mcp/hidden-video";
import { serveMcpOverStdio } from "../mcp/stdio-server";
+import { readReleaseLookup, refreshReleaseLookup, updateNotice } from "../mcp/update-notice";
import { registerSttIpc, shutdownStt } from "../stt";
import { sendUsagePing, USAGE_PING_INTERVAL_MS } from "../usage-ping";
import { createRunnerWindow } from "../windows";
@@ -402,15 +403,31 @@ export function runCli(command: CliCommand): void {
});
if (command.kind === "mcp") {
+ // Only where the app updates itself: elsewhere a package manager already does, and
+ // opening the app would not change that.
+ const tellsAboutUpdates = app.isPackaged && ownsItsUpdates(getInstallChannel());
await serveMcpOverStdio({
...agentServices,
userDataDir,
runners,
openVideo: openVideoInHiddenWindow,
+ updateNotice: tellsAboutUpdates
+ ? (updateNotice(app.getVersion(), readReleaseLookup(userDataDir)) ?? undefined)
+ : undefined,
// The Whisper helper is a process of its own: it must not outlive this one.
onClose: () => void shutdownStt().finally(() => app.exit(0)),
});
milestone("mcp server listening on stdio");
+ if (tellsAboutUpdates) {
+ refreshReleaseLookup({
+ userData: userDataDir,
+ currentVersion: app.getVersion(),
+ fetchLatest: (url, init) => net.fetch(url, init),
+ }).catch(() => {
+ // Offline or rate-limited: the next session looks again. Nothing to report,
+ // and stdout is the protocol.
+ });
+ }
// An install driven only by an agent is an active install too. Same ping, state
// file and opt-outs as the GUI's, and it writes nothing: stdout is the protocol.
// The other commands stay silent: they are scripts and CI more often than people.
diff --git a/electron/mcp/openscreen-mcp-server.ts b/electron/mcp/openscreen-mcp-server.ts
index c73378b6a..774f3ccde 100644
--- a/electron/mcp/openscreen-mcp-server.ts
+++ b/electron/mcp/openscreen-mcp-server.ts
@@ -177,6 +177,9 @@ export interface McpToolDeps extends ImportMediaDeps {
/** The main process's on-device Whisper (`SttManager.transcribe`). Absent: no transcribe tool. */
transcribe?(request: SttTranscribeRequest): Promise<SttTranscribeResponse>;
version: string;
+ /** `openscreen mcp` only: a newer OpenScreen to tell the user about, for the user who never
+ * opens the app and so never sees its update button. */
+ updateNotice?: string;
}
export const LIST_PROJECTS_TOOL = "listProjects";
@@ -287,9 +290,13 @@ export function mcpInstructions(options: {
media?: string;
/** The transcribe tool is served. */
transcribe?: boolean;
+ /** A newer OpenScreen to tell the user about (update-notice.ts). First, so it is not lost
+ * under the editing guidance. */
+ updateNotice?: string;
}): string {
const { transport, editsAllowed, media } = options;
const preamble = [
+ ...(options.updateNotice ? [options.updateNotice] : []),
...(media ? [media] : []),
...CORE_PREAMBLES[transport],
CHECKPOINT_LIFETIMES[transport],
@@ -860,6 +867,7 @@ export function createOpenScreenMcpServer(
editsAllowed: deps.editsAllowed(),
media: media?.preamble,
transcribe: deps.transcribe !== undefined,
+ updateNotice: deps.updateNotice,
}),
},
);
diff --git a/electron/mcp/stdio-server.ts b/electron/mcp/stdio-server.ts
index e38e66ece..e0c245bf6 100644
--- a/electron/mcp/stdio-server.ts
+++ b/electron/mcp/stdio-server.ts
@@ -32,6 +32,8 @@ export async function serveMcpOverStdio(options: {
runners: MediaToolDeps["runners"];
openVideo: MediaToolDeps["openVideo"];
renderFrames?: MediaToolDeps["renderFrames"];
+ /** A newer OpenScreen to tell the agent about (update-notice.ts). */
+ updateNotice?: string;
/** The client went away: nothing is left to serve. */
onClose(): void;
}): Promise<void> {
@@ -39,6 +41,7 @@ export async function serveMcpOverStdio(options: {
...options.mcpToolDeps,
transport: "stdio",
editsAllowed: () => true,
+ updateNotice: options.updateNotice,
};
// The media tools' own document calls (stopRecording's checkpoint, setPointerTrack)
// take the same route.
diff --git a/electron/mcp/update-notice.test.ts b/electron/mcp/update-notice.test.ts
new file mode 100644
index 000000000..b4ce6947b
--- /dev/null
+++ b/electron/mcp/update-notice.test.ts
@@ -0,0 +1,106 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { mcpInstructions } from "./openscreen-mcp-server";
+import {
+ RELEASE_LOOKUP_INTERVAL_MS,
+ readReleaseLookup,
+ refreshReleaseLookup,
+ updateNotice,
+} from "./update-notice";
+
+const dirs: string[] = [];
+afterEach(() => {
+ for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+ dirs.length = 0;
+});
+function userData(): string {
+ const dir = mkdtempSync(path.join(os.tmpdir(), "os-mcp-update-"));
+ dirs.push(dir);
+ return dir;
+}
+
+function release(tag: string) {
+ return vi.fn(async () => ({
+ ok: true,
+ status: 200,
+ json: async () => ({
+ tag_name: tag,
+ html_url: `https://github.com/getopenscreen/openscreen/releases/tag/${tag}`,
+ draft: false,
+ prerelease: false,
+ }),
+ }));
+}
+
+describe("updateNotice", () => {
+ it("says nothing without a lookup, or when the running version is the latest or newer", () => {
+ expect(updateNotice("2.1.2", null)).toBeNull();
+ expect(updateNotice("2.1.2", { latestVersion: "2.1.2", checkedAt: 0 })).toBeNull();
+ expect(updateNotice("2.2.0-rc.1", { latestVersion: "2.1.2", checkedAt: 0 })).toBeNull();
+ });
+
+ it("says nothing rather than throw on a version it cannot read", () => {
+ expect(updateNotice("2.1.2", { latestVersion: "not-a-version", checkedAt: 0 })).toBeNull();
+ });
+
+ // The user updates, not the agent: the line hands them the news and keeps the agent off it.
+ it("names both versions and leaves the update to the user", () => {
+ const notice = updateNotice("2.1.2", { latestVersion: "2.2.0", checkedAt: 0 });
+ expect(notice).toContain("OpenScreen 2.2.0 is available; this is 2.1.2.");
+ expect(notice).toContain("opening the OpenScreen app");
+ expect(notice).toContain("Never update OpenScreen yourself.");
+ });
+
+ it("opens the stdio instructions, ahead of the editing guidance", () => {
+ const instructions = mcpInstructions({
+ transport: "stdio",
+ editsAllowed: true,
+ updateNotice: "OpenScreen 2.2.0 is available.",
+ });
+ expect(instructions.startsWith("OpenScreen 2.2.0 is available.\n")).toBe(true);
+ expect(mcpInstructions({ transport: "stdio", editsAllowed: true })).not.toContain(
+ "is available",
+ );
+ });
+});
+
+describe("refreshReleaseLookup", () => {
+ it("stores the latest release for the next session to read", async () => {
+ const dir = userData();
+ await refreshReleaseLookup({
+ userData: dir,
+ currentVersion: "2.1.2",
+ fetchLatest: release("v2.2.0"),
+ now: 1000,
+ });
+ expect(readReleaseLookup(dir)).toEqual({ latestVersion: "2.2.0", checkedAt: 1000 });
+ });
+
+ it("asks GitHub at most once per interval", async () => {
+ const dir = userData();
+ const fetchLatest = release("v2.2.0");
+ await refreshReleaseLookup({ userData: dir, currentVersion: "2.1.2", fetchLatest, now: 0 });
+ await refreshReleaseLookup({
+ userData: dir,
+ currentVersion: "2.1.2",
+ fetchLatest,
+ now: RELEASE_LOOKUP_INTERVAL_MS - 1,
+ });
+ expect(fetchLatest).toHaveBeenCalledTimes(1);
+ await refreshReleaseLookup({
+ userData: dir,
+ currentVersion: "2.1.2",
+ fetchLatest,
+ now: RELEASE_LOOKUP_INTERVAL_MS,
+ });
+ expect(fetchLatest).toHaveBeenCalledTimes(2);
+ });
+
+ it("reads a corrupt cache as no lookup at all", () => {
+ const dir = userData();
+ writeFileSync(path.join(dir, "mcp-update-check.json"), "{not json");
+ expect(readReleaseLookup(dir)).toBeNull();
+ });
+});
diff --git a/electron/mcp/update-notice.ts b/electron/mcp/update-notice.ts
new file mode 100644
index 000000000..2d4d3c5a9
--- /dev/null
+++ b/electron/mcp/update-notice.ts
@@ -0,0 +1,64 @@
+// What `openscreen mcp` tells the agent about a newer OpenScreen, for the user who only ever
+// reaches OpenScreen through an agent and so never sees the app's update button.
+//
+// This process updates nothing. Its stdout is the protocol, its lifetime is the client's, and an
+// installer would end it mid-session. It only looks the latest release up, at most every six
+// hours, and says so in its instructions; the agent passes it on, and the user updates. The
+// lookup runs in the background and is cached, so the handshake never waits on the network: the
+// session that finds a release says nothing, the next one does.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { checkLatestRelease, compareVersions } from "../update-checker";
+
+const CACHE_FILE = "mcp-update-check.json";
+export const RELEASE_LOOKUP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+
+interface ReleaseLookup {
+ latestVersion: string;
+ checkedAt: number;
+}
+
+type FetchLatest = Parameters<typeof checkLatestRelease>[0]["fetchLatest"];
+
+export function readReleaseLookup(userData: string): ReleaseLookup | null {
+ try {
+ const raw = JSON.parse(readFileSync(path.join(userData, CACHE_FILE), "utf8")) as unknown;
+ const { latestVersion, checkedAt } = (raw ?? {}) as Partial<ReleaseLookup>;
+ if (typeof latestVersion !== "string" || typeof checkedAt !== "number") return null;
+ return { latestVersion, checkedAt };
+ } catch {
+ return null;
+ }
+}
+
+/** The line for the instructions, or null when there is nothing newer to tell. */
+export function updateNotice(currentVersion: string, lookup: ReleaseLookup | null): string | null {
+ if (!lookup) return null;
+ try {
+ if (compareVersions(lookup.latestVersion, currentVersion) <= 0) return null;
+ } catch {
+ return null;
+ }
+ return `OpenScreen ${lookup.latestVersion} is available; this is ${currentVersion}. Tell the user once, when it fits, that they can install it by opening the OpenScreen app. Never update OpenScreen yourself.`;
+}
+
+/** Looks the latest release up if the cached answer is older than the interval. Throws on a
+ * network or GitHub failure; the caller drops it, as the next session tries again. */
+export async function refreshReleaseLookup(options: {
+ userData: string;
+ currentVersion: string;
+ fetchLatest: FetchLatest;
+ now?: number;
+}): Promise<void> {
+ const now = options.now ?? Date.now();
+ const cached = readReleaseLookup(options.userData);
+ if (cached && now - cached.checkedAt < RELEASE_LOOKUP_INTERVAL_MS) return;
+ const result = await checkLatestRelease({
+ currentVersion: options.currentVersion,
+ fetchLatest: options.fetchLatest,
+ signal: AbortSignal.timeout(10_000),
+ });
+ const lookup: ReleaseLookup = { latestVersion: result.latestVersion, checkedAt: now };
+ writeFileSync(path.join(options.userData, CACHE_FILE), `${JSON.stringify(lookup)}\n`, "utf8");
+}
diff --git a/technical-documentation/architecture/mcp-server.md b/technical-documentation/architecture/mcp-server.md
index 446212da4..7165ec2b0 100644
--- a/technical-documentation/architecture/mcp-server.md
+++ b/technical-documentation/architecture/mcp-server.md
@@ -64,6 +64,7 @@ The server's one resource, `openscreen://effects/contract` ([`effects-contract.t
Every text a client reads must be true on the server that serves it, so the texts are composed rather than shared verbatim. `McpToolDeps.transport` (`"http"` or `"stdio"`) selects them:
- **Instructions** (`mcpInstructions`): the media tools' capability block (`mediaPreamble`), then the projects-and-checkpoints rules of the transport, then how long checkpoints live there, then `buildSystemPrompt`. The checkpoint rule is in both. Over HTTP the media block says a take goes through the app's recording bar and opens in the editor, and the rules speak of the editor and its undo stack; while **MCP edits** is off, a line says `startRecording`, `exportVideo` and `createProject` are refused too. Over stdio the media block says the takes land in the app's project list, and the rules say that calls go through the app while it runs (the open project live, with `Ctrl/Cmd+Z`), and to the files when it does not.
+- **A newer OpenScreen** (`update-notice.ts`), stdio only, and only on an install that updates itself (a Store, Flathub, Snap or Nix copy is kept current by its package manager). A user who reaches OpenScreen only through an agent never sees the app's update button, so `openscreen mcp` looks the latest release up on GitHub, at most every six hours, in the background and cached in `mcp-update-check.json`. When the cache names a newer version, a line opens the instructions: tell the user once that opening the app installs it, and never update OpenScreen yourself. The process itself updates nothing: its stdout is the protocol, its lifetime is the client's, and the NSIS installer would end it. The lookup never holds the handshake back, so the session that finds a release says nothing and the next one does.
- **`buildSystemPrompt`** takes the transport's facts as options: `editsSetting` names the switch its consent block points to (the MCP server's **MCP edits**, not the in-app agent's **Agent edits**), and `canExport` drops "exporting" from its examples of a request with no tool, since both serve `exportVideo`.
- **Tool descriptions**: `projectId` is "omit it for the open project" over HTTP and "omit it only for the open project, while the app runs" over stdio. `startRecording` and `stopRecording` say how each server makes a take ([below](#the-media-tools)), and the paths of `exportVideo` and `getFrames` must be absolute over HTTP: the app has no working directory of the client's.
- **Messages**: no project to fall back on, a checkpoint required, an unknown checkpoint, edits turned off. Each has a version per transport, or exists only on the one that can produce it. The stdio versions are only met with no app answering, and say so.