rootr-cli 0.19.0 → 0.20.0

package/README.ko.md

@@ -211,6 +211,11 @@ rootr config                       # 등록된 키 목록 확인
 워크스페이스가 바뀌고, 그 워크스페이스를 담당하는 키가 자동으로 선택·기억됩니다. 계정
 키(PAT)를 쓰면 소속된 어느 워크스페이스로든 바로 전환됩니다.
 
+MCP 서버를 `ROOTR_WORKSPACE` 환경변수로 띄웠다면(MCP 클라이언트 설정의 `env: {…}`), 재시작할 때마다
+환경변수가 다시 이깁니다. `rootr_use_workspace` 전환은 그 서버 프로세스가 켜져 있는 동안만 적용되고,
+전환 응답이 "재시작하면 어느 워크스페이스로 돌아가는지"를 알려 줍니다. 전환을 계속 유지하려면 그 설정의
+`ROOTR_WORKSPACE` 를 바꾸거나 지우세요.
+
 워크스페이스 키는 자기 워크스페이스 밖에서는 열리지 않습니다 — `rootr ws`(=`rootr_workspaces`)
 목록에 보여도 접근은 안 되는 경우가 있어, 등록된 키가 워크스페이스 키뿐이면 목록에
 `[등록된 키로는 접근 불가]`를 함께 표시합니다.
@@ -346,7 +351,7 @@ rootr memory forget <id>                         # 폐기(--hard면 행 삭제)
 
 ## MCP 서버로 사용하기
 
