@hyperstar/mcp 0.1.15 → 0.1.16

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
 
@@ -144,18 +142,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 +340,44 @@ 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
+only prove that npm can resolve the package and both binaries can start.
+
+## 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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hyperstar/mcp",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "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"
   ],