plonk-mcp 0.0.4 → 0.1.0

package/dist/cli.js

@@ -0,0 +1,239 @@
+#!/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";
+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.`;
+/** Pulls "--name value" out of argv and returns what is left. */
+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 };
+}
+/** 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/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.4",
+  "version": "0.1.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",
@@ -21,9 +21,16 @@
     "workspaces",
     "screenshots"
   ],
-  "engines": { "node": ">=18" },
-  "files": ["dist"],
-  "bin": { "plonk-mcp": "dist/server.js" },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "plonk-mcp": "dist/server.js",
+    "plonk": "dist/cli.js"
+  },
   "main": "dist/server.js",
   "scripts": {
     "build": "tsc",