plonk-mcp 0.2.2 → 0.2.4

package/README.md

@@ -58,7 +58,7 @@ config to tell two sessions of the same client apart.
 | `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 |
-| `take_screenshot` · `annotate_screenshot` | Capture, mark up, hand the image back |
+| `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/tools/screenshot.js

@@ -2,13 +2,34 @@ import { readFile } from "node:fs/promises";
 import { z } from "zod";
 import { call, text } from "../api.js";
 // The interactive modes hand the user a crosshair and wait for them.
+const INTERACTIVE_MODES = new Set(["region", "window"]);
 const INTERACTIVE_TIMEOUT_MS = 5 * 60_000;
 // Refuse to inline anything larger; a full retina desktop is easily 10 MB,
 // which is dead weight in the conversation.
 const MAX_INLINE_BYTES = 4 << 20;
+/**
+ * Which mode a call really asks for.
+ *
+ * Naming a window is asking for that window, so a caller that passes 'app' and
+ * leaves 'mode' at its default gets the window rather than the whole screen —
+ * which would answer a question nobody asked and look right enough to be
+ * believed. Only the default is overridden: asking for a crosshair outright
+ * still hands the user a crosshair.
+ */
+export function captureMode(mode, app, titleContains) {
+    return mode === "screen" && (app || titleContains) ? "app" : mode;
+}
 export function register(server) {
-    server.tool("take_screenshot", "Capture the screen and return the image so it can be looked at. mode 'screen' captures everything (no user interaction), 'region' and 'window' hand the user the native crosshair/window picker and wait for them. Set annotate=true to open Plonk's drawing editor on the capture instead of returning it — use that when the user wants to mark the shot up themselves. Optional 'path' writes to an explicit file, otherwise the configured screenshot folder is used; 'clipboard' overrides the configured copy-to-clipboard behavior. The returned image is scaled down for legibility; the file at 'path' keeps full resolution. To draw on the result, pass that 'path' to annotate_screenshot.", {
-        mode: z.enum(["screen", "region", "window"]).default("screen"),
+    server.tool("take_screenshot", "Capture the screen and return the image so it can be looked at. mode 'screen' captures everything (no user interaction); mode 'app' captures one named window and needs no user interaction either — pass 'app' and/or 'title_contains', and it works even when that window is behind others, minimized excepted, without raising it or taking focus; 'region' and 'window' hand the user the native crosshair/window picker and wait for them. Prefer 'app' whenever the user asks about a particular program (\"what is playing in Spotify\", \"read the error in Xcode\") — it is the only mode that can see a window the user cannot, and it does not disturb their desktop. Set annotate=true to open Plonk's drawing editor on the capture instead of returning it — use that when the user wants to mark the shot up themselves. Optional 'path' writes to an explicit file, otherwise the configured screenshot folder is used; 'clipboard' overrides the configured copy-to-clipboard behavior. The returned image is scaled down for legibility; the file at 'path' keeps full resolution. To draw on the result, pass that 'path' to annotate_screenshot.", {
+        mode: z.enum(["screen", "app", "region", "window"]).default("screen"),
+        app: z
+            .string()
+            .optional()
+            .describe("mode 'app': app name or bundle id, case-insensitive substring (e.g. 'Spotify')"),
+        title_contains: z
+            .string()
+            .optional()
+            .describe("mode 'app': narrows to a window whose title contains this, for an app with several"),
         annotate: z.boolean().optional().describe("Open the annotation editor instead of returning the image"),
         path: z.string().optional().describe("Explicit output file path (.png)"),
         clipboard: z.boolean().optional().describe("Also copy the capture to the clipboard"),
@@ -16,11 +37,12 @@ export function register(server) {
             .boolean()
             .optional()
             .describe("Return the image content itself, so it can be inspected (default true)"),
-    }, async ({ mode, annotate, path, clipboard, include_image }) => {
+    }, async ({ mode, app, title_contains, annotate, path, clipboard, include_image }) => {
+        const wanted = captureMode(mode, app, title_contains);
         const result = await call("/shot/capture", {
             method: "POST",
-            body: { mode, annotate, path, clipboard, preview: include_image !== false },
-            timeoutMs: mode === "screen" ? undefined : INTERACTIVE_TIMEOUT_MS,
+            body: { mode: wanted, app, title_contains, annotate, path, clipboard, preview: include_image !== false },
+            timeoutMs: INTERACTIVE_MODES.has(wanted) ? INTERACTIVE_TIMEOUT_MS : undefined,
         });
         const savedPath = "path" in result && typeof result.path === "string" ? result.path : undefined;
         if (!savedPath || include_image === false)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plonk-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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",
@@ -16,10 +16,14 @@
     "mcp",
     "model-context-protocol",
     "claude",
+    "claude-code",
     "macos",
     "window-manager",
     "workspaces",
-    "screenshots"
+    "zones",
+    "screenshots",
+    "ocr",
+    "accessibility"
   ],
   "engines": {
     "node": ">=18"