plonk-mcp 0.3.5 → 0.4.0

package/README.md

@@ -1,10 +1,10 @@
 # plonk-mcp
 
 The MCP server for [Plonk](https://github.com/ostapondo/plonk), a macOS menu bar
-app that is ten utilities at once, a window manager among them. It lets an agent
-work the desk: apply layouts across monitors, save and relaunch workspaces, snap
-windows into zones, keep the screen awake, take and annotate screenshots, and
-read text off the screen without uploading a pixel.
+app that is eight utilities at once, a window manager among them. It lets an
+agent work the desk: apply layouts across monitors, save and relaunch
+workspaces, snap windows into zones, keep the screen awake, take and annotate
+screenshots, and read text off the screen without uploading a pixel.
 
 > browser on the left 60%, terminal top right, notes bottom right
 >
@@ -54,11 +54,14 @@ config to tell two sessions of the same client apart.
 | | |
 | --- | --- |
 | `get_state` | Monitors, every open window and where it sits, zone sets, saved workspaces, awake status |
-| `apply_layout` · `snap_window` | Place windows by fraction of a screen, or drop one into a numbered zone |
+| `apply_layout` · `snap_window` | Place windows by fraction of a screen, or drop one into a zone by number or by name |
 | `save_workspace` · `launch_workspace` · `delete_workspace` | Named desktops that reopen their apps and restore every window |
 | `save_zone_set` · `assign_zone_set` · `delete_zone_set` | Snap zones, assigned per monitor |
+| `set_app_rule` · `clear_app_rule` | Where an app's new windows open: a zone, and optionally a monitor |
 | `set_awake` | Keep the Mac awake, optionally time-limited, optionally also holding your chat status at available |
 | `take_screenshot` · `annotate_screenshot` | Capture, mark up, hand the image back — `mode: "app"` photographs one named window even when it is buried, without raising it |
+| `extract_text` | Read the words off the screen, with a box per line in the same coordinates `annotate_screenshot` draws in |
+| `measure_screen` | How far a point can travel each way before it meets an edge, or the distance between two points, in points and pixels |
 | `select_agent` | Make an agent the active one, optionally the only one allowed to control |
 | `check_for_update` · `install_update` | Ask GitHub for a newer release and install it |
 

package/dist/cli.js

@@ -8,10 +8,11 @@ import { spawn } from "node:child_process";
 import { BASE, call, INTERACTIVE_TIMEOUT_MS, processIdentityHolder } from "./api.js";
 import { options } from "./args.js";
 import { CLI_NAME } from "./messages.js";
+import { PACKAGE_VERSION } from "./version.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 snap <app> <zone>           drop a window into a zone, by number or name
   plonk workspaces                  list saved workspaces
   plonk launch <name> [--screen N]  launch one
   plonk save <name>                 save the desktop as one
@@ -80,6 +81,11 @@ async function summarize() {
     lines.push(`zone sets  ${Object.keys(state.zone_sets).sort().join(", ")}`);
     if (state.excluded_apps?.length)
         lines.push(`excluded   ${state.excluded_apps.join(", ")}`);
+    if (state.app_rules?.length) {
+        const where = (rule) => rule.screen !== undefined ? ` on screen ${rule.screen}` : rule.screen_uuid ? " on a screen that is not attached" : "";
+        const rules = state.app_rules.map((rule) => `${rule.app} -> zone ${rule.zone}${where(rule)}`);
+        lines.push(`rules      ${rules.join(", ")}`);
+    }
     lines.push(`windows   ${state.windows.length}`);
     for (const window of state.windows) {
         lines.push(`  ${window.app}${window.title ? ` — ${window.title}` : ""} [screen ${window.screen}]`);
@@ -118,6 +124,10 @@ async function awakeWhile(argv) {
 }
 async function main() {
     const argv = process.argv.slice(2);
+    if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v")) {
+        console.log(PACKAGE_VERSION);
+        return;
+    }
     // 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.
@@ -142,10 +152,13 @@ async function main() {
         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");
+                fail("snap needs an app and a zone, e.g. plonk snap Safari 1 or plonk snap Slack chat");
+            // A whole number travels as one, which is what every app so far
+            // expects; anything else is a name, and the app says so if the set
+            // has neither.
             report(await call("/layout/zone", {
                 method: "POST",
-                body: { app, zone: number(zone, "zone"), screen },
+                body: { app, zone: Number.isInteger(Number(zone)) ? Number(zone) : zone, screen },
             }));
         }
         case "workspaces": {
@@ -226,7 +239,7 @@ async function main() {
 }
 // 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: CLI_NAME, version: "", pid: process.pid };
+processIdentityHolder().identity = { name: CLI_NAME, version: PACKAGE_VERSION, pid: process.pid };
 try {
     await main();
 }

package/dist/schemas.js

@@ -18,7 +18,19 @@ export const itemsSchema = z
     frame: frameSchema,
 }))
     .min(1);
-export const zonesSchema = z.array(frameSchema).min(1);
+/** A zone is a frame with, optionally, what it is called. The app decides
+ * what a name may be (it cuts one at 24 characters and refuses a bare
+ * number), the way it decides the gap; measuring it here would count code
+ * units and refuse names the app itself keeps. */
+export const zoneSchema = frameSchema.extend({
+    name: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("What the zone is called, e.g. 'chat': drawn under its number, spoken to, and accepted by snap_window instead of the number. Unique within the set"),
+});
+export const zonesSchema = z.array(zoneSchema).min(1);
 export const workspaceItemsSchema = z
     .array(z.object({
     app: z.string().describe("App name as it appears in get_state, e.g. 'Safari'"),

package/dist/tools/layouts.js

@@ -11,9 +11,11 @@ export function register(server) {
         items: itemsSchema.optional(),
     }, async ({ name, items }) => text(await call("/workspaces/save", { method: "POST", body: { name, items } })));
     server.tool("apply_saved_layout", "Launch a saved workspace by name. Legacy name kept for older clients — new integrations should call launch_workspace, which adds a 'screen' option to pull the whole workspace onto one monitor. Opens every app that is not running, waits for its windows, and moves them into the saved positions; macOS cannot open an app straight into a position, so windows appear first and jump into place. Returns per-app success and reports apps that never opened a window. Takes up to a minute for a large workspace.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/launch", { method: "POST", body: { name }, timeoutMs: 90_000 })));
-    server.tool("snap_window", "Drop one window into a numbered zone of the snap-zone set assigned to that monitor. The numbers are the ones Plonk draws on the zones while a window is dragged, so 'the middle zone' of a three-zone set is 2. Zone sets and their per-monitor assignment are in get_state; use apply_layout instead when the user describes a size rather than a zone.", {
+    server.tool("snap_window", "Drop one window into a zone of the snap-zone set assigned to that monitor, by number or by name. The numbers are the ones Plonk draws on the zones while a window is dragged, so 'the middle zone' of a three-zone set is 2; a name is whatever the set calls a zone ('chat'), listed per zone in get_state.zone_sets, matched ignoring case. Fails with the zones that screen does have, names included, when neither matches. Zone sets and their per-monitor assignment are in get_state; use apply_layout instead when the user describes a size rather than a zone.", {
         app: z.string().describe("App name to match, e.g. 'Visual Studio Code'"),
-        zone: z.number().int().min(1).describe("1-based zone number, as shown on the drag overlay"),
+        zone: z
+            .union([z.number().int().min(1), z.string().min(1)])
+            .describe("1-based zone number as shown on the drag overlay, or the zone's name from get_state.zone_sets"),
         title: z.string().optional().describe("Only windows whose title contains this substring"),
         screen: z.number().int().optional().describe("Monitor index; defaults to the one the window is on"),
     }, async (args) => text(await call("/layout/zone", { method: "POST", body: args })));

package/dist/tools/state.js

@@ -1,4 +1,4 @@
 import { call, text } from "../api.js";
 export function register(server) {
-    server.tool("get_state", "Get the current desktop state: all screens/monitors (index, frame, visible area — coordinates have origin at top-left of the primary screen, y grows down), all open windows (app name, title, which screen it is on, absolute frame, and 'fraction' — its position as fractions 0..1 of that screen's visible area), saved layout names, whether a keep-awake session is holding, and 'disabled_features': the modules the user switched off in Plonk (zones, workspaces, shot, ruler, awake and so on). A tool belonging to one of those fails with an error saying so until the user switches it back on. ALWAYS call this first before applying a layout, to see which apps are running and how many monitors there are.", {}, async () => text(await call("/state")));
+    server.tool("get_state", "Get the current desktop state: all screens/monitors (index, frame, visible area — coordinates have origin at top-left of the primary screen, y grows down), all open windows (app name, title, which screen it is on, absolute frame, and 'fraction' — its position as fractions 0..1 of that screen's visible area), 'zone_sets' (every set by name, each zone as {x,y,w,h} with a 'name' where the set gives it one), 'screen_zone_sets' (which set each monitor wears), saved layout names, 'app_rules' (where each app's new windows open, see set_app_rule), 'place_new_windows' and 'auto_fill_zones', whether a keep-awake session is holding, and 'disabled_features': the modules the user switched off in Plonk (zones, workspaces, shot, ruler, awake and so on). A tool belonging to one of those fails with an error saying so until the user switches it back on. ALWAYS call this first before applying a layout, to see which apps are running and how many monitors there are.", {}, async () => text(await call("/state")));
 }

package/dist/tools/zones.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { call, text } from "../api.js";
 import { zonesSchema } from "../schemas.js";
 export function register(server) {
-    server.tool("save_zone_set", "Create or replace a named zone set used for drag snapping. Zones are rectangles {x,y,w,h} as fractions 0..1 of a screen's visible area, origin TOP-LEFT; each zone must stay inside the screen, but zones may overlap each other (the smallest one under the cursor wins). Pass 'screen' to also assign the set to that monitor so it becomes active immediately. Pass 'gap' to give this set its own spacing around windows in points, or null to make it follow the default gap again; omitting it keeps whatever the set had. Built-in sets already exist: Halves, Thirds, 60 / 40, Quarters, Priority.", {
+    server.tool("save_zone_set", "Create or replace a named zone set used for drag snapping. Zones are rectangles {x,y,w,h} as fractions 0..1 of a screen's visible area, origin TOP-LEFT; each zone must stay inside the screen, but zones may overlap each other (the smallest one under the cursor wins). A zone may also carry a 'name' ('chat', 'editor'): it is drawn under the zone's number, the user can say it out loud, and snap_window takes it instead of the number; names must be unique within the set, ignoring case, and cannot be a bare number. Pass 'screen' to also assign the set to that monitor so it becomes active immediately. Pass 'gap' to give this set its own spacing around windows in points, or null to make it follow the default gap again; omitting it keeps whatever the set had. Built-in sets already exist: Halves, Thirds, 60 / 40, Quarters, Priority.", {
         name: z.string().describe("Zone set name, e.g. 'coding'"),
         zones: zonesSchema,
         screen: z.number().int().optional().describe("Monitor index to assign this set to (0 = primary)"),
@@ -18,4 +18,10 @@ export function register(server) {
         name: z.string().optional().describe("Zone set name, or 'edge' for edge snapping; omit for the default set"),
     }, async ({ screen, name }) => text(await call("/zones/assign", { method: "POST", body: { screen, name } })));
     server.tool("delete_zone_set", "Delete a saved zone set by name. Any monitor currently using it falls back to the default set (Halves), so snapping keeps working. Only sets made with save_zone_set can go: the built-ins (Halves, Thirds, 60 / 40, Quarters, Priority) are refused. Deleting is immediate and cannot be undone — the zones would have to be described again. Saved sets and their per-monitor assignments are listed in get_state; use assign_zone_set instead when a monitor should merely stop using a set that others still need.", { name: z.string().describe("Saved zone set name, as shown in get_state") }, async ({ name }) => text(await call("/zones/delete", { method: "POST", body: { name } })));
+    server.tool("set_app_rule", "Make an app's windows open into a numbered zone from now on, so an arrangement holds without anyone dragging: 'Slack always in zone 1 on the second monitor'. 'app' is matched anywhere in the app's name or bundle id, case-insensitively, the way get_state.excluded_apps entries are; a bundle id such as 'com.tinyspeck.slackmacgap' is the safest form. 'zone' is the number Plonk draws on the zone (1-based) in the set assigned to that monitor. 'screen' is a monitor index from get_state and is stored as that display's identity, so it survives a reboot renumbering the screens; omit it and the window stays on whichever screen it opened on. One rule per app: setting it again replaces the old one; a rule that names the app exactly wins over a bare-word rule. Applies to ordinary windows that open after it is set, not to windows already open (use snap_window for those) and not to dialogs or panels. An app on get_state.excluded_apps is left alone even with a rule. A rule beats the habit Plonk keeps of where an app's last window went, and both beat filling an empty zone. Current rules are get_state.app_rules. Fails when 'screen' names a monitor that is not attached or a zone that monitor's set does not have.", {
+        app: z.string().describe("App name or bundle id to match, e.g. 'com.apple.Safari' or 'Safari'"),
+        zone: z.number().int().min(1).describe("1-based zone number, as shown on the drag overlay"),
+        screen: z.number().int().optional().describe("Monitor index from get_state (0 = primary); omit for the screen the window opens on"),
+    }, async ({ app, zone, screen }) => text(await call("/zones/rules", { method: "POST", body: { app, zone, screen } })));
+    server.tool("clear_app_rule", "Remove the rule set for an app with set_app_rule, so its new windows open wherever the app puts them again, or where its last window went when that habit is switched on in Plonk. 'app' is the pattern exactly as get_state.app_rules lists it, ignoring case. Fails when no rule matches; nothing else changes.", { app: z.string().describe("The app pattern as listed in get_state.app_rules") }, async ({ app }) => text(await call("/zones/rules/delete", { method: "POST", body: { app } })));
 }

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1,2 @@
+import { readFileSync } from "node:fs";
+export const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "mcpName": "io.github.ostapondo/plonk",
   "description": "MCP server for Plonk, a macOS window manager: zones you draw yourself, workspaces, keep-awake, screenshots and on-device OCR, as tools an agent can call.",
   "type": "module",