plonk-mcp 0.0.2 → 0.0.3

package/dist/api.js

@@ -1,6 +1,21 @@
 export const BASE = "http://127.0.0.1:43917";
 const DEFAULT_TIMEOUT_MS = 15_000;
 const NOT_RUNNING = "Plonk menu bar app is not running. Ask the user to launch Plonk.app (its icon should appear in the menu bar).";
+// Stamped on every request so the app can attribute it to a client and, in
+// exclusive mode, gate on it. Set once the MCP handshake reveals who we serve.
+let agentHeaders = {};
+let identityName = "";
+export function setAgentIdentity(name, version) {
+    identityName = name;
+    agentHeaders = {
+        "x-plonk-agent": version ? `${name}/${version}` : name,
+        "x-plonk-agent-pid": String(process.pid),
+    };
+}
+/** The client name this server registered with, e.g. "claude-code". */
+export function agentIdentityName() {
+    return identityName;
+}
 export async function call(path, options = {}) {
     const { method = "GET", body, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
     const timeout = AbortSignal.timeout(timeoutMs);
@@ -8,7 +23,7 @@ export async function call(path, options = {}) {
     try {
         res = await fetch(BASE + path, {
             method,
-            headers: { "content-type": "application/json" },
+            headers: { "content-type": "application/json", ...agentHeaders },
             body: body !== undefined ? JSON.stringify(body) : undefined,
             signal: timeout,
         });

package/dist/server.js

@@ -3,7 +3,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "node:module";
-import { BASE, isAppReachable } from "./api.js";
+import { BASE, call, isAppReachable, setAgentIdentity } from "./api.js";
 import { register as registerState } from "./tools/state.js";
 import { register as registerLayouts } from "./tools/layouts.js";
 import { register as registerWorkspaces } from "./tools/workspaces.js";
@@ -11,6 +11,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 registerAgents } from "./tools/agents.js";
 const { version } = createRequire(import.meta.url)("../package.json");
 const server = new McpServer({ name: "plonk", version });
 registerState(server);
@@ -20,6 +21,31 @@ registerZones(server);
 registerAwake(server);
 registerScreenshot(server);
 registerAnnotate(server);
+registerAgents(server);
+// The handshake tells us which client we serve; PLONK_AGENT_NAME lets the user
+// name a session by hand ("work", "pet-project"). Registering keeps this
+// client on the app's agent list; the heartbeat keeps it marked online.
+// The initialized notification can outrun the initialize handler's bookkeeping
+// in the SDK, leaving clientInfo briefly unset, so poll instead of trusting
+// the callback's timing.
+function identify(attempt = 0) {
+    const client = server.server.getClientVersion();
+    if (!client && attempt < 50) {
+        setTimeout(() => identify(attempt + 1), 100).unref();
+        return;
+    }
+    const agentName = (process.env.PLONK_AGENT_NAME || client?.name || "mcp-client").replaceAll("/", "-");
+    const agentVersion = client?.version ?? "";
+    setAgentIdentity(agentName, agentVersion);
+    const hello = () => call("/agents/hello", {
+        method: "POST",
+        body: { name: agentName, version: agentVersion, pid: process.pid },
+        timeoutMs: 3_000,
+    });
+    void hello();
+    setInterval(hello, 30_000).unref();
+}
+server.server.oninitialized = () => identify();
 const transport = new StdioServerTransport();
 await server.connect(transport);
 // stdout carries the protocol, so this goes to stderr. Not fatal: the app may

package/dist/tools/agents.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { agentIdentityName, call, text } from "../api.js";
+export function register(server) {
+    server.tool("select_agent", "Make an agent the user's active one in Plonk. Omit 'name' to select this client itself; pass \"\" to clear the choice so any agent may drive. The active agent shows in Plonk's menu bar and settings, and is where voice and other outgoing requests will go. With 'exclusive' true the app also rejects window and settings changes from every other agent (they can still read state and take screenshots). Connected agents are listed in get_state under 'agents'.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Agent name from get_state's 'agents'; omit for this client, \"\" to clear"),
+        exclusive: z
+            .boolean()
+            .optional()
+            .describe("Also turn 'only the active agent controls' on or off"),
+    }, async ({ name, exclusive }) => {
+        const target = name === undefined ? agentIdentityName() : name;
+        const selected = await call("/agents/select", { method: "POST", body: { name: target } });
+        if ("error" in selected || exclusive === undefined)
+            return text(selected);
+        const mode = await call("/agents/exclusive", { method: "POST", body: { on: exclusive } });
+        return text({ ...selected, ...mode });
+    });
+}

package/dist/tools/layouts.js

@@ -6,16 +6,16 @@ export function register(server) {
     // Saved layouts became workspaces, which also know how to launch their apps.
     // These two stay so older clients keep working; prefer save_workspace and
     // launch_workspace, which can carry an app's bundle id and what it opens.
-    server.tool("save_layout", "Deprecated alias of save_workspace. Saves the named arrangement as a workspace; omit 'items' to snapshot what is on screen right now.", {
+    server.tool("save_layout", "Save the named window arrangement as a workspace. Legacy name kept for older clients — new integrations should call save_workspace, which can also record whether running apps get moved into place. Omit 'items' to snapshot the windows exactly as they are on screen right now; pass 'items' to describe the arrangement explicitly. Saving over an existing name replaces it. Saved workspaces are listed in get_state, with their full contents.", {
         name: z.string().describe("Workspace name, e.g. 'work', 'focus'"),
         items: itemsSchema.optional(),
     }, async ({ name, items }) => text(await call("/workspaces/save", { method: "POST", body: { name, items } })));
-    server.tool("apply_saved_layout", "Deprecated alias of launch_workspace. Launches the saved workspace of that name, opening any app that is not running.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/launch", { method: "POST", body: { name }, timeoutMs: 90_000 })));
+    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.", {
         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"),
         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 })));
-    server.tool("delete_layout", "Deprecated alias of delete_workspace. Deletes the saved workspace of that name.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/delete", { method: "POST", body: { name } })));
+    server.tool("delete_layout", "Delete the saved workspace with that name, whether it was saved with save_layout or save_workspace. Legacy name kept for older clients — new integrations should call delete_workspace, which does the same. Use it to clean up saved workspaces that are no longer wanted; existing names are listed in get_state.", { name: z.string() }, async ({ name }) => text(await call("/workspaces/delete", { method: "POST", body: { name } })));
 }

package/package.json

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