@hyperstar/mcp 0.1.15 → 0.1.17

package/LICENSE

@@ -0,0 +1,8 @@
+Hyperstar MCP Proprietary License
+
+Copyright (c) Hyperstar. All rights reserved.
+
+This package is published for use with Hyperstar services. The package and its
+contents are proprietary. No permission is granted to copy, modify, distribute,
+sublicense, or use this package except as expressly authorized by Hyperstar.
+

package/README.md

@@ -5,10 +5,19 @@ workflows. It exposes scoped creator search, campaign roster, bulk email, and
 inbox tools for MCP clients using either a service-account key or local browser
 CLI login.
 
-For first-tester setup, MCP client snippets, and safe starter prompts, use the
-[headless agent quickstart](https://github.com/Hyperstar-org/backend/blob/main/docs/headless-agent-quickstart.md).
+This README is self-contained for first-time agent setup. You do not need
+access to the Hyperstar source repository to install the package, configure an
+MCP client, or understand the safe workflow order.
 
-## Install
+## Requirements
+
+- Node.js `22.12.0` or newer.
+- An active Hyperstar account with access to at least one workspace.
+- Either a service-account API key or permission to approve local browser CLI
+  login.
+- An MCP-capable client that can launch a local stdio server.
+
+## Install And Login
 
 Run the MCP server directly from npm:
 
@@ -32,29 +41,18 @@ path, use the equivalent `npm exec` form:
 npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp
 ```
 
-For a one-off browser login without a global install:
+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:
 
 ```sh
 npx -y --package @hyperstar/mcp hyperstar login
 npx -y --package @hyperstar/mcp hyperstar workspaces list --json
-npx -y --package @hyperstar/mcp hyperstar workspaces use org_123
-```
-
-For unreleased local package testing, pack from the package directory and use
-the filename printed by `npm pack`:
-
-```sh
-cd projects/hyperstar-mcp
-TARBALL=$(npm pack --silent)
-npx -y --package "./$TARBALL" hyperstar-mcp
-npx -y --package "./$TARBALL" hyperstar login
-npx -y --package "./$TARBALL" hyperstar workspaces list --json
-npx -y --package "./$TARBALL" hyperstar workspaces use org_123
+npx -y --package @hyperstar/mcp hyperstar workspaces use <organization_id>
 ```
 
-The first public scoped publish must use public access. This package sets
-`publishConfig.access=public`, so `npm publish` is sufficient once npm
-credentials are configured.
+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.
 
 ## MCP client config
 
@@ -106,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`
@@ -144,18 +145,59 @@ It also exposes matching prompts:
 - `hyperstar_bulk_email_safety`
 - `hyperstar_inbox_workflow`
 
-## Development
+## First Agent Prompts
 
-```sh
-npm install
-npm test
-npm run build
-npm run smoke:npm
+Use prompts like these with a newly connected agent:
+
+```text
+Use the Hyperstar MCP tools. First, discover the available Hyperstar workflow
+guides and tell me the safe order for search, campaign save, bulk email, and
+inbox handling.
 ```
 
-`npm run smoke:npm` verifies the published npm package can be resolved and that
-both package binaries print help without requiring local build artifacts,
-authentication, or real workflow API calls.
+```text
+Use Hyperstar to search TikTok creators in the US for ceramic mug reviewers.
+Return only a compact summary and explain the next tool I should approve before
+saving anything to a campaign.
+```
+
+```text
+List my Hyperstar campaigns and explain how you would safely check bulk email
+readiness for one campaign without starting a real send.
+```
+
+```text
+List recent Hyperstar inbox threads, then read the full messages for one thread
+before drafting any reply. Do not send a reply unless I explicitly authorize it.
+```
+
+## Workflow Safety
+
+Agents should start with `get_hyperstar_workflow_guide` or the MCP guide
+resources. The server exposes these main workflow tools:
+
+- `search_creators`
+- `get_search_results`
+- `list_campaigns`
+- `create_campaign`
+- `save_search_results_to_campaign`
+- `list_campaign_creators`
+- `check_bulk_email_readiness`
+- `start_bulk_email`
+- `get_bulk_email_job`
+- `list_inbox_threads`
+- `get_inbox_thread_messages`
+- `update_inbox_thread_state`
+- `send_inbox_reply`
+
+`start_bulk_email` and `send_inbox_reply` perform real sends. Both require
+`send_confirmation: "user_authorized"` and a stable `idempotency_key`. Agents
+should call readiness and full-thread read tools before asking for send
+authorization.
+
+Search result tools return compact creator summaries by default. Bulk campaign
+import uses `search_id` server-side, so the agent does not need to paste an
+entire creator list into its context window.
 
 ## Examples
 
@@ -301,3 +343,46 @@ history:
   }
 }
 ```
+
+## Clean-Room Smoke Check
+
+Without a repository checkout, verify npm can resolve the package and both
+binaries can start:
+
+```bash
+npm view @hyperstar/mcp version --silent
+npm exec --yes --package @hyperstar/mcp -- hyperstar --help
+npm exec --yes --package @hyperstar/mcp -- hyperstar-mcp --help
+```
+
+These checks do not authenticate and do not call Hyperstar workflow APIs. They
+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
+
+- `npm error could not determine executable to run`: use the explicit
+  `--package @hyperstar/mcp -- hyperstar` or
+  `--package @hyperstar/mcp -- hyperstar-mcp` form because the package exposes
+  multiple binaries.
+- `No Hyperstar auth configured`: run `hyperstar login` and select a workspace,
+  or set `HYPERSTAR_API_KEY` in the MCP server environment.
+- Workspace errors in browser-login mode: run
+  `hyperstar workspaces list --json`, then
+  `hyperstar workspaces use <organization_id>`.
+- Non-production login opens the wrong app: set both `HYPERSTAR_API_BASE_URL`
+  and `HYPERSTAR_APP_BASE_URL`.
+
+## Development
+
+```sh
+npm install
+npm test
+npm run build
+npm run smoke:npm
+```
+
+`npm run smoke:npm` verifies the published npm package can be resolved and that
+both package binaries print help without requiring local build artifacts,
+authentication, or real workflow API calls.

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,8 +1,8 @@
 {
   "name": "@hyperstar/mcp",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "SEE LICENSE IN LICENSE",
   "description": "Local stdio MCP server and CLI for Hyperstar headless workflows.",
   "keywords": [
     "hyperstar",
@@ -34,6 +34,7 @@
   "files": [
     "dist",
     "scripts/npm-clean-room-smoke.mjs",
+    "LICENSE",
     "README.md",
     "package.json"
   ],

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 });
 }