rootr-cli 0.4.0 → 0.4.1

package/README.md

@@ -206,6 +206,13 @@ rootr ask "왜 결제 실패가 늘었지?" --workspace ws_123
 
 `rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 29종:
 
+노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
+`recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
+받습니다 — CLI와 같은 규칙으로 `/`로 시작하면 경로로 해석합니다.
+즉 `rootr_add_row`에 `databaseId: "/제작 공정/칸반"`을 그대로 넘길 수 있어,
+경로만 아는 에이전트가 uuid를 찾아 헤맬 필요가 없습니다.
+`rootr_list`·`rootr_search` 출력도 각 줄 끝에 `[노드 id]`를 함께 표시합니다.
+
 #### 문서 (workspace 키, docs:read/docs:write)
 
 | 도구 | 설명 |

package/lib/mcp-tools/attachments.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs';
 
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveOptionalNodeId, NODE_TARGET_HINT } from './shared.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
 import { RootrApiError } from '../client.js';
 
@@ -24,7 +24,7 @@ const uploadInputSchema = {
     .string()
     .optional()
     .describe('Base64-encoded file bytes; use this when the caller has the file in memory instead of on disk'),
-  nodeId: z.string().optional().describe('Document/node id to associate the attachment with (permission-checked)'),
+  nodeId: z.string().optional().describe(`Document/node id${NODE_TARGET_HINT} to associate the attachment with (permission-checked)`),
   workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
 };
 
@@ -48,6 +48,7 @@ export function registerAttachmentTools(server) {
       try {
         const client = makeClient();
         const ws = requireWorkspace(workspace);
+        nodeId = await resolveOptionalNodeId(client, nodeId);
         const data = readAttachmentBytes({ filePath, base64Data });
         const { id } = await client.uploadAttachment(ws, { filename, mimeType, nodeId, data });
         const url = client.attachmentRawUrl(id);

package/lib/mcp-tools/crm.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 
 /**
  * Shared context repeated (shortened) across tool descriptions so an agent
@@ -61,7 +61,7 @@ export function registerCrmTools(server) {
       inputSchema: {
         name: z.string().optional().describe('CRM node name'),
         path: z.string().optional().describe('Full tree path to create at, e.g. "/sales/crm"'),
-        parentId: z.string().optional().describe('Parent folder/node id to create the CRM under'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
         icon: z.string().optional().describe('Emoji icon for the CRM node'),
         pipelines: z
           .array(pipelineShape)
@@ -81,6 +81,7 @@ export function registerCrmTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
         const result = await client.createCrm(ws, {
           name,
           path,
@@ -111,7 +112,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         includeSummary: z
           .boolean()
           .optional()
@@ -121,6 +122,7 @@ export function registerCrmTools(server) {
     async ({ crmId, includeSummary }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const crm = await client.getCrm(crmId);
         if (includeSummary) {
           const summary = await client.getCrmSummary(crmId);
@@ -144,7 +146,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         pipelines: z
           .array(pipelineShape)
           .optional()
@@ -157,6 +159,7 @@ export function registerCrmTools(server) {
     async ({ crmId, pipelines, fields, config, icon }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.updateCrm(crmId, {
           pipelines: coerceJson(pipelines),
           fields: coerceJson(fields),
@@ -182,7 +185,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         q: z.string().optional().describe('Free-text search (name/domain/etc.)'),
         ownerId: z.string().optional().describe('Filter by owning user id'),
         tag: z.string().optional().describe('Filter by tag'),
@@ -194,6 +197,7 @@ export function registerCrmTools(server) {
     async ({ crmId, q, ownerId, tag, sort, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmCompanies(crmId, { q, ownerId, tag, sort, limit, offset });
         return jsonResult(result);
       } catch (err) {
@@ -213,7 +217,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         companyId: z.string().optional().describe('Existing company id to update/delete; omit to create a new company'),
         delete: z.boolean().optional().describe('If true (with companyId), delete the company instead of updating'),
         name: z.string().optional().describe('Company name (required when creating)'),
@@ -231,6 +235,7 @@ export function registerCrmTools(server) {
     async ({ crmId, companyId, delete: doDelete, custom, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         if (companyId && doDelete) {
           await client.deleteCrmCompany(companyId);
           return jsonResult({ deleted: true, companyId });
@@ -283,7 +288,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         q: z.string().optional().describe('Free-text search (name/email/etc.)'),
         companyId: z.string().optional().describe('Filter by company id'),
         lifecycleStage: z.string().optional().describe('lead | mql | sql | opportunity | customer | evangelist'),
@@ -298,6 +303,7 @@ export function registerCrmTools(server) {
     async ({ crmId, q, companyId, lifecycleStage, leadStatus, ownerId, tag, sort, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmContacts(crmId, {
           q,
           companyId,
@@ -327,7 +333,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         contactId: z.string().optional().describe('Existing contact id to update/delete; omit to create a new contact'),
         delete: z.boolean().optional().describe('If true (with contactId), delete the contact instead of updating'),
         name: z.string().optional().describe('Contact name (required when creating)'),
@@ -353,6 +359,7 @@ export function registerCrmTools(server) {
     async ({ crmId, contactId, delete: doDelete, custom, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         if (contactId && doDelete) {
           await client.deleteCrmContact(contactId);
           return jsonResult({ deleted: true, contactId });
@@ -401,7 +408,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         q: z.string().optional().describe('Free-text search (deal name/etc.)'),
         pipelineId: z.string().optional().describe('Filter by pipeline id'),
         stageId: z.string().optional().describe('Filter by stage id'),
@@ -418,6 +425,7 @@ export function registerCrmTools(server) {
     async ({ crmId, q, pipelineId, stageId, status, ownerId, companyId, contactId, tag, sort, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmDeals(crmId, {
           q,
           pipelineId,
@@ -450,7 +458,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         dealId: z.string().optional().describe('Existing deal id to update/delete; omit to create a new deal'),
         delete: z.boolean().optional().describe('If true (with dealId), delete the deal instead of updating'),
         name: z.string().optional().describe('Deal name (required when creating)'),
@@ -478,6 +486,7 @@ export function registerCrmTools(server) {
     async ({ crmId, dealId, delete: doDelete, contacts, custom, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         if (dealId && doDelete) {
           await client.deleteCrmDeal(dealId);
           return jsonResult({ deleted: true, dealId });
@@ -552,7 +561,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         type: z.string().describe('note | call | email | meeting'),
         subject: z.string().optional(),
         body: z.string().optional().describe('Activity body/notes (markdown/plain text)'),
@@ -565,6 +574,7 @@ export function registerCrmTools(server) {
     async ({ crmId, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.createCrmActivity(crmId, rest);
         return jsonResult(result);
       } catch (err) {
@@ -582,7 +592,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         contactId: z.string().optional(),
         companyId: z.string().optional(),
         dealId: z.string().optional(),
@@ -594,6 +604,7 @@ export function registerCrmTools(server) {
     async ({ crmId, contactId, companyId, dealId, type, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmActivities(crmId, { contactId, companyId, dealId, type, limit, offset });
         return jsonResult(result);
       } catch (err) {
@@ -615,7 +626,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id (required when creating; ignored when updating)'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT} (required when creating; ignored when updating)`),
         taskId: z.string().optional().describe('Existing task id to update; omit to create a new task'),
         title: z.string().optional().describe('Task title (required when creating)'),
         type: z.string().optional().describe('todo | call | email | meeting'),
@@ -630,6 +641,7 @@ export function registerCrmTools(server) {
     async ({ crmId, taskId, ...rest }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = taskId ? await client.updateCrmTask(taskId, rest) : await client.createCrmTask(crmId, rest);
         return jsonResult(result);
       } catch (err) {
@@ -648,7 +660,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         status: z.string().optional().describe('open | done | all'),
         assigneeId: z.string().optional(),
         due: z.string().optional().describe('overdue | today | upcoming'),
@@ -662,6 +674,7 @@ export function registerCrmTools(server) {
     async ({ crmId, status, assigneeId, due, contactId, companyId, dealId, limit, offset }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.listCrmTasks(crmId, {
           status,
           assigneeId,
@@ -693,7 +706,7 @@ export function registerCrmTools(server) {
         CRM_CONTEXT,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        crmId: z.string().describe('CRM node id'),
+        crmId: z.string().describe(`CRM node id${NODE_TARGET_HINT}`),
         entity: z.string().describe('contact | company | deal'),
         rows: z.array(z.record(z.unknown())).describe('Array of row objects to import, matching the entity shape'),
       },
@@ -701,6 +714,7 @@ export function registerCrmTools(server) {
     async ({ crmId, entity, rows }) => {
       try {
         const client = makeClient();
+        crmId = await resolveNodeId(client, crmId);
         const result = await client.importCrm(crmId, { entity, rows: coerceJson(rows) });
         return jsonResult(result);
       } catch (err) {

package/lib/mcp-tools/databases.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient } from './shared.js';
+import { jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+
+/** Human text for the `databaseId` param — accepts a path just like the document tools. */
+const DATABASE_TARGET_DESC = `DATABASE node id${NODE_TARGET_HINT} (e.g. "/제작 공정/칸반")`;
 
 /**
  * Resolve a `{propertyNameOrId: value}` map to `{propertyId: value}` using the
@@ -40,15 +43,16 @@ export function registerDatabaseTools(server) {
         'property ids/names and, for board/kanban views, which select column holds the status. Only works on DATABASE nodes.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
       },
     },
     async ({ databaseId }) => {
       try {
         const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
         const [database, rows] = await Promise.all([
-          client.getDatabase(databaseId),
-          client.listRows(databaseId),
+          client.getDatabase(id),
+          client.listRows(id),
         ]);
         return jsonResult({ database, rows });
       } catch (err) {
@@ -66,13 +70,13 @@ export function registerDatabaseTools(server) {
         'Use rootr_read_database instead when you also need the property/column definitions.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
       },
     },
     async ({ databaseId }) => {
       try {
         const client = makeClient();
-        const rows = await client.listRows(databaseId);
+        const rows = await client.listRows(await resolveNodeId(client, databaseId));
         return jsonResult({ rows });
       } catch (err) {
         return errorResult(err);
@@ -91,7 +95,7 @@ export function registerDatabaseTools(server) {
         'Call rootr_read_database first to learn the columns. Optionally set `position` to insert at an index.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
         values: z.record(z.unknown()).describe('{ propertyNameOrId: value } for the new row'),
         position: z.number().optional().describe('0-based insert index; appended at the end if omitted'),
       },
@@ -99,9 +103,10 @@ export function registerDatabaseTools(server) {
     async ({ databaseId, values, position }) => {
       try {
         const client = makeClient();
-        const database = await client.getDatabase(databaseId);
+        const id = await resolveNodeId(client, databaseId);
+        const database = await client.getDatabase(id);
         const resolved = resolveValueKeys(database.properties || [], values);
-        const row = await client.createRow(databaseId, { values: resolved, position });
+        const row = await client.createRow(id, { values: resolved, position });
         return jsonResult(row);
       } catch (err) {
         return errorResult(err);
@@ -120,7 +125,7 @@ export function registerDatabaseTools(server) {
         'Optionally set `position` to reorder the row.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
         rowId: z.string().describe('Row id (must belong to the database)'),
         values: z.record(z.unknown()).optional().describe('{ propertyNameOrId: newValue | null } partial patch'),
         position: z.number().optional().describe('New 0-based position for the row'),
@@ -129,12 +134,13 @@ export function registerDatabaseTools(server) {
     async ({ databaseId, rowId, values, position }) => {
       try {
         const client = makeClient();
+        const id = await resolveNodeId(client, databaseId);
         let resolved;
         if (values !== undefined) {
-          const database = await client.getDatabase(databaseId);
+          const database = await client.getDatabase(id);
           resolved = resolveValueKeys(database.properties || [], values);
         }
-        const row = await client.updateRow(databaseId, rowId, { values: resolved, position });
+        const row = await client.updateRow(id, rowId, { values: resolved, position });
         return jsonResult(row);
       } catch (err) {
         return errorResult(err);
@@ -151,14 +157,14 @@ export function registerDatabaseTools(server) {
         'Verify the row via rootr_read_database first — do not guess rowIds.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        databaseId: z.string().describe('DATABASE node id'),
+        databaseId: z.string().describe(DATABASE_TARGET_DESC),
         rowId: z.string().describe('Row id to delete (must belong to the database)'),
       },
     },
     async ({ databaseId, rowId }) => {
       try {
         const client = makeClient();
-        await client.deleteRow(databaseId, rowId);
+        await client.deleteRow(await resolveNodeId(client, databaseId), rowId);
         return jsonResult({ deleted: true, rowId });
       } catch (err) {
         return errorResult(err);

package/lib/mcp-tools/documents.js

@@ -31,7 +31,12 @@ export function registerDocumentTools(server) {
             const p = n.path || '';
             return p === path || p.startsWith(path.endsWith('/') ? path : path + '/');
           })
-          .map((n) => `${n.type || '?'} ${n.path || n.name || n.id}`)
+          .map((n) => {
+            const label = n.path || n.name || n.id;
+            // Keep the id visible: tools that take a node id (databases, sheets,
+            // whiteboards, …) are otherwise unreachable from a listing.
+            return n.id && label !== n.id ? `${n.type || '?'} ${label}  [${n.id}]` : `${n.type || '?'} ${label}`;
+          })
           .sort();
         return textResult(rows.length ? rows.join('\n') : '(no matching nodes)');
       } catch (err) {
@@ -189,7 +194,11 @@ export function registerDocumentTools(server) {
       try {
         const client = makeClient();
         const results = await client.search(query);
-        const rows = results.map((r) => `${r.path || r.name || r.nodeId} — ${r.snippet || ''}`);
+        const rows = results.map((r) => {
+          const label = r.path || r.name || r.nodeId;
+          const id = r.nodeId && label !== r.nodeId ? `  [${r.nodeId}]` : '';
+          return `${label}${id} — ${r.snippet || ''}`;
+        });
         return textResult(rows.length ? rows.join('\n') : '(no results)');
       } catch (err) {
         return errorResult(err);

package/lib/mcp-tools/forms.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 
 const fieldShape = z
   .object({
@@ -37,10 +37,10 @@ export function registerFormTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Form name/title'),
-        parentId: z.string().optional().describe('Parent folder/node id to create it under'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
         icon: z.string().optional().describe('Emoji icon for the node'),
         fields: z.array(fieldShape).optional().describe('Initial field definitions; defaults to an empty form'),
-        targetDatabaseId: z.string().optional().describe('DATABASE node id whose rows should mirror this form\'s responses'),
+        targetDatabaseId: z.string().optional().describe(`DATABASE node id${NODE_TARGET_HINT} whose rows mirror this form's responses`),
         config: z.record(z.unknown()).optional().describe('Free-form form config object (e.g. publicSubmit mode)'),
         workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config if omitted'),
       },
@@ -49,6 +49,8 @@ export function registerFormTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        targetDatabaseId = await resolveOptionalNodeId(client, targetDatabaseId);
+        parentId = await resolveOptionalNodeId(client, parentId);
         const result = await client.createForm(ws, { name, parentId, icon, fields, targetDatabaseId, config });
         return jsonResult(result);
       } catch (err) {
@@ -67,12 +69,13 @@ export function registerFormTools(server) {
         'which field ids the response `values` are keyed by.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        formId: z.string().describe('FORM node id'),
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ formId }) => {
       try {
         const client = makeClient();
+        formId = await resolveNodeId(client, formId);
         const result = await client.getForm(formId);
         return jsonResult(result);
       } catch (err) {
@@ -92,9 +95,9 @@ export function registerFormTools(server) {
         FIELDS_GUIDE,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        formId: z.string().describe('FORM node id'),
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
         fields: z.array(fieldShape).optional().describe('COMPLETE fields array to set — omitted existing fields will be dropped'),
-        targetDatabaseId: z.string().nullable().optional().describe('DATABASE node id to mirror responses into, or null to unlink'),
+        targetDatabaseId: z.string().nullable().optional().describe(`DATABASE node id${NODE_TARGET_HINT} to mirror responses into, or null to unlink`),
         config: z.record(z.unknown()).optional().describe('Free-form form config object (e.g. publicSubmit mode)'),
         icon: z.string().optional().describe('Emoji icon for the node'),
       },
@@ -102,6 +105,8 @@ export function registerFormTools(server) {
     async ({ formId, fields, targetDatabaseId, config, icon }) => {
       try {
         const client = makeClient();
+        targetDatabaseId = await resolveOptionalNodeId(client, targetDatabaseId);
+        formId = await resolveNodeId(client, formId);
         const result = await client.updateForm(formId, { fields, targetDatabaseId, config, icon });
         return jsonResult(result);
       } catch (err) {
@@ -120,12 +125,13 @@ export function registerFormTools(server) {
         'responses collected from a form.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        formId: z.string().describe('FORM node id'),
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ formId }) => {
       try {
         const client = makeClient();
+        formId = await resolveNodeId(client, formId);
         const result = await client.listFormResponses(formId);
         return jsonResult({ responses: result });
       } catch (err) {
@@ -144,13 +150,14 @@ export function registerFormTools(server) {
         'exact field ids and types.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        formId: z.string().describe('FORM node id'),
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
         values: z.record(z.unknown()).describe('Response values keyed by field id'),
       },
     },
     async ({ formId, values }) => {
       try {
         const client = makeClient();
+        formId = await resolveNodeId(client, formId);
         const result = await client.createFormResponse(formId, values);
         return jsonResult(result);
       } catch (err) {
@@ -169,12 +176,13 @@ export function registerFormTools(server) {
         'rootr_update_form\'s config.publicSubmit ("off" | "login" | "anon").',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        formId: z.string().describe('FORM node id'),
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ formId }) => {
       try {
         const client = makeClient();
+        formId = await resolveNodeId(client, formId);
         const result = await client.createFormShareLink(formId);
         return jsonResult(result);
       } catch (err) {
@@ -190,12 +198,13 @@ export function registerFormTools(server) {
       description: 'List existing public share links/tokens issued for a Rootr (루터) FORM.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        formId: z.string().describe('FORM node id'),
+        formId: z.string().describe(`FORM node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ formId }) => {
       try {
         const client = makeClient();
+        formId = await resolveNodeId(client, formId);
         const result = await client.listFormShareLinks(formId);
         return jsonResult({ links: result });
       } catch (err) {

package/lib/mcp-tools/issues.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { textResult, jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
 
 /** Issue tracker tools: create tracker, list/create/get/update issues, comment. */
 export function registerIssueTools(server) {
@@ -41,7 +41,7 @@ export function registerIssueTools(server) {
         'type id, or a text query. Use rootr_get_issue for full details of one issue.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        trackerId: z.string().describe('Issue tracker node id'),
+        trackerId: z.string().describe(`Issue tracker node id${NODE_TARGET_HINT}`),
         state: z.string().optional().describe('OPEN | CLOSED | ALL'),
         q: z.string().optional().describe('Free-text search within issues'),
         label: z.string().optional().describe('Label id to filter by'),
@@ -51,6 +51,7 @@ export function registerIssueTools(server) {
     async ({ trackerId, state, q, label, type }) => {
       try {
         const client = makeClient();
+        trackerId = await resolveNodeId(client, trackerId);
         const result = await client.listIssues(trackerId, { state, q, label, type });
         return jsonResult(result);
       } catch (err) {
@@ -69,7 +70,7 @@ export function registerIssueTools(server) {
         'parentIssueId nests this issue under another issue (sub-issue).',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        trackerId: z.string().describe('Issue tracker node id'),
+        trackerId: z.string().describe(`Issue tracker node id${NODE_TARGET_HINT}`),
         title: z.string().describe('Issue title'),
         body: z.string().optional().describe('Issue body (markdown)'),
         labels: z.array(z.string()).optional().describe('Label ids to attach'),
@@ -80,6 +81,7 @@ export function registerIssueTools(server) {
     async ({ trackerId, title, body, labels, type, parentIssueId }) => {
       try {
         const client = makeClient();
+        trackerId = await resolveNodeId(client, trackerId);
         const result = await client.createIssue(trackerId, { title, body, labels, type, parentIssueId });
         return jsonResult(result);
       } catch (err) {
@@ -150,7 +152,7 @@ export function registerIssueTools(server) {
         'so this requires an ACCOUNT key (PAT) as ROOTR_API_KEY — a workspace key gets a 403.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        trackerId: z.string().describe('Issue tracker node id'),
+        trackerId: z.string().describe(`Issue tracker node id${NODE_TARGET_HINT}`),
         issueId: z.string().describe('Issue id to comment on'),
         body: z.string().describe('Comment body (markdown)'),
       },
@@ -158,6 +160,7 @@ export function registerIssueTools(server) {
     async ({ trackerId, issueId, body }) => {
       try {
         const client = makeClient();
+        trackerId = await resolveNodeId(client, trackerId);
         const result = await client.commentIssue(trackerId, issueId, body);
         return textResult(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
       } catch (err) {

package/lib/mcp-tools/logs.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 
 /** LOG datastore tools: create/update-fields/add-entries/query-entries/stats. */
 export function registerLogTools(server) {
@@ -22,7 +22,7 @@ export function registerLogTools(server) {
             'Field definitions: [{name, type, ...}]. type=string|int|float|bool|datetime|json|enum|level|relation. ' +
               'relation fields add target (node id), many?, relation?.',
           ),
-        parentId: z.string().optional().describe('Parent node id to nest the LOG store under'),
+        parentId: z.string().optional().describe(`Parent node id${NODE_TARGET_HINT}`),
         workspace: z
           .string()
           .optional()
@@ -33,6 +33,7 @@ export function registerLogTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
         const result = await client.createLogStore(ws, { name, fields, parentId });
         return jsonResult(result);
       } catch (err) {
@@ -51,7 +52,7 @@ export function registerLogTools(server) {
         'Read the LOG store first (e.g. via rootr_read or a get-log call) to see its current fields before calling this.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        logId: z.string().describe('LOG store node id'),
+        logId: z.string().describe(`LOG store node id${NODE_TARGET_HINT}`),
         fields: z
           .array(z.record(z.any()))
           .describe('COMPLETE field list to set — omitted existing fields will be dropped'),
@@ -60,6 +61,7 @@ export function registerLogTools(server) {
     async ({ logId, fields }) => {
       try {
         const client = makeClient();
+        logId = await resolveNodeId(client, logId);
         const result = await client.updateLogFields(logId, fields);
         return jsonResult(result);
       } catch (err) {
@@ -77,7 +79,7 @@ export function registerLogTools(server) {
         '(shaped per the store\'s field schema). This is additive — existing entries are untouched.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        logId: z.string().describe('LOG store node id'),
+        logId: z.string().describe(`LOG store node id${NODE_TARGET_HINT}`),
         entries: z
           .array(z.record(z.any()))
           .describe('Entries to add: [{ts?, source?, level?, message?, data?}, ...]'),
@@ -86,6 +88,7 @@ export function registerLogTools(server) {
     async ({ logId, entries }) => {
       try {
         const client = makeClient();
+        logId = await resolveNodeId(client, logId);
         const result = await client.addLogEntries(logId, entries);
         return jsonResult(result);
       } catch (err) {
@@ -103,7 +106,7 @@ export function registerLogTools(server) {
         'Use this to inspect recent activity or find anomalous entries before asking rootr_ask for root-cause analysis.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        logId: z.string().describe('LOG store node id'),
+        logId: z.string().describe(`LOG store node id${NODE_TARGET_HINT}`),
         from: z.string().optional().describe('ISO timestamp lower bound'),
         to: z.string().optional().describe('ISO timestamp upper bound'),
         source: z.string().optional().describe('Filter by source'),
@@ -116,6 +119,7 @@ export function registerLogTools(server) {
     async ({ logId, from, to, source, level, anomalyOnly, limit, order }) => {
       try {
         const client = makeClient();
+        logId = await resolveNodeId(client, logId);
         const result = await client.queryLogEntries(logId, {
           from,
           to,
@@ -142,7 +146,7 @@ export function registerLogTools(server) {
         'questions without pulling raw entries.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        logId: z.string().describe('LOG store node id'),
+        logId: z.string().describe(`LOG store node id${NODE_TARGET_HINT}`),
         groupBy: z.string().optional().describe('hour | day | source | level'),
         metric: z.string().optional().describe('count | avg | max | min | sum'),
         field: z.string().optional().describe('Numeric field name, required for avg/max/min/sum'),
@@ -153,6 +157,7 @@ export function registerLogTools(server) {
     async ({ logId, groupBy, metric, field, from, to }) => {
       try {
         const client = makeClient();
+        logId = await resolveNodeId(client, logId);
         const result = await client.logStats(logId, { groupBy, metric, field, from, to });
         return jsonResult(result);
       } catch (err) {

package/lib/mcp-tools/presentations.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 
 /**
  * Authoring guide, repeated (shortened) across every tool description so an
@@ -127,7 +127,7 @@ export function registerPresentationTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Deck name/title'),
-        parentId: z.string().optional().describe('Parent folder/node id to create the deck under'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
         theme: themeShape,
         slides: z.array(slideShape).optional().describe('Initial slides, in order'),
         config: z.record(z.unknown()).optional().describe('Free-form deck config/settings object'),
@@ -142,6 +142,7 @@ export function registerPresentationTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
         const result = await client.createPresentation(ws, {
           name,
           parentId,
@@ -167,12 +168,13 @@ export function registerPresentationTools(server) {
         'know the current slide ids and content.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        presentationId: z.string().describe('PRESENTATION node id'),
+        presentationId: z.string().describe(`PRESENTATION node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ presentationId }) => {
       try {
         const client = makeClient();
+        presentationId = await resolveNodeId(client, presentationId);
         const result = await client.getPresentation(presentationId);
         return jsonResult(result);
       } catch (err) {
@@ -193,7 +195,7 @@ export function registerPresentationTools(server) {
         AUTHORING_GUIDE,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        presentationId: z.string().describe('PRESENTATION node id'),
+        presentationId: z.string().describe(`PRESENTATION node id${NODE_TARGET_HINT}`),
         theme: themeShape,
         slides: z
           .array(slideShape)
@@ -206,6 +208,7 @@ export function registerPresentationTools(server) {
     async ({ presentationId, theme, slides, config, icon }) => {
       try {
         const client = makeClient();
+        presentationId = await resolveNodeId(client, presentationId);
         const result = await client.updatePresentation(presentationId, {
           theme,
           slides: ensureSlideIds(slides),
@@ -229,13 +232,14 @@ export function registerPresentationTools(server) {
         AUTHORING_GUIDE,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        presentationId: z.string().describe('PRESENTATION node id'),
+        presentationId: z.string().describe(`PRESENTATION node id${NODE_TARGET_HINT}`),
         slides: z.array(slideShape).describe('Slides to append, in order'),
       },
     },
     async ({ presentationId, slides }) => {
       try {
         const client = makeClient();
+        presentationId = await resolveNodeId(client, presentationId);
         const result = await client.appendPresentationSlides(presentationId, ensureSlideIds(slides));
         return jsonResult(result);
       } catch (err) {
@@ -255,7 +259,7 @@ export function registerPresentationTools(server) {
         AUTHORING_GUIDE,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        presentationId: z.string().describe('PRESENTATION node id'),
+        presentationId: z.string().describe(`PRESENTATION node id${NODE_TARGET_HINT}`),
         slideId: z.string().describe('Slide id to update (must belong to the deck)'),
         slide: slideShape.describe('Partial slide fields to merge into the existing slide'),
       },
@@ -263,6 +267,7 @@ export function registerPresentationTools(server) {
     async ({ presentationId, slideId, slide }) => {
       try {
         const client = makeClient();
+        presentationId = await resolveNodeId(client, presentationId);
         const result = await client.updatePresentationSlide(presentationId, slideId, slide);
         return jsonResult(result);
       } catch (err) {
@@ -280,13 +285,14 @@ export function registerPresentationTools(server) {
         'in the new desired order — call rootr_read_presentation first to get the current ids.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        presentationId: z.string().describe('PRESENTATION node id'),
+        presentationId: z.string().describe(`PRESENTATION node id${NODE_TARGET_HINT}`),
         order: z.array(z.string()).describe('Complete ordered array of slide ids'),
       },
     },
     async ({ presentationId, order }) => {
       try {
         const client = makeClient();
+        presentationId = await resolveNodeId(client, presentationId);
         const result = await client.reorderPresentationSlides(presentationId, order);
         return jsonResult(result);
       } catch (err) {
@@ -310,7 +316,7 @@ export function registerPresentationTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         prompt: z.string().describe('English image description; ask for "no text" in the image'),
-        nodeId: z.string().optional().describe('Presentation/node id to attach the image to (permission-checked)'),
+        nodeId: z.string().optional().describe(`Presentation/node id${NODE_TARGET_HINT} to attach the image to (permission-checked)`),
         workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
       },
     },
@@ -318,6 +324,7 @@ export function registerPresentationTools(server) {
       try {
         const client = makeClient();
         const ws = requireWorkspace(workspace);
+        nodeId = await resolveOptionalNodeId(client, nodeId);
         const result = await client.generateImage(ws, { prompt, nodeId });
         return jsonResult(result);
       } catch (err) {
@@ -338,7 +345,7 @@ export function registerPresentationTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         attachmentId: z.string().describe('Source attachment id (from rootr_generate_image or an upload)'),
-        nodeId: z.string().optional().describe('Presentation/node id to attach the result to (permission-checked)'),
+        nodeId: z.string().optional().describe(`Presentation/node id${NODE_TARGET_HINT} to attach the result to (permission-checked)`),
         workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
       },
     },
@@ -346,6 +353,7 @@ export function registerPresentationTools(server) {
       try {
         const client = makeClient();
         const ws = requireWorkspace(workspace);
+        nodeId = await resolveOptionalNodeId(client, nodeId);
         const result = await client.removeImageBackground(ws, { attachmentId, nodeId });
         return jsonResult(result);
       } catch (err) {

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 } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 import { RootrApiError } from '../client.js';
 
 /** 100MB — the backend's hard limit on a single audio upload. */
@@ -72,7 +72,7 @@ export function registerRecordingTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Recording name/title, e.g. "2026-07-21 주간회의"'),
-        parentId: z.string().optional().describe('Parent folder/node id to create the recording under'),
+        parentId: z.string().optional().describe(`Parent folder/node id${NODE_TARGET_HINT}`),
         path: z
           .string()
           .optional()
@@ -101,6 +101,7 @@ export function registerRecordingTools(server) {
       try {
         const ws = requireWorkspace(workspace);
         const client = makeClient(ws);
+        parentId = await resolveOptionalNodeId(client, parentId);
         const result = await client.createRecording(ws, {
           name,
           parentId,
@@ -130,7 +131,7 @@ export function registerRecordingTools(server) {
         'rootr_transcribe_recording.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        recordingId: z.string().describe('RECORDING node id (create one with rootr_create_recording)'),
+        recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT} (create one with rootr_create_recording)`),
         filePath: z
           .string()
           .optional()
@@ -156,6 +157,7 @@ export function registerRecordingTools(server) {
     async ({ recordingId, filePath, base64Data, filename, mimeType, durationSec }) => {
       try {
         const client = makeClient();
+        recordingId = await resolveNodeId(client, recordingId);
         const data = readAudioBytes({ filePath, base64Data });
         if (data.length > MAX_AUDIO_BYTES) {
           throw new RootrApiError(
@@ -207,12 +209,13 @@ export function registerRecordingTools(server) {
         'TRANSCRIBING = speech-to-text still running (poll again later); ' +
         'READY = transcript available; FAILED = last transcription errored (see `error`).',
       inputSchema: {
-        recordingId: z.string().describe('RECORDING node id'),
+        recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ recordingId }) => {
       try {
         const client = makeClient();
+        recordingId = await resolveNodeId(client, recordingId);
         const result = await client.getRecording(recordingId);
         const segments = result?.transcript?.segments ?? [];
         const names = result?.speakerNames ?? {};
@@ -240,7 +243,7 @@ export function registerRecordingTools(server) {
         '{"S1":"김대표","S2":"이팀장"}. Merge-patch: only the keys you send change. The names apply to the ' +
         'transcript everywhere (web UI, rootr_read_recording, knowledge graph).',
       inputSchema: {
-        recordingId: z.string().describe('RECORDING node id'),
+        recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT}`),
         speakerNames: z
           .record(z.string())
           .optional()
@@ -260,6 +263,7 @@ export function registerRecordingTools(server) {
           throw new RootrApiError('speakerNames 또는 expectedSpeakers 중 하나는 필요합니다.');
         }
         const client = makeClient();
+        recordingId = await resolveNodeId(client, recordingId);
         const current = await client.getRecording(recordingId);
         const merged = speakerNames
           ? { ...(current?.speakerNames ?? {}), ...speakerNames }
@@ -292,12 +296,13 @@ export function registerRecordingTools(server) {
         'take a few minutes).',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        recordingId: z.string().describe('RECORDING node id'),
+        recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT}`),
       },
     },
     async ({ recordingId }) => {
       try {
         const client = makeClient();
+        recordingId = await resolveNodeId(client, recordingId);
         const result = await client.transcribeRecording(recordingId);
         return jsonResult({
           ...result,
@@ -326,7 +331,7 @@ export function registerRecordingTools(server) {
         'for Rootr\'s built-in summary.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        recordingId: z.string().describe('RECORDING node id (status must be READY)'),
+        recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT} (status must be READY)`),
         format: z
           .enum(['summary', 'onepager'])
           .optional()
@@ -343,6 +348,7 @@ export function registerRecordingTools(server) {
     async ({ recordingId, locale, format }) => {
       try {
         const client = makeClient();
+        recordingId = await resolveNodeId(client, recordingId);
         const result = await client.summarizeRecording(recordingId, { locale, format });
         return jsonResult(result);
       } catch (err) {
@@ -370,7 +376,7 @@ export function registerRecordingTools(server) {
         'this way lives wherever you put it (e.g. a document via rootr_write), not in the recording node.',
       annotations: { readOnlyHint: true },
       inputSchema: {
-        recordingId: z.string().describe('RECORDING node id'),
+        recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT}`),
         filePath: z
           .string()
           .optional()
@@ -387,6 +393,7 @@ export function registerRecordingTools(server) {
     async ({ recordingId, filePath, urlOnly }) => {
       try {
         const client = makeClient();
+        recordingId = await resolveNodeId(client, recordingId);
         const rec = await client.getRecording(recordingId);
         if (!rec?.audio?.attachmentId) {
           throw new RootrApiError('이 녹음에는 아직 오디오가 없습니다. rootr_upload_recording_audio로 먼저 올리세요.');

package/lib/mcp-tools/shared.js

@@ -1,6 +1,32 @@
 import { loadConfig, keyForWorkspace } from '../config.js';
 import { RootrClient, RootrApiError } from '../client.js';
 import { currentClientOverride } from '../context.js';
+import { resolveTarget, requireResolved } from '../resolve.js';
+
+/**
+ * Suffix for the `.describe()` of any node-id parameter: every typed-node tool
+ * takes a path too, exactly like rootr_read, so an agent that only knows where
+ * a node lives in the tree never has to hunt for its uuid.
+ */
+export const NODE_TARGET_HINT = ', or its path starting with "/"';
+
+/**
+ * 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.
+ */
+export async function resolveNodeId(client, target) {
+  return requireResolved(await resolveTarget(client, target));
+}
+
+/**
+ * Same as resolveNodeId, but for optional/nullable arguments (parentId,
+ * targetDatabaseId, scopeNodeId …) — undefined/null pass through untouched so
+ * "omitted" and "explicitly cleared" keep their meaning.
+ */
+export async function resolveOptionalNodeId(client, target) {
+  if (target === undefined || target === null || target === '') return target;
+  return resolveNodeId(client, target);
+}
 
 export function textResult(text) {
   return { content: [{ type: 'text', text }] };

package/lib/mcp-tools/spreadsheets.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+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()])
@@ -32,7 +32,7 @@ export function registerSpreadsheetTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Spreadsheet name/title'),
-        parentId: z.string().optional().describe('Parent folder/node id to create it under'),
+        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() })
@@ -46,6 +46,7 @@ export function registerSpreadsheetTools(server) {
       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) {
@@ -64,12 +65,13 @@ export function registerSpreadsheetTools(server) {
         'and cell contents.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        spreadsheetId: z.string().describe('SPREADSHEET node id'),
+        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) {
@@ -88,7 +90,7 @@ export function registerSpreadsheetTools(server) {
         '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'),
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
         sheets: z
           .array(z.record(z.unknown()))
           .optional()
@@ -100,6 +102,7 @@ export function registerSpreadsheetTools(server) {
     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) {
@@ -115,7 +118,7 @@ export function registerSpreadsheetTools(server) {
       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'),
+        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)'),
@@ -124,6 +127,7 @@ export function registerSpreadsheetTools(server) {
     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) {
@@ -141,7 +145,7 @@ export function registerSpreadsheetTools(server) {
         'Call rootr_read_spreadsheet first to get the exact sheetId.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        spreadsheetId: z.string().describe('SPREADSHEET node id'),
+        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(),
@@ -157,6 +161,7 @@ export function registerSpreadsheetTools(server) {
     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,
@@ -179,13 +184,14 @@ export function registerSpreadsheetTools(server) {
       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'),
+        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) {
@@ -204,7 +210,7 @@ export function registerSpreadsheetTools(server) {
         CELLS_GUIDE,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        spreadsheetId: z.string().describe('SPREADSHEET node id'),
+        spreadsheetId: z.string().describe(`SPREADSHEET node id${NODE_TARGET_HINT}`),
         sheetId: z.string().describe('Sheet id to patch'),
         cells: z
           .record(cellShape.nullable())
@@ -214,6 +220,7 @@ export function registerSpreadsheetTools(server) {
     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) {

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',
@@ -60,7 +60,7 @@ export function registerWebhookTools(server) {
         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
@@ -73,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,

package/lib/mcp-tools/whiteboards.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
 
 const shapeShape = z
   .object({
@@ -67,7 +67,7 @@ export function registerWhiteboardTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().optional().describe('Whiteboard name/title'),
-        parentId: z.string().optional().describe('Parent folder/node id to create it under'),
+        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])
@@ -81,6 +81,7 @@ export function registerWhiteboardTools(server) {
       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) {
@@ -101,13 +102,14 @@ export function registerWhiteboardTools(server) {
         'the current ids.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
-        whiteboardId: z.string().describe('WHITEBOARD node id'),
+        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);
@@ -139,7 +141,7 @@ export function registerWhiteboardTools(server) {
         AUTHORING_GUIDE,
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
-        whiteboardId: z.string().describe('WHITEBOARD node id'),
+        whiteboardId: z.string().describe(`WHITEBOARD node id${NODE_TARGET_HINT}`),
         scene: z
           .union([sceneShape, excalidrawSceneShape])
           .optional()
@@ -155,6 +157,7 @@ export function registerWhiteboardTools(server) {
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.4.0",
+  "version": "0.4.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": {