spacepal-mcp 0.3.0 → 0.4.1

package/README.md

@@ -12,7 +12,8 @@ It runs locally over stdio. It reads the Space list Spacepal writes to
 
 ## Requirements
 
-- macOS 14 or later, with Spacepal running (direct or Mac App Store build)
+- macOS 14 or later, with Spacepal running (direct or Mac App Store build).
+  [Download Spacepal](https://getspacepal.com/download/?utm_source=mcp-readme&utm_medium=readme): 14-day free trial, no account; names, notes and switching stay free after it.
 - Node.js 18 or later
 
 ## Tools
@@ -34,6 +35,8 @@ It runs locally over stdio. It reads the Space list Spacepal writes to
 | `restore_window_layout` | Put windows back from the last saved layout |
 | `save_sessions` | Save terminal sessions and Chrome windows on one Space or all of them |
 | `restore_sessions` | Reopen saved sessions on their Spaces |
+| `place_window` | Put the front window in a half, a quarter, maximized, centred, or on the next display |
+| `set_presentation_mode` | Hide Space names, notes and previews for a screen share, or show them again |
 | `add_desktop` | Add a desktop on the current display |
 | `remove_desktop` | Remove a desktop; its windows move to another one |
 

package/index.js

@@ -13,7 +13,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 const run = promisify(execFile);
-const VERSION = "0.3.0";
+const VERSION = "0.4.1";
 
 // Direct build writes to Application Support; the App Store build is sandboxed.
 const SUPPORT_DIRS = [
@@ -26,6 +26,26 @@ const PROFILE_FILES = SUPPORT_DIRS.map((d) => join(d, "profiles.json"));
 const TEMPLATES = ["Developer", "Designer", "Freelancer", "Student", "Streamer"];
 
 const NOT_RUNNING = "Spacepal is not running. Open Spacepal (getspacepal.com) and try again.";
+const DOWNLOAD_URL = "https://getspacepal.com/download/?utm_source=mcp&utm_medium=tool&utm_campaign=not_installed";
+const NOT_INSTALLED =
+  "Spacepal is not installed on this Mac. This MCP server needs the Spacepal app, which names, previews and switches macOS Spaces. " +
+  `Download it from ${DOWNLOAD_URL} (14-day free trial, no account; names and switching stay free after the trial), open it once, then try again.`;
+
+// Not running and never installed reads differently: the user needs a download link, not "open it".
+async function notRunning() {
+  const places = [
+    "/Applications/Spacepal.app",
+    join(homedir(), "Applications/Spacepal.app"),
+    ...SUPPORT_DIRS,
+  ];
+  for (const p of places) {
+    try {
+      await stat(p);
+      return NOT_RUNNING;
+    } catch {}
+  }
+  return NOT_INSTALLED;
+}
 
 async function isRunning() {
   try {
@@ -63,7 +83,7 @@ async function readProfiles() {
 }
 
 async function send(path, query = {}) {
-  if (!(await isRunning())) throw new Error(NOT_RUNNING);
+  if (!(await isRunning())) throw new Error(await notRunning());
   // Encode with %20, not "+": the app reads query values with URLComponents, which keeps "+".
   const qs = Object.entries(query)
     .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
@@ -119,7 +139,7 @@ Start with list_spaces to learn the Spaces, their numbers, names, notes and the
 
 Tools that only read: list_spaces, current_space, list_profiles. Tools that change the user's screen or setup: everything else. Ask the user before remove_desktop, apply_template and apply_profile, which replace or remove things; rename_space and set_space_note are easy to undo by calling them again.
 
-Every action goes through Spacepal, so it must be running (macOS 14 or later). Nothing is sent over the network. If a tool says Spacepal is not running, tell the user to open it. The overview and sessions need Spacepal's trial or a license; names, notes and switching work in the free version.`;
+Every action goes through Spacepal, so it must be running (macOS 14 or later). Nothing is sent over the network. If a tool says Spacepal is not running, tell the user to open it. If it says Spacepal is not installed, give the user the download link from the message. The overview and sessions need Spacepal's trial or a license; names, notes and switching work in the free version.`;
 
 const server = new McpServer({ name: "spacepal", version: VERSION }, { instructions: INSTRUCTIONS });
 
@@ -162,7 +182,7 @@ server.registerTool(
     annotations: { title: "List Spaces", ...RO },
   },
   guarded(async () => {
-    if (!(await isRunning())) return fail(NOT_RUNNING);
+    if (!(await isRunning())) return fail(await notRunning());
     const state = await readState();
     if (!state) return fail("Spacepal has not written its Space list yet. Open the Spacepal menu once and try again.");
     const lines = state.spaces.map((s) => {
@@ -193,7 +213,7 @@ server.registerTool(
     annotations: { title: "Current Space", ...RO },
   },
   guarded(async () => {
-    if (!(await isRunning())) return fail(NOT_RUNNING);
+    if (!(await isRunning())) return fail(await notRunning());
     const state = await readState();
     if (!state) return fail("Spacepal has not written its Space list yet. Open the Spacepal menu once and try again.");
     const active = state.spaces.filter((s) => s.isActive);
@@ -483,6 +503,49 @@ server.registerTool(
   }),
 );
 
+server.registerTool(
+  "place_window",
+  {
+    title: "Place window",
+    description:
+      "Resize and move the user's frontmost window on its current display: a half, a quarter, maximized or centred; " +
+      'or, with "next-display", move it to the next display. It stays on the same Space. ' +
+      "The frontmost window is the one the user last focused (from Claude Desktop that is Claude's own window). " +
+      "Needs the Accessibility permission Spacepal already asks for. Not undoable as one step; place it again to change it. " +
+      "Use move_window_to_space to send a window to another Space instead. Needs Spacepal 1.2.8 or later.",
+    inputSchema: {
+      position: z
+        .enum(["left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right", "maximize", "center", "next-display"])
+        .describe('Where the window goes: a half ("left", "right", "top", "bottom"), a quarter ("top-left" etc.), "maximize", "center", or "next-display".'),
+    },
+    annotations: { title: "Place window", ...CHANGE, idempotentHint: true },
+  },
+  guarded(async ({ position }) => {
+    if (position === "next-display") await send("next-display");
+    else await send(`snap/${position}`);
+    return text(`Asked Spacepal to place the front window: ${position}.`);
+  }),
+);
+
+server.registerTool(
+  "set_presentation_mode",
+  {
+    title: "Set presentation mode",
+    description:
+      "Turn Spacepal's presentation mode on or off. While it is on, Spacepal shows \"Desktop N\" instead of Space names and hides notes, " +
+      "badges and window previews in its overview, menu bar and Mission Control, so a screen share shows nothing private. " +
+      "Names and notes are kept and come back when it is turned off; list_spaces still returns the real names. Reversible by calling it again. Needs Spacepal 1.2.8 or later.",
+    inputSchema: {
+      on: z.boolean().describe("true hides names, notes and previews; false shows them again."),
+    },
+    annotations: { title: "Set presentation mode", ...CHANGE, idempotentHint: true },
+  },
+  guarded(async ({ on }) => {
+    await send(`presentation/${on ? "on" : "off"}`);
+    return text(on ? "Presentation mode on: names, notes and previews hidden." : "Presentation mode off.");
+  }),
+);
+
 server.registerTool(
   "add_desktop",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spacepal-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "MCP server for Spacepal: list, switch, rename macOS Spaces and move windows between them from Claude, Cursor or any MCP client.",
   "mcpName": "com.getspacepal/spacepal",
   "type": "module",

package/server.json

@@ -3,13 +3,13 @@
   "name": "com.getspacepal/spacepal",
   "title": "Spacepal",
   "description": "List, switch and rename macOS Spaces and move windows between them. Needs the Spacepal app.",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "websiteUrl": "https://getspacepal.com/integrations/mcp/",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "spacepal-mcp",
-      "version": "0.3.0",
+      "version": "0.4.1",
       "transport": {
         "type": "stdio"
       }