yungle-cli 0.1.1 → 0.1.2

package/README.md

@@ -27,6 +27,8 @@ starting over.
 | `yungle push <paths…> --collection <id>` | Upload into a collection |
 | `yungle ls transfers\|collections\|contacts` | List things |
 | `yungle rm transfer <id>` | Revoke a transfer |
+| `yungle mcp install` | Let an AI assistant read your Yungle |
+| `yungle mcp status` | Show where that is installed |
 
 `--json` on any command prints a machine-readable object on stdout; progress
 goes to stderr, so `yungle send … --json \| jq` works.
@@ -34,6 +36,36 @@ goes to stderr, so `yungle send … --json \| jq` works.
 Folders keep their structure. Hidden files are skipped when walking a directory
 and kept when named directly.
 
+## Letting an assistant read your Yungle
+
+```bash
+yungle mcp install
+```
+
+Writes the [Yungle MCP server](https://www.npmjs.com/package/yungle-mcp) into
+whichever clients you have — Claude Desktop, Claude Code, Cursor, Windsurf —
+so you can ask *"what did I send last week?"* or *"did the client download it
+yet?"* instead of opening the dashboard. Restart the client afterwards; they
+read their MCP config at startup.
+
+`--dry-run` shows what would change and writes nothing. `--client <id>` targets
+one. Re-running is safe: it reports `already current` when nothing needs doing,
+and updates the entry if your key has changed.
+
+**It refuses a key that can write.** The MCP server has no tool that sends,
+invites, revokes or deletes, so a write scope grants an assistant nothing it can
+use — while putting a credential that *could* change your account into a file an
+assistant reads. Create a read-only key at
+[yungle.co/dashboard/settings/api](https://yungle.co/dashboard/settings/api);
+reading the API is free on any plan.
+
+Two things worth knowing. Your key ends up in that client's config file in plain
+text — that is how stdio MCP servers receive credentials, and it is why the
+read-only rule above is enforced rather than suggested. And a config file that
+does not parse is **refused, never overwritten**: it holds every other MCP server
+you have set up, and a trailing comma is not a reason to replace it. The previous
+contents are copied to `<config>.yungle-bak` before any change.
+
 ## Resuming
 
 State lives in `~/.cache/yungle/`. A session is keyed by the *local files* —

package/dist/yungle.mjs

@@ -204,7 +204,13 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "folder",
   "out",
   "url",
-  "key"
+  "key",
+  // `yungle mcp install --client cursor` silently installed into EVERY client
+  // before this was added: the flag parsed as a boolean, `cursor` became a stray
+  // positional, and the filter was never applied. The help text promised
+  // `--client <id>`, so the command line was correct and the parser was not.
+  // `helpFlagsAreParsed` in args.test.ts now derives this from HELP.
+  "client"
 ]);
 function parseArgs(argv) {
   const [command = "help", ...rest] = argv;
@@ -417,6 +423,82 @@ function formatBytes(bytes) {
   return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
 }
 
+// src/mcp-install.ts
+import { homedir as homedir2, platform } from "node:os";
+import { join as join3 } from "node:path";
+function mcpClients(os = platform(), home = homedir2(), env = process.env) {
+  const appData = env.APPDATA ?? join3(home, "AppData", "Roaming");
+  return [
+    {
+      id: "claude-desktop",
+      label: "Claude Desktop",
+      serversKey: "mcpServers",
+      configPath: os === "darwin" ? join3(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : os === "win32" ? join3(appData, "Claude", "claude_desktop_config.json") : (
+        // No Linux build of Claude Desktop exists, so there is nothing to write.
+        null
+      )
+    },
+    {
+      id: "claude-code",
+      label: "Claude Code",
+      serversKey: "mcpServers",
+      configPath: join3(home, ".claude.json"),
+      viaCli: {
+        bin: "claude",
+        // `-s user` so it applies everywhere, not just the directory the install
+        // happened to be run from — the default scope is `local`, which would
+        // silently give a per-project install nobody asked for.
+        args: (name, json) => ["mcp", "add-json", "-s", "user", name, json]
+      }
+    },
+    {
+      id: "cursor",
+      label: "Cursor",
+      serversKey: "mcpServers",
+      configPath: join3(home, ".cursor", "mcp.json")
+    },
+    {
+      id: "windsurf",
+      label: "Windsurf",
+      serversKey: "mcpServers",
+      configPath: join3(home, ".codeium", "windsurf", "mcp_config.json")
+    }
+  ];
+}
+function serverEntry(opts) {
+  const env = { YUNGLE_API_KEY: opts.apiKey };
+  if (opts.baseUrl) env.YUNGLE_API_URL = opts.baseUrl;
+  return { command: "npx", args: ["-y", "yungle-mcp"], env };
+}
+function mergeServerEntry(existing, serversKey, name, entry) {
+  const root = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  const servers = root[serversKey];
+  const nextServers = servers && typeof servers === "object" && !Array.isArray(servers) ? { ...servers } : {};
+  const before = nextServers[name];
+  if (before !== void 0 && deepEqual(before, entry)) return { kind: "unchanged" };
+  nextServers[name] = entry;
+  root[serversKey] = nextServers;
+  return before === void 0 ? { kind: "added", config: root } : { kind: "updated", config: root, previous: before };
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a !== "object") return false;
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every(
+    (k) => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k])
+  );
+}
+function writeScopes(scopes) {
+  return scopes.filter((s) => s.endsWith(":write"));
+}
+
 // src/upload.ts
 import { createReadStream } from "node:fs";
 import { stat as stat2 } from "node:fs/promises";
