rootr-cli 0.4.0 → 0.5.0

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) {
@@ -353,4 +361,90 @@ export function registerPresentationTools(server) {
       }
     },
   );
+
+  server.registerTool(
+    'rootr_diagram_schema',
+    {
+      title: 'Get the spec shape for a diagram type',
+      description:
+        'Return the JSON Schema and a worked example for one Rootr (루터) diagram family: architecture (components, ' +
+        'services, stores, boundaries), workflow (swimlane process with approvals/retries), sequence (call order ' +
+        'between participants), dataflow (pipelines, lineage), or lifecycle (states, retries, outcomes). ' +
+        'ALWAYS call this before rootr_create_diagram_slide for a family you have not authored yet — every family ' +
+        'has a different shape (a workflow wants lanes/nodes/edges, an architecture wants components/connections), ' +
+        'and the renderer rejects a spec that does not match. Reading the schema first turns a guess-and-fail into ' +
+        'one correct call. Pass no type to list the available families.',
+      annotations: { readOnlyHint: true },
+      inputSchema: {
+        type: z
+          .enum(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle'])
+          .optional()
+          .describe('Diagram family; omit to list the available families'),
+      },
+    },
+    async ({ type }) => {
+      try {
+        const client = makeClient();
+        return jsonResult(type ? await client.diagramSchema(type) : await client.diagramTypes());
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_diagram_slide',
+    {
+      title: 'Draw a diagram onto a slide',
+      description:
+        'Render a typed diagram spec into a Rootr (루터) presentation slide — architecture, workflow, sequence, ' +
+        'dataflow, or lifecycle. The drawing is baked into the slide, so it shows on screen AND in the PDF/PPTX ' +
+        'exports. Use this instead of the mermaid `diagram` field, which the slide viewer does not draw.\n' +
+        'Call rootr_diagram_schema first to get the exact shape for the family you want — the spec is validated ' +
+        'fail-closed and a mismatch is rejected with the offending field named and a suggested fix, which you ' +
+        'should apply and retry.\n' +
+        'Meaning must live in TEXT: `title` (one assertion-style claim, e.g. "Checkout fails when the cache is ' +
+        'cold" — not a topic label like "Checkout"), `blocks[]`, and `notes` are what connects into the knowledge ' +
+        'graph. The picture itself is NEVER indexed, so never put a fact only in the drawing.\n' +
+        'Pass `slideId` to redraw an existing slide; omit it to append a new one. Quality defaults to "standard"; ' +
+        '"showcase" adds a strict composition bar (turn run-ups, legend fit) meant for a hand-tuned hero diagram ' +
+        'and will reject specs that "standard" accepts.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        presentationId: z.string().describe(`PRESENTATION node id${NODE_TARGET_HINT}`),
+        type: z
+          .enum(['architecture', 'workflow', 'sequence', 'dataflow', 'lifecycle'])
+          .describe('Diagram family — see rootr_diagram_schema'),
+        spec: z.record(z.any()).describe('The typed diagram spec matching that family\'s JSON Schema'),
+        title: z.string().optional().describe('Assertion-style slide title — text spine, also drawn as the heading'),
+        subtitle: z.string().optional().describe('One supporting line drawn under the title'),
+        blocks: z
+          .array(z.object({ heading: z.string().optional(), body: z.string().optional() }).passthrough())
+          .optional()
+          .describe('Text spine — the facts the diagram shows, so they reach the knowledge graph'),
+        notes: z.string().optional().describe('Speaker notes — also part of the text spine'),
+        slideId: z.string().optional().describe('Redraw this slide instead of appending a new one'),
+        quality: z.enum(['standard', 'showcase']).optional().describe('Default "standard"'),
+      },
+    },
+    async ({ presentationId, type, spec, title, subtitle, blocks, notes, slideId, quality }) => {
+      try {
+        const client = makeClient();
+        presentationId = await resolveNodeId(client, presentationId);
+        const result = await client.createDiagramSlide(presentationId, {
+          type,
+          spec,
+          title,
+          subtitle,
+          blocks,
+          notes,
+          slideId,
+          quality,
+        });
+        return jsonResult(result);
+      } catch (err) {
+        return errorResult(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 }] };