@tiny-fish/cli 0.12.0 → 0.12.1-next.137

package/dist/commands/connect.d.ts

@@ -1,8 +1,9 @@
 import { Command } from "commander";
+export declare const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 export declare const UPGRADE_HINT = "Run `tinyfish upgrade` any time to update the CLI and skill.";
 export declare const DEFAULT_ONBOARDING_PROMPT: string;
 export declare const OPENCLAW_ONBOARDING_PROMPT: string;
-export type AgentClient = "claude-code" | "codex" | "hermes" | "openclaw";
+export type AgentClient = "claude-code" | "codex" | "cursor" | "hermes" | "openclaw";
 /** Ctrl+C/SIGTERM killed a setup child — abandonment, not error. */
 export declare class ConnectInterruptedError extends Error {
 }
@@ -36,5 +37,10 @@ export declare function connectOpenClaw(options: {
     launch: boolean;
     installCli?: boolean;
 }): Promise<void>;
+/** Writes mcp.json directly — no `cursor mcp add` exists. */
+export declare function connectCursor(options: {
+    apiKey?: string;
+    mcpUrl: string;
+}): Promise<void>;
 export declare function launchAgent(client: AgentClient): void;
 export declare function registerConnect(program: Command): void;

package/dist/commands/connect.js

@@ -3,8 +3,9 @@ import * as path from "node:path";
 import spawn from "cross-spawn";
 import { CONNECT_SOURCE, loadConfig, persistApiKeyToEnvironment, saveConnectContext, validateKeyFormat, writeConfig, } from "../lib/auth.js";
 import { CLI_VERSION } from "../lib/constants.js";
+import { cursorMcpPath, writeCursorMcpConfig } from "../lib/cursor-config.js";
 import { errLine } from "../lib/output.js";
-const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
+export const DEFAULT_MCP_URL = "https://agent.tinyfish.ai/mcp";
 const NON_INTERACTIVE_TIMEOUT_MS = 10_000;
 const SKILL_INSTALL_TIMEOUT_MS = 120_000;
 const HERMES_SEED_TIMEOUT_MS = 120_000;
@@ -687,6 +688,39 @@ export async function connectOpenClaw(options) {
         settle(state, telemetry, "completed");
     });
 }
