rootr-cli 0.17.3 → 0.19.0

package/lib/client.js

@@ -97,10 +97,17 @@ function hintFor(status, body) {
 }
 
 export class RootrClient {
-  constructor({ apiKey, workspace, baseUrl, defaultHeaders }) {
+  constructor({ apiKey, workspace, baseUrl, publicBaseUrl, defaultHeaders }) {
     this.apiKey = apiKey;
     this.workspace = workspace;
     this.baseUrl = (baseUrl || '').replace(/\/+$/, '');
+    /**
+     * ISSUE-61 — 사람·문서에 건네는 주소(첨부 `/raw` 등)의 뿌리. 로컬 CLI 는 baseUrl 이 곧 밖에서
+     * 보이는 주소라 비워 둔다. 원격 커넥터는 API 를 127.0.0.1 로 되부르므로(baseUrl) 그 주소를
+     * 그대로 문서에 넣으면 사람 화면에서 그림이 깨진다 — 호스티드 전송 계층이 공개 주소를 따로 넘긴다.
+     * 요청을 보내는 데는 절대 쓰지 않는다(그건 언제나 baseUrl).
+     */
+    this.publicBaseUrl = (publicBaseUrl || '').replace(/\/+$/, '') || this.baseUrl;
     /** Sent on every request — the hosted transport forwards Accept-Language
      * here so API error text comes back in the caller's language. */
     this.defaultHeaders = defaultHeaders || {};
@@ -247,6 +254,32 @@ export class RootrClient {
     }
   }
 
+  /** Resolve a published `/p/{slug}` public URL to a node in the active workspace. */
+  async getNodeBySlug(slug) {
+    this._requireWorkspace();
+    try {
+      const data = await this.request(
+        `/workspaces/${encodeURIComponent(this.workspace)}/nodes/by-slug?slug=${encodeURIComponent(slug)}`,
+      );
+      return data;
+    } catch (err) {
+      if (err instanceof RootrApiError && err.status === 404) return null;
+      throw err;
+    }
+  }
+
+  /**
+   * ISSUE-127 — 공개 발행본을 읽는다: `/p/{slug}` 화면이 받는 것과 같은 응답(`GET /public/docs/:slug`).
+   * 로그인 없이 누구나 읽는 경로라 키가 무엇이든 더 열리는 것이 없다 — 발행한 판만 주고, 발행을 내렸거나
+   * 만료·삭제된 것은 404, 비밀번호가 걸린 것은 401(`PUBLIC_DOC_PASSWORD`). 통과증(`pass`)은 일부러 받지 않는다.
+   */
+  async getPublicDocument(slug) {
+    // ISSUE-127 — 이 읽기는 요금제 조회 한도에 1회로 센다(내 문서 읽기와 같다). 계정 키(PAT)는 워크스페이스에 묶여 있지 않아
+    // 서버가 어느 워크스페이스의 한도로 셀지 모른다 — 지금 연결된 워크스페이스를 알려 준다(워크스페이스 키는 서버가 키에서 안다).
+    const qs = this.workspace ? `?workspaceId=${encodeURIComponent(this.workspace)}` : '';
+    return this.request(`/public/docs/${encodeURIComponent(slug)}${qs}`);
+  }
+
   async createNode({ type = 'DOCUMENT', path, createParents = true, autoRename = false, content }) {
     this._requireWorkspace();
     return this.request(`/workspaces/${encodeURIComponent(this.workspace)}/nodes`, {
@@ -307,10 +340,29 @@ export class RootrClient {
       returnResponse: true,
     });
     const etag = res.headers.get('etag') || res.headers.get('ETag') || undefined;
-    return { etag };
+    // ISSUE-105 — 서버가 쓰기 응답에 실은 알림(HTML 주석이 저장 때 사라졌다 등)을 버리지 않는다.
+    let warnings;
+    try {
+      const text = await res.text();
+      warnings = text ? JSON.parse(text).warnings : undefined;
+    } catch {
+      warnings = undefined;
+    }
+    return { etag, ...(Array.isArray(warnings) && warnings.length ? { warnings } : {}) };
   }
 
   /** Safe, conflict-free append. */
+  /**
+   * EMBED-API — 문서에 노드(표·시트·발표자료…) 하나를 끼워 넣는다. `node` 는 id 든 경로든 된다
+   * (서버가 id 로 바꿔 `[[embed:<id>]]` 한 줄을 붙인다).
+   */
+  async embedNode(documentId, { node, underHeading, createIfMissing } = {}) {
+    return this.request(`/documents/${encodeURIComponent(documentId)}/embeds`, {
+      method: 'POST',
+      body: { node, underHeading, createIfMissing },
+    });
+  }
+
   async appendDocument(id, { content, underHeading, createIfMissing } = {}) {
     const res = await this.request(`/documents/${encodeURIComponent(id)}/append`, {
       method: 'POST',
@@ -458,6 +510,71 @@ export class RootrClient {
     return this.request(`/nodes/${encodeURIComponent(nodeId)}/public-status`);
   }
 
+  // ── BOOKING — 공개한 표에서 방문자가 일정을 잡게 한다 ──────────────────
+  //
+  // 예약은 **공개 주소 위에 서는 기능**이다. 그래서 켜기 전에 표가 발행돼 있어야 하고,
+  // 안 돼 있으면 서버가 "먼저 표를 웹에 공개해 주세요"로 거절한다.
+
+  /** 예약 설정(규칙·확정 방식·물어볼 칸·구글 캘린더)과 연결 상태를 본다. */
+  async getBooking(nodeId) {
+    return this.request(`/nodes/${encodeURIComponent(nodeId)}/booking`);
+  }
+
+  /**
+   * 예약 설정을 저장한다. 보낸 칸만 바뀌고 나머지는 그대로다.
+   * 날짜·메일 칸이 없으면 서버가 만들어 준다(승인제면 상태 칸까지).
+   */
+  async setBooking(nodeId, settings = {}) {
+    return this.request(`/nodes/${encodeURIComponent(nodeId)}/booking`, {
+      method: 'PUT',
+      body: settings,
+    });
+  }
+
+  /**
+   * 방문자에게 보이는 **빈 시간**. 공개 주소(slug)로 부르는 로그인 없는 길이라,
+   * 주인이 보는 것과 방문자가 보는 것이 같은지 여기서 바로 확인할 수 있다.
+   */
+  async bookingSlots(slug, { from, to, pass, type } = {}) {
+    const q = new URLSearchParams();
+    if (from) q.set('from', from);
+    if (to) q.set('to', to);
+    if (pass) q.set('pass', pass);
+    // 약속 종류마다 길이가 달라 빈 시간도 다르다 — 안 주면 첫 종류로 본다.
+    if (type) q.set('type', type);
+    return this.request(`/public/nodes/${encodeURIComponent(slug)}/booking/slots?${q.toString()}`);
+  }
+
+  // ── BOOKING-GCAL — 구글 캘린더 연결(사람 한 명의 것) ───────────────────
+
+  /** 내가 연결해 둔 구글 계정들. `available:false`면 서버에 구글 설정이 아직 없다. */
+  async googleCalendarConnections() {
+    return this.request('/integrations/google-calendar/connections');
+  }
+
+  /**
+   * 구글 동의 화면 주소를 받는다. **브라우저에서 한 번은 허용해야** 연결이 된다 —
+   * 구글이 그렇게만 허락한다. 허용하고 나면 그 뒤로는 명령줄에서 다 된다.
+   */
+  async googleCalendarAuthorizeUrl(returnTo = '/') {
+    return this.request('/integrations/google-calendar/authorize', {
+      method: 'POST',
+      body: { returnTo },
+    });
+  }
+
+  /** 그 연결로 볼 수 있는 캘린더들(막을 것·적을 것을 여기서 고른다). */
+  async googleCalendars(connectionId) {
+    return this.request(`/integrations/google-calendar/connections/${encodeURIComponent(connectionId)}/calendars`);
+  }
+
+  /** 연결을 끊는다. 구글 쪽 권한도 같이 거둔다. */
+  async disconnectGoogleCalendar(connectionId) {
+    return this.request(`/integrations/google-calendar/connections/${encodeURIComponent(connectionId)}`, {
+      method: 'DELETE',
+    });
+  }
+
   // ── DB-PERM-001 / DB-WATCH — 표에 거는 자물쇠와 알림 규칙 ──────────────
   //
   // 노션에 없는 것들이라, 에이전트가 표를 만들어 놓고도 "지원서는 서로 못 보게" 같은
@@ -511,6 +628,65 @@ export class RootrClient {
     );
   }
 
+  // ── DB-AUTO — "값이 이렇게 되면 이 일을 해라" 규칙 ───────────────────────
+  //
+  // 버튼과 같은 단계 문법을 쓰되 사람이 안 눌러도 돈다. 2026-09-18 클린베테랑 요청
+  // 4번: 투입 확정 시 해피콜 3건을 사람이 버튼으로 잡고 있었고, 안 누르면 빠졌다.
+
+  /** 이 표의 자동 규칙 목록. */
+  async listDatabaseAutomations(databaseId) {
+    return this.request(`/databases/${encodeURIComponent(databaseId)}/automations`);
+  }
+
+  /** 자동 규칙을 **통째로** 갈아끼운다(MANAGE 필요). 남길 규칙도 같이 보내야 한다. */
+  async setDatabaseAutomations(databaseId, automations) {
+    return this.request(`/databases/${encodeURIComponent(databaseId)}/automations`, {
+      method: 'PUT',
+      body: { automations },
+    });
+  }
+
+  // ── FORM-MAP — 폼 질문이 표의 어느 칸으로 가는가 ───────────────────────
+
+  /** 질문마다 어느 칸으로 들어가는지 + 짝 없는 질문(값이 버려진다). */
+  async formMapping(formId) {
+    return this.request(`/forms/${encodeURIComponent(formId)}/mapping`);
+  }
+
+  /** 질문↔칸 짝을 손으로 정한다. `{ 질문id: 칸id }`, 값이 null이면 자동으로 되돌린다. */
+  async setFormMapping(formId, fieldMap) {
+    return this.request(`/forms/${encodeURIComponent(formId)}/mapping`, {
+      method: 'PUT',
+      body: { fieldMap },
+    });
+  }
+
+  // ── XLSX-FOLD — 시트 복제형 엑셀을 표 하나로 접기 ──────────────────────
+
+  /**
+   * 시트가 수백 장인 엑셀을 표 한 개로 접어 가져온다(2026-09-18 요청 7번).
+   * `dryRun: true`면 아무것도 만들지 않고 어떻게 접히는지만 돌려준다.
+   */
+  async importFoldedSheets(workspaceId, body) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/databases/import/sheets`, {
+      method: 'POST',
+      body,
+    });
+  }
+
+  // ── MIGRATION-GRACE — 초기 이관 동안 하루 조회 한도 풀기 ────────────────
+
+  async startMigrationGrace(workspaceId) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/billing/migration-grace`, {
+      method: 'POST',
+      body: {},
+    });
+  }
+
+  async migrationGrace(workspaceId) {
+    return this.request(`/workspaces/${encodeURIComponent(workspaceId)}/billing/migration-grace`);
+  }
+
   // ── PUBLIC-DOCS — 발행한 문서에 올라온 변경 제안 ────────────────────────
 
   async listDocumentCommits(documentId, status = 'OPEN') {
@@ -564,10 +740,10 @@ export class RootrClient {
   }
 
   /** Create a brand-new workspace from a scaffold tree. Requires an account key (PAT) with workspaces:create. */
-  async createWorkspaceScaffold({ name, intent, tree }) {
+  async createWorkspaceScaffold({ name, intent, tree, mode }) {
     return this.request('/scaffold/workspace', {
       method: 'POST',
-      body: { name, intent, tree },
+      body: { name, intent, tree, mode },
     });
   }
 
@@ -592,18 +768,18 @@ export class RootrClient {
    * Check a designed tree BEFORE building it — the compiler pass of scaffolding.
    * Needs no workspace, creates nothing. Returns { score, counts, findings, summary }.
    */
-  async scaffoldReview(tree) {
-    return this.request('/scaffold/review', { method: 'POST', body: { tree } });
+  async scaffoldReview(tree, mode) {
+    return this.request('/scaffold/review', { method: 'POST', body: { tree, mode } });
   }
 
   /**
    * Check the workspace that was ACTUALLY built (not the tree you sent).
    * Optional rootPath narrows it to one subtree.
    */
-  async scaffoldReviewBuilt(workspace, rootPath) {
+  async scaffoldReviewBuilt(workspace, rootPath, mode) {
     return this.request(`/workspaces/${encodeURIComponent(workspace)}/scaffold/review-built`, {
       method: 'POST',
-      body: { rootPath },
+      body: { rootPath, mode },
     });
   }
 
@@ -620,10 +796,10 @@ export class RootrClient {
   }
 
   /** Apply a scaffold tree to an existing workspace. */
-  async scaffoldApply(workspace, { rootPath, tree } = {}) {
+  async scaffoldApply(workspace, { rootPath, tree, mode } = {}) {
     return this.request(`/workspaces/${encodeURIComponent(workspace)}/scaffold/apply`, {
       method: 'POST',
-      body: { rootPath, tree },
+      body: { rootPath, tree, mode },
     });
   }
 
@@ -690,13 +866,21 @@ export class RootrClient {
   async ask(workspaceId, question) {
     this._requireApiKey();
     const graphqlUrl = `${this.baseUrl.replace(/\/v1\/?$/, '')}/graphql`;
-    const query =
-      'query($ws:String!,$q:String!){ask(workspaceId:$ws,question:$q){text citations{documentPath quote}}}';
-    const data = await this.request(null, {
-      url: graphqlUrl,
-      method: 'POST',
-      body: { query, variables: { ws: workspaceId, q: question } },
-    });
+    // DB-SEARCH — 표의 행에서 온 출처는 행 제목·행 주소를 같이 받는다. 이 필드를 모르는 옛 서버에
+    // 붙으면 GraphQL 이 질문 전체를 거절하므로, 그때만 예전 모양으로 한 번 더 묻는다.
+    const ask = (fields) =>
+      this.request(null, {
+        url: graphqlUrl,
+        method: 'POST',
+        body: {
+          query: `query($ws:String!,$q:String!){ask(workspaceId:$ws,question:$q){text citations{${fields}}}}`,
+          variables: { ws: workspaceId, q: question },
+        },
+      });
+    let data = await ask('documentTitle documentPath quote rowId rowTitle url');
+    if (data && Array.isArray(data.errors) && data.errors.some((e) => /Cannot query field/.test(e.message || ''))) {
+      data = await ask('documentPath quote');
+    }
     if (data && Array.isArray(data.errors) && data.errors.length) {
       const msg = data.errors.map((e) => e.message || String(e)).join('; ');
       throw new RootrApiError(tr(`ask 오류: ${msg}`, `ask failed: ${msg}`), { body: data.errors });
@@ -901,7 +1085,11 @@ export class RootrClient {
     const query = params.length ? `?${params.join('&')}` : '';
     const data = await this.request(`/databases/${encodeURIComponent(databaseId)}/rows${query}`);
     if (Array.isArray(data)) return data;
-    if (data && Array.isArray(data.rows)) return data.rows;
+    if (data && Array.isArray(data.rows)) {
+      // 벡터 칸이 있는 표는 서버가 행마다 채워진 벡터 칸(칸 id → 차원)을 `vectors` 로 따로 준다 — 행에 붙여 MCP 에도 보인다.
+      if (!data.vectors) return data.rows;
+      return data.rows.map((r) => ({ ...r, vectors: data.vectors[r.id] ?? {} }));
+    }
     return [];
   }
 
@@ -927,10 +1115,12 @@ export class RootrClient {
    * DB-BULK — 여러 행을 **한 번에 넣는다**. 전부 아니면 전무다.
    * 칸은 이름으로도 id로도 적을 수 있다.
    */
-  async bulkCreateRows(databaseId, rows) {
+  async bulkCreateRows(databaseId, rows, upsertKey) {
     return this.request(`/databases/${encodeURIComponent(databaseId)}/rows/bulk`, {
       method: 'POST',
-      body: { rows },
+      // BULK-UPSERT — 열쇠 칸을 주면 이미 있는 행은 고치고 없는 것만 만든다.
+      // 재시도가 안전해야 외부 시스템 동기화를 만들 수 있다(2026-09-18 요청 5번).
+      body: { rows, ...(upsertKey ? { upsertKey } : {}) },
     });
   }
 
@@ -1018,18 +1208,51 @@ export class RootrClient {
   // PATCH /databases/:id replaces the whole properties array, so rebuilding it
   // client-side drops any column left out. These merge server-side instead.
 
-  async addColumn(databaseId, { name, type, options, relationDatabaseId, formula, rollup, prefix } = {}) {
+  async addColumn(
+    databaseId,
+    { name, type, options, relationDatabaseId, reverseName, formula, rollup, prefix, searchExcluded, dimensions } = {},
+  ) {
     return this.request(`/databases/${encodeURIComponent(databaseId)}/columns`, {
       method: 'POST',
       // 계산 칸(수식·롤업·번호)은 설정이 곧 그 칸이라 같이 보내야 한다.
-      body: { name, type, options, relationDatabaseId, formula, rollup, prefix },
+      // reverseName 은 상대 표에 짝 칸을 만든다(양방향 관계).
+      // searchExcluded 는 "검색 색인에서 제외"(표 관리자만).
+      body: { name, type, options, relationDatabaseId, reverseName, formula, rollup, prefix, searchExcluded, dimensions },
     });
   }
 
-  async updateColumn(databaseId, propertyId, { name, options } = {}) {
+  async updateColumn(databaseId, propertyId, { name, options, formula, rollup, prefix, reverseName, searchExcluded } = {}) {
     return this.request(
       `/databases/${encodeURIComponent(databaseId)}/columns/${encodeURIComponent(propertyId)}`,
-      { method: 'PATCH', body: { name, options } },
+      { method: 'PATCH', body: { name, options, formula, rollup, prefix, reverseName, searchExcluded } },
+    );
+  }
+
+  // DB-VECTOR — 에이전트용 벡터 칸(칸 id 또는 이름).
+  async putVectors(databaseId, column, items) {
+    return this.request(`/databases/${encodeURIComponent(databaseId)}/vectors/${encodeURIComponent(column)}`, {
+      method: 'PUT',
+      body: { items },
+    });
+  }
+
+  async queryVectors(databaseId, column, { vector, topK, minScore } = {}) {
+    return this.request(`/databases/${encodeURIComponent(databaseId)}/vectors/${encodeURIComponent(column)}/query`, {
+      method: 'POST',
+      body: { vector, topK, minScore },
+    });
+  }
+
+  async getRowVector(databaseId, rowId, column) {
+    return this.request(
+      `/databases/${encodeURIComponent(databaseId)}/rows/${encodeURIComponent(rowId)}/vectors/${encodeURIComponent(column)}`,
+    );
+  }
+
+  async deleteRowVector(databaseId, rowId, column) {
+    return this.request(
+      `/databases/${encodeURIComponent(databaseId)}/rows/${encodeURIComponent(rowId)}/vectors/${encodeURIComponent(column)}`,
+      { method: 'DELETE' },
     );
   }
 
@@ -1296,7 +1519,8 @@ export class RootrClient {
    * redirect to the storage bucket isn't sent our API key.
    */
   async downloadAttachmentBytes(attachmentId) {
-    const url = this.attachmentRawUrl(attachmentId);
+    // ISSUE-61 — 바이트는 우리가 직접 받는다: 공개 주소(publicBaseUrl)가 아니라 요청을 보내는 baseUrl 로.
+    const url = `${this.baseUrl}/attachments/${encodeURIComponent(attachmentId)}/raw`;
     const res = await fetch(url);
     if (!res.ok) {
       throw new RootrApiError(tr(`오디오 다운로드 실패 (HTTP ${res.status})`, `Audio download failed (HTTP ${res.status})`), { status: res.status });
@@ -1425,7 +1649,7 @@ export class RootrClient {
 
   /** Public, unauthenticated URL an <img> tag (or a published /p/ document) can load directly. */
   attachmentRawUrl(attachmentId) {
-    return `${this.baseUrl}/attachments/${encodeURIComponent(attachmentId)}/raw`;
+    return `${this.publicBaseUrl}/attachments/${encodeURIComponent(attachmentId)}/raw`;
   }
 
   // ---- Spreadsheets ---------------------------------------------------------

package/lib/credentials.js

@@ -155,6 +155,22 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
 
   if (target) {
     const scoped = lastRejection && lastRejection.status === 403;
+    // ISSUE-172 — `rootr config --add-key`/`--api-key` writes to
+    // ~/.rootr/config.json from a SEPARATE process. If this (MCP server)
+    // process was started with ROOTR_API_KEY set, config.js makes that env
+    // var win over anything just written to the file (see its ENV-WINS
+    // comment) — so the fix this message recommends silently does nothing
+    // until the server itself is restarted. Say so instead of pointing at a
+    // remedy that cannot take effect.
+    const envPinned = !!process.env.ROOTR_API_KEY;
+    const restartNote = envPinned
+      ? tr(
+          '\n주의: 이 서버 프로세스는 ROOTR_API_KEY 환경변수로 키가 고정되어 있어, 위 명령으로 키를 추가해도 서버를 ' +
+            '재시작해야 반영됩니다 (같은 프로세스가 계속 돌아가는 동안은 파일에 새로 쓴 키를 읽지 않습니다).',
+          '\nNote: this server process has ROOTR_API_KEY pinned via env var, so adding a key with the command above ' +
+            'only takes effect after the server is restarted (it keeps reading the env-pinned key while running).',
+        )
+      : '';
     return {
       error: tr(
         `"${target.name || target.id}" (${target.id}) 는 접근 권한 목록에는 있지만, 등록된 키로는 열 수 없습니다` +
@@ -164,7 +180,8 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
             : `원인: ${lastRejection ? lastRejection.message : '알 수 없음'}\n`) +
           '조치 (둘 중 하나, 사용자가 직접):\n' +
           '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
-          `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\``,
+          `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\`` +
+          restartNote,
         `"${target.name || target.id}" (${target.id}) is on your access list, but none of the registered keys opens it` +
           `${target.role ? ` (your role: ${target.role})` : ''}.\n` +
           (scoped
@@ -172,7 +189,8 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
             : `Cause: ${lastRejection ? lastRejection.message : 'unknown'}\n`) +
           'Fix (either one, done by you):\n' +
           '1) Create an account key (PAT) under rootr.io > Settings > API keys → `rootr config --api-key <key>` (works everywhere)\n' +
-          `2) Create a key for that workspace → \`rootr config --add-key <key> --workspace ${target.id}\``,
+          `2) Create a key for that workspace → \`rootr config --add-key <key> --workspace ${target.id}\`` +
+          restartNote,
       ),
     };
   }

package/lib/mcp-tools/ask.js

@@ -28,7 +28,12 @@ export function registerAskTools(server) {
         const client = makeClient(ws);
         const result = await client.ask(ws, question);
         const citations = Array.isArray(result.citations) ? result.citations : [];
-        const citationLines = citations.map((c) => `- ${c.documentPath}: ${c.quote}`);
+        // DB-SEARCH — 표의 행 출처는 "표 › 행 (주소)" — 표 이름만 주면 찾아 놓고도 그 행을 못 연다.
+        const citationLines = citations.map((c) =>
+          c.rowId
+            ? `- ${c.documentTitle || c.documentPath} › ${c.rowTitle || '(untitled row)'}${c.url ? ` (${c.url})` : ''}: ${c.quote}`
+            : `- ${c.documentPath}${c.url ? ` (${c.url})` : ''}: ${c.quote}`,
+        );
         const text = [
           result.text || '(no answer text)',
           '',

package/lib/mcp-tools/attachments.js

@@ -2,33 +2,50 @@ import { readFileSync } from 'node:fs';
 
 import { z } from 'zod';
 
-import { jsonResult, errorResult, makeClient, requireWorkspace, resolveOptionalNodeId, NODE_TARGET_HINT } from './shared.js';
+import {
+  jsonResult,
+  errorResult,
+  makeClient,
+  requireWorkspace,
+  resolveOptionalNodeId,
+  NODE_TARGET_HINT,
+  assertLocalFilesAllowed,
+  isHostedMcp,
+  localFileArg,
+} from './shared.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
 import { RootrApiError } from '../client.js';
 
 /** Reads file bytes from a local path or a base64 string; exactly one must be given. */
 function readAttachmentBytes({ 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 중 하나가 필요합니다.');
 }
 
-const uploadInputSchema = {
+// 등록 시점(원격이면 요청마다)에 만든다 — 원격 커넥터에서는 filePath 칸이 스키마에서 빠진다.
+const buildUploadInputSchema = () => ({
   filename: z.string().describe('File name to store, e.g. "screenshot.png"'),
   mimeType: z.string().describe('MIME type, e.g. "image/png"'),
-  filePath: z
-    .string()
-    .optional()
-    .describe('Local filesystem path to the file to upload (the MCP server reads this itself, e.g. "/tmp/screenshot.png")'),
+  ...localFileArg(
+    z
+      .string()
+      .optional()
+      .describe('Local filesystem path to the file to upload (the MCP server reads this itself, e.g. "/tmp/screenshot.png")'),
+  ),
   base64Data: z
     .string()
     .optional()
     .describe('Base64-encoded file bytes; use this when the caller has the file in memory instead of on disk'),
   nodeId: z.string().optional().describe(`Document/node id${NODE_TARGET_HINT} to associate the attachment with (permission-checked)`),
   workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
-};
+});
 
 export function registerAttachmentTools(server) {
+  const uploadInputSchema = buildUploadInputSchema();
   server.registerTool(
     'rootr_upload_attachment',
     {
@@ -46,8 +63,11 @@ export function registerAttachmentTools(server) {
     },
     async ({ filename, mimeType, filePath, base64Data, nodeId, workspace }) => {
       try {
-        const client = makeClient();
+        // ISSUE-61 — workspace 를 먼저 정하고 그 워크스페이스의 키로 클라이언트를 만든다. 인자 없이
+        // makeClient() 를 부르면 기본 키가 골라져, 키를 워크스페이스별로 둔 구성에서 403 이 났다.
+        // (원격 커넥터는 makeClient 가 연결된 워크스페이스와 다른 값을 거절한다.)
         const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
         nodeId = await resolveOptionalNodeId(client, nodeId);
         const data = readAttachmentBytes({ filePath, base64Data });
         const { id } = await client.uploadAttachment(ws, { filename, mimeType, nodeId, data });
@@ -81,7 +101,7 @@ export function registerAttachmentTools(server) {
         target: z.string().describe('Document path (starting with "/") or node id to insert the image into'),
         filename: uploadInputSchema.filename,
         mimeType: uploadInputSchema.mimeType,
-        filePath: uploadInputSchema.filePath,
+        ...(uploadInputSchema.filePath ? { filePath: uploadInputSchema.filePath } : {}),
         base64Data: uploadInputSchema.base64Data,
         alt: z.string().optional().describe('Alt text / caption for the image (defaults to filename)'),
         underHeading: z
@@ -93,8 +113,8 @@ export function registerAttachmentTools(server) {
     },
     async ({ target, filename, mimeType, filePath, base64Data, alt, underHeading, workspace }) => {
       try {
-        const client = makeClient();
-        const ws = requireWorkspace(workspace);
+        const ws = requireWorkspace(workspace); // ISSUE-61 — 위와 같다: 워크스페이스 → 그 키
+        const client = makeClient(ws);
         const resolved = await resolveTarget(client, target);
         const nodeId = requireResolved(resolved);
         const data = readAttachmentBytes({ filePath, base64Data });