@@ -517,6 +599,10 @@ var HELP = `yungle \u2014 send and sync files with Yungle
     --folder <id>         target folder
   yungle ls transfers|collections|contacts
   yungle rm transfer <id>                 revoke a transfer
+  yungle mcp install                      let an AI assistant read your Yungle
+    --client <id>         claude-desktop | claude-code | cursor | windsurf
+    --dry-run             show what would change, write nothing
+  yungle mcp status                       show where it is installed
 
 Global flags
   --json                  machine-readable output
@@ -553,6 +639,8 @@ async function main(argv) {
         return await list(positionals, flags, json);
       case "rm":
         return await remove(positionals, flags, json);
+      case "mcp":
+        return await mcp(positionals, flags, json);
       default:
         process.stderr.write(`Unknown command: ${command}
 
@@ -857,7 +945,186 @@ function fail(err, json) {
 `);
   return 1;
 }
+async function mcp(positionals, flags, json) {
+  const sub = positionals[0] ?? "install";
+  if (sub !== "install" && sub !== "status") {
+    process.stderr.write("Usage: yungle mcp install | yungle mcp status\n");
+    return 2;
+  }
+  const { readFile: readFile2, writeFile: writeFile2, mkdir: mkdir2, copyFile } = await import("node:fs/promises");
+  const { dirname: dirname2 } = await import("node:path");
+  const all = mcpClients();
+  const only = stringFlag(flags.client);
+  if (only && !all.some((c) => c.id === only)) {
+    process.stderr.write(
+      `Unknown client: ${only}. Known: ${all.map((c) => c.id).join(", ")}
+`
+    );
+    return 2;
+  }
+  const targets = only ? all.filter((c) => c.id === only) : all;
+  if (sub === "status") {
+    const rows = [];
+    for (const c of targets) {
+      let installed = false;
+      if (c.configPath) {
+        try {
+          const doc = JSON.parse(await readFile2(c.configPath, "utf8"));
+          const servers = doc[c.serversKey];
+          installed = !!servers && typeof servers === "object" && "yungle" in servers;
+        } catch {
+          installed = false;
+        }
+      }
+      rows.push({ client: c.id, path: c.configPath, installed });
+    }
+    return out(
+      json,
+      { clients: rows },
+      rows.map(
+        (r) => `${pad(r.client, 16)} ${r.installed ? "installed" : r.path ? "not installed" : "n/a on this platform"}`
+      ).join("\n")
+    );
+  }
+  const resolved = await resolveKey();
+  if (!resolved) {
+    process.stderr.write(
+      `No API key. Run \`yungle auth login\` first, or set YUNGLE_API_KEY.
+Get a key at https://yungle.co/dashboard/settings/api \u2014 reading is free on any plan.
+`
+    );
+    return 1;
+  }
+  let scopes;
+  try {
+    const me = await client(flags).me();
+    scopes = me.key.scopes ?? [];
+  } catch (err) {
+    process.stderr.write(
+      `Could not check what this key is allowed to do: ${err.message}
+Not installing \u2014 an agent should never get a key of unknown scope.
+`
+    );
+    return 1;
+  }
+  const writes = writeScopes(scopes);
+  if (writes.length > 0) {
+    process.stderr.write(
+      `This key can write (${writes.join(", ")}).
+
+The MCP server has no tool that sends, invites, revokes or deletes, so a
+write scope grants an assistant nothing it can use \u2014 but it does put a
+credential that can change your account into a config file an assistant
+reads. Create a read-only key instead:
+
+  https://yungle.co/dashboard/settings/api
+
+then \`yungle auth login\` with it and re-run this.
+`
+    );
+    return 1;
+  }
+  const entry = serverEntry({ apiKey: resolved.apiKey, baseUrl: resolved.baseUrl });
+  const dryRun = flags["dry-run"] === true;
+  const results = [];
+  for (const c of targets) {
+    const r = await installInto(c, entry, { dryRun, readFile: readFile2, writeFile: writeFile2, mkdir: mkdir2, copyFile, dirname: dirname2 });
+    results.push({ client: c.id, ...r });
+  }
+  const changed = results.filter((r) => r.action === "added" || r.action === "updated");
+  const lines = results.map((r) => `${pad(r.client, 16)} ${r.action}${r.detail ? ` \u2014 ${r.detail}` : ""}`);
+  if (changed.length > 0 && !dryRun) {
+    lines.push("");
+    lines.push("Restart the client(s) above to pick it up.");
+    lines.push('Then ask: "what did I send recently?" or "did the client download it?"');
+    lines.push("");
+    lines.push(`Your API key is now also in ${changed.length === 1 ? "that config file" : "those config files"}, in plain text.`);
+  }
+  if (changed.length === 0 && !dryRun) {
+    lines.push("");
+    lines.push("Nothing to do. `yungle mcp status` shows where it is installed.");
+  }
+  return out(json, { installed: results, dryRun }, lines.join("\n"));
+}
+async function installInto(c, entry, io) {
+  if (!c.configPath) return { action: "skipped", detail: "not available on this platform" };
+  if (c.viaCli) {
+    const { spawnSync } = await import("node:child_process");
+    const probe = spawnSync(c.viaCli.bin, ["--version"], { stdio: "ignore", shell: false });
+    if (probe.error) return { action: "skipped", detail: `${c.viaCli.bin} not installed` };
+    if (io.dryRun) {
+      return { action: "would run", detail: `${c.viaCli.bin} mcp add-json -s user yungle \u2026` };
+    }
+    const existed = spawnSync(c.viaCli.bin, ["mcp", "get", "yungle"], { stdio: "ignore", shell: false }).status === 0;
+    if (existed) {
+      spawnSync(c.viaCli.bin, ["mcp", "remove", "-s", "user", "yungle"], {
+        stdio: "ignore",
+        shell: false
+      });
+    }
+    const res = spawnSync(c.viaCli.bin, c.viaCli.args("yungle", JSON.stringify(entry)), {
+      stdio: "pipe",
+      shell: false,
+      encoding: "utf8"
+    });
+    if (res.status !== 0) {
+      const why = (res.stderr || res.stdout || "").trim().split("\n")[0] || `exit ${res.status}`;
+      return { action: "failed", detail: why };
+    }
+    return {
+      action: existed ? "updated" : "added",
+      detail: `via ${c.viaCli.bin} mcp add-json`
+    };
+  }
+  let raw = null;
+  try {
+    raw = await io.readFile(c.configPath, "utf8");
+  } catch {
+    let dirExists = true;
+    try {
+      await io.readFile(io.dirname(c.configPath), "utf8");
+    } catch (err) {
+      dirExists = err.code === "EISDIR";
+    }
+    if (!dirExists) return { action: "skipped", detail: "not installed" };
+  }
+  let existing = {};
+  if (raw !== null && raw.trim() !== "") {
+    try {
+      existing = JSON.parse(raw);
+    } catch {
+      return {
+        action: "refused",
+        path: c.configPath,
+        detail: `${c.configPath} is not valid JSON \u2014 fix or move it, nothing was written`
+      };
+    }
+    if (existing === null || typeof existing !== "object" || Array.isArray(existing)) {
+      return {
+        action: "refused",
+        path: c.configPath,
+        detail: `${c.configPath} is not a JSON object \u2014 nothing was written`
+      };
+    }
+  }
+  const merged = mergeServerEntry(existing, c.serversKey, "yungle", entry);
+  if (merged.kind === "unchanged") return { action: "already current", path: c.configPath };
+  if (io.dryRun) {
+    return { action: `would be ${merged.kind}`, path: c.configPath, detail: c.configPath };
+  }
+  if (raw !== null) {
+    try {
+      await io.copyFile(c.configPath, `${c.configPath}.yungle-bak`);
+    } catch {
+    }
+  }
+  await io.mkdir(io.dirname(c.configPath), { recursive: true });
+  await io.writeFile(c.configPath, `${JSON.stringify(merged.config, null, 2)}
+`, { mode: 384 });
+  return { action: merged.kind, path: c.configPath, detail: c.configPath };
+}
 export {
+  HELP,
   loadCredentials,
   main
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yungle-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "Send and sync files with Yungle from the command line.",
   "bin": {