+/** Writes mcp.json directly — no `cursor mcp add` exists. */
+export async function connectCursor(options) {
+    const telemetry = createConnectTelemetry(options.mcpUrl, "cursor", options.apiKey);
+    const state = { stage: "prerequisite_check", settled: false };
+    await runGuarded(state, telemetry, () => {
+        telemetry.track("started");
+        telemetry.track("checkpoint", { phase: "prerequisite_ok" });
+        state.stage = "registration";
+        errLine("Adding TinyFish to Cursor...");
+        const mcpUrl = new URL(options.mcpUrl);
+        mcpUrl.searchParams.set("source", CONNECT_SOURCE);
+        mcpUrl.searchParams.set("client", "cursor");
+        // Attempt id rides telemetry only; persisting it would break idempotency.
+        const result = writeCursorMcpConfig(mcpUrl.toString());
+        if (result.status === "corrupt_skip") {
+            throw new Error(`Could not update ${cursorMcpPath()}: existing file could not be read or is not valid JSON (${result.error}). ` +
+                `Fix the file, then re-run: tinyfish connect cursor`);
+        }
+        if (result.backupPath) {
+            errLine(`Backed up existing Cursor MCP config to ${result.backupPath}`);
+        }
+        telemetry.track("checkpoint", { phase: "registered" });
+        state.stage = "authentication";
+        ensureCliAuthenticated("cursor", options.apiKey);
+        telemetry.track("checkpoint", { phase: "authenticated" });
+        saveConnectContext("cursor", telemetry.attemptId);
+        // A server written into mcp.json lands unauthenticated: only Cursor's own "Add to
+        // Cursor" deep link auto-starts OAuth, so name the click or the install never completes.
+        errLine("Added to Cursor. Restart Cursor (or reload the window), then open");
+        errLine('Settings -> Tools & MCP and click Connect on "tinyfish" to sign in.');
+        settle(state, telemetry, "completed");
+    });
+}
 export function launchAgent(client) {
     if (client === "claude-code") {
         launchNativeMcpClient(CLAUDE_CODE);
@@ -697,15 +731,23 @@ export function launchAgent(client) {
     else if (client === "hermes") {
         launchNativeMcpClient(HERMES);
     }
-    else {
+    else if (client === "openclaw") {
         launchOpenClawWalkthrough();
     }
+    else if (client === "cursor") {
+        // Cursor has no chat CLI to launch.
+        throw new Error("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
+    }
+    else {
+        const unhandled = client;
+        throw new Error(`No launch support for client: ${String(unhandled)}`);
+    }
 }
 export function registerConnect(program) {
     program
         .command("connect")
         .description("Connect TinyFish to an AI agent")
-        .argument("<client>", "Agent client to connect (claude-code, codex, hermes, or openclaw)")
+        .argument("<client>", "Agent client to connect (claude-code, codex, cursor, hermes, or openclaw)")
         .option("--api-key <apiKey>", "TinyFish API key to persist for the installed skill")
         .option("--launch", "Launch the agent and start the TinyFish walkthrough")
         .option("--url <mcpUrl>", "MCP endpoint override")
@@ -740,8 +782,18 @@ export function registerConnect(program) {
         else if (client === "openclaw") {
             await connectOpenClaw({ mcpUrl: connectOptions.mcpUrl, launch: connectOptions.launch });
         }
+        else if (client === "cursor") {
+            // `connect <client> --launch` is the shape every doc uses; connect anyway, then say
+            // why nothing launched rather than throwing away a working install.
+            await connectCursor({ apiKey: connectOptions.apiKey, mcpUrl: connectOptions.mcpUrl });
+            if (connectOptions.launch) {
+                errLine("Cursor has no launchable walkthrough. Open Cursor and start chatting.");
+            }
+        }
         else {
-            throw new Error(`Unsupported client: ${client}. Supported clients: claude-code, codex, hermes, openclaw`);
+            throw new Error("Unsupported client: " +
+                client +
+                ". Supported clients: claude-code, codex, cursor, hermes, openclaw");
         }
     });
 }

package/dist/lib/cursor-config.d.ts

@@ -0,0 +1,13 @@
+export declare function cursorConfigDir(): string;
+export declare function cursorMcpPath(): string;
+export interface CursorMcpWriteResult {
+    status: "written" | "unchanged" | "corrupt_skip";
+    backupPath?: string;
+    error?: string;
+}
+/** Dry-run description of the pending write; touches nothing. */
+export declare function planCursorWrite(mcpUrl: string): string;
+/** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
+export declare function writeCursorMcpConfig(mcpUrl: string): CursorMcpWriteResult;
+/** Removes only the `tinyfish` key. */
+export declare function removeCursorMcpServer(): CursorMcpWriteResult;

package/dist/lib/cursor-config.js

@@ -0,0 +1,115 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+// The one config file the CLI writes directly — hence backup/merge rigor.
+const TINYFISH_SERVER_KEY = "tinyfish";
+export function cursorConfigDir() {
+    return path.join(os.homedir(), ".cursor");
+}
+export function cursorMcpPath() {
+    return path.join(cursorConfigDir(), "mcp.json");
+}
+function isPlainRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function buildTinyfishServerEntry(mcpUrl) {
+    return { url: mcpUrl };
+}
+function parseMcpJson(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isPlainRecord(parsed))
+            return { ok: false, error: "mcp.json root is not a JSON object" };
+        if ("mcpServers" in parsed && !isPlainRecord(parsed.mcpServers)) {
+            return { ok: false, error: "mcp.json mcpServers is not a JSON object" };
+        }
+        return { ok: true, value: parsed };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+// Non-ENOENT read failures count as corruption: skip, never clobber.
+function readExisting() {
+    let raw;
+    try {
+        raw = fs.readFileSync(cursorMcpPath(), "utf8");
+    }
+    catch (e) {
+        if (e?.code === "ENOENT")
+            return { parsed: {} };
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    const parsed = parseMcpJson(raw);
+    if (!parsed.ok)
+        return { error: parsed.error };
+    return { raw, parsed: parsed.value };
+}
+/** Dry-run description of the pending write; touches nothing. */
+export function planCursorWrite(mcpUrl) {
+    const existing = readExisting();
+    const filePath = cursorMcpPath();
+    if ("error" in existing) {
+        return `${filePath}: existing file is corrupt (${existing.error}) — would skip and leave it untouched`;
+    }
+    const servers = existing.parsed.mcpServers;
+    const current = isPlainRecord(servers) ? servers[TINYFISH_SERVER_KEY] : undefined;
+    if (JSON.stringify(current) === JSON.stringify(buildTinyfishServerEntry(mcpUrl))) {
+        return `${filePath}: already has the tinyfish MCP entry — no change`;
+    }
+    return existing.raw === undefined
+        ? `${filePath}: would create with a "tinyfish" MCP server entry`
+        : `${filePath}: would back up to a timestamped copy, then merge in the "tinyfish" MCP server entry`;
+}
+// Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
+function commitServers(filePath, existing, servers) {
+    fs.mkdirSync(cursorConfigDir(), { recursive: true, mode: 0o700 });
+    let backupPath;
+    if (existing.raw !== undefined) {
+        backupPath = `${filePath}.bak-${Date.now()}-${process.pid}`;
+        fs.writeFileSync(backupPath, existing.raw, { mode: 0o600 });
+    }
+    const next = { ...existing.parsed, mcpServers: servers };
+    const tmpPath = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    try {
+        fs.renameSync(tmpPath, filePath);
+    }
+    catch (e) {
+        fs.rmSync(tmpPath, { force: true });
+        throw e;
+    }
+    return { status: "written", backupPath };
+}
+/** Merges only the `tinyfish` key; skips unreadable/corrupt files rather than clobber. */
+export function writeCursorMcpConfig(mcpUrl) {
+    const filePath = cursorMcpPath();
+    const existing = readExisting();
+    if ("error" in existing)
+        return { status: "corrupt_skip", error: existing.error };
+    const servers = isPlainRecord(existing.parsed.mcpServers)
+        ? { ...existing.parsed.mcpServers }
+        : {};
+    const nextEntry = buildTinyfishServerEntry(mcpUrl);
+    if (JSON.stringify(servers[TINYFISH_SERVER_KEY]) === JSON.stringify(nextEntry)) {
+        return { status: "unchanged" };
+    }
+    servers[TINYFISH_SERVER_KEY] = nextEntry;
+    return commitServers(filePath, existing, servers);
+}
+/** Removes only the `tinyfish` key. */
+export function removeCursorMcpServer() {
+    const filePath = cursorMcpPath();
+    const existing = readExisting();
+    if ("error" in existing)
+        return { status: "corrupt_skip", error: existing.error };
+    if (existing.raw === undefined)
+        return { status: "unchanged" };
+    const servers = isPlainRecord(existing.parsed.mcpServers)
+        ? { ...existing.parsed.mcpServers }
+        : {};
+    if (!(TINYFISH_SERVER_KEY in servers))
+        return { status: "unchanged" };
+    delete servers[TINYFISH_SERVER_KEY];
+    return commitServers(filePath, existing, servers);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.12.0",
+  "version": "0.12.1-next.137",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {