plonk-mcp 0.3.3 → 0.3.5

package/README.md

@@ -57,8 +57,7 @@ config to tell two sessions of the same client apart.
 | `apply_layout` · `snap_window` | Place windows by fraction of a screen, or drop one into a numbered zone |
 | `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_awake` | Keep-awake, optionally time-limited |
-| `set_active` | Stay active, so chat apps do not show you as Away |
+| `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 |
 | `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/factory.js

@@ -7,7 +7,6 @@ import { register as registerState } from "./tools/state.js";
 import { register as registerLayouts } from "./tools/layouts.js";
 import { register as registerWorkspaces } from "./tools/workspaces.js";
 import { register as registerZones } from "./tools/zones.js";
-import { register as registerActive } from "./tools/active.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";
@@ -23,7 +22,6 @@ export function createPlonkServer() {
     registerLayouts(server);
     registerZones(server);
     registerAwake(server);
-    registerActive(server);
     registerScreenshot(server);
     registerAnnotate(server);
     registerText(server);

package/dist/tools/awake.js

@@ -1,11 +1,17 @@
 import { z } from "zod";
 import { call, text } from "../api.js";
 export function register(server) {
-    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. " +
+    server.tool("set_awake", "Keep the Mac from sleeping, and optionally keep the user shown as available in chat apps. One session with two levels, called Pulse in the app. " +
+        "'available' picks the level. Left off, Plonk holds a power assertion: the Mac does not sleep, but Slack and Teams still slide the user to Away, because those read the system idle timer and an assertion does not touch it. Turned on, Plonk also resets that idle timer with a Shift keypress every two minutes, which is what keeps a chat status green — and which postpones sleep by itself, so being available always includes being awake. Use it whenever the point is how the user looks to other people rather than whether a job finishes. " +
+        "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, or until the user's configured default timeout expires. " +
+        "Switching it by hand overrides the schedule until the schedule itself next changes, so turning it off during scheduled hours lasts until those hours end rather than being undone on the next tick. Sessions Plonk starts on its own — a recurring schedule of hours and weekdays, a list of apps whose being open arms it, or the charger being plugged in — are settings on the Pulse page rather than parameters here; get_state reports all of them under 'awake_details'. " +
+        "Behavior also follows those settings: a session may pause on battery, so the returned 'status' is what actually happened, 'awake' is whether an assertion is held right now, and 'available' is whether a keypress is actually being posted. Those differ from what was asked for when Plonk has no Accessibility permission (nothing can be posted, though the Mac still stays awake) or when the user disallowed running on battery and the Mac is unplugged; neither is an error, since the request was understood. The menu bar cube glows while a session holds. " +
         "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(),
+        available: z
+            .boolean()
+            .optional()
+            .describe("Also reset the idle timer, so chat apps go on showing the user as available instead of Away. This is the user's stored level rather than a property of one session: later sessions run at it too, until it is changed again. Omit to leave it as the user set it"),
         minutes: z.number().int().min(1).optional().describe("End the session after this many minutes"),
         until: z
             .string()
@@ -17,5 +23,5 @@ export function register(server) {
             .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 } })));
+    }, async ({ on, available, minutes, until, pid }) => text(await call("/awake", { method: "POST", body: { on, available, minutes, until, pid } })));
 }

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 keep-awake is on, and 'disabled_features': the modules the user switched off in Plonk (zones, workspaces, shot, ruler, awake, active 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), 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")));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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",

package/dist/tools/active.js

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import { call, text } from "../api.js";
-export function register(server) {
-    server.tool("set_active", "Turn stay-active on or off, so chat apps go on showing the user as available instead of Away. " +
-        "Pick this over 'set_awake' by what is being protected: set_awake holds a power assertion and stops the Mac sleeping, which does nothing for a Slack or Teams status; set_active resets the system idle timer by posting a Shift keypress every two minutes, which is what those apps actually read. Resetting the idle timer also postpones sleep, so stay-active implies keep-awake and there is no need to turn both on. " +
-        "Two ways to end the session: 'until' ends it at a wall-clock time ('17:00', or an ISO-8601 timestamp); 'minutes' ends it after a countdown. Give neither and it runs until switched off, or until the user's configured default timeout expires. " +
-        "This only starts and ends sessions. The recurring schedule (hours and weekdays) and the list of apps that arm it automatically are settings on the Stay active page, not parameters here; get_state reports both under 'active_details'. " +
-        "Switching it by hand overrides the schedule until the schedule itself next changes, so turning it off during scheduled hours lasts until those hours end rather than being undone on the next tick. " +
-        "Returns 'active', whether a keypress is actually being posted right now, and 'status', what happened in words. Those differ when Plonk has no Accessibility permission (nothing can be posted) or when the user disallowed running on battery and the Mac is unplugged; neither is reported as an error, since the request was understood. An 'until' that has already passed is an error.", {
-        on: z.boolean(),
-        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'"),
-    }, async ({ on, minutes, until }) => text(await call("/active", { method: "POST", body: { on, minutes, until } })));
-}