rootr-cli 0.18.0 → 0.19.0

package/lib/mcp-tools/misc.js

@@ -147,13 +147,16 @@ export function registerMiscTools(server) {
         'permanent delete. Use rootr_read/rootr_list first to confirm you have the right target.',
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
-        target: z.string().describe('Document/folder path (starting with "/") or node id'),
+        target: z.string().optional().describe('Document/folder path (starting with "/") or node id'),
+        nodeId: z.string().optional().describe('Alias for `target` — node id of the item to delete'),
       },
     },
-    async ({ target }) => {
+    async ({ target, nodeId }) => {
       try {
+        const want = target ?? nodeId;
+        if (!want) throw new Error('target (or nodeId) is required');
         const client = makeClient();
-        const resolved = await resolveTarget(client, target);
+        const resolved = await resolveTarget(client, want);
         const id = requireResolved(resolved);
         await client.deleteNode(id);
         return jsonResult({
@@ -203,6 +206,9 @@ export function registerMiscTools(server) {
       description:
         'Read the READ-ACK state of a Rootr (루터) node — who must read it, the due date, who has read or ' +
         'acknowledged, and (for a DATABASE or FOLDER) how far through the documents inside each person is. ' +
+        'Each target has `completed`; on a DATABASE/FOLDER a person is done once they have read every document THEY can open ' +
+        '(`readCount`/`readTotal` per person — on an "own rows only" table that is their own row pages plus shared documents). ' +
+        'If you cannot see every document inside, other people carry only `completed` (no counts). ' +
         'Use it to answer "누가 아직 안 읽었나" for a 규정/공지/교육자료. If the node itself has no requirement ' +
         'but an ancestor does, `ancestorRequirementId` names the node that carries it.',
       annotations: { readOnlyHint: true, destructiveHint: false },

package/lib/mcp-tools/pages.js

@@ -25,7 +25,7 @@ import {
  */
 const BLOCK_GUIDE =
   'A page is `blocks[]` (ordered, max 200) + `config`. Each block is {id?, type, props}. ' +
-  'You assemble a page from these 15 block types:\n' +
+  'You assemble a page from these block types:\n' +
   '· hero {title, subtitle?, align?:"left"|"center", background?:{kind:"color",color}|{kind:"image",attachmentId}, button?:{label,target}} — the opening banner\n' +
   '· text {body (markdown), title?} — prose section; markdown is sanitized when rendered\n' +
   '· features {columns?:1|2|3, items:[{title, body, icon?(emoji)}]} — "what it does" grid\n' +
@@ -38,13 +38,31 @@ const BLOCK_GUIDE =
   '· footer {links:[{label, target}], contact?, copyright?}\n' +
   '· liveStats {cards:[{label, icon?, source:{nodeId(DATABASE/LOG node), agg:"count"|"sum"|"avg"|"min"|"max", column?}}]} — numbers read LIVE from a table\n' +
   '· liveTable {source:{nodeId}, columns?:[name], rowLimit?(1-200), orderBy?:{column, dir:"asc"|"desc"}}\n' +
-  '· liveChart {source:{nodeId}, chart:"bar"|"line"|"donut", labelColumn, valueColumn, agg:"count"|"sum"|"avg"}\n' +
+  '· liveChart {source:{nodeId, sheet?, range?}, chart, labelColumn, valueColumn?, agg?, …} — a LIVE chart (46 kinds, see CHARTS below)\n' +
   '· form {formNodeId(FORM node), headline?, submitLabel?} — visitors submit right on the page\n' +
   '· custom {html, height?(40-4000, default 260)} — free HTML/CSS, rendered inside a locked-down sandboxed iframe ' +
   '(no scripts, no same-origin, no network). Use it for a look the other blocks cannot make. Page theme colors are ' +
   'available inside as var(--pg-bg|text|muted|faint|card|line|accent|on-accent) and var(--pg-font). Scripts and ' +
   'on*= handlers are stripped on save — do not put behaviour here, only markup and CSS.\n' +
-  'LIVE/FORM BLOCKS: `source.nodeId` / `formNodeId` must be a node in the SAME workspace, and `column`/`labelColumn`/' +
+  'LAYOUT: any block takes `width:"full"|"twoThirds"|"half"|"third"` — neighbouring blocks sit side by side (phones stack them). ' +
+  'That is how a page becomes a DASHBOARD: a row of `chart:"kpi"` blocks at width "third", then charts at width "half".\n' +
+  'CHARTS (liveChart): chart ∈ bar|barH|stackedBar|stackedBarH|percentBar|lollipop|dumbbell|bullet|waterfall|pareto|radar|polarBar|line|step|area|stackedArea|percentArea|combo|slope|stream|calendar|pie|donut|halfDonut|rose|funnel|treemap|sunburst|waffle|histogram|boxplot|heatmap|scatter|bubble|sankey|chord|network|tree|kpi|gauge|progress|ring|candlestick|gantt|wordCloud|pivot. ' +
+  'source = a DATABASE, SPREADSHEET or LOG node (sheet: {nodeId, sheet?(name), range?:"A1:F200"} — first row = column names, formula results are read). ' +
+  'Category charts: labelColumn (dates are bucketed: dateBucket day|week|month|quarter|year|weekday|hour, empty periods filled with 0) + ' +
+  'valueColumn & agg (count|sum|avg|min|max|median|distinct — valueColumn is optional for count/distinct, which just count the matching rows per label) OR values:[{column?, agg, label?, as?:"bar"|"line"|"area", axis?:"left"|"right"}] (several series, combo/dual axis) ' +
+  'OR seriesColumn (break down / stack by another column; heatmap, stream and pivot need it). sort auto|value-desc|value-asc|label-asc|label-desc, limit (+ others:true folds the rest into "Other"), cumulative:true. ' +
+  'kpi|gauge|progress|ring: valueColumn+agg, optional dateColumn + period (today|7d|30d|90d|week|month|quarter|year) → value vs the previous same-length period + sparkline; goal or goalColumn. ' +
+  'scatter|bubble: xColumn, yColumn, sizeColumn?, seriesColumn?. histogram|boxplot: valueColumn (+labelColumn groups for boxplot), bins?. ' +
+  'sankey|chord|network: labelColumn (from) → targetColumn (to), value = agg. treemap|sunburst|tree: labelColumn + levels:[col,…]. ' +
+  'candlestick: labelColumn + open/high/low/closeColumn. gantt: labelColumn, startColumn, endColumn?. bullet: values[0]=actual + goalColumn (or goal). wordCloud: labelColumn (+splitWords:true for free text). ' +
+  'filters:[{column, op: is|is_not|contains|not_contains|gt|gte|lt|lte|empty|not_empty|last_days, value}] (values may be "@today-30"). ' +
+  'Display: title, subtitle, height(160-1200), format auto|number|compact|percent|krw|usd|decimal1|decimal2, prefix, suffix, palette theme|vivid|pastel|ocean|sunset|forest|mono, goalLabel, thresholds:[{value,color}], showLabels, showLegend, smooth. ' +
+  'rootr_read_page_live_data shows what each chart computed — a chart that could not be drawn says why (column_missing/no_rows/needs_number).\n' +
+  'LIVE/FORM BLOCKS: `source.nodeId` / `formNodeId` must be a node in the SAME workspace that you can open — write it as ' +
+  'the node id, a full "/folder/name" path, or a name that is the ONLY table/sheet/log (or form, for `formNodeId`) with ' +
+  'that name. The server resolves it and stores the id (the response shows the id). A path or name it cannot resolve — ' +
+  'missing, not readable by you, wrong node type, or a name shared by two nodes — is rejected with 400 and NOTHING is ' +
+  'saved; it is never stored as a silently empty block. `column`/`labelColumn`/' +
   '`valueColumn`/`orderBy.column` are the column NAMES as shown in the table (not column ids). A table or form that ' +
   'sits in a PRIVATE subtree is silently skipped on the published page — that is deliberate, never a bug to work around.\n' +
   'LINKS: every `target` is {kind:"url", href} (absolute http(s)://, mailto: or tel: only) or {kind:"node", nodeId} ' +
@@ -65,8 +83,11 @@ export function registerPageTools(server) {
       description:
         'Create a new PAGE node in a Rootr (루터) workspace — a web page assembled from safe typed blocks, which ' +
         'can then be published to the web at a public address (see rootr_publish_node). Use this when someone asks ' +
-        'for a landing page, an announcement page, an event page, a product/pricing page or a signup page. ' +
+        'for a DASHBOARD / report / KPI board over their tables, spreadsheets or logs (46 live chart kinds, numbers stay ' +
+        'current), or for a landing page, an announcement page, an event page, a product/pricing page or a signup page. ' +
         'Omit `blocks` to start from a hero/text/footer skeleton. ' +
+        'In the response, `nodeId` is the page\'s node id — pass THAT as `pageId` to every later page tool ' +
+        '(and in REST paths like /v1/pages/:nodeId/live-data). The response `id` is an internal page-row id and is NOT accepted there (404). ' +
         BLOCK_GUIDE +
         ' ' +
         NODE_URL_HINT +
@@ -222,9 +243,12 @@ export function registerPageTools(server) {
       title: 'Read what a page\'s live blocks currently show',
       description:
         'Read the values a Rootr (루터) PAGE\'s live blocks (liveStats/liveTable/liveChart) are showing right now — ' +
-        'the aggregates, rows and chart points computed from their source tables. Use it to check that a live block ' +
-        'points at the right table and column: an empty result usually means the source is missing, is in a PRIVATE ' +
-        'subtree, or the column name does not match.',
+        'the aggregates, rows and chart data computed from their source tables, spreadsheets or logs. Use it after ' +
+        'building a dashboard to check every chart actually draws. Each chart carries `data` shaped by kind ' +
+        '(category {labels, series[]} · single {value, previous, goal, spark} · xy · distribution · tree · flow · ohlc · range). ' +
+        'A chart that cannot draw says why: `{shape:"empty", reason:"column_missing"|"no_rows"|"needs_number", column}` — ' +
+        'fix that column name or filter. A block missing from the result means its source was not found, is deleted, ' +
+        'or sits in a PRIVATE subtree.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {
         pageId: z.string().describe(`PAGE node id${NODE_TARGET_HINT}`),

package/lib/mcp-tools/presentations.js

@@ -10,7 +10,7 @@ import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, N
 const AUTHORING_GUIDE =
   'Authoring guide: give each slide ONE assertion-style title (a claim, e.g. "Latency dropped 40% after the cache fix" — ' +
   'not a topic label like "Latency"), plus blocks[] (bullet-like {id, heading?, body?, icon?} items) and, where useful, ' +
-  'a diagram ({type:"mermaid", code}) or images. Canvas is 16:9 (1280x720). Meaning must live in TEXT — ' +
+  'a diagram ({type:"mermaid", code} — drawn on "content" slides) or images. Canvas is 16:9 (1280x720). Meaning must live in TEXT — ' +
   'title/blocks[].heading/blocks[].body/notes are what auto-connects into the knowledge graph; diagrams/code/html and the ' +
   'image pixels themselves are visual-only and are NOT indexed, so never put facts ONLY in a diagram or picture.\n' +
   'Images: `image` is the single primary/background image (cover, section, full-bleed); `images[]` holds additional ' +
@@ -19,8 +19,10 @@ const AUTHORING_GUIDE =
   'an https URL, or a data: URI — you cannot upload the file bytes through these MCP tools, only reference the resulting URL. ' +
   'To get a REAL image, call rootr_generate_image with an English prompt (say "no text"), then put the returned `url` ' +
   'into the slide image\'s `src`; rootr_remove_image_background cuts out an image\'s background. ' +
-  '`placement` is a layout hint ("full"|"right"|"top"|...); x/y/w/h give freeform PPT-style placement in 1280x720 canvas ' +
-  'coords. ALWAYS add an `alt` caption to every image — alt text is part of the graph text spine, so a captioned image ' +
+  'Set `placement` on the primary `image`: "full" = background (full-bleed on cover/section/closing, faint on content); ' +
+  '"right" / "top" = beside / above the blocks, content slides only; other values are ignored and a content slide without ' +
+  'placement does not draw the image. For `images[]`, x/y/w/h give freeform PPT-style placement in 1280x720 canvas ' +
+  'coords (drawn only when both x and y are set). ALWAYS add an `alt` caption to every image — alt text is part of the graph text spine, so a captioned image ' +
   'connects into the knowledge graph while an uncaptioned one does not.\n' +
   'Use kind to mark each slide\'s role: "cover" (deck title slide), "section" (chapter divider), "content" (body slide, ' +
   'the default), "closing" (last slide / call to action).\n' +
@@ -54,7 +56,13 @@ const imageShape = z
       .optional()
       .describe('Caption / alt text. Part of the knowledge-graph text spine — ALWAYS set this so the image is indexed.'),
     prompt: z.string().optional().describe('English AI-generation prompt, no text baked into the image (used when src is absent)'),
-    placement: z.string().optional().describe('Layout hint: "full" | "right" | "top" | ...'),
+    placement: z
+      .string()
+      .optional()
+      .describe(
+        'Where the primary `image` goes: "full" (background — full-bleed on cover/section/closing, faint on content) | ' +
+          '"right" | "top" (content slides only). Other values are ignored.',
+      ),
     x: z.number().optional().describe('Freeform placement X in 1280x720 canvas coords'),
     y: z.number().optional().describe('Freeform placement Y in 1280x720 canvas coords'),
     w: z.number().optional().describe('Freeform placement width in canvas coords'),
@@ -66,7 +74,14 @@ const slideShape = z
   .object({
     id: z.string().optional().describe('Unique slide id, e.g. "SLD-001". Auto-generated if omitted.'),
     kind: z.string().optional().describe('cover | section | content | closing'),
-    layout: z.string().optional().describe('Layout hint, e.g. "2-col" | "kpi-grid" | "timeline"'),
+    layout: z
+      .string()
+      .optional()
+      .describe(
+        'Block arrangement on content slides: "two-col" (needs 2+ blocks) | "kpi-grid" (alias "kpi"). ' +
+          'Any other value silently falls back to the default arrangement. On cover/section slides it is printed as ' +
+          'the small label above the title.',
+      ),
     title: z.string().optional().describe('Assertion-style title (the claim this slide makes) — text spine'),
     blocks: z
       .array(
@@ -82,7 +97,10 @@ const slideShape = z
     diagram: z
       .object({ type: z.literal('mermaid').optional(), code: z.string() })
       .optional()
-      .describe('Mermaid diagram; visual only, not indexed — keep the facts in title/blocks too'),
+      .describe(
+        'Mermaid diagram, drawn below the blocks on "content" slides (ignored on cover/section/closing and when the ' +
+          'slide has baked html); visual only, not indexed — keep the facts in title/blocks too',
+      ),
     image: imageShape
       .optional()
       .describe('Single primary/background image (cover, section, full-bleed). See imageShape fields.'),
@@ -242,7 +260,12 @@ export function registerPresentationTools(server) {
       try {
         const client = makeClient();
         presentationId = await resolveNodeId(client, presentationId);
-        const result = await client.appendPresentationSlides(presentationId, ensureSlideIds(slides));
+        // ISSUE-185 — do NOT mint ids here: numbering by this call's own
+        // array index always collides with the deck's existing slides
+        // (e.g. restamping "SLD-001" onto a deck that already has one).
+        // The server fills any omitted slide/block id, avoiding the deck's
+        // current ids (see PresentationsService.appendSlides).
+        const result = await client.appendPresentationSlides(presentationId, slides);
         return jsonResult(result);
       } catch (err) {
         return errorResult(err);
@@ -328,8 +351,8 @@ export function registerPresentationTools(server) {
     },
     async ({ prompt, nodeId, workspace }) => {
       try {
-        const client = makeClient();
-        const ws = requireWorkspace(workspace);
+        const ws = requireWorkspace(workspace); // ISSUE-61 — 워크스페이스를 먼저 정하고 그 키로(attachments.js 와 같은 결함)
+        const client = makeClient(ws);
         nodeId = await resolveOptionalNodeId(client, nodeId);
         const result = await client.generateImage(ws, { prompt, nodeId });
         return jsonResult(result);
@@ -357,8 +380,8 @@ export function registerPresentationTools(server) {
     },
     async ({ attachmentId, nodeId, workspace }) => {
       try {
-        const client = makeClient();
-        const ws = requireWorkspace(workspace);
+        const ws = requireWorkspace(workspace); // ISSUE-61 — 위와 같다
+        const client = makeClient(ws);
         nodeId = await resolveOptionalNodeId(client, nodeId);
         const result = await client.removeImageBackground(ws, { attachmentId, nodeId });
         return jsonResult(result);
@@ -405,7 +428,8 @@ export function registerPresentationTools(server) {
       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' +
+        'exports. Prefer this over the mermaid `diagram` field when the diagram has to look designed — a plain ' +
+        '"content" slide also draws its mermaid `diagram`, but with mermaid\'s default look.\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' +

package/lib/mcp-tools/public.js

@@ -86,7 +86,8 @@ export function registerPublicTools(server) {
         '`{"password": "..."}` locks the page (the content is not sent at all until the password is entered — it is ' +
         'not hidden in the browser), `{"password": null}` unlocks; ' +
         '`{"expiresAt": "2026-12-31T00:00:00Z"}` auto-closes on that date, `null` clears it; ' +
-        '`{"noIndex": true}` asks search engines to stay away; ' +
+        '`{"noIndex": true}` asks search engines to stay away (Team plan and up — a Free workspace gets 403 ' +
+        'PLAN_UPGRADE_REQUIRED; a password-locked page is always hidden and cannot be re-exposed until unlocked); ' +
         '`{"design": {"layout": "board", "skin": "paper"}}` changes how a published TABLE looks — it does not ' +
         'have to be a table (cards, gallery, list, board, timeline, calendar, chart, ranking). ' +
         'For DOCUMENT nodes use rootr_set_document_public instead — documents keep their own settings (skins, ' +
@@ -129,6 +130,8 @@ export function registerPublicTools(server) {
         'currently open, when it expires, whether a password is set (the password itself is never returned), whether ' +
         'cloning is allowed, and whether the pages underneath went out with it. ' +
         '`publishable: false` means this type cannot be published at all (FOLDER). ' +
+        '`closed: "PUBLIC_OWN_ROW_PAGE"` (with `isPublic: false` and a `closedReason`) means publishing is switched on but the ' +
+        'address is closed right now — do NOT hand that URL out; tell the user why and how to reopen it. ' +
         'Call this before publishing so you do not tell the user a page is new when it already had a URL.',
       annotations: { readOnlyHint: true, destructiveHint: false },
       inputSchema: {

package/lib/mcp-tools/recordings.js

@@ -4,7 +4,19 @@ import { basename, extname, join, isAbsolute } from 'node:path';
 
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveNodeId, NODE_TARGET_HINT, NODE_URL_HINT, resolveOptionalNodeId } from './shared.js';
+import {
+  jsonResult,
+  errorResult,
+  makeClient,
+  requireWorkspace,
+  resolveNodeId,
+  NODE_TARGET_HINT,
+  NODE_URL_HINT,
+  resolveOptionalNodeId,
+  assertLocalFilesAllowed,
+  isHostedMcp,
+  localFileArg,
+} from './shared.js';
 import { RootrApiError } from '../client.js';
 
 /** 100MB — the backend's hard limit on a single audio upload. */
@@ -25,8 +37,11 @@ const AUDIO_MIME_BY_EXT = {
 
 /** Reads file bytes from a local path or a base64 string; exactly one must be given. */
 function readAudioBytes({ filePath, base64Data }) {
+  // SEC-MCP-FILES — 원격 커넥터에서는 서버 파일을 읽게 되므로 읽기 전에 거절한다.
+  assertLocalFilesAllowed(filePath);
   if (filePath) return readFileSync(filePath);
   if (base64Data) return Buffer.from(base64Data, 'base64');
+  if (isHostedMcp()) throw new RootrApiError('base64Data 가 필요합니다 (원격 커넥터에서는 filePath 를 쓸 수 없습니다).');
   throw new RootrApiError('filePath 또는 base64Data 중 하나가 필요합니다.');
 }
 
@@ -133,10 +148,12 @@ export function registerRecordingTools(server) {
       annotations: { readOnlyHint: false, destructiveHint: true },
       inputSchema: {
         recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT} (create one with rootr_create_recording)`),
-        filePath: z
-          .string()
-          .optional()
-          .describe('Local filesystem path to the audio file (the MCP server reads this itself, e.g. "/tmp/meeting.m4a")'),
+        ...localFileArg(
+          z
+            .string()
+            .optional()
+            .describe('Local filesystem path to the audio file (the MCP server reads this itself, e.g. "/tmp/meeting.m4a")'),
+        ),
         base64Data: z
           .string()
           .optional()
@@ -380,13 +397,15 @@ export function registerRecordingTools(server) {
       annotations: { readOnlyHint: true },
       inputSchema: {
         recordingId: z.string().describe(`RECORDING node id${NODE_TARGET_HINT}`),
-        filePath: z
-          .string()
-          .optional()
-          .describe(
-            'Where to save the audio ON THE MACHINE RUNNING THIS MCP SERVER. A directory saves under the ' +
-              'original filename. Omit to use a temp file. Ignored when urlOnly is true.',
-          ),
+        ...localFileArg(
+          z
+            .string()
+            .optional()
+            .describe(
+              'Where to save the audio ON THE MACHINE RUNNING THIS MCP SERVER. A directory saves under the ' +
+                'original filename. Omit to use a temp file. Ignored when urlOnly is true.',
+            ),
+        ),
         urlOnly: z
           .boolean()
           .optional()
@@ -403,18 +422,23 @@ export function registerRecordingTools(server) {
         }
         const { attachmentId, filename, mimeType, size } = rec.audio;
         const url = client.attachmentRawUrl(attachmentId);
-        if (urlOnly) {
+        // SEC-MCP-FILES — 원격 커넥터에서는 서버에 파일을 쓰지 않는다. filePath 를 주면 거절하고,
+        // 안 줘도(예전엔 서버 임시 폴더에 썼다) 주소만 돌려준다.
+        assertLocalFilesAllowed(filePath);
+        if (urlOnly || isHostedMcp()) {
           return jsonResult({ audioUrl: url, filename, mimeType, size, durationSec: rec.durationSec ?? null });
         }
         const data = await client.downloadAttachmentBytes(attachmentId);
         // A directory (existing path ending in a separator, or no extension) →
         // keep the original filename; otherwise treat it as the target file.
+        // 저장 이름은 오디오를 올린 쪽이 정한 값이다 — 경로 조각(../)이 섞여 있어도 파일 이름만 쓴다.
+        const safeName = basename(String(filename || 'audio')) || 'audio';
         let target = filePath?.trim();
         if (!target) {
-          target = join(tmpdir(), `rootr-${recordingId}-${filename}`);
+          target = join(tmpdir(), `rootr-${recordingId}-${safeName}`);
         } else {
           if (!isAbsolute(target)) target = join(process.cwd(), target);
-          if (target.endsWith('/') || !extname(target)) target = join(target, filename);
+          if (target.endsWith('/') || !extname(target)) target = join(target, safeName);
         }
         writeFileSync(target, data);
         return jsonResult({

package/lib/mcp-tools/shared.js

@@ -53,6 +53,34 @@ export function jsonResult(value) {
   return textResult(JSON.stringify(value, null, 2));
 }
 
+/**
+ * SEC-MCP-FILES — 원격 커넥터(호스티드 `/mcp`)에서는 "MCP 서버가 도는 기계"가 곧 API 서버다.
+ * `filePath` 처럼 그 기계의 파일을 읽고 쓰는 인자를 받으면, 호출자가 서버 파일(.env 등)을 첨부로
+ * 읽어 가거나 서버 아무 경로에 파일을 쓸 수 있다. 원격이면 무조건 거절한다(stdio 는 사용자
+ * 자기 기계라 그대로). 스키마에서 빼는 것(`localFileArg`)과 여기 거절, 두 겹으로 막는다.
+ */
+export function isHostedMcp() {
+  return !!currentClientOverride();
+}
+
+export function assertLocalFilesAllowed(filePath) {
+  if (!currentClientOverride()) return;
+  if (filePath === undefined || filePath === null || filePath === '') return;
+  throw new RootrApiError('원격 커넥터에서는 filePath 를 쓸 수 없습니다.', {
+    hint:
+      'filePath 는 MCP 서버가 도는 기계의 파일을 가리킵니다. 원격 커넥터에서는 그 기계가 Rootr 서버라 ' +
+      '쓸 수 없습니다 — 파일 내용을 base64Data 로 보내거나, 로컬 rootr CLI(npx rootr-cli mcp)를 쓰세요.',
+  });
+}
+
+/**
+ * 도구 입력 스키마에 넣을 `filePath` 칸. 원격 커넥터에서는 빈 객체를 돌려줘 칸 자체가 스키마에서
+ * 빠진다(모델이 시도하지 않게) — `...localFileArg(z.string()…)` 로 펼쳐 쓴다.
+ */
+export function localFileArg(schema) {
+  return currentClientOverride() ? {} : { filePath: schema };
+}
+
 /**
  * Build a RootrClient. If `workspaceOverride` is given, it wins over the
  * configured/env workspace — this backs the optional `workspace` argument