plonk-mcp 0.0.5 → 0.2.0

package/README.md

@@ -40,7 +40,10 @@ server. One-pagers for
 
 A client that cannot spawn a process connects over HTTP instead:
 `npx -y plonk-mcp --http` serves Streamable HTTP at
-`http://127.0.0.1:43918/mcp` (loopback only, `--port` to change).
+`http://127.0.0.1:43918/mcp` (loopback only, `--port` to change). Requests to
+it carry the same token as the app's own API — send the contents of
+`~/Library/Application Support/Plonk/token` as an `X-Plonk-Token` header. The
+stdio transport reads that file itself and needs no configuration.
 
 Several clients may be connected at once. Set `PLONK_AGENT_NAME` in a client's
 config to tell two sessions of the same client apart.
@@ -70,5 +73,10 @@ The server talks to the app over loopback HTTP on `127.0.0.1:43917` and nowhere
 else. No account, no cloud, no telemetry. It depends only on the official MCP
 SDK and zod.
 
+The app gates that API on a token it writes to
+`~/Library/Application Support/Plonk/token`. This server reads the file itself,
+so there is nothing to configure — but it does have to run as the same user
+Plonk is running as.
+
 MIT. Source, screenshots and the rest of the documentation are in the
 [repository](https://github.com/ostapondo/plonk).

package/dist/api.js

@@ -35,17 +35,90 @@ function agentHeaders() {
         "x-plonk-agent-pid": String(id.pid),
     };
 }