-`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 178종:
+`rootr mcp`는 stdio로 MCP(Model Context Protocol) 서버를 구동합니다. 제공 도구 186종:
 
 노드를 가리키는 인자(`target`, `databaseId`, `spreadsheetId`, `formId`, `crmId`, `trackerId`,
 `recordingId`, `presentationId`, `whiteboardId`, `logId`, `parentId` 등)는 **노드 id와 경로를 모두**
@@ -380,6 +385,8 @@ rootr memory forget <id>                         # 폐기(--hard면 행 삭제)
 |---|---|
 | `rootr_upload_attachment` | 로컬 파일(`filePath`) 또는 base64(`base64Data`)를 업로드하고 `{id, url, markdown}` 반환 |
 | `rootr_attach_image_to_document` | 위 업로드 + 지정 문서에 `rootr_append`로 바로 삽입 (가장 흔한 용법) |
+| `rootr_create_upload_url` | 잠깐(5분) 쓰는 올리기 주소를 받는다 — 파일 바이트를 그 주소에 직접 `PUT`. 큰 파일, 그리고 `filePath` 를 못 쓰는 원격 커넥터용 |
+| `rootr_complete_upload` | `PUT` 이 끝난 뒤 호출 — 올라간 것을 확인하고 `{id, url, markdown}` 반환 |
 
 `url`은 `/attachments/{id}/raw` — 로그인 없이 렌더되는 공개 경로라 published(`/p/`) 문서에도
 그대로 쓸 수 있습니다. CLI에서는 `rootr attach <file> [--doc <path|id>] [--heading "## X"] [--alt <text>]`.

package/README.md

@@ -11,7 +11,7 @@ citations back to the exact paragraph.
 *(한국어 문서: [README.ko.md](https://github.com/gwmage/rootr-cli/blob/main/README.ko.md))*
 
 - `rootr` CLI — documents, databases, forms, signed documents, publishing, permissions, memory
-- `rootr mcp` — stdio MCP server, **178 tools** (see [MCP tools](#mcp-tools))
+- `rootr mcp` — stdio MCP server, **186 tools** (see [MCP tools](#mcp-tools))
 
 Plain Node.js ESM, no build step. Node 18+ (uses the built-in `fetch`).
 
@@ -117,6 +117,11 @@ After that, `rootr use` (and the `rootr_use_workspace` MCP tool) accepts a **nam
 rootr.io URL**; the key that opens that workspace is selected and remembered automatically. An
 account key (PAT) switches to any workspace you belong to.
 
+If the MCP server was started with `ROOTR_WORKSPACE` set (the usual `env: {…}` block in an MCP client
+config), the env var wins again on every restart: a `rootr_use_workspace` switch applies for as long as
+that server process runs, and the reply says which workspace it returns to after a restart/reconnect.
+To make the switch permanent, change (or remove) `ROOTR_WORKSPACE` in that config.
+
 A workspace key does not open anything outside its own workspace. Because of that, `rootr ws`
 marks entries your registered keys cannot open — **being listed and being reachable are not the
 same thing**.
@@ -389,7 +394,7 @@ is refused and says when the grace was used.
 
 ## MCP tools
 
-`rootr mcp` speaks MCP over stdio. 178 tools:
+`rootr mcp` speaks MCP over stdio. 186 tools:
 
 | Group | Count | Tools |
 |---|---|---|
@@ -408,7 +413,7 @@ is refused and says when the grace was used.
 | LOG datastores | 5 | create store, update fields, add entries, query, stats |
 | Templates | 4 | list, apply, save as template, update |
 | Whiteboards | 3 | create, read and update the shapes & edges scene |
-| Attachments | 2 | upload a file, attach an image straight into a document |
+| Attachments | 4 | upload a file, attach an image straight into a document, upload by presigned URL (`rootr_create_upload_url` → PUT the bytes → `rootr_complete_upload`; for large files and the remote connector, where `filePath` is not available) |
 | Agent memory | 3 | remember, recall, forget |
 | Webhooks | 3 | list, create (secret shown once), delete |
 | Visitor booking & Google Calendar | 6 | turn a published table into a booking page, rules, open slots, connect / list / disconnect Google Calendar |

package/bin/rootr.js

@@ -5,7 +5,7 @@ import { dirname, join, basename, extname } from 'node:path';
 
 import { loadConfig, saveConfig, keyForWorkspace, maskKey, upsertKey, CONFIG_PATH, DEFAULT_BASE_URL } from '../lib/config.js';
 import { candidateClients, rememberWorkspace, resolveWorkspaceSwitch, surveyWorkspaces } from '../lib/credentials.js';
-import { RootrClient, RootrApiError } from '../lib/client.js';
+import { RootrClient, RootrApiError, imageMarkdown } from '../lib/client.js';
 import { resolveTarget, requireResolved, resolveMoveDestination } from '../lib/resolve.js';
 import { t as tr, lang } from '../lib/i18n.js';
 
@@ -576,7 +576,7 @@ async function cmdAttach(args) {
 
   const { id } = await client.uploadAttachment(workspace, { filename, mimeType, nodeId, data });
   const url = client.attachmentRawUrl(id);
-  const markdown = `![${args.alt || filename}](${url})`;
+  const markdown = imageMarkdown(args.alt || filename, url);
 
   if (nodeId) {
     const result = await client.appendDocument(nodeId, { content: markdown, underHeading: args.heading });

package/lib/client.js

@@ -1652,6 +1652,24 @@ export class RootrClient {
     return `${this.publicBaseUrl}/attachments/${encodeURIComponent(attachmentId)}/raw`;
   }
 
+  /**
+   * ISSUE-222 — presigned-URL upload (option 1 from the feature request): the
+   * caller PUTs the file bytes straight to S3 from wherever it has local disk
+   * access, instead of inlining them into an MCP tool call as base64Data.
+   * Mirrors the editor's presign→PUT→complete flow (`/attachments/presign`).
+   */
+  async presignAttachment(workspaceId, { filename, mimeType, size, nodeId } = {}) {
+    return this.request('/attachments/presign', {
+      method: 'POST',
+      body: { workspaceId, filename, mimeType, size, nodeId },
+    });
+  }
+
+  /** Marks a presigned attachment READY after the bytes have been PUT to S3. */
+  async completeAttachment(attachmentId) {
+    return this.request(`/attachments/${encodeURIComponent(attachmentId)}/complete`, { method: 'POST' });
+  }
+
   // ---- Spreadsheets ---------------------------------------------------------
 
   async listSpreadsheets(workspace) {
@@ -2043,3 +2061,22 @@ export class RootrClient {
   }
 
 }
+
+/**
+ * `![alt](url)` — 문서에 그대로 붙여 넣을 그림 한 줄.
+ *
+ * alt 자리에는 파일 이름이 그대로 들어가는데, 이름에 `]` 가 있으면 거기서 대괄호가 닫혀 그림이
+ * 아니라 깨진 글자가 되고(실측: 편집기에서 그림이 안 뜬다), `![가짜](http://…)` 같은 이름은
+ * 남의 주소의 그림을 문서에 끼워 넣는다. 역슬래시로 피하는 방법은 편집기의 해석기가 역슬래시를
+ * 글자 그대로 보여 줘서 쓰지 않는다 — 대괄호는 소괄호로, 역슬래시는 빗금으로, 줄바꿈·탭은
+ * 빈칸으로 바꾼다(alt 는 설명 글이라 뜻이 달라지지 않는다). 저장되는 파일 이름은 건드리지 않는다.
+ */
+export function imageMarkdown(alt, url) {
+  const safe = String(alt ?? '')
+    .replace(/\[/g, '(')
+    .replace(/\]/g, ')')
+    .replace(/\\/g, '/')
+    .replace(/[\r\n\t]+/g, ' ')
+    .trim();
+  return `![${safe}](${url})`;
+}

package/lib/credentials.js

@@ -15,6 +15,7 @@ import { t as tr } from './i18n.js';
 export function candidateClients(cfg = loadConfig()) {
   const out = [];
   const seen = new Set();
+  // (sessionKeys — 아래 rememberSessionKey 참고 — 는 맨 뒤에 붙는다.)
   if (cfg.apiKey) {
     seen.add(cfg.apiKey);
     out.push({ apiKey: cfg.apiKey, label: 'default', client: new RootrClient({ ...cfg, apiKey: cfg.apiKey }) });
@@ -24,9 +25,37 @@ export function candidateClients(cfg = loadConfig()) {
     seen.add(k.apiKey);
     out.push({ apiKey: k.apiKey, label: k.label || k.workspace || 'key', client: new RootrClient({ ...cfg, apiKey: k.apiKey }) });
   }
+  for (const apiKey of sessionKeys) {
+    if (seen.has(apiKey)) continue;
+    seen.add(apiKey);
+    out.push({ apiKey, label: 'session', ephemeral: true, client: new RootrClient({ ...cfg, apiKey }) });
+  }
   return out;
 }
 
+/**
+ * ISSUE-221 — keys this (long-running, stdio MCP) process was handed through
+ * the ROOTR_API_KEY env var and has since switched away from.
+ *
+ * rootr_use_workspace swaps process.env.ROOTR_API_KEY to the key that opens
+ * the target workspace. If the key it replaces lived only in the environment
+ * (the usual MCP client config: `env: { ROOTR_API_KEY, ROOTR_WORKSPACE }`),
+ * nothing else remembers it — so after A → B the server could no longer open
+ * A again ("none of the registered keys opens it"), although it was started
+ * with exactly that key. Keep such keys for the life of the process so the way
+ * back stays open.
+ *
+ * In memory only: an env-supplied secret is never written to
+ * ~/.rootr/config.json behind the user's back (rememberWorkspace skips
+ * `ephemeral` candidates). Never called on the hosted path — that one returns
+ * before any switch happens, so tenants cannot see each other's keys here.
+ */
+const sessionKeys = [];
+
+export function rememberSessionKey(apiKey) {
+  if (apiKey && !sessionKeys.includes(apiKey)) sessionKeys.push(apiKey);
+}
+
 /**
  * Collect every workspace the registered keys can see, and which of them a
  * key can actually open — listing is not a capability probe: a workspace key
@@ -155,22 +184,36 @@ 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.
+    // ISSUE-172/221 — when this (MCP server) process was started with
+    // ROOTR_API_KEY set, config.js makes that env var win over the DEFAULT key
+    // in ~/.rootr/config.json (see its ENV-WINS comment), now and after every
+    // restart. So for such a server the usual first remedy (`rootr config
+    // --api-key <PAT>`) never takes effect — the PAT has to go into the MCP
+    // server's own env config. Extra keys (`--add-key`) are different: the
+    // file is re-read on every call and they are tried as candidates, so that
+    // remedy works at once, without a restart. (Measured 2026-10-09 against a
+    // real server: the earlier note had both of these the wrong way round.)
     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).',
-        )
-      : '';
+    const remediesKo = envPinned
+      ? '조치 (둘 중 하나, 사용자가 직접):\n' +
+        '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → MCP 서버 설정의 ROOTR_API_KEY 환경변수를 그 키로 바꾸고 ' +
+        '서버를 재시작 (이 서버는 ROOTR_API_KEY 환경변수의 키를 쓰므로, `rootr config --api-key` 로 파일에 적은 키는 ' +
+        '재시작해도 쓰이지 않습니다)\n' +
+        `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\` ` +
+        '(재시작 없이, 등록한 뒤 바로 다시 전환하면 됩니다)'
+      : '조치 (둘 중 하나, 사용자가 직접):\n' +
+        '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
+        `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\``;
+    const remediesEn = envPinned
+      ? 'Fix (either one, done by you):\n' +
+        '1) Create an account key (PAT) under rootr.io > Settings > API keys → put it in the ROOTR_API_KEY env var of ' +
+        'the MCP server config and restart the server (this server uses the key from ROOTR_API_KEY, so a key written ' +
+        'with `rootr config --api-key` is not used, even after a restart)\n' +
+        `2) Create a key for that workspace → \`rootr config --add-key <key> --workspace ${target.id}\` ` +
+        '(no restart needed — switch again right after registering it)'
+      : '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}\``;
     return {
       error: tr(
         `"${target.name || target.id}" (${target.id}) 는 접근 권한 목록에는 있지만, 등록된 키로는 열 수 없습니다` +
@@ -178,19 +221,13 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
           (scoped
             ? '원인: 지금 등록된 키가 다른 워크스페이스 전용 키입니다 (워크스페이스 키는 자기 워크스페이스 밖에서 403).\n'
             : `원인: ${lastRejection ? lastRejection.message : '알 수 없음'}\n`) +
-          '조치 (둘 중 하나, 사용자가 직접):\n' +
-          '1) rootr.io > 설정 > API 키에서 계정 키(PAT)를 발급 → `rootr config --api-key <키>` (모든 워크스페이스에 통함)\n' +
-          `2) 그 워크스페이스용 키를 발급 → \`rootr config --add-key <키> --workspace ${target.id}\`` +
-          restartNote,
+          remediesKo,
         `"${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
             ? 'Cause: the registered key belongs to a different workspace (a workspace key gets 403 outside its own).\n'
             : `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}\`` +
-          restartNote,
+          remediesEn,
       ),
     };
   }
@@ -222,7 +259,9 @@ export async function resolveWorkspaceSwitch(wantedRaw, cfg = loadConfig()) {
 /** Persist the switch: remember the workspace and which key covers it. */
 export function rememberWorkspace({ workspace, candidate }, cfg = loadConfig()) {
   saveConfig({ workspace: workspace.id });
-  if (candidate && candidate.apiKey !== cfg.apiKey) {
+  // `ephemeral` = a key that only ever lived in this process's environment (see
+  // rememberSessionKey) — it stays out of the config file.
+  if (candidate && candidate.apiKey !== cfg.apiKey && !candidate.ephemeral) {
     upsertKey({ apiKey: candidate.apiKey, workspace: workspace.id, label: candidate.label });
   }
 }

package/lib/mcp-tools/attachments.js

@@ -14,18 +14,41 @@ import {
   localFileArg,
 } from './shared.js';
 import { resolveTarget, requireResolved } from '../resolve.js';
-import { RootrApiError } from '../client.js';
+import { RootrApiError, imageMarkdown } from '../client.js';
+
+// ISSUE-222 — 원격 커넥터에서 filePath 를 쓰려다 막힌 호출자가 막다른 길에 서지 않게, 거절하면서
+// 새 길(주소를 받아 직접 올리기)을 같이 알려 준다. 큰 파일은 base64Data 로도 못 싣는다.
+const PRESIGN_HINT =
+  '큰 파일은 rootr_create_upload_url 로 올리기 주소를 받아 파일 바이트를 그 주소에 직접 PUT 한 뒤 ' +
+  'rootr_complete_upload 를 부르세요 (파일 내용이 도구 호출에 실리지 않습니다).';
 
 /** 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 (isHostedMcp() && filePath) {
+    throw new RootrApiError('원격 커넥터에서는 filePath 를 쓸 수 없습니다.', {
+      hint:
+        'filePath 는 MCP 서버가 도는 기계의 파일을 가리킵니다. 원격 커넥터에서는 그 기계가 Rootr 서버라 ' +
+        `쓸 수 없습니다 — 작은 파일은 내용을 base64Data 로 보내세요. ${PRESIGN_HINT}`,
+    });
+  }
+  assertLocalFilesAllowed(filePath); // 위에서 걸렀지만 두 겹으로 둔다
   if (filePath) return readFileSync(filePath);
   if (base64Data) return Buffer.from(base64Data, 'base64');
-  if (isHostedMcp()) throw new RootrApiError('base64Data 가 필요합니다 (원격 커넥터에서는 filePath 를 쓸 수 없습니다).');
+  if (isHostedMcp()) {
+    throw new RootrApiError('base64Data 가 필요합니다 (원격 커넥터에서는 filePath 를 쓸 수 없습니다).', {
+      hint: PRESIGN_HINT,
+    });
+  }
   throw new RootrApiError('filePath 또는 base64Data 중 하나가 필요합니다.');
 }
 
+/** 첨부 id 모양(UUID). 주소 칸에 들어가는 값이라 다른 모양은 서버에 보내지 않는다. */
+const ATTACHMENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** 빈 값·공백뿐인 값은 받지 않는다(값 자체는 건드리지 않는다 — 앞뒤 공백도 이름의 일부일 수 있다). */
+const nonBlank = (what) => [(v) => typeof v === 'string' && v.trim().length > 0, `${what} must not be empty`];
+
 // 등록 시점(원격이면 요청마다)에 만든다 — 원격 커넥터에서는 filePath 칸이 스키마에서 빠진다.
 const buildUploadInputSchema = () => ({
   filename: z.string().describe('File name to store, e.g. "screenshot.png"'),
@@ -57,7 +80,9 @@ export function registerAttachmentTools(server) {
         '{ id, url, markdown, filename, mimeType, size } — `url` is the public, unauthenticated ' +
         '/attachments/{id}/raw link (renders in <img> tags and on published /p/ documents without login), and ' +
         '`markdown` is ready to paste into a document body (![alt](url)). For the common case of inserting an ' +
-        'image straight into a document, prefer rootr_attach_image_to_document instead.',
+        'image straight into a document, prefer rootr_attach_image_to_document instead. For a large file (or ' +
+        'over the remote connector, where filePath is not available), use rootr_create_upload_url → PUT → ' +
+        'rootr_complete_upload instead of inlining the bytes as base64Data.',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: uploadInputSchema,
     },
@@ -75,7 +100,7 @@ export function registerAttachmentTools(server) {
         return jsonResult({
           id,
           url,
-          markdown: `![${filename}](${url})`,
+          markdown: imageMarkdown(filename, url),
           filename,
           mimeType,
           size: data.length,
@@ -120,7 +145,7 @@ export function registerAttachmentTools(server) {
         const data = readAttachmentBytes({ filePath, base64Data });
         const { id } = await client.uploadAttachment(ws, { filename, mimeType, nodeId, data });
         const url = client.attachmentRawUrl(id);
-        const markdown = `![${alt || filename}](${url})`;
+        const markdown = imageMarkdown(alt || filename, url);
         const result = await client.appendDocument(nodeId, { content: markdown, underHeading });
         return jsonResult({ id, url, markdown, appended: true, etag: result.etag });
       } catch (err) {
@@ -128,4 +153,97 @@ export function registerAttachmentTools(server) {
       }
     },
   );
+
+  // ISSUE-222 — rootr_upload_attachment/rootr_attach_image_to_document require
+  // the full file as base64Data over the remote connector (it can't read
+  // filePath), which breaks down for larger images. This gives the caller a
+  // short-lived presigned S3 URL instead: PUT the bytes there directly (works
+  // from anywhere with local disk access, no MCP message-size cost), then call
+  // rootr_complete_upload with the returned id.
+  server.registerTool(
+    'rootr_create_upload_url',
+    {
+      title: 'Get a presigned URL to upload a file/image as a Rootr attachment',
+      description:
+        'Get a short-lived presigned URL for uploading a file (screenshot, photo, diagram export, ...) to the ' +
+        'Rootr (루터) workspace as an attachment. PUT the raw file bytes to `uploadUrl` yourself (Content-Type ' +
+        'must match the `mimeType` you gave here) — this is the preferred path for larger files, since no file ' +
+        'bytes travel through this tool call. After the PUT succeeds, call rootr_complete_upload with the ' +
+        'returned `id` to mark the attachment ready and get its `url`/`markdown`.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        filename: z.string().refine(...nonBlank('filename')).describe('File name to store, e.g. "diagram.png"'),
+        mimeType: z.string().refine(...nonBlank('mimeType')).describe('MIME type, e.g. "image/png"'),
+        size: z
+          .number()
+          .int()
+          .positive()
+          .describe('File size in bytes (max 75MB). The stored size is whatever you actually PUT to uploadUrl.'),
+        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'),
+      },
+    },
+    async ({ filename, mimeType, size, nodeId, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        nodeId = await resolveOptionalNodeId(client, nodeId);
+        const { id, uploadUrl, expiresIn } = await client.presignAttachment(ws, { filename, mimeType, size, nodeId });
+        return jsonResult({
+          id,
+          uploadUrl,
+          expiresIn,
+          instructions: `PUT the raw file bytes to uploadUrl with header Content-Type: ${mimeType}, then call rootr_complete_upload with id "${id}".`,
+        });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_complete_upload',
+    {
+      title: 'Finish a presigned attachment upload',
+      description:
+        'Call this after PUTting file bytes to the `uploadUrl` from rootr_create_upload_url. Verifies the ' +
+        'upload landed in storage and marks the attachment READY. Returns { id, url, markdown } — `url` is the ' +
+        'public /attachments/{id}/raw link and `markdown` is ready to paste into a document body.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        // id 는 주소의 한 칸으로 들어간다. `../workspaces` 같은 값은 인코딩해 보내도 운영의 프록시가
+        // 풀어서 다른 길(/v1/workspaces/complete)로 보내고, 호출한 쪽은 "Cannot POST …" 라는 날것의
+        // 라우팅 오류를 받는다(운영 실측 2026-10-09). 받은 id 모양이 아니면 보내기 전에 거절한다.
+        id: z
+          .string()
+          .refine(...nonBlank('id'))
+          .refine(
+            (v) => typeof v !== 'string' || v.trim().length === 0 || ATTACHMENT_ID.test(v),
+            'id must be the attachment id returned by rootr_create_upload_url (a UUID) — not a path, URL or filename',
+          )
+          .describe('The attachment id returned by rootr_create_upload_url'),
+        filename: z.string().optional().describe('Filename to use in the markdown alt text (defaults to the one given at presign time)'),
+        workspace: z.string().optional().describe('Workspace id; defaults to ROOTR_WORKSPACE/config'),
+      },
+    },
+    async ({ id, filename, workspace }) => {
+      try {
+        const ws = requireWorkspace(workspace);
+        const client = makeClient(ws);
+        const attachment = await client.completeAttachment(id);
+        const url = client.attachmentRawUrl(id);
+        const name = filename || attachment.filename;
+        return jsonResult({
+          id,
+          url,
+          markdown: imageMarkdown(name, url),
+          filename: name,
+          mimeType: attachment.mimeType,
+          size: attachment.size,
+        });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
 }

package/lib/mcp-tools/workspaces.js

@@ -3,8 +3,27 @@ import { z } from 'zod';
 import { textResult, jsonResult, errorResult, makeClient, requireWorkspace } from './shared.js';
 import { loadConfig } from '../config.js';
 import { currentClientOverride } from '../context.js';
-import { candidateClients, rememberWorkspace, resolveWorkspaceSwitch, surveyWorkspaces } from '../credentials.js';
+import {
+  candidateClients,
+  rememberSessionKey,
+  rememberWorkspace,
+  resolveWorkspaceSwitch,
+  surveyWorkspaces,
+} from '../credentials.js';
 import { parseRootrUrl } from '../resolve.js';
+import { t as tr } from '../i18n.js';
+
+/**
+ * ISSUE-221 — the workspace this server process was pinned to at launch via the
+ * ROOTR_WORKSPACE env var ('' when it was not). Read once, before any switch
+ * rewrites process.env: a switch on an env-pinned server only lasts as long as
+ * the process does (the MCP client passes the same env again on every restart
+ * or reconnect, and env deliberately wins over the config file), so the switch
+ * reply has to say where the server will be after a restart — otherwise the
+ * next write after a reconnect lands in the pinned workspace while the agent
+ * still believes it is in the one it switched to.
+ */
+const LAUNCH_WORKSPACE = process.env.ROOTR_WORKSPACE || '';
 
 /**
  * Scaffold `tree` argument schema. Declared as an ARRAY of node objects so MCP
@@ -49,6 +68,8 @@ export function registerWorkspaceTools(server) {
         'reconfiguration, no restart. With an account key (PAT) you can switch to any workspace you belong ' +
         'to; if separate workspace keys are configured, the one that covers the target is selected and ' +
         'remembered automatically. Call rootr_workspaces first if you need to see what is available. ' +
+        'If the server was started with the ROOTR_WORKSPACE env var, the switch lasts until the server ' +
+        'restarts (the reply says so) — after a restart/reconnect, check rootr_workspaces again. ' +
         '(A hosted/remote connector is bound to a single workspace at consent time and cannot switch.)',
       annotations: { readOnlyHint: false, destructiveHint: false },
       inputSchema: {
@@ -91,6 +112,9 @@ export function registerWorkspaceTools(server) {
         // process, same request loop) picks up the switch immediately.
         if (process.env.ROOTR_WORKSPACE) process.env.ROOTR_WORKSPACE = match.workspace.id;
         if (process.env.ROOTR_API_KEY && match.candidate && match.candidate.apiKey !== process.env.ROOTR_API_KEY) {
+          // ISSUE-221 — the key being replaced may exist nowhere but in this
+          // process's environment; keep it so switching back still works.
+          rememberSessionKey(process.env.ROOTR_API_KEY);
           process.env.ROOTR_API_KEY = match.candidate.apiKey;
         }
         // Verify the switch actually took before reporting success — never
@@ -107,7 +131,23 @@ export function registerWorkspaceTools(server) {
           );
         }
         const name = match.workspace.name || match.workspace.slug || '';
-        return textResult(`활성 워크스페이스를 "${name}" (${match.workspace.id}) 로 바꿨습니다. 이후 도구 호출은 여기에 적용됩니다.`);
+        // ISSUE-221 — say how long the switch lasts when the server is env-pinned.
+        const pinnedNote =
+          LAUNCH_WORKSPACE && LAUNCH_WORKSPACE !== match.workspace.id
+            ? tr(
+                `\n주의: 이 MCP 서버는 ROOTR_WORKSPACE 환경변수(${LAUNCH_WORKSPACE})로 고정되어 시작됐습니다. 이 전환은 서버가 ` +
+                  `켜져 있는 동안만 유효하고, 서버가 재시작(재연결)되면 ${LAUNCH_WORKSPACE} 로 돌아갑니다 — 재시작 뒤에는 쓰기 전에 ` +
+                  'rootr_workspaces 로 현재 워크스페이스를 다시 확인하세요. 계속 이 워크스페이스를 쓰려면 MCP 서버 설정의 ' +
+                  `ROOTR_WORKSPACE 를 ${match.workspace.id} 로 바꾸거나 지우세요 (사용자가 직접).`,
+                `\nNote: this MCP server was started pinned to ROOTR_WORKSPACE=${LAUNCH_WORKSPACE}. The switch lasts only while ` +
+                  `the server keeps running; after a restart/reconnect it is back on ${LAUNCH_WORKSPACE} — check rootr_workspaces ` +
+                  'again before writing. To stay on this workspace, change (or remove) ROOTR_WORKSPACE in the MCP server ' +
+                  `config to ${match.workspace.id} (a step for the user).`,
+              )
+            : '';
+        return textResult(
+          `활성 워크스페이스를 "${name}" (${match.workspace.id}) 로 바꿨습니다. 이후 도구 호출은 여기에 적용됩니다.${pinnedNote}`,
+        );
       } catch (err) {
         return errorResult(err);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rootr-cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Official Rootr CLI + MCP server — read, write, edit and search Rootr documents from the shell or from an AI agent.",
   "type": "module",
   "bin": {