spacepal-mcp 0.2.0 → 0.3.0

package/index.js

@@ -13,7 +13,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 const run = promisify(execFile);
-const VERSION = "0.2.0";
+const VERSION = "0.3.0";
 
 // Direct build writes to Application Support; the App Store build is sandboxed.
 const SUPPORT_DIRS = [
@@ -113,18 +113,53 @@ function guarded(fn) {
   };
 }
 
-const server = new McpServer({ name: "spacepal", version: VERSION });
+const INSTRUCTIONS = `Spacepal MCP server: work with macOS Spaces (desktops) through the Spacepal app on this Mac.
+
+Start with list_spaces to learn the Spaces, their numbers, names, notes and the apps on each; most tools take a Space by desktop number or by name from that list. Use current_space when you only need the active one.
+
+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.`;
+
+const server = new McpServer({ name: "spacepal", version: VERSION }, { instructions: INSTRUCTIONS });
+
 const spaceArg = z
   .union([z.number().int().positive(), z.string().min(1)])
-  .describe("Desktop number (1, 2, ...) or Space name, e.g. \"Mail\".");
+  .describe(
+    'Which Space: its desktop number (1 = leftmost on the display) or its name as list_spaces shows it, e.g. "Mail". Names match without regard to case.',
+  );
+const optionalSpaceArg = spaceArg.optional().describe(
+  'Which Space: desktop number or name from list_spaces. Leave it out for the Space the user is on now.',
+);
+
+const spaceEntry = z
+  .object({
+    id: z.string().describe("Stable id of the Space"),
+    name: z.string().describe("Name shown in Spacepal, or \"Desktop N\" if unnamed"),
+    number: z.number().int().optional().describe("Desktop number on its display; absent for full-screen Spaces"),
+    display: z.string().describe("Id of the display the Space is on"),
+    isActive: z.boolean().describe("True for the Space currently shown on its display"),
+    isFullscreen: z.boolean().describe("True for an app's full-screen Space"),
+    apps: z.array(z.string()).describe("Apps with a window on this Space"),
+    note: z.string().optional().describe("The user's note about what the Space is for"),
+    color: z.string().optional().describe("Colour as #RRGGBB"),
+  })
+  .passthrough();
+
+const RO = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const CHANGE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 
 server.registerTool(
   "list_spaces",
   {
     title: "List Spaces",
-    description: "List every macOS Space (desktop) with its number, name, display, the apps that have windows there, its note, and which one is active.",
+    description:
+      "List every macOS Space (desktop) on every display: desktop number, name, note, the apps with windows on it, and which one is active. " +
+      "Read-only. Call this first to get valid Space numbers and names for the other tools. " +
+      "Fails if Spacepal is not running or has not written its list yet.",
     inputSchema: {},
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    outputSchema: { current: z.string().describe("Name of the active Space"), spaces: z.array(spaceEntry) },
+    annotations: { title: "List Spaces", ...RO },
   },
   guarded(async () => {
     if (!(await isRunning())) return fail(NOT_RUNNING);
@@ -141,7 +176,7 @@ server.registerTool(
       content: [
         { type: "text", text: `Current: ${state.current}\n${displays} display(s), ${state.spaces.length} Spaces (* = active)\n${lines.join("\n")}` },
       ],
-      structuredContent: state,
+      structuredContent: { current: state.current ?? "", spaces: state.spaces },
     };
   }),
 );
