rootr-cli 0.2.1 → 0.4.1

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
@@ -38,16 +41,18 @@ export function registerDatabaseTools(server) {
         'Read a Rootr (루터) DATABASE node — its schema (properties with ids/types and select options) plus all rows ' +
         '(each with its rowId and values). ALWAYS call this before rootr_add_row / rootr_update_row so you know the exact ' +
         '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) {
@@ -63,14 +68,15 @@ export function registerDatabaseTools(server) {
       description:
         'List the rows of a Rootr (루터) DATABASE (id + values + position), without the schema. ' +
         '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);
@@ -87,8 +93,9 @@ export function registerDatabaseTools(server) {
         'Value shapes by type: title/text/url/select/person → string; number → number; multi_select → string[]; ' +
         'checkbox → boolean; date → { start: "YYYY-MM-DD", end? }. A select value is the OPTION NAME. ' +
         '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'),
       },
@@ -96,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);
@@ -115,8 +123,9 @@ export function registerDatabaseTools(server) {
         '`values` maps property NAME (or id) → new value; only the passed keys change, `null` clears a key, omitted keys ' +
         'are left unchanged. To MOVE a kanban card to another column, set its select/status property to the new option name. ' +
         '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'),
@@ -125,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);
@@ -145,15 +155,16 @@ export function registerDatabaseTools(server) {
       description:
         'Delete ONE row of a Rootr (루터) DATABASE by rowId (its linked page, if any, is moved to the trash). ' +
         '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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 
 import { RootrApiError } from '../client.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
-import { textResult, errorResult, makeClient } from './shared.js';
+import { textResult, jsonResult, errorResult, makeClient } from './shared.js';
 
 /** Registers the original 6 document tools: list/read/append/edit/write/search. */
 export function registerDocumentTools(server) {
@@ -13,6 +13,7 @@ export function registerDocumentTools(server) {
       description:
         'List documents and folders in the connected Rootr (루터) workspace, optionally filtered to a path prefix. ' +
         'Use this first to discover what exists before reading or writing.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         path: z
           .string()
@@ -30,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) {
@@ -46,6 +52,7 @@ export function registerDocumentTools(server) {
       description:
         'Read the full markdown content of a Rootr (루터) document by path (starting with "/") or by node id. ' +
         'Read a document before editing or appending to it so you know its current structure.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (e.g. "/notes/todo.md") or node id'),
       },
@@ -71,6 +78,7 @@ export function registerDocumentTools(server) {
         'Append content to a Rootr document, optionally under a given heading. This is a conflict-free, ' +
         'additive operation — it never overwrites existing content, so PREFER this over rootr_write whenever ' +
         'you just need to add new information (log entries, notes, findings) to an existing document.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id'),
         content: z.string().describe('Markdown content to append'),
@@ -105,6 +113,7 @@ export function registerDocumentTools(server) {
         'Fails with a clear error if the snippet is missing or ambiguous (not unique), so read the document ' +
         'first to copy the exact text to find. Good for precise, targeted edits; use rootr_append instead when ' +
         'you are only adding new content.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/") or node id'),
         find: z.string().describe('Exact existing text to find (must be unique unless replaceAll is set)'),
@@ -133,6 +142,7 @@ export function registerDocumentTools(server) {
         'Replace the ENTIRE content of a Rootr document, or create a new document at a path if it does not exist. ' +
         'This is DESTRUCTIVE — it discards whatever is currently there. Read the document first and pass its etag ' +
         'as ifMatch to avoid clobbering concurrent changes. Prefer rootr_append or rootr_edit for incremental changes.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         target: z.string().describe('Document path (starting with "/", created if missing) or node id'),
         content: z.string().describe('Full new markdown content for the document'),
@@ -175,6 +185,7 @@ export function registerDocumentTools(server) {
       description:
         'Full-text search across the connected Rootr (루터) workspace. Use this to find relevant documents before ' +
         'reading or editing them.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         query: z.string().describe('Search query text'),
       },
@@ -183,11 +194,161 @@ 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);
       }
     },
   );
