rootr-cli 0.16.0 → 0.17.1

package/bin/rootr.js

@@ -91,7 +91,7 @@ const USAGE = `Rootr CLI v${pkg.version}
   rootr memory add "<내용>" [--kind 지시|사람|프로젝트|참고] [--source <경로|id>] [--related a,b]  기억 저장
   rootr memory edit <id> [--content "<내용>"] [--kind …] [--source …] [--related a,b]  기억 고치기(준 칸만)
   rootr memory forget <id> [--hard]                 기억 폐기(--hard면 행 삭제)
-  rootr mcp                                        MCP stdio 서버 구동 (도구 151종 — README 참고)
+  rootr mcp                                        MCP stdio 서버 구동 (도구 167종 — README 참고)
   rootr --help                                     도움말
   rootr --version                                  버전 출력
 

package/lib/client.js

@@ -1407,7 +1407,7 @@ export class RootrClient {
     });
   }
 
-  /** Full spreadsheet: node meta + sheets[] (each with a sparse `cells` map). */
+  /** Full spreadsheet: node meta + data.sheets[] (each with a sparse `cells` map). */
   async getSpreadsheet(spreadsheetId) {
     return this.request(`/spreadsheets/${encodeURIComponent(spreadsheetId)}`);
   }

package/lib/credentials.js

@@ -27,16 +27,22 @@ export function candidateClients(cfg = loadConfig()) {
 }
 
 /**
- * Collect every workspace the registered keys can see, and (when asked) which
- * of them a key can actually open — listing is not a capability probe: a
- * workspace key lists all of its owner's workspaces while being rejected by
- * every one but its own.
+ * Collect every workspace the registered keys can see, and which of them a
+ * key can actually open — listing is not a capability probe: a workspace key
+ * lists all of its owner's workspaces while being rejected by every one but
+ * its own. `GET /workspaces` now tags each entry with `accessible` (computed
+ * server-side from the calling key's own scope), so this reads straight off
+ * that field instead of firing one extra request per workspace. Older
+ * servers that predate the field fall back to the old per-workspace probe
+ * when `probe` is requested.
  */
 export async function surveyWorkspaces(candidates, { probe = false, probeLimit = 12 } = {}) {
   const seen = new Map();
   const reachable = new Set();
   let listed = 0;
   let failures = 0;
+  let sawAccessibleField = false;
+  const lists = [];
   for (const { client } of candidates) {
     let list = [];
     try {
@@ -46,19 +52,29 @@ export async function surveyWorkspaces(candidates, { probe = false, probeLimit =
       failures += 1;
       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);
-    if (!probe) continue;
-    for (const w of list.slice(0, probeLimit)) {
-      if (reachable.has(w.id)) continue;
-      try {
-        await client.request(`/workspaces/${encodeURIComponent(w.id)}`);
-        reachable.add(w.id);
-      } catch {
-        // scoped key rejected here; another key may still cover it
+    lists.push({ client, list });
+    for (const w of list) {
+      if (!seen.has(w.id)) seen.set(w.id, w);
+      if (typeof w.accessible === 'boolean') {
+        sawAccessibleField = true;
+        if (w.accessible) reachable.add(w.id);
+      }
+    }
+  }
+  if (!sawAccessibleField && probe) {
+    for (const { client, list } of lists) {
+      for (const w of list.slice(0, probeLimit)) {
+        if (reachable.has(w.id)) continue;
+        try {
+          await client.request(`/workspaces/${encodeURIComponent(w.id)}`);
+          reachable.add(w.id);
+        } catch {
+          // scoped key rejected here; another key may still cover it
+        }
       }
     }
   }
-  return { workspaces: [...seen.values()], reachable, listed, failures };
+  return { workspaces: [...seen.values()], reachable, listed, failures, probed: sawAccessibleField || probe };
 }
 
 /**

package/lib/mcp-tools/crm.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 
 /**
  * Shared context repeated (shortened) across tool descriptions so an agent
@@ -56,7 +56,9 @@ export function registerCrmTools(server) {
         'activities and tasks all live inside it. Optionally seed custom `pipelines` (name + ordered stages, each ' +
         'with an optional win probability/color) and/or custom company/contact/deal `fields`; sane defaults are ' +
         'used if omitted. ' +
-        CRM_CONTEXT,
+        CRM_CONTEXT +
+        ' ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('CRM node name'),

package/lib/mcp-tools/databases.js

@@ -8,6 +8,7 @@ import {
   resolveNodeId,
   resolveOptionalNodeId,
   NODE_TARGET_HINT,
+  NODE_URL_HINT,
 } from './shared.js';
 
 /** Human text for the `databaseId` param — accepts a path just like the document tools. */
@@ -139,7 +140,8 @@ export function registerDatabaseTools(server) {
         'COST NOTE: by default, every row added to this table (now or later) queues that table for graph extraction ' +
         '(embeddings + LLM) — fine for a handful of rows, expensive for a bulk-loaded roster/log table. Pass ' +
         'graphSync:false for tables you are about to bulk-load; flip it back with ' +
-        '`rootr_update_node({ graphSyncOff: true|false })` any time after.',
+        '`rootr_update_node({ graphSyncOff: true|false })` any time after. ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().describe('Table name, e.g. "업무 목록"'),

package/lib/mcp-tools/documents.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 import { RootrApiError } from '../client.js';
 import { resolveTarget, requireResolved, resolveMoveDestination } from '../resolve.js';
-import { textResult, jsonResult, errorResult, makeClient, NODE_TARGET_HINT } from './shared.js';
+import { textResult, jsonResult, errorResult, makeClient, NODE_TARGET_HINT, NODE_URL_HINT } from './shared.js';
 
 /** Registers the original 6 document tools: list/read/append/edit/write/search. */
 export function registerDocumentTools(server) {
@@ -147,7 +147,8 @@ export function registerDocumentTools(server) {
       description:
         'Replace the ENTIRE content of a Rootr document, or create a new document at a path if it does not exist. ' +
         'This is DESTRUCTIVE — it discards whatever is currently there. Read the document first and pass its etag ' +
-        'as ifMatch to avoid clobbering concurrent changes. Prefer rootr_append or rootr_edit for incremental changes.',
+        'as ifMatch to avoid clobbering concurrent changes. Prefer rootr_append or rootr_edit for incremental changes. ' +
+        `When this creates a new document, the result text includes its address (same idea as: ${NODE_URL_HINT}).`,
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/", created if missing) or node id, or a full rootr.io URL'),
@@ -174,7 +175,8 @@ export function registerDocumentTools(server) {
             content,
           });
           const id = created.id || (created.node && created.node.id);
-          return textResult(`created ${resolved.path} (id ${id})`);
+          const url = created.url || (created.node && created.node.url);
+          return textResult(`created ${resolved.path} (id ${id})${url ? ` — ${url}` : ''}`);
         }
         const { etag } = await client.putDocument(resolved.id, content, { ifMatch });
         return textResult(`wrote (etag ${etag || 'n/a'})`);

package/lib/mcp-tools/forms.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 
 const fieldShape = z
   .object({
@@ -88,7 +88,9 @@ export function registerFormTools(server) {
         'Create a new FORM node (fillable intake) in a Rootr (루터) workspace, optionally seeded with field ' +
         'definitions. Use FORM for surveys/request queues collected from people outside the tree — set ' +
         '`targetDatabaseId` to also mirror each response into a DATABASE\'s rows. ' +
-        FIELDS_GUIDE,
+        FIELDS_GUIDE +
+        ' ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Form name/title'),

package/lib/mcp-tools/issues.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { textResult, jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+import { textResult, jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT } from './shared.js';
 
 /** Issue tracker tools: create tracker, list/create/get/update issues, comment. */
 export function registerIssueTools(server) {
@@ -10,7 +10,8 @@ export function registerIssueTools(server) {
       title: 'Create an issue tracker in a Rootr workspace',
       description:
         'Create a new GitHub-style issue tracker document in a Rootr (루터) workspace. Returns the tracker with ' +
-        'its id, plus its default labels/types — use rootr_create_issue afterward to add issues to it.',
+        'its id, plus its default labels/types — use rootr_create_issue afterward to add issues to it. ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().describe('Name of the issue tracker'),

package/lib/mcp-tools/logs.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 
 /** LOG datastore tools: create/update-fields/add-entries/query-entries/stats. */
 export function registerLogTools(server) {
@@ -12,7 +12,8 @@ export function registerLogTools(server) {
         'Create a new typed LOG store (a structured, queryable table-like node) in a Rootr (루터) workspace. ' +
         'Each field has a name/type; type is one of string|int|float|bool|datetime|json|enum|level|relation. ' +
         'Relation fields additionally need target (a node id to relate to) and optional many/relation flags. ' +
-        'Use rootr_add_log_entries afterward to insert rows, and rootr_query_log_entries / rootr_log_stats to read them back.',
+        'Use rootr_add_log_entries afterward to insert rows, and rootr_query_log_entries / rootr_log_stats to read them back. ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().describe('Name of the LOG store'),

package/lib/mcp-tools/pages.js

@@ -8,6 +8,7 @@ import {
   resolveNodeId,
   resolveOptionalNodeId,
   NODE_TARGET_HINT,
+  NODE_URL_HINT,
 } from './shared.js';
 
 /**
@@ -66,7 +67,10 @@ export function registerPageTools(server) {
         'can then be published to the web at a public address (see rootr_publish_node). Use this when someone asks ' +
         'for a landing page, an announcement page, an event page, a product/pricing page or a signup page. ' +
         'Omit `blocks` to start from a hero/text/footer skeleton. ' +
-        BLOCK_GUIDE,
+        BLOCK_GUIDE +
+        ' ' +
+        NODE_URL_HINT +
+        ' (that is the editor address; use rootr_publish_node for the public address.)',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Page name (also the browser tab title of the published page)'),

package/lib/mcp-tools/presentations.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 
 /**
  * Authoring guide, repeated (shortened) across every tool description so an
@@ -123,7 +123,9 @@ export function registerPresentationTools(server) {
       description:
         'Create a new PRESENTATION node (a slide deck) in a Rootr (루터) workspace, optionally seeded with an ' +
         'initial theme and slides. ' +
-        AUTHORING_GUIDE,
+        AUTHORING_GUIDE +
+        ' ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Deck name/title'),

package/lib/mcp-tools/recordings.js

@@ -4,7 +4,7 @@ import { basename, extname, join, isAbsolute } from 'node:path';
 
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 import { RootrApiError } from '../client.js';
 
 /** 100MB — the backend's hard limit on a single audio upload. */
@@ -68,7 +68,8 @@ export function registerRecordingTools(server) {
         'speech-to-text; nothing is transcribed until you call it) → poll rootr_read_recording until status is ' +
         'READY → read the transcript (and optionally name the speakers with rootr_rename_recording_speakers) → ' +
         'write the minutes yourself with rootr_write, or call rootr_summarize_recording to use Rootr\'s built-in ' +
-        'summarizer.',
+        'summarizer. ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Recording name/title, e.g. "2026-07-21 주간회의"'),

package/lib/mcp-tools/shared.js

@@ -10,6 +10,15 @@ import { resolveTarget, requireResolved } from '../resolve.js';
  */
 export const NODE_TARGET_HINT = ', or its path starting with "/", or a full rootr.io URL';
 
+/**
+ * ISSUE-103 — every node create/read tool's result carries `url` (the address
+ * to hand a human) and `routeSegment` (the URL segment, in case `url` is
+ * missing). Never guess the segment yourself: DOCUMENT/db/log/sheet/whiteboard/
+ * form/issues/deck/crm/rec are all different, and SIGNED reuses DOCUMENT's 'd'.
+ */
+export const NODE_URL_HINT =
+  'The result includes `url` — the address to open this node at. Use it as-is; never guess or construct it.';
+
 /**
  * Resolve a path-or-id argument to a node id. Paths go through the by-path
  * endpoint; anything else is already an id and is passed through untouched.

package/lib/mcp-tools/signed.js

@@ -9,6 +9,7 @@ import {
   resolveNodeId,
   resolveOptionalNodeId,
   NODE_TARGET_HINT,
+  NODE_URL_HINT,
 } from './shared.js';
 
 /**
@@ -77,7 +78,9 @@ export function registerSignedDocTools(server) {
         '문서, 연구노트, 점검 기록, 회의 확인서. ' +
         'Flow: create (body + approval line) → edit the body freely with rootr_write/rootr_append → ' +
         'rootr_request_signing_code → ask the human for the 6-digit code → rootr_submit_signed_document ' +
-        '(freezes + first signature) → each remaining signer does request-code + rootr_sign_document.',
+        '(freezes + first signature) → each remaining signer does request-code + rootr_sign_document. ' +
+        NODE_URL_HINT +
+        ' (SIGNED opens on the DOCUMENT screen, not a dedicated one.)',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('문서 이름, 예: "2026-08-25 실험 기록"'),

package/lib/mcp-tools/spreadsheets.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 
 const CELL_VALUE = z
   .union([z.string(), z.number(), z.boolean(), z.null()])
@@ -28,7 +28,9 @@ export function registerSpreadsheetTools(server) {
         '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,
+        CELLS_GUIDE +
+        ' ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Spreadsheet name/title'),
@@ -60,7 +62,8 @@ export function registerSpreadsheetTools(server) {
     {
       title: 'Read a Rootr spreadsheet',
       description:
-        'Read a Rootr (루터) SPREADSHEET node — its sheets, each with a sparse `cells` map and dimensions. Call ' +
+        'Read a Rootr (루터) SPREADSHEET node — returns { data: { sheets: [...] }, ... }, where each sheet has ' +
+        'a sparse `cells` map and dimensions (sheets are under `data.sheets`, not top-level `sheets`). Call ' +
         'this before rootr_update_spreadsheet / rootr_patch_spreadsheet_cells so you know the current sheetIds ' +
         'and cell contents.',
       annotations: { readOnlyHint: true, destructiveHint: false },

package/lib/mcp-tools/whiteboards.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
 
 const shapeShape = z
   .object({
@@ -63,7 +63,9 @@ export function registerWhiteboardTools(server) {
         '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,
+        AUTHORING_GUIDE +
+        ' ' +
+        NODE_URL_HINT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Whiteboard name/title'),

package/lib/mcp-tools/workspaces.js

@@ -118,12 +118,12 @@ export function registerWorkspaceTools(server) {
         }
         const cfg = loadConfig();
         const candidates = candidateClients(cfg);
-        // Probing costs one API call per workspace (they count against the
-        // daily read quota), so only do it in the case it actually diagnoses:
-        // no account key registered, i.e. every credential here is scoped to
-        // one workspace and most of the list is unusable.
+        // Probe only matters as a fallback for servers that predate the
+        // `accessible` field on GET /workspaces — surveyWorkspaces() reads
+        // that field for free when present, so this no longer costs extra
+        // API calls in the normal case.
         const probe = !cfg.apiKey && (cfg.keys || []).length > 0;
-        const { workspaces, reachable, failures } = await surveyWorkspaces(candidates, { probe });
+        const { workspaces, reachable, failures, probed } = await surveyWorkspaces(candidates, { probe });
         if (!workspaces.length) {
           return textResult(
             (failures ? '등록된 키로 워크스페이스 목록을 조회하지 못했습니다 (키 만료/취소 가능성).\n' : '이 컴퓨터에 등록된 Rootr 키가 없습니다.\n') +
@@ -133,13 +133,14 @@ export function registerWorkspaceTools(server) {
         const rows = workspaces.map(
           (w) =>
             `${w.id === cfg.workspace ? '* ' : '  '}${w.id}\t${w.name || w.slug || ''}` +
-            (!probe || reachable.has(w.id) ? '' : '\t[등록된 키로는 접근 불가]'),
+            (!probed || reachable.has(w.id) ? '' : '\t[등록된 키로는 접근 불가]'),
         );
-        const blocked = probe && workspaces.some((w) => !reachable.has(w.id));
+        const blocked = probed && workspaces.some((w) => !reachable.has(w.id));
         return textResult(
           `${rows.join('\n')}\n\n(* = 현재 워크스페이스, rootr_use_workspace 로 전환)` +
             (blocked
               ? '\n"접근 불가" = 내 소속 워크스페이스지만 등록된 키가 워크스페이스 전용이라 못 엽니다. ' +
+                '쓰기 전에 이 목록에서 "접근 불가"가 없는 워크스페이스만 고르세요. ' +
                 '계정 키(PAT)를 등록하면 전부 열립니다: rootr.io > 설정 > API 키 → `rootr config --api-key <키>`'
               : ''),
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
   "type": "module",
   "bin": {