@hyperstar/mcp 0.1.17 → 0.1.19

package/README.md

@@ -41,8 +41,9 @@ path, use the equivalent `npm exec` form:
 npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp
 ```
 
-For interactive local use, start with browser login. The CLI opens Hyperstar in
-your browser and never asks for a raw Hyperstar password in the terminal:
+For interactive local use, start with browser login. An agent with shell access
+on the same machine may run this command for the user. The CLI opens Hyperstar
+in the browser and never asks for a raw Hyperstar password in the terminal:
 
 ```sh
 npx -y --package @hyperstar/mcp hyperstar login
@@ -50,6 +51,19 @@ npx -y --package @hyperstar/mcp hyperstar workspaces list --json
 npx -y --package @hyperstar/mcp hyperstar workspaces use <organization_id>
 ```
 
+If the agent should not open the browser automatically, use `--no-open`. The
+agent can show the printed URL to the user and keep the command running while
+the browser completes the loopback callback:
+
+```sh
+npx -y --package @hyperstar/mcp hyperstar login --no-open
+```
+
+`hyperstar logout` revokes and clears the CLI token, but it does not sign out of
+the browser session at `app.hyper-star.org`. To switch accounts, sign out in the
+browser first or open the printed authorization URL in a private browser window.
+After login, list workspaces and select exactly one before using workflow tools.
+
 For unattended automation, create a service-account key from Team -> API keys in
 the dashboard. Use the headless workflow preset. Enable inbox write only for
 agents that are allowed to send inbox replies.
@@ -368,6 +382,12 @@ and `prompts/list` discovery.
   multiple binaries.
 - `No Hyperstar auth configured`: run `hyperstar login` and select a workspace,
   or set `HYPERSTAR_API_KEY` in the MCP server environment.
+- The agent says login must be run manually: the agent can run
+  `hyperstar login --no-open`, show the printed URL, and wait while the user
+  completes browser authentication on the same machine.
+- Login keeps returning the same account: `hyperstar logout` clears only the CLI
+  token. Sign out of `app.hyper-star.org` in the browser or use a private window
+  for the authorization URL.
 - Workspace errors in browser-login mode: run
   `hyperstar workspaces list --json`, then
   `hyperstar workspaces use <organization_id>`.

package/dist/auth/cli-auth-client.js

@@ -9,7 +9,7 @@ export function createCliAuthClient(options) {
             code,
             code_verifier: verifier,
             client_id: CLI_CLIENT_ID,
-            redirect_uri: redirectUri,
+            loopback_redirect: toLoopbackRedirect(redirectUri),
         }),
         refresh: async (refreshToken) => requestRefresh(fetcher, options.apiBaseUrl, now, {
             refresh_token: refreshToken,
@@ -102,6 +102,23 @@ async function requestToken(fetcher, apiBaseUrl, now, body) {
     }
     return parseTokenPair(payload, now);
 }
+/** Convert the local callback URL to the API-safe descriptor. */
+function toLoopbackRedirect(redirectUri) {
+    const url = new URL(redirectUri);
+    const port = Number(url.port);
+    if (url.protocol !== "http:" ||
+        url.pathname !== "/callback" ||
+        (url.hostname !== "127.0.0.1" && url.hostname !== "localhost") ||
+        !Number.isInteger(port) ||
+        port < 1024 ||
+        port > 65535) {
+        throw new Error("Hyperstar CLI callback URL was invalid");
+    }
+    return {
+        host: url.hostname === "127.0.0.1" ? "ipv4" : "localhost",
+        port,
+    };
+}
 /** Rotate a refresh token using the backend refresh route. */
 async function requestRefresh(fetcher, apiBaseUrl, now, body) {
     const response = await fetcher(buildApiUrl(apiBaseUrl, "/api/v1/cli-auth/refresh"), {

package/dist/cli-messages.d.ts

@@ -0,0 +1,4 @@
+export declare const CLI_USAGE: string;
+export declare const BROWSER_SESSION_BOUNDARY = "Browser sessions are separate from CLI sessions; logout does not sign out of the browser account.";
+export declare const BROWSER_ACCOUNT_SWITCH_GUIDANCE = "Browser sessions are separate from CLI sessions; sign out in the browser or use a private window to switch browser accounts.";
+export declare const WORKSPACE_SELECTION_GUIDANCE = "Run `hyperstar workspaces list --json`, select exactly one workspace, then run `hyperstar workspaces use <organization_id>`.";

package/dist/cli-messages.js

@@ -0,0 +1,18 @@
+export const CLI_USAGE = [
+    "Usage: hyperstar <command> [options]",
+    "",
+    "Commands:",
+    "  login [--no-open]             Open browser login and save local CLI auth",
+    "  logout                        Revoke and clear local CLI auth",
+    "  whoami [--json]               Print the authenticated principal",
+    "  workspaces list [--json]      List accessible workspaces",
+    "  workspaces use <workspace_id> Select a workspace for Product API calls",
+    "",
+    "Options:",
+    "  --json     Print supported command output as JSON",
+    "  --no-open  Print the login URL without opening a browser",
+    "  --help     Show this help",
+].join("\n");
+export const BROWSER_SESSION_BOUNDARY = "Browser sessions are separate from CLI sessions; logout does not sign out of the browser account.";
+export const BROWSER_ACCOUNT_SWITCH_GUIDANCE = "Browser sessions are separate from CLI sessions; sign out in the browser or use a private window to switch browser accounts.";
+export const WORKSPACE_SELECTION_GUIDANCE = "Run `hyperstar workspaces list --json`, select exactly one workspace, then run `hyperstar workspaces use <organization_id>`.";

package/dist/cli.js

@@ -9,20 +9,7 @@ import { startLocalCallbackServer, } from "./auth/local-callback.js";
 import { createPkcePair, createState } from "./auth/pkce.js";
 import { DEFAULT_API_BASE_URL, DEFAULT_APP_BASE_URL, createCliWorkspaceSelection, normalizeBaseUrl, } from "./config.js";
 import { createHyperstarClient } from "./http.js";
-const CLI_USAGE = [
-    "Usage: hyperstar <command> [options]",
-    "",
-    "Commands:",
-    "  login                         Open browser login and save local CLI auth",
-    "  logout                        Revoke and clear local CLI auth",
-    "  whoami [--json]               Print the authenticated principal",
-    "  workspaces list [--json]      List accessible workspaces",
-    "  workspaces use <workspace_id> Select a workspace for Product API calls",
-    "",
-    "Options:",
-    "  --json   Print supported command output as JSON",
-    "  --help   Show this help",
-].join("\n");
+import { BROWSER_ACCOUNT_SWITCH_GUIDANCE, BROWSER_SESSION_BOUNDARY, CLI_USAGE, WORKSPACE_SELECTION_GUIDANCE, } from "./cli-messages.js";
 /** Return whether a module URL is the process entrypoint, following npm bin symlinks. */
 export function isDirectCliInvocation(moduleUrl, argvPath, resolveRealpath = realpathSync) {
     if (argvPath === undefined) {
@@ -49,7 +36,14 @@ export async function runCli(argv = process.argv.slice(2), dependencies = {}) {
         const store = dependencies.stateStore ?? createFileCliAuthStateStore({ env });
         const fetcher = dependencies.fetcher;
         if (command.positionals[0] === "login") {
-            await login({ env, store, fetcher, stdout, dependencies });
+            await login({
+                env,
+                store,
+                fetcher,
+                stdout,
+                dependencies,
+                noOpen: command.noOpen,
+            });
             return 0;
         }
         if (command.positionals[0] === "logout") {
@@ -104,6 +98,7 @@ function parseCommand(argv) {
         allowPositionals: true,
         options: {
             json: { type: "boolean", default: false },
+            "no-open": { type: "boolean", default: false },
             help: { type: "boolean", default: false },
         },
     });
@@ -111,6 +106,7 @@ function parseCommand(argv) {
         positionals: parsed.positionals,
         json: parsed.values.json ?? false,
         help: parsed.values.help ?? false,
+        noOpen: parsed.values["no-open"] ?? false,
     };
 }
 /** Complete browser-based local login and persist token state. */
@@ -128,13 +124,21 @@ async function login(options) {
             fetcher: options.fetcher,
         });
         const authorizeUrl = client.buildAuthorizeUrl(callback.callbackUrl, pkce, state);
+        options.stdout(`Hyperstar API: ${apiBaseUrl}`);
+        options.stdout(`Hyperstar app: ${appBaseUrl}`);
         options.stdout(`Open this URL to authorize Hyperstar CLI: ${authorizeUrl.toString()}`);
-        try {
-            await (options.dependencies.openBrowser ?? openBrowser)(authorizeUrl);
+        options.stdout(BROWSER_SESSION_BOUNDARY);
+        if (options.noOpen) {
+            options.stdout("Browser auto-open disabled. Open the URL above in a browser on this machine.");
         }
-        catch (error) {
-            void error;
-            options.stdout("Could not open your browser automatically. Copy the URL above into your browser.");
+        else {
+            try {
+                await (options.dependencies.openBrowser ?? openBrowser)(authorizeUrl);
+            }
+            catch (error) {
+                void error;
+                options.stdout("Could not open your browser automatically. Copy the URL above into your browser.");
+            }
         }
         const callbackResult = await callback.result;
         if ("error" in callbackResult) {
@@ -149,6 +153,7 @@ async function login(options) {
             }));
         });
         options.stdout("Logged in to Hyperstar.");
+        options.stdout(WORKSPACE_SELECTION_GUIDANCE);
     }
     finally {
         await callback.close();
@@ -176,6 +181,7 @@ async function logout(options) {
         }
     });
     options.stdout("Logged out of Hyperstar.");
+    options.stdout(BROWSER_ACCOUNT_SWITCH_GUIDANCE);
 }
 /** Print the authenticated principal from the Product API. */
 async function whoami(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperstar/mcp",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Local stdio MCP server and CLI for Hyperstar headless workflows.",