@hyperstar/mcp 0.1.16 → 0.1.18

package/README.md

@@ -104,8 +104,11 @@ when `HYPERSTAR_API_KEY` is used. For non-production login, set matching
 ## Tools
 
 Agents should start by reading `get_hyperstar_workflow_guide` or the MCP
-resources/prompts listed below. Tool responses include `agent_guidance` and,
-where the next step is deterministic, `next_tool` and `next_arguments`.
+resources/prompts listed below. The MCP server starts without auth so clients
+can discover tools and guides first; Product API workflow calls still require
+local browser login or `HYPERSTAR_API_KEY`. Tool responses include
+`agent_guidance` and, where the next step is deterministic, `next_tool` and
+`next_arguments`.
 
 - `hyperstar_whoami`
 - `list_workspaces`
@@ -353,7 +356,9 @@ npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp --help
 ```
 
 These checks do not authenticate and do not call Hyperstar workflow APIs. They
-only prove that npm can resolve the package and both binaries can start.
+prove that npm can resolve the package and both binaries can start. The package
+smoke script also verifies unauthenticated MCP `tools/list`, `resources/list`,
+and `prompts/list` discovery.
 
 ## Troubleshooting
 

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/config.d.ts

@@ -12,7 +12,11 @@ export type CliConfig = {
     readonly accessTokenProvider: CliAccessTokenProvider;
     readonly workspaceSelection: CliWorkspaceSelection;
 };
-export type HyperstarMcpConfig = ServiceAccountConfig | CliConfig;
+export type UnauthenticatedConfig = {
+    readonly authMode: "unauthenticated";
+    readonly apiBaseUrl: string;
+};
+export type HyperstarMcpConfig = ServiceAccountConfig | CliConfig | UnauthenticatedConfig;
 export type Env = Readonly<Record<string, string | undefined>>;
 export type CliWorkspaceSelection = {
     readonly getSelectedOrganizationId: () => Promise<string | undefined>;
@@ -20,6 +24,7 @@ export type CliWorkspaceSelection = {
 };
 export declare const DEFAULT_API_BASE_URL = "https://autopilot.hyper-star.org";
 export declare const DEFAULT_APP_BASE_URL = "https://app.hyper-star.org";
+export declare const AUTH_CONFIGURATION_MESSAGE = "Run `hyperstar login` or set HYPERSTAR_API_KEY";
 export type LoadConfigOptions = {
     readonly env?: Env;
     readonly fetcher?: Fetcher | undefined;
@@ -27,6 +32,8 @@ export type LoadConfigOptions = {
 };
 /** Load MCP configuration from env or persisted CLI auth state. */
 export declare function loadConfig(options?: Env | LoadConfigOptions): HyperstarMcpConfig;
+/** Load config for MCP server startup, allowing unauthenticated discovery. */
+export declare function loadServerConfig(options?: Env | LoadConfigOptions): HyperstarMcpConfig;
 /** Create the local CLI workspace-selection port backed by auth state. */
 export declare function createCliWorkspaceSelection(store: CliAuthStateStore): CliWorkspaceSelection;
 /** Redact an API key or bearer token for error messages. */

package/dist/config.js

@@ -2,6 +2,7 @@ import { createCliAuthClient, createStoredCliAccessTokenProvider, } from "./auth
 import { createFileCliAuthStateStore, } from "./auth/cli-auth-state.js";
 export const DEFAULT_API_BASE_URL = "https://autopilot.hyper-star.org";
 export const DEFAULT_APP_BASE_URL = "https://app.hyper-star.org";
+export const AUTH_CONFIGURATION_MESSAGE = "Run `hyperstar login` or set HYPERSTAR_API_KEY";
 /** Load MCP configuration from env or persisted CLI auth state. */
 export function loadConfig(options = process.env) {
     const loadOptions = isLoadConfigOptions(options) ? options : { env: options };
@@ -24,7 +25,7 @@ export function loadConfig(options = process.env) {
     const store = createFileCliAuthStateStore({ env });
     const state = store.readSync();
     if (state === null) {
-        throw new Error("Run `hyperstar login` or set HYPERSTAR_API_KEY");
+        throw new Error(AUTH_CONFIGURATION_MESSAGE);
     }
     const stateApiBaseUrl = normalizeBaseUrl(state.apiBaseUrl, "stored Hyperstar auth API base URL");
     const rawCliApiBaseUrl = env.HYPERSTAR_API_BASE_URL?.trim();
@@ -52,6 +53,28 @@ export function loadConfig(options = process.env) {
         workspaceSelection: createCliWorkspaceSelection(store),
     };
 }
+/** Load config for MCP server startup, allowing unauthenticated discovery. */
+export function loadServerConfig(options = process.env) {
+    try {
+        return loadConfig(options);
+    }
+    catch (error) {
+        if (!(error instanceof Error) ||
+            error.message !== AUTH_CONFIGURATION_MESSAGE) {
+            throw error;
+        }
+        const loadOptions = isLoadConfigOptions(options)
+            ? options
+            : { env: options };
+        const env = loadOptions.env ?? process.env;
+        const rawBaseUrl = env.HYPERSTAR_API_BASE_URL?.trim() ?? DEFAULT_API_BASE_URL;
+        const apiBaseUrl = normalizeBaseUrl(rawBaseUrl.length === 0 ? DEFAULT_API_BASE_URL : rawBaseUrl, "HYPERSTAR_API_BASE_URL");
+        return {
+            authMode: "unauthenticated",
+            apiBaseUrl,
+        };
+    }
+}
 /** Create the local CLI workspace-selection port backed by auth state. */
 export function createCliWorkspaceSelection(store) {
     return {
@@ -60,7 +83,7 @@ export function createCliWorkspaceSelection(store) {
             await store.withExclusiveLock(async () => {
                 const state = await store.read();
                 if (state === null) {
-                    throw new Error("Run `hyperstar login` or set HYPERSTAR_API_KEY");
+                    throw new Error(AUTH_CONFIGURATION_MESSAGE);
                 }
                 await store.write({
                     ...state,

package/dist/http.js

@@ -1,4 +1,4 @@
-import { redactSecret } from "./config.js";
+import { AUTH_CONFIGURATION_MESSAGE, redactSecret, } from "./config.js";
 export class HyperstarApiError extends Error {
     status;
     detail;
@@ -24,6 +24,9 @@ export function createHyperstarClient(options) {
         };
         const secretsToRedact = [];
         let retryCliAccessToken;
+        if (options.config.authMode === "unauthenticated") {
+            throw new Error(AUTH_CONFIGURATION_MESSAGE);
+        }
         if (options.config.authMode === "service_account") {
             baseHeaders["x-hyperstar-api-key"] = options.config.apiKey;
             secretsToRedact.push(options.config.apiKey);

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { loadConfig } from "./config.js";
+import { loadServerConfig } from "./config.js";
 import { createHyperstarMcpServer } from "./server.js";
 const MCP_SERVER_USAGE = [
     "Usage: hyperstar-mcp [--help]",
@@ -8,7 +8,8 @@ const MCP_SERVER_USAGE = [
     "Starts the Hyperstar stdio MCP server.",
     "",
     "Authentication:",
-    "  Run `hyperstar login` first, or set HYPERSTAR_API_KEY in the MCP server environment.",
+    "  Tools and guides are discoverable before auth.",
+    "  Product API calls require `hyperstar login` or HYPERSTAR_API_KEY.",
 ].join("\n");
 /** Start the stdio MCP server process. */
 async function main() {
@@ -16,7 +17,7 @@ async function main() {
         process.stdout.write(`${MCP_SERVER_USAGE}\n`);
         return;
     }
-    const config = loadConfig();
+    const config = loadServerConfig();
     const server = createHyperstarMcpServer(config);
     await server.connect(new StdioServerTransport());
 }

package/dist/server.js

@@ -10,8 +10,12 @@ export function createHyperstarMcpServer(config) {
         version: packageVersion(),
     });
     registerHyperstarDiscovery(server, { apiBaseUrl: config.apiBaseUrl });
-    registerHyperstarTools(server, createHyperstarClient({ config }), config.authMode === "cli"
-        ? { workspaceSelection: config.workspaceSelection }
-        : {});
+    const toolOptions = config.authMode === "cli"
+        ? {
+            authMode: config.authMode,
+            workspaceSelection: config.workspaceSelection,
+        }
+        : { authMode: config.authMode };
+    registerHyperstarTools(server, createHyperstarClient({ config }), toolOptions);
     return server;
 }

package/dist/workspaces.d.ts

@@ -1,6 +1,7 @@
-import type { CliWorkspaceSelection } from "./config.js";
+import type { CliWorkspaceSelection, HyperstarMcpConfig } from "./config.js";
 import type { HyperstarClient, JsonObject } from "./http.js";
 export type WorkspaceToolOptions = {
+    readonly authMode?: HyperstarMcpConfig["authMode"];
     readonly workspaceSelection?: CliWorkspaceSelection;
 };
 /** List workspaces through the Product API workspace route. */

package/dist/workspaces.js

@@ -1,5 +1,5 @@
 import { WorkspaceListResponseSchema } from "./schemas.js";
-import { workflowGuideJson } from "./workflow-content.js";
+import { CLI_SAFETY_NOTES, CLI_WORKFLOW_SEQUENCE, WORKFLOW_DATA_FLOW_NOTES, workflowGuideJson, workflowGuideResourceDefinitions, } from "./workflow-content.js";
 /** List workspaces through the Product API workspace route. */
 export async function listAvailableWorkspaces(client, options = {}) {
     const payload = WorkspaceListResponseSchema.parse(await client.get("/v1/workspaces"));
@@ -33,6 +33,20 @@ export async function selectAvailableWorkspace(client, organizationId, options =
 }
 /** Return the recommended Hyperstar agent workflow and send-safety notes. */
 export function getHyperstarWorkflowGuide(options = {}) {
+    if (options.authMode === "unauthenticated") {
+        return {
+            sequence: [
+                "Configure auth first: run `hyperstar login` and select a workspace, or set HYPERSTAR_API_KEY.",
+                ...CLI_WORKFLOW_SEQUENCE,
+            ],
+            safety_notes: [
+                "MCP tools and guides are discoverable before auth, but Product API workflow calls require local browser login or HYPERSTAR_API_KEY.",
+                ...CLI_SAFETY_NOTES,
+            ],
+            data_flow_notes: [...WORKFLOW_DATA_FLOW_NOTES],
+            resources: workflowGuideResourceDefinitions.map((resource) => resource.uri),
+        };
+    }
     if (options.workspaceSelection === undefined) {
         return workflowGuideJson("service_account");
     }

package/package.json

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

package/scripts/npm-clean-room-smoke.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, isAbsolute, resolve } from "node:path";
@@ -39,11 +40,25 @@ function logLocalPackageSpec(value) {
   );
 }
 
+function smokeEnv() {
+  const env = {
+    ...process.env,
+    HOME: scratchDir,
+    XDG_CONFIG_HOME: resolve(scratchDir, "config"),
+    npm_config_cache: resolve(scratchDir, "npm-cache"),
+    npm_config_update_notifier: "false",
+  };
+  delete env.HYPERSTAR_API_KEY;
+  delete env.HYPERSTAR_API_BASE_URL;
+  delete env.HYPERSTAR_APP_BASE_URL;
+  return env;
+}
+
 function runStep(step, command, args) {
   const result = spawnSync(command, args, {
     cwd: scratchDir,
     encoding: "utf8",
-    env: process.env,
+    env: smokeEnv(),
     shell: false,
   });
   const stdout = result.stdout.trim();
@@ -79,6 +94,115 @@ function runStep(step, command, args) {
   );
 }
 
+async function runMcpDiscoveryStep() {
+  const child = spawn(
+    "npm",
+    ["exec", "--yes", "--package", packageSpec, "--", "hyperstar-mcp"],
+    {
+      cwd: scratchDir,
+      env: smokeEnv(),
+      stdio: ["pipe", "pipe", "pipe"],
+    },
+  );
+  const responses = [];
+  let stdout = "";
+  let stderr = "";
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk;
+    for (;;) {
+      const lineEnd = stdout.indexOf("\n");
+      if (lineEnd === -1) {
+        break;
+      }
+      const line = stdout.slice(0, lineEnd).trim();
+      stdout = stdout.slice(lineEnd + 1);
+      if (line.length === 0) {
+        continue;
+      }
+      responses.push(JSON.parse(line));
+    }
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk;
+  });
+
+  const send = (message) => {
+    child.stdin.write(`${JSON.stringify(message)}\n`);
+  };
+  const waitFor = (id) =>
+    new Promise((resolveResponse, rejectResponse) => {
+      const started = Date.now();
+      const interval = setInterval(() => {
+        const response = responses.find((item) => item.id === id);
+        if (response !== undefined) {
+          clearInterval(interval);
+          resolveResponse(response);
+          return;
+        }
+        if (Date.now() - started > 15_000) {
+          clearInterval(interval);
+          rejectResponse(
+            new Error(`Timed out waiting for MCP response ${id}: ${stderr}`),
+          );
+        }
+      }, 50);
+    });
+
+  try {
+    send({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "hyperstar-npm-smoke", version: "0.0.0" },
+      },
+    });
+    await waitFor(1);
+    send({ jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+    send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+    send({ jsonrpc: "2.0", id: 3, method: "resources/list", params: {} });
+    send({ jsonrpc: "2.0", id: 4, method: "prompts/list", params: {} });
+    const [tools, resources, prompts] = await Promise.all([
+      waitFor(2),
+      waitFor(3),
+      waitFor(4),
+    ]);
+    console.log(
+      JSON.stringify(
+        {
+          step: "hyperstar-mcp-discovery",
+          ok: true,
+          tools: tools.result.tools.map((tool) => tool.name).slice(0, 8),
+          resources: resources.result.resources.map((resource) => resource.uri),
+          prompts: prompts.result.prompts.map((prompt) => prompt.name),
+        },
+        null,
+        2,
+      ),
+    );
+  } catch (error) {
+    console.error(
+      JSON.stringify(
+        {
+          step: "hyperstar-mcp-discovery",
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+          stderr: stderr.trim(),
+        },
+        null,
+        2,
+      ),
+    );
+    process.exitCode = 1;
+  } finally {
+    child.kill("SIGTERM");
+  }
+}
+
 try {
   if (isLocalPackageSpec(packageSpec)) {
     logLocalPackageSpec(packageSpec);
@@ -108,6 +232,7 @@ try {
     "hyperstar-mcp",
     "--help",
   ]);
+  await runMcpDiscoveryStep();
 } finally {
   rmSync(scratchDir, { recursive: true, force: true });
 }