@@ -150,16 +185,22 @@ server.registerTool(
   "current_space",
   {
     title: "Current Space",
-    description: "Name and number of the Space you are on.",
+    description:
+      "Return the Space the user is on now: its name and desktop number (one per display). " +
+      "Read-only and cheaper than list_spaces when you only need the active Space.",
     inputSchema: {},
-    annotations: { readOnlyHint: true, openWorldHint: false },
+    outputSchema: { spaces: z.array(spaceEntry).describe("The active Space on each display") },
+    annotations: { title: "Current Space", ...RO },
   },
   guarded(async () => {
     if (!(await isRunning())) return fail(NOT_RUNNING);
     const state = await readState();
-    const active = state?.spaces.filter((s) => s.isActive) ?? [];
-    if (!active.length) return text(state?.current ? `Current: ${state.current}` : "Unknown");
-    return text(active.map((s) => `${s.name} (Desktop ${s.number ?? "full screen"})`).join("\n"));
+    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);
+    const t = active.length
+      ? active.map((s) => `${s.name} (Desktop ${s.number ?? "full screen"})`).join("\n")
+      : `Current: ${state.current || "unknown"}`;
+    return { content: [{ type: "text", text: t }], structuredContent: { spaces: active } };
   }),
 );
 
@@ -167,9 +208,16 @@ server.registerTool(
   "switch_space",
   {
     title: "Switch Space",
-    description: "Switch to a Space by desktop number or name. Use \"next\", \"previous\" or \"back\" to step.",
-    inputSchema: { space: spaceArg },
-    annotations: { openWorldHint: false },
+    description:
+      "Show another Space on the user's screen, instantly and without the slide animation. " +
+      'Give a desktop number or name from list_spaces, or "next", "previous" (neighbouring desktop) or "back" (the Space shown before). ' +
+      "Changes only what is visible; no windows move. Undo with space=\"back\". Returns the Space now shown; fails if no Space has that name.",
+    inputSchema: {
+      space: spaceArg.describe(
+        'Desktop number or name from list_spaces, or one of "next", "previous", "back".',
+      ),
+    },
+    annotations: { title: "Switch Space", ...CHANGE, idempotentHint: true },
   },
   guarded(async ({ space }) => {
     const before = (await readState())?.current;
@@ -194,12 +242,16 @@ server.registerTool(
   {
     title: "Move window to Space",
     description:
-      "Send the frontmost window to another Space (by number or name, or \"next\"/\"previous\"). " +
-      "On macOS 14.0-14.4 and 26.4+ the window moves directly; on other versions Spacepal drags it, " +
-      "which takes a moment longer. The frontmost window is usually the one the user worked in last, " +
-      "not the MCP client's own window when it runs in a terminal.",
-    inputSchema: { space: spaceArg },
-    annotations: { openWorldHint: false },
+      "Move the user's frontmost window to another Space; the window keeps its size and position. " +
+      'Target is a desktop number or name from list_spaces, or "next"/"previous". ' +
+      "The frontmost window is the one the user last focused: from a terminal client that is usually the window they worked in, " +
+      "from Claude Desktop it is Claude's own window. On macOS 14.0-14.4 and 26.4+ the window moves directly; on other versions " +
+      "Spacepal drags it, which takes a moment. Depending on the user's settings the screen may follow the window. " +
+      "Undo by moving it back. Fails if no Space has that name.",
+    inputSchema: {
+      space: spaceArg.describe('Target desktop number or name from list_spaces, or "next" / "previous".'),
+    },
+    annotations: { title: "Move window to Space", ...CHANGE },
   },
   guarded(async ({ space }) => {
     const s = String(space).toLowerCase();
@@ -217,12 +269,15 @@ server.registerTool(
   "rename_space",
   {
     title: "Rename Space",
-    description: "Give a Space a name. Leave space empty for the current one; an empty name restores the default.",
+    description:
+      "Set the name Spacepal shows for a Space in its menu bar, overview and Mission Control. " +
+      "Replaces the old name; an empty name goes back to \"Desktop N\". The name stays with the Space even if desktops are reordered. " +
+      "Reversible: call again with the old name (get it from list_spaces first). Fails if the Space does not exist.",
     inputSchema: {
-      space: spaceArg.optional(),
-      name: z.string().max(60).describe("New name. Empty text restores \"Desktop N\"."),
+      space: optionalSpaceArg,
+      name: z.string().max(60).describe('New name, up to 60 characters. Empty text ("") restores the default "Desktop N".'),
     },
-    annotations: { openWorldHint: false },
+    annotations: { title: "Rename Space", ...CHANGE, idempotentHint: true },
   },
   guarded(async ({ space, name }) => {
     if (space !== undefined && !(await findSpace(space))) return fail(`No Space called "${space}".`);
@@ -232,13 +287,37 @@ server.registerTool(
   }),
 );
 
+server.registerTool(
+  "set_space_note",
+  {
+    title: "Set Space note",
+    description:
+      "Set the short note that says what a Space is for, e.g. \"Client B invoices\"; list_spaces returns it and Spacepal shows it in its overview. " +
+      "Replaces any existing note; empty text removes the note. Reversible by setting the old note again (read it from list_spaces first). " +
+      "Fails if the Space does not exist.",
+    inputSchema: {
+      space: optionalSpaceArg,
+      text: z.string().max(500).describe('The note, up to 500 characters. Empty text ("") removes the note.'),
+    },
+    annotations: { title: "Set Space note", ...CHANGE, idempotentHint: true },
+  },
+  guarded(async ({ space, text: note }) => {
+    if (space !== undefined && !(await findSpace(space))) return fail(`No Space called "${space}".`);
+    await send(`note/${ref(space)}`, { text: note });
+    return text(note ? "Note saved." : "Note removed.");
+  }),
+);
+
 server.registerTool(
   "open_overview",
   {
     title: "Open overview",
-    description: "Open Spacepal's overview grid of all Spaces on screen.",
+    description:
+      "Show Spacepal's full-screen overview of every Space with live previews, for the user to look at and pick from. " +
+      "It is a toggle: calling it while the overview is open closes it. Changes nothing else. " +
+      "Needs Spacepal's trial or a license; without one Spacepal shows its license window instead. To get the Space list as data, use list_spaces.",
     inputSchema: {},
-    annotations: { openWorldHint: false },
+    annotations: { title: "Open overview", ...CHANGE },
   },
   guarded(async () => {
     await send("overview");
@@ -247,17 +326,22 @@ server.registerTool(
 );
 
 server.registerTool(
-  "set_space_note",
+  "list_profiles",
   {
-    title: "Set Space note",
-    description: "Attach a short note to a Space (what it is for).",
-    inputSchema: { space: spaceArg.optional(), text: z.string().max(500) },
-    annotations: { openWorldHint: false },
+    title: "List profiles",
+    description:
+      "List the names of the user's saved Spacepal profiles. A profile is a saved set of Space names, colours, notes and automations, such as \"Work\" and \"Home\". " +
+      "Read-only. Use it to get a valid name for apply_profile.",
+    inputSchema: {},
+    outputSchema: { profiles: z.array(z.string()).describe("Saved profile names") },
+    annotations: { title: "List profiles", ...RO },
   },
-  guarded(async ({ space, text: note }) => {
-    if (space !== undefined && !(await findSpace(space))) return fail(`No Space called "${space}".`);
-    await send(`note/${ref(space)}`, { text: note });
-    return text("Note saved.");
+  guarded(async () => {
+    const names = await readProfiles();
+    return {
+      content: [{ type: "text", text: names.length ? names.join("\n") : "No saved profiles yet." }],
+      structuredContent: { profiles: names },
+    };
   }),
 );
 
@@ -265,9 +349,15 @@ server.registerTool(
   "apply_profile",
   {
     title: "Apply profile",
-    description: "Apply a saved Spacepal profile by name (names, layouts and rules).",
-    inputSchema: { name: z.string().min(1) },
-    annotations: { openWorldHint: false },
+    description:
+      "Switch to one of the user's saved profiles, replacing the names, colours, notes and automations of every Space with the profile's. " +
+      "If a profile was active, Spacepal first saves the current set under it, so the user can switch back. If none was active, the current names are not saved anywhere and are lost, so ask the user to save them as a profile first. " +
+      "Windows and desktops are not changed. Unlike apply_template, which uses built-in starter names, this uses the user's own saved sets. " +
+      "Get valid names from list_profiles; fails with the list of names if the profile does not exist. Ask the user first.",
+    inputSchema: {
+      name: z.string().min(1).describe("Profile name from list_profiles. Matching ignores case."),
+    },
+    annotations: { title: "Apply profile", ...CHANGE, destructiveHint: true, idempotentHint: true },
   },
   guarded(async ({ name }) => {
     const names = await readProfiles();
@@ -280,29 +370,17 @@ server.registerTool(
   }),
 );
 
-server.registerTool(
-  "list_profiles",
-  {
-    title: "List profiles",
-    description: "Names of the saved Spacepal profiles (sets of Space names, colours, notes and automations).",
-    inputSchema: {},
-    annotations: { readOnlyHint: true, openWorldHint: false },
-  },
-  guarded(async () => {
-    const names = await readProfiles();
-    return text(names.length ? names.join("\n") : "No saved profiles yet.");
-  }),
-);
-
 server.registerTool(
   "apply_template",
   {
     title: "Apply template",
     description:
-      `Name and colour the Spaces from a built-in starter template: ${TEMPLATES.join(", ")}. ` +
-      "This replaces the current Space names; the user can save them first as a profile.",
-    inputSchema: { name: z.enum(TEMPLATES) },
-    annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: false },
+      `Name and colour the user's desktops from one of Spacepal's built-in starter templates: ${TEMPLATES.join(", ")}. ` +
+      "Overwrites the names, colours and notes of the desktops it covers, so ask the user first; to keep the current names they can save them as a profile in Spacepal. " +
+      "If the template needs more desktops than exist, Spacepal shows a dialog on screen asking the user whether to add them. " +
+      "For the user's own saved sets use apply_profile instead.",
+    inputSchema: { name: z.enum(TEMPLATES).describe("Template name, exactly as listed") },
+    annotations: { title: "Apply template", ...CHANGE, destructiveHint: true, idempotentHint: true },
   },
   guarded(async ({ name }) => {
     await send(`template/${encodeURIComponent(name)}`);
@@ -315,9 +393,12 @@ server.registerTool(
   "set_up_space",
   {
     title: "Set up Space",
-    description: "Switch to a Space and run its automations now: open its apps, URLs and files, run its Shortcut or script.",
-    inputSchema: { space: spaceArg.optional() },
-    annotations: { openWorldHint: false },
+    description:
+      "Switch to a Space and open the apps, URLs and files its Spacepal automation lists, even if they were opened before. " +
+      "Entering the Space also runs its usual on-enter actions, such as a Shortcut. Use it to prepare a workspace; to only change the visible Space use switch_space. " +
+      "Opens apps on the user's Mac, so it cannot be undone automatically. Does nothing beyond switching if the Space has no automation. Fails if the Space does not exist.",
+    inputSchema: { space: optionalSpaceArg },
+    annotations: { title: "Set up Space", ...CHANGE },
   },
   guarded(async ({ space }) => {
     const target = space === undefined ? null : await findSpace(space);
@@ -331,9 +412,11 @@ server.registerTool(
   "save_window_layout",
   {
     title: "Save window layout",
-    description: "Save which Space and position every window is in, for this display setup. Replaces the previous manual save.",
+    description:
+      "Record which Space and screen position every open window has, for the current display setup, so restore_window_layout can put them back. " +
+      "Overwrites the previous manual save for these displays (Spacepal also saves automatically in the background). Moves nothing.",
     inputSchema: {},
-    annotations: { idempotentHint: true, openWorldHint: false },
+    annotations: { title: "Save window layout", ...CHANGE, idempotentHint: true },
   },
   guarded(async () => {
     await send("save-layout");
@@ -346,10 +429,11 @@ server.registerTool(
   {
     title: "Restore window layout",
     description:
-      "Put windows back on the Spaces and positions from the last saved layout for this display setup. " +
-      "Moving windows between Spaces needs macOS 14.0-14.4 or 26.4+.",
+      "Move open windows back to the Spaces and positions recorded by save_window_layout (or Spacepal's automatic save) for the current display setup. " +
+      "Moving windows between Spaces only works on macOS 14.0-14.4 and 26.4+; on other versions positions are restored but windows stay on their Space. " +
+      "Windows of apps that are not open are skipped; to reopen terminals and Chrome windows use restore_sessions. Spacepal shows how many windows it moved.",
     inputSchema: {},
-    annotations: { openWorldHint: false },
+    annotations: { title: "Restore window layout", ...CHANGE, idempotentHint: true },
   },
   guarded(async () => {
     await send("restore-layout");
@@ -362,13 +446,14 @@ server.registerTool(
   {
     title: "Save sessions",
     description:
-      "Save the terminal sessions and Chrome windows on a Space (or on every Space with all=true), " +
-      "so Spacepal can reopen them after a restart. Needs the Spacepal trial or a license.",
+      "Save the terminal windows (with their folders) and Chrome windows (with their tabs) on one Space, or on every Space with all=true, " +
+      "so restore_sessions can reopen them on the right Space after a restart. Replaces the earlier save for those Spaces and drops windows that were closed. " +
+      "Needs Spacepal's trial or a license; without one nothing is saved.",
     inputSchema: {
-      space: spaceArg.optional(),
-      all: z.boolean().optional().describe("Save every Space instead of one."),
+      space: optionalSpaceArg,
+      all: z.boolean().optional().describe("true to save every Space; then space is ignored. Default false."),
     },
-    annotations: { idempotentHint: true, openWorldHint: false },
+    annotations: { title: "Save sessions", ...CHANGE, idempotentHint: true },
   },
   guarded(async ({ space, all }) => {
     if (all) {
@@ -385,9 +470,12 @@ server.registerTool(
   "restore_sessions",
   {
     title: "Restore sessions",
-    description: "Reopen the saved terminal sessions and Chrome windows on their Spaces. Needs the Spacepal trial or a license.",
+    description:
+      "Reopen the terminal and Chrome windows saved by save_sessions, each on the Space it was saved from. " +
+      "Opens new windows, so calling it twice can open duplicates. Needs Spacepal's trial or a license. " +
+      "To move windows that are already open, use restore_window_layout instead.",
     inputSchema: {},
-    annotations: { openWorldHint: false },
+    annotations: { title: "Restore sessions", ...CHANGE },
   },
   guarded(async () => {
     await send("session-restore");
@@ -399,9 +487,11 @@ server.registerTool(
   "add_desktop",
   {
     title: "Add desktop",
-    description: "Add a new desktop (Space) on the current display.",
+    description:
+      "Create a new empty desktop at the end of the display the pointer is on. Mission Control opens for a moment while Spacepal adds it. " +
+      "Undo with remove_desktop. Returns the new number of Spaces once Spacepal confirms it.",
     inputSchema: {},
-    annotations: { openWorldHint: false },
+    annotations: { title: "Add desktop", ...CHANGE },
   },
   guarded(async () => {
     const before = (await readState())?.spaces.length ?? 0;
@@ -421,10 +511,11 @@ server.registerTool(
   {
     title: "Remove desktop",
     description:
-      "Remove a desktop by number or name. Its windows move to another desktop, as when you close it in Mission Control. " +
-      "Full-screen Spaces cannot be removed this way. Ask the user before calling this.",
-    inputSchema: { space: spaceArg },
-    annotations: { destructiveHint: true, openWorldHint: false },
+      "Close a desktop, as with its close button in Mission Control. Its windows move to another desktop and are not closed, " +
+      "but its Spacepal name, note and automation are lost and cannot be restored automatically. Full-screen Spaces cannot be removed this way. " +
+      "Always ask the user before calling this. Fails if the Space does not exist.",
+    inputSchema: { space: spaceArg.describe("Desktop number or name from list_spaces") },
+    annotations: { title: "Remove desktop", ...CHANGE, destructiveHint: true },
   },
   guarded(async ({ space }) => {
     const target = await findSpace(space);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spacepal-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -37,6 +37,9 @@
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.0",
-    "zod": "^3.23.8"
+    "zod": "^4.6.7"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs"
   }
 }

package/server.json

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