@hyperstar/mcp 0.1.13 → 0.1.15

package/README.md

@@ -5,6 +5,9 @@ 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).
+
 ## Install
 
 Run the MCP server directly from npm:
@@ -147,8 +150,13 @@ It also exposes matching prompts:
 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.
+
 ## Examples
 
 Search creators:

package/dist/index.js

@@ -2,8 +2,20 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig } from "./config.js";
 import { createHyperstarMcpServer } from "./server.js";
+const MCP_SERVER_USAGE = [
+    "Usage: hyperstar-mcp [--help]",
+    "",
+    "Starts the Hyperstar stdio MCP server.",
+    "",
+    "Authentication:",
+    "  Run `hyperstar login` first, or set HYPERSTAR_API_KEY in the MCP server environment.",
+].join("\n");
 /** Start the stdio MCP server process. */
 async function main() {
+    if (process.argv.slice(2).some((arg) => arg === "--help" || arg === "-h")) {
+        process.stdout.write(`${MCP_SERVER_USAGE}\n`);
+        return;
+    }
     const config = loadConfig();
     const server = createHyperstarMcpServer(config);
     await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperstar/mcp",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Local stdio MCP server and CLI for Hyperstar headless workflows.",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "scripts/npm-clean-room-smoke.mjs",
     "README.md",
     "package.json"
   ],
@@ -44,6 +45,7 @@
     "format:check": "prettier --check .",
     "prepack": "npm run build",
     "smoke:dev": "npm run build && node scripts/dev-smoke.mjs",
+    "smoke:npm": "node scripts/npm-clean-room-smoke.mjs",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },

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

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(
+  readFileSync(resolve(packageRoot, "package.json"), "utf8"),
+);
+const packageSpec =
+  process.env.HYPERSTAR_MCP_NPM_PACKAGE ??
+  `${packageJson.name}@${packageJson.version}`;
+const scratchDir = mkdtempSync(resolve(tmpdir(), "hyperstar-mcp-npm-smoke-"));
+
+function isLocalPackageSpec(value) {
+  return (
+    value.startsWith("file:") ||
+    value.startsWith(".") ||
+    value.endsWith(".tgz") ||
+    isAbsolute(value)
+  );
+}
+
+function logLocalPackageSpec(value) {
+  console.log(
+    JSON.stringify(
+      {
+        step: "local-package",
+        ok: true,
+        command: [],
+        stdout: [value],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function runStep(step, command, args) {
+  const result = spawnSync(command, args, {
+    cwd: scratchDir,
+    encoding: "utf8",
+    env: process.env,
+    shell: false,
+  });
+  const stdout = result.stdout.trim();
+  const stderr = result.stderr.trim();
+  if (result.status !== 0) {
+    console.error(
+      JSON.stringify(
+        {
+          step,
+          ok: false,
+          command: [command, ...args],
+          status: result.status,
+          stdout,
+          stderr,
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(result.status ?? 1);
+  }
+  console.log(
+    JSON.stringify(
+      {
+        step,
+        ok: true,
+        command: [command, ...args],
+        stdout: stdout.split("\n").slice(0, 8),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+try {
+  if (isLocalPackageSpec(packageSpec)) {
+    logLocalPackageSpec(packageSpec);
+  } else {
+    runStep("registry-version", "npm", [
+      "view",
+      packageSpec,
+      "version",
+      "--silent",
+    ]);
+  }
+  runStep("hyperstar-cli-help", "npm", [
+    "exec",
+    "--yes",
+    "--package",
+    packageSpec,
+    "--",
+    "hyperstar",
+    "--help",
+  ]);
+  runStep("hyperstar-mcp-help", "npm", [
+    "exec",
+    "--yes",
+    "--package",
+    packageSpec,
+    "--",
+    "hyperstar-mcp",
+    "--help",
+  ]);
+} finally {
+  rmSync(scratchDir, { recursive: true, force: true });
+}