rootr-cli 0.2.1 → 0.4.1

package/lib/mcp-tools/spreadsheets.js

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+
+const CELL_VALUE = z
+  .union([z.string(), z.number(), z.boolean(), z.null()])
+  .describe('Raw/display value; null clears the cell when patching');
+
+const cellShape = z
+  .object({
+    v: CELL_VALUE.optional(),
+    f: z.string().optional().describe('Formula source, e.g. "=SUM(A1:A3)" (leading "=" included)'),
+  })
+  .describe('One cell: v (value) and/or f (formula). Formulas are recalculated server-side.');
+
+const CELLS_GUIDE =
+  'Cells are addressed A1-style ("A1", "B12", ...) in a sparse map: { "A1": { v: 42 }, "B1": { f: "=A1*2" } }. ' +
+  'Set a cell to `null` to clear it. Read the sheet first (rootr_read_spreadsheet) so you know current dimensions ' +
+  'and existing content before patching — patchCells only touches the keys you send, everything else is untouched.';
+
+/** SPREADSHEET node tools: create/read/update the grid, manage sheets, patch cells. */
+export function registerSpreadsheetTools(server) {
+  server.registerTool(
+    'rootr_create_spreadsheet',
+    {
+      title: 'Create a Rootr spreadsheet',
+      description:
+        'Create a new SPREADSHEET node (a grid with formulas) in a Rootr (루터) workspace. Use SPREADSHEET when ' +
+        'content needs calculation (budgets, models, estimates) — for plain tracked lists use DATABASE instead. ' +
+        'Defaults to a single empty "Sheet1" if no `data` is given. ' +
+        CELLS_GUIDE,
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        name: z.string().optional().describe('Spreadsheet name/title'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
+        icon: z.string().optional().describe('Emoji icon for the node'),
+        data: z
+          .object({ sheets: z.array(z.record(z.unknown())).optional() })
+          .optional()
+          .describe('Initial data payload; defaults to a single empty "Sheet1"'),
+        config: z.record(z.unknown()).optional().describe('Free-form spreadsheet config object'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ name, parentId, icon, data, config, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
+        const result = await client.createSpreadsheet(ws, { name, parentId, icon, data, config });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_read_spreadsheet',
+    {
+      title: 'Read a Rootr spreadsheet',
+      description:
+        'Read a Rootr (루터) SPREADSHEET node — its sheets, each with a sparse `cells` map and dimensions. Call ' +
+        'this before rootr_update_spreadsheet / rootr_patch_spreadsheet_cells so you know the current sheetIds ' +
+        'and cell contents.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
+      },
+    },
+    async ({ spreadsheetId }) => {
+      try {
+        const client = makeClient();
+        spreadsheetId = await resolveNodeId(client, spreadsheetId);
+        const result = await client.getSpreadsheet(spreadsheetId);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_spreadsheet',
+    {
+      title: 'Update a Rootr spreadsheet (config/icon, or replace all sheets)',
+      description:
+        'Merge-patch a Rootr (루터) SPREADSHEET: update config/icon, or REPLACE THE WHOLE sheets array (if you ' +
+        'pass `sheets`, it replaces every existing sheet — call rootr_read_spreadsheet first and resend sheets ' +
+        'you want to keep, or prefer rootr_create_sheet / rootr_patch_spreadsheet_cells for incremental changes).',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
+        sheets: z
+          .array(z.record(z.unknown()))
+          .optional()
+          .describe('COMPLETE sheets array to set — omitted existing sheets will be dropped'),
+        config: z.record(z.unknown()).optional().describe('Free-form spreadsheet config object'),
+        icon: z.string().optional().describe('Emoji icon for the node'),
+      },
+    },
+    async ({ spreadsheetId, sheets, config, icon }) => {
+      try {
+        const client = makeClient();
+        spreadsheetId = await resolveNodeId(client, spreadsheetId);
+        const result = await client.updateSpreadsheet(spreadsheetId, { sheets, config, icon });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_sheet',
+    {
+      title: 'Add a sheet (tab) to a Rootr spreadsheet',
+      description: 'Add a new empty sheet (tab) to an existing Rootr (루터) SPREADSHEET, without touching other sheets.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
+        name: z.string().optional().describe('Sheet name, e.g. "Q1 Budget"'),
+        rowCount: z.number().int().min(1).max(10_000).optional().describe('Row count (default 1000)'),
+        colCount: z.number().int().min(1).max(500).optional().describe('Column count (default 52)'),
+      },
+    },
+    async ({ spreadsheetId, name, rowCount, colCount }) => {
+      try {
+        const client = makeClient();
+        spreadsheetId = await resolveNodeId(client, spreadsheetId);
+        const result = await client.createSheet(spreadsheetId, { name, rowCount, colCount });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_sheet',
+    {
+      title: 'Rename/resize ONE sheet of a Rootr spreadsheet',
+      description:
+        'Merge-patch a single sheet\'s name/dimensions/row-col sizing by sheetId, without touching its cells. ' +
+        'Call rootr_read_spreadsheet first to get the exact sheetId.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
+        sheetId: z.string().describe('Sheet id to update'),
+        name: z.string().optional().describe('New sheet name'),
+        rowCount: z.number().int().min(1).max(10_000).optional(),
+        colCount: z.number().int().min(1).max(500).optional(),
+        rowSizes: z.record(z.number()).optional().describe('Per-row heights (px), keyed by 0-based row index string'),
+        colSizes: z.record(z.number()).optional().describe('Per-column widths (px), keyed by 0-based col index string'),
+        merges: z
+          .array(z.object({ r1: z.number(), c1: z.number(), r2: z.number(), c2: z.number() }))
+          .optional()
+          .describe('Merged-cell ranges (0-indexed, inclusive, anchor = top-left)'),
+      },
+    },
+    async ({ spreadsheetId, sheetId, name, rowCount, colCount, rowSizes, colSizes, merges }) => {
+      try {
+        const client = makeClient();
+        spreadsheetId = await resolveNodeId(client, spreadsheetId);
+        const result = await client.patchSheet(spreadsheetId, sheetId, {
+          name,
+          rowCount,
+          colCount,
+          rowSizes,
+          colSizes,
+          merges,
+        });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_delete_sheet',
+    {
+      title: 'Delete a sheet (tab) from a Rootr spreadsheet',
+      description: 'Delete one sheet (tab) from a Rootr (루터) SPREADSHEET by sheetId. Not recoverable — read first to confirm.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
+        sheetId: z.string().describe('Sheet id to delete'),
+      },
+    },
+    async ({ spreadsheetId, sheetId }) => {
+      try {
+        const client = makeClient();
+        spreadsheetId = await resolveNodeId(client, spreadsheetId);
+        await client.deleteSheet(spreadsheetId, sheetId);
+        return jsonResult({ deleted: sheetId });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_patch_spreadsheet_cells',
+    {
+      title: 'Write cells into a Rootr spreadsheet sheet (preferred way to fill in data)',
+      description:
+        'Sparse-patch cells of ONE sheet in a Rootr (루터) SPREADSHEET, without touching the rest of the sheet. ' +
+        'PREFER this over rootr_update_spreadsheet when you are only filling in / editing cell values or formulas. ' +
+        CELLS_GUIDE,
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
+        sheetId: z.string().describe('Sheet id to patch'),
+        cells: z
+          .record(cellShape.nullable())
+          .describe('Map of A1-style ref -> cell (or null to clear), e.g. { "A1": { "v": 42 }, "B1": { "f": "=A1*2" } }'),
+      },
+    },
+    async ({ spreadsheetId, sheetId, cells }) => {
+      try {
+        const client = makeClient();
+        spreadsheetId = await resolveNodeId(client, spreadsheetId);
+        const result = await client.patchCells(spreadsheetId, sheetId, cells);
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/webhooks.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveOptionalNodeId, NODE_TARGET_HINT } from './shared.js';
 
 const VALID_EVENTS = [
   'document.created',
@@ -23,6 +23,7 @@ export function registerWebhookTools(server) {
       description:
         'List webhooks configured on a Rootr (루터) workspace. Secrets are not re-shown here (they only appear ' +
         'once, at creation time).',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         workspace: z
           .string()
@@ -54,11 +55,12 @@ export function registerWebhookTools(server) {
         'shown again. LOOP GUARD: deliveries carry the actor as data.actorId ("apikey:<key-id>" for API writes) — ' +
         'a consumer MUST skip deliveries caused by its own key before reacting, or an agent that writes on ' +
         'notification will trigger itself forever.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         url: z.string().describe('HTTPS endpoint to receive webhook POSTs'),
         events: z.array(z.string()).describe(`Event names to subscribe to, from: ${VALID_EVENTS.join(', ')}`),
         name: z.string().optional().describe('Human-readable name for the webhook'),
-        scopeNodeId: z.string().optional().describe('Restrict to this node and its descendants'),
+        scopeNodeId: z.string().optional().describe(`Node id${NODE_TARGET_HINT} — restrict to this node and its descendants`),
         filterTags: z.array(z.string()).optional().describe('Only fire for nodes carrying one of these tags'),
         debounceSeconds: z.number().optional().describe('Trailing debounce window in seconds (server-capped)'),
         workspace: z
@@ -71,6 +73,7 @@ export function registerWebhookTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        scopeNodeId = await resolveOptionalNodeId(client, scopeNodeId);
         const result = await client.createWebhook(ws, {
           name,
           url,
@@ -93,6 +96,7 @@ export function registerWebhookTools(server) {
     {
       title: 'Delete a webhook',
       description: 'Delete a webhook from a Rootr (루터) workspace. This cannot be undone.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         webhookId: z.string().describe('Webhook id to delete'),
         workspace: z

package/lib/mcp-tools/whiteboards.js

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+
+const shapeShape = z
+  .object({
+    id: z.string().describe('Unique shape id, referenced by edges\' from/to'),
+    type: z.string().describe('e.g. "rect" | "ellipse" | "text" | "sticky" | "arrow"'),
+    x: z.number().describe('X position'),
+    y: z.number().describe('Y position'),
+    w: z.number().describe('Width'),
+    h: z.number().describe('Height'),
+    text: z.string().optional().describe('Label/body text — text spine, put facts here'),
+    style: z.record(z.unknown()).optional().describe('Free-form style hints (color, fill, etc.)'),
+  })
+  .describe('A whiteboard shape (node of the diagram).');
+
+const edgeShape = z
+  .object({
+    id: z.string().describe('Unique edge id'),
+    from: z.string().describe('Source shape id'),
+    to: z.string().describe('Target shape id'),
+    label: z.string().optional().describe('Edge label — text spine'),
+    fromHandle: z.string().optional().describe('Connection point on the `from` shape, e.g. "b" (bottom)'),
+    toHandle: z.string().optional().describe('Connection point on the `to` shape'),
+  })
+  .describe('A whiteboard edge (connection between two shapes).');
+
+const sceneShape = z
+  .object({
+    shapes: z.array(shapeShape).optional(),
+    edges: z.array(edgeShape).optional(),
+  })
+  .describe('Simple scene: { shapes[], edges[] } — converted server-side to Excalidraw elements.');
+
+// Raw Excalidraw-native scene — full-fidelity access to EVERY element kind
+// (freehand strokes, images, frames, …), not just the simple shapes/edges view.
+const excalidrawSceneShape = z
+  .object({
+    format: z.literal('excalidraw'),
+    elements: z.array(z.record(z.unknown())).describe('Excalidraw elements (raw, as returned by mode:"full")'),
+    appState: z.record(z.unknown()).optional(),
+    files: z.record(z.unknown()).optional().describe('Image blobs keyed by fileId ({ mimeType, dataURL })'),
+  })
+  .describe('Raw Excalidraw scene: { format:"excalidraw", elements[], appState?, files? }.');
+
+const AUTHORING_GUIDE =
+  'Authoring guide: author in { shapes: [{id,type,x,y,w,h,text?,style?}], edges: [{id,from,to,label?}] } — shapes ' +
+  'are the nodes of a diagram (types: rect | ellipse | diamond | sticky | text), edges connect them by id and render ' +
+  'as arrows (with arrowheads and optional labels). style supports {color:"<stroke css color>", background:"<fill>"}. ' +
+  'The board itself is an Excalidraw canvas (humans also draw freehand/pen strokes and paste images on it — those ' +
+  'survive merge updates but are not expressible in shapes/edges). Meaning must live in shape/edge TEXT (text/label) ' +
+  '— that is what gets indexed into the knowledge graph; x/y/w/h and style are visual-only layout. Read the board ' +
+  'first (rootr_read_whiteboard) before updating so you know the existing shape ids edges refer to.';
+
+/** WHITEBOARD node tools: create/read/update the freeform diagram scene. */
+export function registerWhiteboardTools(server) {
+  server.registerTool(
+    'rootr_create_whiteboard',
+    {
+      title: 'Create a Rootr whiteboard',
+      description:
+        'Create a new WHITEBOARD node (a freeform visual canvas) in a Rootr (루터) workspace, optionally seeded ' +
+        'with an initial scene. Use WHITEBOARD for flow diagrams, brainstorming, journey maps — not for anything ' +
+        'that needs typed/trackable rows (use DATABASE) or calculation (use SPREADSHEET). ' +
+        AUTHORING_GUIDE,
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        name: z.string().optional().describe('Whiteboard name/title'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
+        icon: z.string().optional().describe('Emoji icon for the node'),
+        scene: z
+          .union([sceneShape, excalidrawSceneShape])
+          .optional()
+          .describe('Initial scene; defaults to an empty board. Simple {shapes,edges} or raw Excalidraw format.'),
+        config: z.record(z.unknown()).optional().describe('Free-form whiteboard config object'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
+      },
+    },
+    async ({ name, parentId, icon, scene, config, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
+        const result = await client.createWhiteboard(ws, { name, parentId, icon, scene, config });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_read_whiteboard',
+    {
+      title: 'Read a Rootr whiteboard',
+      description:
+        'Read a Rootr (루터) WHITEBOARD node. mode:"summary" (default) returns the compact {shapes[], edges[]} ' +
+        'view plus counts of content it cannot express (freehand strokes, images). mode:"full" additionally ' +
+        'returns EVERY raw Excalidraw element (freehand/image/frame/…, verbose) — use it when you need ' +
+        'full-fidelity access or plan a raw-format update. Call this before rootr_update_whiteboard so you know ' +
+        'the current ids.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        whiteboardId: z.string().describe(`WHITEBOARD node id${NODE_TARGET_HINT}`),
+        mode: z.enum(['summary', 'full']).optional().describe('"summary" (default) or "full" (raw elements too)'),
+      },
+    },
+    async ({ whiteboardId, mode }) => {
+      try {
+        const client = makeClient();
+        whiteboardId = await resolveNodeId(client, whiteboardId);
+        const result = await client.getWhiteboard(whiteboardId);
+        const { scene, ...rest } = result ?? {};
+        if (mode !== 'full') return jsonResult(rest);
+        // Full fidelity, but image blobs are replaced with metadata — a single
+        // dataURL can be megabytes and would swamp the model context.
+        const files = Object.fromEntries(
+          Object.entries(scene?.files ?? {}).map(([id, f]) => [
+            id,
+            { mimeType: f?.mimeType, dataURLBytes: typeof f?.dataURL === 'string' ? f.dataURL.length : 0 },
+          ]),
+        );
+        return jsonResult({ ...rest, scene: { ...scene, files } });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_whiteboard',
+    {
+      title: 'Update a Rootr whiteboard (replace or merge the scene, or config/icon)',
+      description:
+        'Update a Rootr (루터) WHITEBOARD: update config/icon, or set the scene. merge=true upserts the passed ' +
+        'shapes/edges by id onto the existing board and leaves everything else untouched (including freehand ' +
+        'drawings/images people made in the editor — PREFER merge=true when editing a board that has existing ' +
+        'content). merge=false/omitted REPLACES the whole scene — call rootr_read_whiteboard first and resend ' +
+        'anything you want to keep. ' +
+        AUTHORING_GUIDE,
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        whiteboardId: z.string().describe(`WHITEBOARD node id${NODE_TARGET_HINT}`),
+        scene: z
+          .union([sceneShape, excalidrawSceneShape])
+          .optional()
+          .describe('Scene to set (complete, unless merge=true). Simple {shapes,edges} or raw Excalidraw format.'),
+        merge: z
+          .boolean()
+          .optional()
+          .describe('true = upsert shapes/edges by id onto the existing board; false/omitted = replace the whole scene'),
+        config: z.record(z.unknown()).optional().describe('Free-form whiteboard config object'),
+        icon: z.string().optional().describe('Emoji icon for the node'),
+      },
+    },
+    async ({ whiteboardId, scene, merge, config, icon }) => {
+      try {
+        const client = makeClient();
+        whiteboardId = await resolveNodeId(client, whiteboardId);
+        const result = await client.updateWhiteboard(whiteboardId, { scene, merge, config, icon });
+        const { scene: _scene, ...rest } = result ?? {};
+        return jsonResult(rest);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}

package/lib/mcp-tools/workspaces.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 
 import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { loadConfig, saveConfig, keyForWorkspace, upsertKey } from '../config.js';
+import { currentClientOverride } from '../context.js';
+import { RootrClient } from '../client.js';
 
 /**
  * Scaffold `tree` argument schema. Declared as an ARRAY of node objects so MCP
@@ -22,8 +25,127 @@ function parseTree(tree) {
   }
 }
 
+/**
+ * Every credential this machine can use, default key first. An account key
+ * (PAT) reaches every workspace its owner belongs to; workspace keys reach one.
+ * Which one applies to a given workspace is discovered by asking the API
+ * (listWorkspaces), not guessed from the key string.
+ */
+function candidateClients() {
+  const cfg = loadConfig();
+  const out = [];
+  const seen = new Set();
+  if (cfg.apiKey) {
+    seen.add(cfg.apiKey);
+    out.push({ apiKey: cfg.apiKey, label: 'default', client: new RootrClient({ ...cfg, apiKey: cfg.apiKey }) });
+  }
+  for (const k of cfg.keys || []) {
+    if (!k.apiKey || seen.has(k.apiKey)) continue;
+    seen.add(k.apiKey);
+    out.push({ apiKey: k.apiKey, label: k.label || k.workspace || 'key', client: new RootrClient({ ...cfg, apiKey: k.apiKey }) });
+  }
+  return out;
+}
+
 /** Workspace listing and scaffolding tools: rootr_workspaces, rootr_scaffold_plan, rootr_create_workspace, rootr_scaffold_apply. */
 export function registerWorkspaceTools(server) {
+  server.registerTool(
+    'rootr_use_workspace',
+    {
+      title: 'Switch the active Rootr workspace',
+      description:
+        'Switch which Rootr (루터) workspace every later tool call works on, by id OR by name — no ' +
+        'reconfiguration, no restart. With an account key (PAT) you can switch to any workspace you belong ' +
+        'to; if separate workspace keys are configured, the one that covers the target is selected and ' +
+        'remembered automatically. Call rootr_workspaces first if you need to see what is available. ' +
+        '(A hosted/remote connector is bound to a single workspace at consent time and cannot switch.)',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        workspace: z.string().describe('Workspace id, or its name (case-insensitive)'),
+      },
+    },
+    async ({ workspace }) => {
+      try {
+        if (currentClientOverride()) {
+          return errorResult(
+            new Error(
+              '이 원격 연결은 승인 시 지정한 워크스페이스 하나에만 연결됩니다. ' +
+                '다른 워크스페이스를 쓰려면 설정>연동에서 그 워크스페이스로 커넥터를 새로 발급하세요.',
+            ),
+          );
+        }
+        const wanted = workspace.trim();
+        const wantedLower = wanted.toLowerCase();
+        const candidates = candidateClients();
+
+        // Step 1 — resolve the name/id to a real workspace. /workspaces lists
+        // the KEY OWNER's workspaces, so any key can answer this.
+        let target = null;
+        for (const candidate of candidates) {
+          let list = [];
+          try {
+            list = await candidate.client.listWorkspaces();
+          } catch {
+            continue;
+          }
+          const hit = list.find(
+            (w) => w.id === wanted || (w.name || '').toLowerCase() === wantedLower || (w.slug || '').toLowerCase() === wantedLower,
+          );
+          if (hit) {
+            target = hit;
+            break;
+          }
+        }
+
+        // Step 2 — find a key that can actually WORK in it. Listing is not a
+        // capability probe: a workspace-scoped key still lists all of its
+        // owner's workspaces while being rejected by every one but its own.
+        // Only a workspace-scoped call proves the binding.
+        let usable = null;
+        if (target) {
+          for (const candidate of candidates) {
+            try {
+              await candidate.client.request(`/workspaces/${encodeURIComponent(target.id)}`);
+              usable = candidate;
+              break;
+            } catch {
+              continue;
+            }
+          }
+        }
+        const match = target && usable ? { workspace: target, candidate: usable } : null;
+
+        if (target && !usable) {
+          return errorResult(
+            new Error(
+              `"${target.name || target.id}" 워크스페이스에 접근할 수 있는 키가 없습니다. ` +
+                '그 워크스페이스용 키를 등록하세요: rootr config --add-key <키>',
+            ),
+          );
+        }
+        if (!match) {
+          return errorResult(
+            new Error(
+              `"${wanted}" 워크스페이스를 찾지 못했습니다. rootr_workspaces로 접근 가능한 목록을 확인하세요. ` +
+                '목록에 없다면 그 워크스페이스용 키가 등록되지 않은 것입니다 (rootr config --add-key <키>).',
+            ),
+          );
+        }
+        const cfg = loadConfig();
+        saveConfig({ workspace: match.workspace.id });
+        // Remember which key covers this workspace so later calls resolve
+        // directly instead of probing every key again.
+        if (match.candidate.apiKey !== cfg.apiKey) {
+          upsertKey({ apiKey: match.candidate.apiKey, workspace: match.workspace.id, label: match.candidate.label });
+        }
+        const name = match.workspace.name || match.workspace.slug || '';
+        return textResult(`활성 워크스페이스를 "${name}" (${match.workspace.id}) 로 바꿨습니다. 이후 도구 호출은 여기에 적용됩니다.`);
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
   server.registerTool(
     'rootr_workspaces',
     {
@@ -31,15 +153,33 @@ export function registerWorkspaceTools(server) {
       description:
         'List the Rootr (루터) workspaces the current API key can see. Works with either key type: with an ' +
         'account key (PAT) this lists all workspaces you belong to; a workspace key only sees the workspace ' +
-        "it's scoped to. Use this to find a workspace id before calling other workspace-scoped tools.",
+        "it's scoped to. Use this to find a workspace id before calling other workspace-scoped tools, then " +
+        'switch to one with rootr_use_workspace (no reconfiguration needed).',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {},
     },
     async () => {
       try {
-        const client = makeClient();
-        const workspaces = await client.listWorkspaces();
-        const rows = workspaces.map((w) => `${w.id}\t${w.name || w.slug || ''}`);
-        return textResult(rows.length ? rows.join('\n') : '(no workspaces visible to this key)');
+        const hosted = currentClientOverride();
+        const active = hosted ? hosted.workspace : loadConfig().workspace;
+        const seen = new Map();
+        for (const { client } of candidateClients()) {
+          let list = [];
+          try {
+            list = await client.listWorkspaces();
+          } catch {
+            continue; // a revoked/foreign key shouldn't hide the others
+          }
+          for (const w of list) if (!seen.has(w.id)) seen.set(w.id, w);
+        }
+        const rows = [...seen.values()].map(
+          (w) => `${w.id === active ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}`,
+        );
+        return textResult(
+          rows.length
+            ? `${rows.join('\n')}\n\n(* = current; switch with rootr_use_workspace)`
+            : '(no workspaces visible to this key)',
+        );
       } catch (err) {
         return errorResult(err);
       }
@@ -58,6 +198,7 @@ export function registerWorkspaceTools(server) {
         'GENERATE your own questions from those frameworks, ask the user, and only design the tree AFTER their ' +
         'answers — every answer must visibly shape the result. Never build straight from a one-line intent. ' +
         'No workspace needed; create with rootr_create_workspace or rootr_scaffold_apply afterwards.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         intent: z.string().describe('Natural-language description of what the workspace/tree should be for'),
       },
@@ -87,6 +228,7 @@ export function registerWorkspaceTools(server) {
         'the scaffold schema in llms.txt (max 200 nodes). AFTER creating: if your runtime can receive HTTP ' +
         'callbacks, offer the user to register a webhook on the new tree (rootr_create_webhook with scopeNodeId) ' +
         'so changes flow back to you — skip your own actorId to avoid self-triggering.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().describe('Name for the new workspace'),
         intent: z.string().optional().describe('Original natural-language intent, for reference/regeneration'),
@@ -115,6 +257,7 @@ export function registerWorkspaceTools(server) {
         'bar as rootr_create_workspace — real building blocks with icons/views/seed content, not thin markdown). ' +
         'AFTER creating: if your runtime can receive HTTP callbacks, offer a webhook on the new subtree ' +
         '(rootr_create_webhook with scopeNodeId) so changes flow back to you — skip your own actorId.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         tree: treeArg('Scaffold tree — an ARRAY of node objects to create (see llms.txt tree schema)'),
         rootPath: z.string().optional().describe('Existing path to root the new tree under, e.g. "/projects"'),