+// The app gates its API on a secret it writes to a file only this user can
+// read, because binding to loopback keeps the network out and does nothing
+// about the machine. Reading it is the whole handshake: anything that can read
+// the file could ask macOS for the screen directly.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const TOKEN_PATH = join(homedir(), "Library", "Application Support", "Plonk", "token");
+let cachedToken;
+function readTokenFile() {
+    try {
+        return readFileSync(TOKEN_PATH, "utf8").trim() || undefined;
+    }
+    catch {
+        // No app yet, or a file this user cannot read. The request goes without a
+        // token and the app's own 401 explains it better than a guess here would.
+        return undefined;
+    }
+}
+/** Only a successful read is cached: a client started before the app has ever
+ * run would otherwise never see the token the app writes on first launch. */
+function apiToken() {
+    if (cachedToken)
+        return cachedToken;
+    cachedToken = readTokenFile();
+    return cachedToken;
+}
+/** The token the HTTP transport gates its own callers on, read from disk every
+ * time rather than from the cache above.
+ *
+ * A cache here would be a gate on a secret the app may already have replaced:
+ * it would keep accepting the token a restored backup leaked — the exact one
+ * the app rotated away from — and keep refusing the current one, until this
+ * process was restarted. Nothing else could fix it, because the retry that
+ * refreshes the cache lives on the far side of this check and never runs when
+ * no session gets in. It is one small read per request on a transport that
+ * handles few. */
+export function localApiToken() {
+    const fresh = readTokenFile();
+    // Outgoing calls may as well learn about a rotation from the same read.
+    if (fresh !== undefined && fresh !== cachedToken)
+        cachedToken = fresh;
+    return fresh;
+}
+/** Drops the cache and reads again, true only when the file now holds
+ * something other than what this request actually sent — the one case where
+ * repeating a refused request can help.
+ *
+ * `sent` rather than the cache, because the cache is shared: the hello
+ * heartbeat and the inbox long-poll are always in flight beside a tool call,
+ * so after a rotation the first 401 refreshes the cache and every other
+ * request in the air would find it already fresh and give up, handing the
+ * model a token error for a token that had just been fixed. */
+function refreshToken(sent) {
+    cachedToken = undefined;
+    const fresh = apiToken();
+    return fresh !== undefined && fresh !== sent;
+}
 export async function call(path, options = {}) {
     const { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
     const timeout = AbortSignal.timeout(timeoutMs);
-    let res;
-    try {
-        res = await fetch(BASE + path, {
+    // Captured per attempt, so the retry can tell "the token changed" from
+    // "somebody else refreshed the cache while this request was in the air".
+    let sent;
+    const send = () => {
+        sent = apiToken();
+        return fetch(BASE + path, {
             method,
-            headers: { "content-type": "application/json", ...agentHeaders() },
+            headers: {
+                "content-type": "application/json",
+                ...agentHeaders(),
+                ...(sent ? { "x-plonk-token": sent } : {}),
+            },
             body: body !== undefined ? JSON.stringify(body) : undefined,
             signal: timeout,
         });
+    };
+    let res;
+    try {
+        res = await send();
+        // A long-lived client outlives the token if the file is ever replaced.
+        // One re-read makes that a hiccup instead of a session to restart.
+        if (res.status === 401 && refreshToken(sent))
+            res = await send();
     }
     catch (err) {
         if (timeout.aborted) {

package/dist/args.js

@@ -0,0 +1,32 @@
+// Argument parsing for the `plonk` command, kept out of cli.ts so it can be
+// tested without running the CLI: importing cli.ts runs it.
+/**
+ * Pulls "--name value" out of argv and returns what is left, in order.
+ *
+ * A flag with nothing usable after it — the end of argv, or another flag — is
+ * a switch and reads as "true", so `--json` and `--screen 1` parse the same
+ * way. Values are not converted here; the caller knows which of its flags are
+ * numbers and says so in the error when one is not.
+ */
+export function options(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                flags[key] = "true";
+            }
+            else {
+                flags[key] = next;
+                i++;
+            }
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { flags, rest };
+}

package/dist/cli.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// `plonk` — the same loopback API the MCP tools use, from a shell.
+//
+// Agents reach Plonk over MCP, and the settings window covers the rest, but
+// neither helps a script, a Raycast command or a Makefile. This is that gap:
+// every subcommand is one HTTP call to 127.0.0.1, and nothing here holds state.
+import { spawn } from "node:child_process";
+import { BASE, call, processIdentityHolder } from "./api.js";
+import { options } from "./args.js";
+const USAGE = `plonk — drive the Plonk menu bar app from a shell
+
+  plonk state [--json]              screens, windows, zone sets, workspaces
+  plonk snap <app> <zone>           drop a window into a numbered zone
+  plonk workspaces                  list saved workspaces
+  plonk launch <name> [--screen N]  launch one
+  plonk save <name>                 save the desktop as one
+  plonk zones [--screen N] <set>    assign a zone set to a monitor
+  plonk awake off
+  plonk awake on [--minutes N] [--until HH:MM] [--pid N]
+  plonk awake while <command...>    stay awake until that command exits
+  plonk text [--mode region|window|screen] [--path FILE]
+  plonk shot [--mode region|window|screen] [--path FILE]
+
+Everything talks to ${BASE}; Plonk.app has to be running.`;
+/** Unwinds to the top instead of calling process.exit, which on a pipe cuts
+ * stdout off mid-write: `plonk state --json | jq` would get invalid JSON.
+ * Letting the process end on its own flushes first. */
+class Exit extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+function fail(message) {
+    console.error(`plonk: ${message}`);
+    throw new Exit(1);
+}
+function number(raw, what) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value))
+        fail(`${what} must be a whole number, got "${raw}"`);
+    return value;
+}
+/** Prints the reply and exits non-zero when the app refused. */
+function report(result) {
+    if ("error" in result) {
+        console.error(`plonk: ${result.error}`);
+        throw new Exit(1);
+    }
+    console.log(JSON.stringify(result, null, 2));
+    throw new Exit(0);
+}
+async function summarize() {
+    const state = await call("/state");
+    if ("error" in state)
+        report(state);
+    const lines = [];
+    lines.push(`awake     ${state.awake_details.status}`);
+    lines.push(`screens   ${state.screens.length}`);
+    for (const screen of state.screens) {
+        const set = state.screen_zone_sets[String(screen.index)];
+        const zones = set === "" ? "edge snapping" : (set ?? "Halves");
+        lines.push(`  ${screen.index}: ${Math.round(screen.frame.w)}x${Math.round(screen.frame.h)}  ${zones}`);
+    }
+    lines.push(`workspaces ${state.saved_layouts.join(", ") || "none"}`);
+    lines.push(`zone sets  ${Object.keys(state.zone_sets).sort().join(", ")}`);
+    if (state.excluded_apps?.length)
+        lines.push(`excluded   ${state.excluded_apps.join(", ")}`);
+    lines.push(`windows   ${state.windows.length}`);
+    for (const window of state.windows) {
+        lines.push(`  ${window.app}${window.title ? ` — ${window.title}` : ""} [screen ${window.screen}]`);
+    }
+    console.log(lines.join("\n"));
+    throw new Exit(0);
+}
+/** Runs a command with its output passed through, holding keep-awake for
+ * exactly as long as it lives. The exit status is the command's own, so this
+ * drops into a Makefile without changing what a failure means. */
+async function awakeWhile(argv) {
+    if (argv.length === 0)
+        fail("awake while needs a command to run");
+    const child = spawn(argv[0], argv.slice(1), { stdio: "inherit" });
+    // Both listeners go on before the round trip below: a command that finishes
+    // inside it — `plonk awake while echo hi` — would otherwise fire exit into
+    // an empty room and hang here forever.
+    const finished = new Promise((resolve) => {
+        child.on("error", (err) => {
+            console.error(`plonk: could not run ${argv[0]}: ${err.message}`);
+            resolve(1);
+        });
+        child.on("exit", (code, signal) => resolve(signal ? 1 : (code ?? 0)));
+    });
+    // No pid means the spawn failed outright. Asking for keep-awake without one
+    // would hold an assertion nothing ever releases.
+    if (child.pid !== undefined) {
+        const started = await call("/awake", { method: "POST", body: { on: true, pid: child.pid } });
+        if ("error" in started) {
+            console.error(`plonk: keep-awake not held — ${started.error}`);
+        }
+    }
+    // Plonk drops the assertion itself when the process goes; waiting here only
+    // makes the shell finish at the same moment.
+    throw new Exit(await finished);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    // Everything after `awake while` belongs to the command being run, flags
+    // included, so it is taken verbatim rather than parsed for plonk's own.
+    // Otherwise `plonk awake while cargo build --release` builds in debug.
+    if (argv[0] === "awake" && argv[1] === "while")
+        await awakeWhile(argv.slice(2));
+    const { flags, rest } = options(argv);
+    const [command, ...args] = rest;
+    const screen = number(flags.screen, "--screen");
+    switch (command) {
+        case undefined:
+        case "help":
+        case "-h":
+        case "--help":
+            console.log(USAGE);
+            return;
+        case "ping":
+            report(await call("/ping"));
+            break;
+        case "state":
+            if (flags.json)
+                report(await call("/state"));
+            await summarize();
+            break;
+        case "snap": {
+            const [app, zone] = args;
+            if (!app || zone === undefined)
+                fail("snap needs an app and a zone number, e.g. plonk snap Safari 1");
+            report(await call("/layout/zone", {
+                method: "POST",
+                body: { app, zone: number(zone, "zone"), screen },
+            }));
+            break;
+        }
+        case "workspaces": {
+            const state = await call("/state");
+            if ("error" in state)
+                report(state);
+            console.log(state.saved_layouts.join("\n"));
+            return;
+        }
+        case "launch":
+            if (!args[0])
+                fail("launch needs a workspace name");
+            report(await call("/workspaces/launch", {
+                method: "POST",
+                body: { name: args[0], screen },
+                timeoutMs: 90_000,
+            }));
+            break;
+        case "save":
+            if (!args[0])
+                fail("save needs a name for the workspace");
+            report(await call("/workspaces/save", { method: "POST", body: { name: args[0] } }));
+            break;
+        case "zones":
+            if (!args[0])
+                fail("zones needs a set name, or 'edge' for edge snapping");
+            report(await call("/zones/assign", { method: "POST", body: { screen: screen ?? 0, name: args[0] } }));
+            break;
+        case "awake": {
+            // `while` is handled before flags are parsed; anything else must be on/off.
+            if (args[0] !== "on" && args[0] !== "off")
+                fail("awake needs 'on', 'off' or 'while <command>'");
+            report(await call("/awake", {
+                method: "POST",
+                body: {
+                    on: args[0] === "on",
+                    minutes: number(flags.minutes, "--minutes"),
+                    until: flags.until,
+                    pid: number(flags.pid, "--pid"),
+                },
+            }));
+            break;
+        }
+        case "text": {
+            const result = await call("/shot/text", {
+                method: "POST",
+                body: { mode: flags.mode ?? "region", path: flags.path },
+                timeoutMs: 5 * 60_000,
+            });
+            if ("error" in result)
+                report(result);
+            // Bare text, so it can be piped.
+            console.log(result.text ?? "");
+            return;
+        }
+        case "shot":
+            report(await call("/shot/capture", {
+                method: "POST",
+                body: { mode: flags.mode ?? "region", path: flags.path },
+                timeoutMs: 5 * 60_000,
+            }));
+            break;
+        default:
+            fail(`unknown command "${command}"\n\n${USAGE}`);
+    }
+}
+// Named so the app can attribute the calls, and so "only the active agent
+// controls" can be pointed at the shell like anything else.
+processIdentityHolder().identity = { name: "plonk-cli", version: "", pid: process.pid };
+try {
+    await main();
+}
+catch (err) {
+    if (!(err instanceof Exit))
+        throw err;
+    process.exitCode = err.code;
+}

package/dist/factory.js

@@ -10,6 +10,7 @@ import { register as registerZones } from "./tools/zones.js";
 import { register as registerAwake } from "./tools/awake.js";
 import { register as registerScreenshot } from "./tools/screenshot.js";
 import { register as registerAnnotate } from "./tools/annotate.js";
+import { register as registerText } from "./tools/text.js";
 import { register as registerAgents } from "./tools/agents.js";
 import { register as registerUpdate } from "./tools/update.js";
 const { version } = createRequire(import.meta.url)("../package.json");
@@ -22,6 +23,7 @@ export function createPlonkServer() {
     registerAwake(server);
     registerScreenshot(server);
     registerAnnotate(server);
+    registerText(server);
     registerAgents(server);
     registerUpdate(server);
     return server;

package/dist/http.js

@@ -3,13 +3,22 @@
 // threat model as the app's own API: a web page must never be able to drive
 // the desktop, and a DNS-rebinding page must not reach the port by Host games.
 import { createServer } from "node:http";
-import { randomUUID } from "node:crypto";
+import { randomUUID, timingSafeEqual } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { runWithIdentity } from "./api.js";
+import { localApiToken, runWithIdentity } from "./api.js";
 import { createPlonkServer, startHello, startInboxLoop, watchClientInfo } from "./factory.js";
 // The app's registry tells sessions apart by (name, pid). Every HTTP client
 // shares this process, so each session gets a synthetic pid instead.
 let syntheticPid = 100_000 + (process.pid % 1_000) * 100;
+function headerToken(req) {
+    const value = req.headers["x-plonk-token"];
+    return (Array.isArray(value) ? value[0] : value) ?? "";
+}
+/** Length is not the secret; which byte differed would be. */
+function timingSafeEqualString(presented, token) {
+    const a = Buffer.from(presented, "utf8"), b = Buffer.from(token, "utf8");
+    return a.length === b.length && a.length > 0 && timingSafeEqual(a, b);
+}
 function reject(res, status, error) {
     res.writeHead(status, { "content-type": "application/json" });
     res.end(JSON.stringify({ error }));
@@ -32,6 +41,20 @@ export async function serveHttp(port) {
             reject(res, 404, "the MCP endpoint is /mcp");
             return;
         }
+        // This process holds the app's token, so without a gate of its own it is a
+        // way around the app's: anything local could call take_screenshot through
+        // it and borrow Screen Recording. Same secret, same header, same file —
+        // there is nothing extra for a client to be given.
+        const token = localApiToken();
+        if (!token) {
+            reject(res, 503, "no Plonk API token could be read, so this transport is answering nothing");
+            return;
+        }
+        if (!timingSafeEqualString(headerToken(req), token)) {
+            reject(res, 401, "this request carried no valid token; send the contents of " +
+                "~/Library/Application Support/Plonk/token as the X-Plonk-Token header");
+            return;
+        }
         const sessionId = req.headers["mcp-session-id"];
         const existing = typeof sessionId === "string" ? sessions.get(sessionId) : undefined;
         if (existing) {

package/dist/tools/awake.js

@@ -1,8 +1,21 @@
 import { z } from "zod";
 import { call, text } from "../api.js";
 export function register(server) {
-    server.tool("set_awake", "Turn keep-awake on or off. Optional 'minutes' limits the session (it ends automatically). Behavior also follows the user's settings: keep-awake may pause on battery or engage automatically while charging; the returned 'status' explains the current state. The menu bar icon glows while active.", {
+    server.tool("set_awake", "Turn keep-awake on or off, so the Mac does not sleep part-way through something. " +
+        "Three ways to end the session, in order of preference: 'pid' ends it the moment that process exits — best by far when something is running, because a build or a render knows when it is finished and nothing is left holding the machine awake afterwards; 'until' ends it at a wall-clock time ('17:00', or an ISO-8601 timestamp); 'minutes' ends it after a countdown. Give none of them and it runs until switched off. " +
+        "Behavior also follows the user's settings: keep-awake may pause on battery or engage automatically while charging, so the returned 'status' is what actually happened and 'awake' is whether an assertion is held right now. The menu bar icon glows while it is. " +
+        "A process-bound session is deliberately not restored if Plonk restarts, since the pid would mean nothing by then. Errors come back for a pid that is not running or a time that has already passed.", {
         on: z.boolean(),
-        minutes: z.number().int().min(1).optional().describe("Auto-off after this many minutes"),
-    }, async ({ on, minutes }) => text(await call("/awake", { method: "POST", body: { on, minutes } })));
+        minutes: z.number().int().min(1).optional().describe("End the session after this many minutes"),
+        until: z
+            .string()
+            .optional()
+            .describe("End at a time of day, e.g. '17:00' (the next such moment — tomorrow if today's has passed), or an ISO-8601 timestamp like '2026-08-08T17:00:00Z'"),
+        pid: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe("End when this process exits. Use the pid of the long job being waited on; get_state lists a pid for every open window"),
+    }, async ({ on, minutes, until, pid }) => text(await call("/awake", { method: "POST", body: { on, minutes, until, pid } })));
 }

package/dist/tools/text.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { call, text } from "../api.js";
+// The interactive mode hands the user a crosshair and waits for them.
+const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
+export function register(server) {
+    server.tool("extract_text", "Read the words off the screen, or off a saved image, and return them as text. Recognition runs on the Mac itself and nothing is uploaded. " +
+        "Prefer this over take_screenshot whenever the answer is words rather than a picture — an error dialog, a log, a terminal, a table, text baked into an image or a paused video, a PDF page in a viewer that will not let text be selected. It costs a fraction of the tokens an image does and does not depend on reading pixels correctly. " +
+        "Use take_screenshot instead when layout, colour or 'what does this look like' is the question. " +
+        "mode 'screen' captures everything with no user interaction; 'region' and 'window' hand the user the native crosshair or window picker and wait for them, up to five minutes. Pass 'path' instead of a mode to read an image already on disk, including one take_screenshot just wrote. " +
+        "Returns 'text' (every line in reading order, top to bottom) and 'lines' — each with the recognized string, Vision's 0..1 'confidence', and 'box' {x,y,w,h} as fractions 0..1 of the image with origin at TOP-LEFT. Those boxes share the coordinate space annotate_screenshot draws in, so a line can be circled where it was found by passing the same path to that tool. The text is also copied to the clipboard unless 'clipboard' is false. " +
+        "An area with no readable text returns ok with an empty 'text' and a 'note' rather than an error.", {
+        mode: z
+            .enum(["screen", "region", "window"])
+            .default("region")
+            .describe("What to capture; ignored when 'path' is given"),
+        path: z.string().optional().describe("Read this image file instead of capturing (.png, .jpg)"),
+        clipboard: z.boolean().optional().describe("Copy the recognized text to the clipboard (default true)"),
+        languages: z
+            .array(z.string())
+            .optional()
+            .describe("BCP-47 tags to recognize, most likely first, e.g. ['uk-UA','en-US']. Omit to use the user's configured choice. Which are available depends on the macOS version; get_state lists the current setting under 'text_languages'"),
+    }, async ({ mode, path, clipboard, languages }) => text(await call("/shot/text", {
+        method: "POST",
+        body: { mode, path, clipboard, languages },
+        timeoutMs: path || mode === "screen" ? 60_000 : INTERACTIVE_TIMEOUT_MS,
+    })));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.0.5",
+  "version": "0.2.0",
   "mcpName": "io.github.ostapondo/plonk",
   "description": "MCP server for Plonk — the Mac window manager your AI agent can drive. Layouts, workspaces, snap zones, keep-awake and screenshots.",
   "type": "module",
@@ -28,13 +28,15 @@
     "dist"
   ],
   "bin": {
-    "plonk-mcp": "dist/server.js"
+    "plonk-mcp": "dist/server.js",
+    "plonk": "dist/cli.js"
   },
   "main": "dist/server.js",
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "tsc",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "tsc && node --test test/*.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",