+
+  server.registerTool(
+    'rootr_comment_document',
+    {
+      title: 'Comment on a Rootr document',
+      description:
+        'Add a comment to a Rootr (루터) document (optionally anchored to a block, or as a reply via parentId). ' +
+        'Comments carry a user identity, so this requires an ACCOUNT key (PAT) — a workspace-scoped key ' +
+        '(including remote-connector tokens) gets a 403; fall back to rootr_append in that case.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        body: z.string().describe('Comment text (markdown)'),
+        blockId: z.string().optional().describe('Block id to anchor the comment to'),
+        parentId: z.string().optional().describe('Parent comment id, to reply in a thread'),
+      },
+    },
+    async ({ target, body, blockId, parentId }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.createComment(id, { body, blockId, parentId }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_list_document_comments',
+    {
+      title: 'List comments on a Rootr document',
+      description:
+        'List the comment threads on a Rootr (루터) document, optionally filtered to one block. Works with any key.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        blockId: z.string().optional().describe('Only comments anchored to this block'),
+      },
+    },
+    async ({ target, blockId }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.listComments(id, { blockId }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_publish_document',
+    {
+      title: 'Publish a Rootr document to a public URL',
+      description:
+        'Publish a Rootr (루터) document at a public read-only URL (rootr.io/p/{slug}) — outsiders can read it ' +
+        'and propose git-style edit suggestions the owner can merge. Publishing is an owner-level action: it needs ' +
+        'MANAGE permission, which workspace-scoped keys (including remote-connector tokens) do not carry — use an ' +
+        'ACCOUNT key (PAT) of the owner, or ask the user to publish from the share dialog. ' +
+        'Returns the slug/URL. Check rootr_document_public_status first; unpublish via rootr_set_document_public.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+      },
+    },
+    async ({ target }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.publishDocument(id));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_document_public',
+    {
+      title: 'Update public settings of a Rootr document',
+      description:
+        'Update a published Rootr (루터) document\'s public settings — e.g. {"isPublic": false} to unpublish. ' +
+        'Owner-level action (MANAGE): works with an account key (PAT), not with workspace-scoped/connector tokens.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+        isPublic: z.boolean().optional().describe('false to unpublish, true to re-enable'),
+      },
+    },
+    async ({ target, isPublic }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.setDocumentPublic(id, { isPublic }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_document_public_status',
+    {
+      title: 'Public status of a Rootr document',
+      description: 'Whether a Rootr (루터) document is published, and at which public slug/URL.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Document path (starting with "/") or node id'),
+      },
+    },
+    async ({ target }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.getDocumentPublicStatus(id));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_duplicate_node',
+    {
+      title: 'Duplicate a Rootr node (deep copy)',
+      description:
+        'Deep-copy a Rootr (루터) node — a document or a whole folder tree — next to the original, or into ' +
+        'another workspace the user can access (targetWorkspaceId). Returns the new root node.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe('Node path (starting with "/") or node id to copy'),
+        deep: z.boolean().optional().describe('Copy children too (default true)'),
+        targetWorkspaceId: z.string().optional().describe('Destination workspace id (defaults to same workspace)'),
+      },
+    },
+    async ({ target, deep, targetWorkspaceId }) => {
+      try {
+        const client = makeClient();
+        const id = requireResolved(await resolveTarget(client, target));
+        return jsonResult(await client.duplicateNode(id, { deep, targetWorkspaceId }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/forms.js

@@ -0,0 +1,215 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, resolveOptionalNodeId } from './shared.js';
+
+const fieldShape = z
+  .object({
+    id: z.string().optional().describe('Stable field id (also the key under response `values`). Server-generated if omitted.'),
+    name: z.string().describe('Field label shown to respondents'),
+    type: z
+      .enum(['text', 'textarea', 'number', 'select', 'multi_select', 'checkbox', 'date'])
+      .describe('Field input type'),
+    required: z.boolean().optional().describe('Whether the field must be filled in'),
+    options: z
+      .array(z.object({ name: z.string(), color: z.string() }))
+      .optional()
+      .describe('Choices for select/multi_select fields'),
+  })
+  .describe('One form field definition.');
+
+const FIELDS_GUIDE =
+  'Fields are typed inputs shown to respondents: text | textarea | number | select | multi_select | checkbox | date; ' +
+  'select/multi_select need `options` ({name,color}[]). Read the form first (rootr_read_form) before updating so ' +
+  'you keep each field\'s `id` stable — response values are keyed by field id, so renaming/dropping an id orphans ' +
+  'past responses\' answers for that field.';
+
+/** FORM node tools: create/read/update the field definitions, list/submit responses, manage public share links. */
+export function registerFormTools(server) {
+  server.registerTool(
+    'rootr_create_form',
+    {
+      title: 'Create a Rootr form',
+      description:
+        'Create a new FORM node (fillable intake) in a Rootr (루터) workspace, optionally seeded with field ' +
+        'definitions. Use FORM for surveys/request queues collected from people outside the tree — set ' +
+        '`targetDatabaseId` to also mirror each response into a DATABASE\'s rows. ' +
+        FIELDS_GUIDE,
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        name: z.string().optional().describe('Form name/title'),
+        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${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'),
+      },
+    },
+    async ({ name, parentId, icon, fields, targetDatabaseId, config, workspace }) => {
+      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) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_read_form',
+    {
+      title: 'Read a Rootr form',
+      description:
+        'Read a Rootr (루터) FORM node — its field definitions, targetDatabaseId, and config. Call this before ' +
+        'rootr_update_form so you keep existing field ids stable, or before rootr_list_form_responses to know ' +
+        'which field ids the response `values` are keyed by.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        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) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_update_form',
+    {
+      title: 'Update a Rootr form (fields/targetDatabaseId/config)',
+      description:
+        'Merge-patch a Rootr (루터) FORM: if you pass `fields`, it REPLACES the whole fields array — call ' +
+        'rootr_read_form first and resend fields you want to keep (with their existing ids) so past responses ' +
+        'stay attributable. Pass `targetDatabaseId: null` to unlink the mirrored DATABASE. ' +
+        FIELDS_GUIDE,
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        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${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'),
+      },
+    },
+    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) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_list_form_responses',
+    {
+      title: 'List a Rootr form\'s submitted responses',
+      description:
+        'List all responses submitted to a Rootr (루터) FORM, most recent first. Each response has `values` keyed ' +
+        'by field id — call rootr_read_form first to map ids to field names. This is what lets an AI analyze ' +
+        'responses collected from a form.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        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) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_submit_form_response',
+    {
+      title: 'Submit a response to a Rootr form',
+      description:
+        'Submit one response to a Rootr (루터) FORM on behalf of the caller (authenticated submission, not the ' +
+        'public/anonymous share-link flow). `values` is keyed by field id — call rootr_read_form first to get the ' +
+        'exact field ids and types.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        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) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_create_form_share_link',
+    {
+      title: 'Issue a public share link for a Rootr form',
+      description:
+        'Issue a new public share link/token for a Rootr (루터) FORM so people outside the workspace can submit ' +
+        'responses (via the /f/{token} page). The form\'s public-submit mode itself is controlled separately via ' +
+        'rootr_update_form\'s config.publicSubmit ("off" | "login" | "anon").',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        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) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_list_form_share_links',
+    {
+      title: 'List a Rootr form\'s public share links',
+      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${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) {
+        return errorResult(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) {
@@ -11,6 +11,7 @@ export function registerIssueTools(server) {
       description:
         'Create a new GitHub-style issue tracker document in a Rootr (루터) workspace. Returns the tracker with ' +
         'its id, plus its default labels/types — use rootr_create_issue afterward to add issues to it.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         name: z.string().describe('Name of the issue tracker'),
         workspace: z
@@ -38,8 +39,9 @@ export function registerIssueTools(server) {
       description:
         'List issues in a Rootr (루터) issue tracker, optionally filtered by state (OPEN/CLOSED/ALL), label id, ' +
         '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'),
@@ -49,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) {
@@ -65,8 +68,9 @@ export function registerIssueTools(server) {
         'Create a new issue in a Rootr (루터) issue tracker. labels is an array of label ids, type is a type id ' +
         '(both from the tracker\'s custom type/label definitions — see rootr_read on the tracker or its metadata). ' +
         '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'),
@@ -77,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) {
@@ -90,6 +95,7 @@ export function registerIssueTools(server) {
     {
       title: 'Get an issue',
       description: 'Fetch full details of a single Rootr (루터) issue by id.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         issueId: z.string().describe('Issue id'),
       },
@@ -112,6 +118,7 @@ export function registerIssueTools(server) {
       description:
         'Update arbitrary fields of a Rootr (루터) issue. To close an issue, set state to "CLOSED" and stateReason ' +
         'to one of completed | not_planned | duplicate.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
         issueId: z.string().describe('Issue id'),
         title: z.string().optional(),
@@ -143,8 +150,9 @@ export function registerIssueTools(server) {
       description:
         'Add a comment to a Rootr (루터) issue within its tracker. Comments carry a user identity, ' +
         '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)'),
       },
@@ -152,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) {