stoaken 0.4.0 → 0.5.0

package/README.md

@@ -32,15 +32,28 @@ npx stoaken init --client cursor
 | `copilot` | `.vscode/mcp.json` (`servers.stoaken`, VS Code agent mode) |
 | `claude-desktop` | Nothing: prints the steps to add a custom connector (Customize > Connectors) |
 | `v0` | Nothing: prints the steps to add a custom MCP server in v0 (+ > MCPs) |
+| `windsurf` | `.devin/mcp_config.json` (`mcpServers.stoaken`, URL only). Windsurf is now Devin Desktop; this is for its Devin Local agent and Devin CLI |
+| `zed` | `.zed/settings.json` (`context_servers.stoaken`, URL only; OAuth). With an API key: nothing, prints how to add it to your user settings |
+| `gemini-cli` | `.gemini/settings.json` (`mcpServers.stoaken.httpUrl`; loads in trusted folders only) |
+| `jetbrains` | `.junie/mcp/mcp.json` (`mcpServers.stoaken`, URL only; Junie). With an API key: nothing, prints how to add it to `~/.junie/mcp/mcp.json` |
+| `cline` | Nothing: prints the steps for Cline's Remote Servers tab |
+| `lovable` | Nothing: prints the steps to add a custom MCP server (Connectors > Add custom) |
+| `bolt` | Nothing: prints the steps to add a custom connector (+ > Connectors) |
+| `replit` | Nothing: prints a one-click Replit install link and the manual steps |
 
 init merges: other servers in the file are kept and only the `stoaken` entry is replaced. If the
-file isn't plain JSON (for example `.vscode/mcp.json` with comments) it is left alone and you're told.
-No secret goes into these files, so they are safe to commit:
+file isn't plain JSON (for example `.vscode/mcp.json` or `.zed/settings.json` with comments) it is
+left alone and you're told. No secret goes into these files, so they are safe to commit:
 
 - Signed in with the browser: the entry has just the URL, and the tool signs you in itself with
-  OAuth (Claude Code `/mcp`, Cursor Connect, `codex mcp login stoaken`, VS Code Start).
+  OAuth (Claude Code `/mcp`, Cursor Connect, `codex mcp login stoaken`, VS Code Start,
+  `/mcp auth stoaken` in Gemini CLI, Authenticate in Devin Local, Zed's sign-in prompt, Junie's
+  `/mcp` Authorize).
 - Pasted an API key: the entry reads the `STOAKEN_API_KEY` environment variable (VS Code instead
-  asks for the key once and stores it securely).
+  asks for the key once and stores it securely). Devin Local, Zed and Junie document no variable
+  expansion in headers, so init never writes the key for them: Devin gets a gitignored
+  `.devin/mcp_config.local.json` override (`devin mcp add -s local ... -H`), and Zed and Junie are
+  told to use a user-level file outside the repo.
 
 ## Authentication
 
@@ -101,7 +114,7 @@ Bitbucket Pipelines, Azure Pipelines and Vercel builds: see /docs/webhooks#ci an
 
 ## What this connects to
 
-Once set up, any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Copilot, v0) or a direct HTTP client can reach Stoaken's MCP server at `/mcp`. Its main tools (full list at /docs/mcp):
+Once set up, any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, Copilot, v0, Devin Desktop, Zed, Gemini CLI, Junie, Cline, Lovable, Bolt, Replit) or a direct HTTP client can reach Stoaken's MCP server at `/mcp`. Its main tools (full list at /docs/mcp):
 
 - `list_brands` -- every Brand you hold at least Viewer on.
 - `get_theme_tokens(themeId)` -- a Theme's cascade-merged token tree.

package/dist/index.js

