@thothica/docs-cli 1.0.0 → 1.1.0

package/README.md

@@ -43,15 +43,20 @@ thd whoami                                   Show the signed-in account
 
 thd doc ls [-q QUERY] [--shared] [--json]    List / search documents
 thd doc new "Title" [--md FILE|-]            Create (markdown body, or --template ID)
+thd doc upload FILE.docx [--folder id|name]  Upload an existing .docx (optional --title)
 thd doc cat ID [--text]                      Print content (markdown by default)
 thd doc get ID [-o FILE]                     Download the real .docx
-thd doc set ID --md FILE|-                   Replace content from markdown
+thd doc set ID --md FILE|- [--force]         Replace content from markdown
+thd doc mv ID (--folder id|name | --root)    Move a document into a folder
 thd doc rm ID [--permanent]                  Trash (or delete) a document
 
+thd folder ls                                List your folders
+thd folder new "Name" [--parent id|name]     Create a folder
 thd comment ls ID                            List comments inside the document
 thd comment add ID "text" [--anchor "..."]   Add a comment (optional --reply-to ID)
 
 thd templates                                List document templates
+thd mcp-config [--client NAME]               Print connector config for MCP clients
 thd open [ID]                                Open the app (or a document) in the browser
 thd mcp                                       Run the MCP server (for AI agents) over stdio
 ```

package/bin/thd.mjs

@@ -3,6 +3,7 @@
 // edit, and comment on documents from the terminal or an AI agent. Ships an MCP
 // server (`thd mcp`). Zero dependencies; Node >= 18.
 import { readFileSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
 import {
   DEFAULT_ORIGIN,
   CLI_VERSION,
@@ -42,6 +43,7 @@ const BOOLEANS = new Set([
   "markdown",
   "text",
   "force",
+  "root",
   "no-open",
   "help",
   "version",
@@ -120,6 +122,22 @@ function readInput(spec) {
   return readFileSync(spec, "utf8");
 }
 
+const DOCX_MIME =
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+
+// Resolve a --folder value that may be a folder id or a folder name.
+async function resolveFolder(origin, token, value) {
+  const res = await call(origin, token, "GET", "/folders");
+  const folders = res.folders || [];
+  const byId = folders.find((f) => f.id === value);
+  if (byId) return byId.id;
+  const byName = folders.find(
+    (f) => f.name.toLowerCase() === String(value).toLowerCase()
+  );
+  if (byName) return byName.id;
+  die(`folder not found: "${value}". See 'thd folder ls', or 'thd folder new "${value}"'.`);
+}
+
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -237,6 +255,35 @@ async function cmdDoc(flags, sub, rest) {
       out(green("✓ Saved ") + dim(`version ${res.version}`));
       return;
     }
+    case "upload": {
+      const file = rest[0];
+      if (!file) die("usage: thd doc upload FILE.docx [--folder id|name] [--title T]");
+      const buf = readFileSync(file);
+      const fd = new FormData();
+      fd.set("file", new Blob([buf], { type: DOCX_MIME }), basename(file));
+      if (flags.title) fd.set("title", flags.title);
+      if (flags.folder) fd.set("folderId", await resolveFolder(origin, token, flags.folder));
+      const doc = await call(origin, token, "POST", "/documents", { body: fd });
+      if (flags.json) return out(JSON.stringify(doc, null, 2));
+      out(green("✓ Uploaded ") + bold(doc.title));
+      out(`  id:  ${doc.id}`);
+      out(`  url: ${cyan(`${origin}/doc/${doc.id}`)}`);
+      return;
+    }
+    case "mv":
+    case "move": {
+      const id = rest[0];
+      if (!id) die("usage: thd doc mv ID (--folder id|name | --root)");
+      let folderId;
+      if (flags.root) folderId = null;
+      else if (flags.folder) folderId = await resolveFolder(origin, token, flags.folder);
+      else die("specify a destination: --folder id|name, or --root");
+      await call(origin, token, "PATCH", `/documents/${encodeURIComponent(id)}`, {
+        body: { folderId },
+      });
+      out(green("✓ Moved ") + dim(folderId ? `to folder ${folderId}` : "to root"));
+      return;
+    }
     case "rm":
     case "delete": {
       const id = rest[0];
@@ -292,6 +339,61 @@ async function cmdTemplates(flags) {
   }
 }
 
+async function cmdFolder(flags, sub, rest) {
+  const { origin, token } = requireToken(flags);
+  if (!sub || sub === "ls" || sub === "list") {
+    const res = await call(origin, token, "GET", "/folders");
+    if (flags.json) return out(JSON.stringify(res.folders, null, 2));
+    const folders = res.folders || [];
+    if (!folders.length) return out(dim("No folders."));
+    for (const f of folders)
+      out(`${bold(f.id)}  ${f.name}${f.parentId ? dim(`  (in ${f.parentId})`) : ""}`);
+    return;
+  }
+  if (sub === "new" || sub === "create") {
+    const name = rest[0];
+    if (!name) die('usage: thd folder new "Name" [--parent id|name]');
+    const body = { name };
+    if (flags.parent) body.parentId = await resolveFolder(origin, token, flags.parent);
+    const f = await call(origin, token, "POST", "/folders", { body });
+    out(green("✓ Created folder ") + bold(f.name) + dim(` (${f.id})`));
+    return;
+  }
+  die('usage: thd folder ls | new "Name"');
+}
+
+function cmdMcpConfig(flags) {
+  const local = { command: "thd", args: ["mcp"] };
+  const blocks = {
+    "claude-code": "claude mcp add thothica-docs -- thd mcp",
+    "claude-desktop": JSON.stringify({ mcpServers: { "thothica-docs": local } }, null, 2),
+    cursor: JSON.stringify({ mcpServers: { "thothica-docs": local } }, null, 2),
+    codex: '[mcp_servers.thothica-docs]\ncommand = "thd"\nargs = ["mcp"]',
+    opencode: JSON.stringify(
+      { mcp: { "thothica-docs": { type: "local", command: ["thd", "mcp"], enabled: true } } },
+      null,
+      2
+    ),
+  };
+  const client = (flags.client || "").toLowerCase().replace(/\s+/g, "-");
+  if (client && blocks[client]) return out(blocks[client]);
+  const show = (label, hint, block) => {
+    out(bold(label) + (hint ? dim("  " + hint) : ""));
+    out(block);
+    out("");
+  };
+  show("Claude Code", "", blocks["claude-code"]);
+  show(
+    "Claude Desktop",
+    "~/Library/Application Support/Claude/claude_desktop_config.json (macOS)",
+    blocks["claude-desktop"]
+  );
+  show("Cursor", ".cursor/mcp.json", blocks.cursor);
+  show("Codex", "~/.codex/config.toml", blocks.codex);
+  show("opencode", "opencode.json", blocks.opencode);
+  out(dim("Run `thd login` once so the server has a credential. For CI, set THOTHICA_DOCS_TOKEN."));
+}
+
 function cmdOpen(flags, rest) {
   const origin = resolveOrigin(flags.origin);
   const url = rest[0] ? `${origin}/doc/${rest[0]}` : origin;
@@ -310,17 +412,22 @@ ${bold("Access")}
 ${bold("Documents")}
   thd doc ls [-q QUERY] [--shared] [--json]    List / search documents
   thd doc new "Title" [--md FILE|-]            Create (markdown body, or --template ID)
+  thd doc upload FILE.docx [--folder id|name]  Upload an existing .docx (optional --title)
   thd doc cat ID [--text]                      Print content (markdown by default)
   thd doc get ID [-o FILE]                     Download the real .docx
   thd doc set ID --md FILE|- [--force]         Replace content from markdown
+  thd doc mv ID (--folder id|name | --root)    Move a document into a folder
   thd doc rm ID [--permanent]                  Trash (or delete) a document
 
-${bold("Comments")}
+${bold("Folders & comments")}
+  thd folder ls                                List your folders
+  thd folder new "Name" [--parent id|name]     Create a folder
   thd comment ls ID                            List comments inside the document
   thd comment add ID "text" [--anchor "..."]   Add a comment (optional --reply-to ID)
 
 ${bold("More")}
   thd templates                                List document templates
+  thd mcp-config [--client NAME]               Print connector config (Claude Desktop, Cursor, ...)
   thd open [ID]                                Open the app (or a document) in the browser
   thd mcp                                       Run the MCP server (for AI agents) over stdio
 
@@ -357,8 +464,13 @@ async function main() {
       case "comment":
       case "comments":
         return await cmdComment(flags, sub, rest);
+      case "folder":
+      case "folders":
+        return await cmdFolder(flags, sub, rest);
       case "templates":
         return await cmdTemplates(flags);
+      case "mcp-config":
+        return cmdMcpConfig(flags);
       case "open":
         return cmdOpen(flags, parsed._.slice(1));
       case "mcp":

package/lib/core.mjs

@@ -17,7 +17,7 @@ import { join } from "node:path";
 import { randomBytes, scryptSync, createCipheriv, createDecipheriv } from "node:crypto";
 
 export const DEFAULT_ORIGIN = "https://docs.thothica.com";
-export const CLI_VERSION = "1.0.0";
+export const CLI_VERSION = "1.1.0";
 const SERVICE = "thothica-docs";
 
 // ---------------------------------------------------------------------------
@@ -334,10 +334,18 @@ export async function api(origin, token, method, path, opts = {}) {
   const headers = { ...(opts.headers || {}) };
   if (token) headers["Authorization"] = `Bearer ${token}`;
   let body = opts.body;
-  if (body != null && typeof body === "object" && !(body instanceof Uint8Array) && !Buffer.isBuffer(body)) {
+  const isForm = typeof FormData !== "undefined" && body instanceof FormData;
+  if (
+    body != null &&
+    typeof body === "object" &&
+    !isForm &&
+    !(body instanceof Uint8Array) &&
+    !Buffer.isBuffer(body)
+  ) {
     headers["Content-Type"] = headers["Content-Type"] || "application/json";
     body = JSON.stringify(body);
   }
+  // FormData sets its own multipart Content-Type (with boundary); leave it alone.
   const res = await fetch(url, { method, headers, body });
   if (opts.raw) return res;
   const text = await res.text();

package/lib/mcp.mjs

@@ -245,6 +245,28 @@ const TOOLS = [
       );
     },
   },
+  {
+    name: "move_document",
+    description:
+      "Move a document into a folder, or to the root. Pass folderId (from list_folders/create_folder), or set toRoot:true.",
+    inputSchema: {
+      type: "object",
+      required: ["id"],
+      properties: {
+        id: { type: "string" },
+        folderId: { type: "string" },
+        toRoot: { type: "boolean" },
+      },
+    },
+    async handler(args, ctx) {
+      const folderId = args.toRoot ? null : args.folderId;
+      if (folderId === undefined) return fail("Provide folderId, or set toRoot:true.");
+      const doc = await ctx.call("PATCH", `/documents/${encodeURIComponent(args.id)}`, {
+        folderId,
+      });
+      return ok(`Moved "${doc.title}" ${folderId ? `into folder ${folderId}` : "to root"}.`);
+    },
+  },
   {
     name: "list_folders",
     description: "List the user's folders.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thothica/docs-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Command-line tool and MCP server for Thothica Docs: let any AI agent read, create, edit, and comment on native .docx documents.",
   "type": "module",
   "bin": {