@@ -214,7 +214,7 @@ async function listBrands(serverUrl, credential) {
   const transport = new StreamableHTTPClientTransport(new URL("/mcp", serverUrl), {
     requestInit: { headers: { Authorization: `Bearer ${credential}` } }
   });
-  const client = new Client({ name: "stoaken-cli", version: "0.4.0" });
+  const client = new Client({ name: "stoaken-cli", version: "0.5.0" });
   await client.connect(transport);
   try {
     const result = await client.callTool({ name: "list_brands", arguments: {} });
@@ -229,7 +229,22 @@ async function listBrands(serverUrl, credential) {
 }
 
 // src/client-config.ts
-var CLIENTS = ["claude-code", "claude-desktop", "cursor", "codex", "copilot", "v0"];
+var CLIENTS = [
+  "claude-code",
+  "claude-desktop",
+  "cursor",
+  "codex",
+  "copilot",
+  "v0",
+  "windsurf",
+  "zed",
+  "gemini-cli",
+  "jetbrains",
+  "cline",
+  "lovable",
+  "bolt",
+  "replit"
+];
 var SERVER_NAME = "stoaken";
 var API_KEY_ENV = "STOAKEN_API_KEY";
 var CLIENT_LABELS = {
@@ -238,17 +253,43 @@ var CLIENT_LABELS = {
   cursor: "Cursor",
   codex: "OpenAI Codex",
   copilot: "GitHub Copilot (VS Code)",
-  v0: "v0 (Vercel)"
+  v0: "v0 (Vercel)",
+  windsurf: "Windsurf / Devin Desktop",
+  zed: "Zed",
+  "gemini-cli": "Gemini CLI",
+  jetbrains: "JetBrains (Junie)",
+  cline: "Cline",
+  lovable: "Lovable",
+  bolt: "Bolt (bolt.new)",
+  replit: "Replit Agent"
+};
+var JSON_CLIENTS = ["claude-code", "cursor", "copilot", "windsurf", "zed", "gemini-cli", "jetbrains"];
+var SERVERS_KEY = {
+  "claude-code": "mcpServers",
+  cursor: "mcpServers",
+  copilot: "servers",
+  windsurf: "mcpServers",
+  zed: "context_servers",
+  "gemini-cli": "mcpServers",
+  jetbrains: "mcpServers"
 };
 function isClient(value) {
   return CLIENTS.includes(value);
 }
+function isJsonClient(client) {
+  return JSON_CLIENTS.includes(client);
+}
 function mcpUrl(serverUrl) {
   return `${serverUrl.replace(/\/+$/, "")}/mcp`;
 }
+function replitInstallLink(serverUrl) {
+  const json = JSON.stringify({ displayName: "Stoaken", baseUrl: mcpUrl(serverUrl) });
+  return `https://replit.com/integrations?mcp=${Buffer.from(json, "utf8").toString("base64")}`;
+}
 function planFor(client, auth, serverUrl) {
   const url = mcpUrl(serverUrl);
   const keyStep = `Set ${API_KEY_ENV} in your shell to an API key from Settings > API keys (never commit it).`;
+  const oauthInstead = "Or run init again, sign in with the browser, and use OAuth instead.";
   switch (client) {
     case "claude-code":
       return {
@@ -268,7 +309,8 @@ function planFor(client, auth, serverUrl) {
     case "copilot":
       return {
         file: ".vscode/mcp.json",
-        nextSteps: auth === "oauth" ? ["In VS Code open .vscode/mcp.json, click Start above stoaken and sign in in the browser.", "Use Copilot Chat in Agent mode."] : ["In VS Code open .vscode/mcp.json, click Start above stoaken and paste an API key when asked (VS Code stores it securely).", "Use Copilot Chat in Agent mode."]
+        nextSteps: auth === "oauth" ? ["In VS Code open .vscode/mcp.json, click Start above stoaken and sign in in the browser.", "Use Copilot Chat in Agent mode."] : ["In VS Code open .vscode/mcp.json, click Start above stoaken and paste an API key when asked (VS Code stores it securely).", "Use Copilot Chat in Agent mode."],
+        keyNote: "VS Code asks for the key once and stores it securely"
       };
     case "claude-desktop":
       return {
@@ -290,10 +332,104 @@ function planFor(client, auth, serverUrl) {
           "v0 uses the tools while it generates; the app it builds cannot call them."
         ]
       };
+    case "windsurf":
+      return {
+        file: ".devin/mcp_config.json",
+        nextSteps: auth === "oauth" ? [
+          "Open this project in Devin Desktop (formerly Windsurf) with the Devin Local agent. Devin CLI reads the same file.",
+          "When stoaken shows Needs auth in the MCP list, click Authenticate (or run: devin mcp login stoaken)."
+        ] : [
+          keyStep,
+          `Devin documents no variable expansion in MCP headers, so add the key to the gitignored local override: devin mcp add -s local stoaken ${url} -H "Authorization: Bearer $${API_KEY_ENV}"`,
+          "That override replaces the project entry for you only. The legacy Cascade agent ignores project files (see the guide)."
+        ],
+        keyNote: "the key goes in the gitignored `.devin/mcp_config.local.json` override"
+      };
+    case "zed":
+      return auth === "oauth" ? {
+        file: ".zed/settings.json",
+        nextSteps: [
+          "Trust this project in Zed: in Restricted Mode project settings and their MCP servers don't load.",
+          "Zed asks you to sign in to stoaken (MCP OAuth). Settings > AI > MCP Servers shows a green dot when it's active."
+        ]
+      } : {
+        file: null,
+        nextSteps: [
+          "Zed documents no variable expansion in headers, so the key can't go in a project file.",
+          `Run "zed: open settings file" and add under "context_servers": "stoaken": { "url": "${url}", "headers": { "Authorization": "Bearer <API key>" } }`,
+          oauthInstead
+        ]
+      };
+    case "gemini-cli":
+      return {
+        file: ".gemini/settings.json",
+        nextSteps: auth === "oauth" ? ["Trust this folder (gemini trust): untrusted folders ignore .gemini/settings.json.", "In Gemini CLI run /mcp auth stoaken to sign in in the browser."] : [keyStep, "Trust this folder (gemini trust): untrusted folders ignore .gemini/settings.json."]
+      };
+    case "jetbrains":
+      return auth === "oauth" ? {
+        file: ".junie/mcp/mcp.json",
+        nextSteps: [
+          "Junie in the IDE: Settings > Tools > Junie > MCP Settings lists stoaken and its status.",
+          "Junie CLI: run /mcp, select stoaken, choose Authorize and sign in in the browser."
+        ]
+      } : {
+        file: null,
+        nextSteps: [
+          "Junie has no secret storage or variable expansion for MCP configs, so the key can't go in a project file.",
+          `In your user file ~/.junie/mcp/mcp.json, under "mcpServers", add "stoaken": { "url": "${url}", "headers": { "Authorization": "Bearer <API key>" } }`,
+          oauthInstead
+        ]
+      };
+    case "cline":
+      return {
+        file: null,
+        nextSteps: [
+          "Cline keeps MCP servers in its own settings, not a project file.",
+          ...auth === "oauth" ? [
+            `Cline panel > MCP Servers > Remote Servers: name stoaken, URL ${url}, transport Streamable HTTP, Add Server.`,
+            "If it asks you to authenticate, sign in in the browser (Cline CLI: cline mcp > Authorize OAuth)."
+          ] : [
+            `Cline panel > MCP Servers > Configure > Configure MCP Servers, and add under "mcpServers": "stoaken": { "type": "streamableHttp", "url": "${url}", "headers": { "Authorization": "Bearer <API key>" } }`
+          ]
+        ]
+      };
+    case "lovable":
+      return {
+        file: null,
+        nextSteps: [
+          "Lovable adds MCP servers in its own UI, not through a project file.",
+          "Connectors > Add custom > MCP server. Server name: Stoaken.",
+          `Server URL: ${url}. Authentication: OAuth (Add & authorize), or Bearer token with an API key.`,
+          "The connection is yours alone and only for Lovable's chat; the app it publishes can't call it."
+        ]
+      };
+    case "bolt":
+      return {
+        file: null,
+        nextSteps: [
+          "Bolt adds MCP servers in its own UI, not through a project file.",
+          "In the chatbox: + > Connectors > Manage connectors > Custom MCP server.",
+          `Name: Stoaken. URL: ${url}. Transport type: HTTP. Authentication: MCP OAuth.`,
+          "Then turn the connector on for the project (+ > Connectors)."
+        ]
+      };
+    case "replit":
+      return {
+        file: null,
+        nextSteps: [
+          "Replit adds MCP servers in its own UI, not through a project file.",
+          `Open ${replitInstallLink(serverUrl)} (or Integrations > MCP Servers > + Add MCP server, URL ${url}).`,
+          auth === "oauth" ? "Click Test & save and sign in when Replit runs the OAuth flow." : "Under Advanced settings add the header Authorization: Bearer <API key>, then Test & save."
+        ]
+      };
   }
 }
 function jsonEntry(client, auth, serverUrl) {
   const url = mcpUrl(serverUrl);
+  if (client === "windsurf" || client === "zed" || client === "jetbrains") return { url };
+  if (client === "gemini-cli") {
+    return auth === "oauth" ? { httpUrl: url } : { httpUrl: url, headers: { Authorization: `Bearer \${${API_KEY_ENV}}` } };
+  }
   if (client === "claude-code") {
     return auth === "oauth" ? { type: "http", url } : { type: "http", url, headers: { Authorization: `Bearer \${${API_KEY_ENV}}` } };
   }
@@ -325,8 +461,9 @@ var COPILOT_INPUT = {
 };
 function mergeJsonConfig(client, existing, auth, serverUrl) {
   const file = planFor(client, auth, serverUrl).file;
+  if (file === null) throw new ConfigMergeError(`${CLIENT_LABELS[client]} gets no project file with an API key; follow the steps instead.`);
   const doc = parseObject(existing, file);
-  const key = client === "copilot" ? "servers" : "mcpServers";
+  const key = SERVERS_KEY[client];
   const current = doc[key];
   if (current !== void 0 && (typeof current !== "object" || current === null || Array.isArray(current))) {
     throw new ConfigMergeError(`${file} has a "${key}" that isn't an object, so it was left alone.`);
@@ -377,7 +514,7 @@ file -- it's already in \`.gitignore\`).
   }
   const { client, auth } = target;
   const plan = planFor(client, auth, serverUrl);
-  const how = auth === "oauth" ? "the client signs in with OAuth" : `it reads the \`${API_KEY_ENV}\` environment variable`;
+  const how = auth === "oauth" ? "the client signs in with OAuth" : plan.keyNote ?? `it reads the \`${API_KEY_ENV}\` environment variable`;
   const where = plan.file ? `It is configured for ${CLIENT_LABELS[client]} in \`${plan.file}\` (no secret in that file: ${how}).` : `${CLIENT_LABELS[client]} connects through its own settings, not a project file.`;
   return `${where}
 
@@ -557,6 +694,7 @@ async function runInit(options) {
       const path = join2(cwd, plan.file);
       const existingText = existsSync2(path) ? await readFile2(path, "utf8") : null;
       try {
+        if (client !== "codex" && !isJsonClient(client)) throw new Error(`No file writer for ${client}.`);
         const next = client === "codex" ? mergeCodexToml(existingText, auth, serverUrl) : mergeJsonConfig(client, existingText, auth, serverUrl);
         await mkdir2(dirname(path), { recursive: true });
         await writeFile2(path, next, "utf8");
@@ -590,7 +728,7 @@ async function call(serverUrl, token, path) {
   let response;
   try {
     response = await fetch(new URL(path, serverUrl), {
-      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.4.0" }
+      headers: { Authorization: `Bearer ${token}`, "User-Agent": "stoaken-cli/0.5.0" }
     });
   } catch (error) {
     throw new Error(`Couldn't reach ${serverUrl}: ${error instanceof Error ? error.message : String(error)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stoaken",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Stoaken CLI -- set up a project for MCP/API access, and export your design tokens as code.",
   "license": "UNLICENSED",
   "type": "module",