@hyperstar/mcp 0.1.9 → 0.1.11

package/dist/config.js

@@ -26,7 +26,14 @@ export function loadConfig(options = process.env) {
     if (state === null) {
         throw new Error("Run `hyperstar login` or set HYPERSTAR_API_KEY");
     }
-    const cliApiBaseUrl = normalizeBaseUrl(env.HYPERSTAR_API_BASE_URL?.trim() ?? state.apiBaseUrl, "HYPERSTAR_API_BASE_URL");
+    const stateApiBaseUrl = normalizeBaseUrl(state.apiBaseUrl, "stored Hyperstar auth API base URL");
+    const rawCliApiBaseUrl = env.HYPERSTAR_API_BASE_URL?.trim();
+    const cliApiBaseUrl = normalizeBaseUrl(rawCliApiBaseUrl === undefined || rawCliApiBaseUrl.length === 0
+        ? stateApiBaseUrl
+        : rawCliApiBaseUrl, "HYPERSTAR_API_BASE_URL");
+    if (rawCliApiBaseUrl !== undefined && rawCliApiBaseUrl.length > 0) {
+        assertCliApiBaseUrlMatchesState(cliApiBaseUrl, stateApiBaseUrl);
+    }
     const cliAppBaseUrl = normalizeBaseUrl(env.HYPERSTAR_APP_BASE_URL?.trim() ?? state.appBaseUrl, "HYPERSTAR_APP_BASE_URL");
     const client = createCliAuthClient({
         apiBaseUrl: cliApiBaseUrl,
@@ -79,6 +86,13 @@ export function redactSecret(value) {
 function isValidApiKeyHeaderValue(value) {
     return /^[\x21-\x7e]+$/.test(value);
 }
+/** Refuse to send persisted CLI tokens to a different API base URL. */
+function assertCliApiBaseUrlMatchesState(requestedApiBaseUrl, stateApiBaseUrl) {
+    if (requestedApiBaseUrl === stateApiBaseUrl) {
+        return;
+    }
+    throw new Error("Run `hyperstar login` again before changing HYPERSTAR_API_BASE_URL");
+}
 /** Normalize an env-provided base URL. */
 export function normalizeBaseUrl(rawBaseUrl, envName) {
     let parsed;
@@ -98,4 +112,3 @@ export function normalizeBaseUrl(rawBaseUrl, envName) {
     }
     return parsed.toString().replace(/\/+$/, "");
 }
-//# sourceMappingURL=config.js.map

package/dist/discovery.js

@@ -60,4 +60,3 @@ export function registerHyperstarDiscovery(server, options) {
         }));
     }
 }
-//# sourceMappingURL=discovery.js.map

package/dist/http.js

@@ -157,4 +157,3 @@ function redactSecrets(value, secrets) {
     }
     return value;
 }
-//# sourceMappingURL=http.js.map

package/dist/index.js

@@ -13,4 +13,3 @@ main().catch((error) => {
     process.stderr.write(`Failed to start Hyperstar MCP server: ${message}\n`);
     process.exitCode = 1;
 });
-//# sourceMappingURL=index.js.map

package/dist/package-metadata.d.ts

@@ -0,0 +1,2 @@
+/** Read package metadata from the package root at runtime. */
+export declare function packageVersion(): string;

package/dist/package-metadata.js

@@ -0,0 +1,12 @@
+import { readFileSync } from "node:fs";
+import { JsonObjectSchema } from "./schemas.js";
+/** Read package metadata from the package root at runtime. */
+export function packageVersion() {
+    const raw = readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const metadata = JsonObjectSchema.parse(JSON.parse(raw));
+    const version = metadata.version;
+    if (typeof version !== "string" || version.trim().length === 0) {
+        throw new Error("package.json version is missing");
+    }
+    return version;
+}

package/dist/schemas.js

@@ -66,4 +66,3 @@ export const BulkEmailJobResponseSchema = JsonObjectSchema;
 export const InboxThreadPageResponseSchema = JsonObjectSchema;
 export const InboxAggregatesResponseSchema = JsonObjectSchema;
 export const InboxWorkspaceStateResponseSchema = JsonObjectSchema;
-//# sourceMappingURL=schemas.js.map

package/dist/search-result-projection.d.ts

@@ -7,4 +7,6 @@ export type SearchResultPage = {
     readonly limit: number;
 };
 /** Project search results to the requested MCP-facing detail level. */
-export declare function projectSearchResultPage(page: SearchResultPage, detailLevel: SearchResultDetailLevel): JsonObject;
+export declare function projectSearchResultPage(page: SearchResultPage, detailLevel: SearchResultDetailLevel, searchId?: string, options?: {
+    readonly deterministicNextPage?: boolean;
+}): JsonObject;

package/dist/search-result-projection.js

@@ -1,13 +1,15 @@
 import { compactJsonObject } from "./tool-http-helpers.js";
 /** Project search results to the requested MCP-facing detail level. */
-export function projectSearchResultPage(page, detailLevel) {
+export function projectSearchResultPage(page, detailLevel, searchId, options = {}) {
+    const pagination = paginationGuidance(page, searchId, options);
     if (detailLevel === "full") {
-        return { ...page, detail_level: detailLevel };
+        return { ...page, detail_level: detailLevel, ...pagination };
     }
     return {
         ...page,
         creators: page.creators.map(compactCreatorSummary),
         detail_level: detailLevel,
+        ...pagination,
     };
 }
 /** Return a compact creator summary suitable for model context. */
@@ -71,4 +73,32 @@ function stringArrayValue(value) {
     }
     return value;
 }
-//# sourceMappingURL=search-result-projection.js.map
+function paginationGuidance(page, searchId, options) {
+    const nextOffset = page.offset + page.limit;
+    const hasMore = nextOffset < page.total;
+    const includeDeterministicNext = options.deterministicNextPage !== false &&
+        hasMore &&
+        searchId !== undefined;
+    return compactJsonObject([
+        ["has_more", hasMore],
+        ["next_offset", hasMore ? nextOffset : undefined],
+        [
+            "agent_guidance",
+            searchId === undefined
+                ? undefined
+                : "Use search_id server-side for campaign import. Page with get_search_results only when the user needs more creator summaries; do not load every creator into context.",
+        ],
+        ["next_tool", includeDeterministicNext ? "get_search_results" : undefined],
+        [
+            "next_arguments",
+            includeDeterministicNext
+                ? {
+                    search_id: searchId,
+                    offset: nextOffset,
+                    limit: page.limit,
+                    detail_level: "summary",
+                }
+                : undefined,
+        ],
+    ]);
+}

package/dist/server.js

@@ -1,14 +1,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { registerHyperstarDiscovery } from "./discovery.js";
 import { createHyperstarClient } from "./http.js";
+import { packageVersion } from "./package-metadata.js";
 import { registerHyperstarTools } from "./tools.js";
 /** Create the Hyperstar MCP server and register HTTP-backed workflow tools. */
 export function createHyperstarMcpServer(config) {
-    const server = new McpServer({ name: "hyperstar", version: "0.1.0" });
+    const server = new McpServer({
+        name: "hyperstar",
+        version: packageVersion(),
+    });
     registerHyperstarDiscovery(server, { apiBaseUrl: config.apiBaseUrl });
     registerHyperstarTools(server, createHyperstarClient({ config }), config.authMode === "cli"
         ? { workspaceSelection: config.workspaceSelection }
         : {});
     return server;
 }
-//# sourceMappingURL=server.js.map

package/dist/tool-descriptions.d.ts

@@ -3,17 +3,17 @@ export declare const TOOL_DESCRIPTIONS: {
     readonly listWorkspaces: "List Hyperstar workspaces available to the current auth session. In local browser CLI auth, call select_workspace next when a workspace is not selected.";
     readonly selectWorkspace: "Persist the Hyperstar workspace selected for CLI-authenticated tools. Call hyperstar_whoami next to confirm scope.";
     readonly workflowGuide: "Return the recommended Hyperstar workflow sequence, discovery resources, and send-safety notes.";
-    readonly searchCreators: "Create a creator search and return the first page as compact creator summaries. Use search_id with save_search_results_to_campaign; request detail_level full only when raw rows are needed.";
+    readonly searchCreators: "Create a creator search and return the first page as compact creator summaries. Filters use structured keys such as follower_range, avg_engagement_rate, avg_views, has_email, email_contactability, creator_language, category_1, category_name, gmv, and gpm. Put broad niches in query unless a platform-specific category field applies. Use search_id with save_search_results_to_campaign; request detail_level full only when raw rows are needed.";
     readonly getSearchResults: "Page through an existing creator search. Defaults to compact creator summaries; use detail_level full only for raw detail-on-demand pages.";
     readonly listCampaigns: "List campaigns in the authenticated workspace so agents can choose a campaign_id before saving search results.";
     readonly createCampaign: "Create a campaign in the authenticated workspace. Use the returned campaign id with save_search_results_to_campaign.";
     readonly saveSearchResultsToCampaign: "Save selected or top-ranked creator search results to a campaign roster server-side using search_id.";
     readonly listCampaignCreators: "List creators saved on a campaign roster. Call check_bulk_email_readiness before any bulk-email send.";
-    readonly checkBulkEmailReadiness: "The final dry-run gate before bulk email. Checks selected campaign recipients and returns sendability guidance.";
-    readonly startBulkEmail: "REAL SEND: start a campaign bulk-email job with an explicit idempotency key after readiness has passed.";
+    readonly checkBulkEmailReadiness: "The final dry-run gate before bulk email. Requires recipient_target with exact IDs or a narrowed selection, checks those selected recipients, and returns sendability guidance.";
+    readonly startBulkEmail: "REAL SEND: start a campaign bulk-email job after readiness has passed and the user authorized sending. Requires recipient_target, an explicit idempotency key, and send_confirmation: \"user_authorized\".";
     readonly getBulkEmailJob: "Read campaign bulk-email job status after start_bulk_email returns a job_id.";
     readonly listInboxThreads: "List Hyperstar inbox threads with filters for triage before reading or replying.";
     readonly getInboxAggregates: "Read aggregate counts for Hyperstar inbox filters to summarize inbox state.";
     readonly updateInboxThreadState: "Archive, snooze, star, or set read state for one inbox thread without sending a message.";
-    readonly sendInboxReply: "REAL SEND: send one reply to a Hyperstar inbox thread with an explicit idempotency key.";
+    readonly sendInboxReply: "REAL SEND: send one user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key.";
 };

package/dist/tool-descriptions.js

@@ -3,18 +3,17 @@ export const TOOL_DESCRIPTIONS = {
     listWorkspaces: "List Hyperstar workspaces available to the current auth session. In local browser CLI auth, call select_workspace next when a workspace is not selected.",
     selectWorkspace: "Persist the Hyperstar workspace selected for CLI-authenticated tools. Call hyperstar_whoami next to confirm scope.",
     workflowGuide: "Return the recommended Hyperstar workflow sequence, discovery resources, and send-safety notes.",
-    searchCreators: "Create a creator search and return the first page as compact creator summaries. Use search_id with save_search_results_to_campaign; request detail_level full only when raw rows are needed.",
+    searchCreators: "Create a creator search and return the first page as compact creator summaries. Filters use structured keys such as follower_range, avg_engagement_rate, avg_views, has_email, email_contactability, creator_language, category_1, category_name, gmv, and gpm. Put broad niches in query unless a platform-specific category field applies. Use search_id with save_search_results_to_campaign; request detail_level full only when raw rows are needed.",
     getSearchResults: "Page through an existing creator search. Defaults to compact creator summaries; use detail_level full only for raw detail-on-demand pages.",
     listCampaigns: "List campaigns in the authenticated workspace so agents can choose a campaign_id before saving search results.",
     createCampaign: "Create a campaign in the authenticated workspace. Use the returned campaign id with save_search_results_to_campaign.",
     saveSearchResultsToCampaign: "Save selected or top-ranked creator search results to a campaign roster server-side using search_id.",
     listCampaignCreators: "List creators saved on a campaign roster. Call check_bulk_email_readiness before any bulk-email send.",
-    checkBulkEmailReadiness: "The final dry-run gate before bulk email. Checks selected campaign recipients and returns sendability guidance.",
-    startBulkEmail: "REAL SEND: start a campaign bulk-email job with an explicit idempotency key after readiness has passed.",
+    checkBulkEmailReadiness: "The final dry-run gate before bulk email. Requires recipient_target with exact IDs or a narrowed selection, checks those selected recipients, and returns sendability guidance.",
+    startBulkEmail: 'REAL SEND: start a campaign bulk-email job after readiness has passed and the user authorized sending. Requires recipient_target, an explicit idempotency key, and send_confirmation: "user_authorized".',
     getBulkEmailJob: "Read campaign bulk-email job status after start_bulk_email returns a job_id.",
     listInboxThreads: "List Hyperstar inbox threads with filters for triage before reading or replying.",
     getInboxAggregates: "Read aggregate counts for Hyperstar inbox filters to summarize inbox state.",
     updateInboxThreadState: "Archive, snooze, star, or set read state for one inbox thread without sending a message.",
-    sendInboxReply: "REAL SEND: send one reply to a Hyperstar inbox thread with an explicit idempotency key.",
+    sendInboxReply: "REAL SEND: send one user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key.",
 };
-//# sourceMappingURL=tool-descriptions.js.map

package/dist/tool-guidance.js

@@ -27,12 +27,17 @@ export function campaignRosterGuidance(payload, campaignId) {
         ...payload,
         next_tool: "check_bulk_email_readiness",
         next_arguments: { campaign_id: campaignId },
-        agent_guidance: "Before any bulk email, call check_bulk_email_readiness for the exact selected campaign_creator_ids or selection filter.",
+        next_required_arguments: ["recipient_target"],
+        agent_guidance: "Before any bulk email, call check_bulk_email_readiness with recipient_target set to exact campaign creator IDs or a narrowed selection filter.",
     };
 }
 /** Add send or no-send guidance after the readiness dry run. */
 export function readinessGuidance(payload, input) {
     const sendable = numberValue(payload.sendable);
+    const campaignCreatorIds = "campaign_creator_ids" in input ? input.campaign_creator_ids : undefined;
+    const campaignCreatorSelection = "campaign_creator_selection" in input
+        ? input.campaign_creator_selection
+        : undefined;
     if (sendable === undefined || sendable <= 0) {
         return {
             ...payload,
@@ -44,14 +49,27 @@ export function readinessGuidance(payload, input) {
         next_tool: "start_bulk_email",
         next_arguments: compactJsonObject([
             ["campaign_id", input.campaign_id],
-            ["campaign_creator_ids", input.campaign_creator_ids],
             [
-                "campaign_creator_selection",
-                selectionBody(input.campaign_creator_selection),
+                "recipient_target",
+                recipientTargetArgument(campaignCreatorIds, campaignCreatorSelection),
             ],
         ]),
-        next_required_arguments: ["subject", "body_text", "idempotency_key"],
-        agent_guidance: "Readiness passed. start_bulk_email performs a real send, so only call it after user authorization and after filling subject, body_text, and a stable idempotency_key.",
+        next_required_arguments: [
+            "subject",
+            "body_text",
+            "idempotency_key",
+            "send_confirmation",
+        ],
+        agent_guidance: 'Readiness passed. start_bulk_email performs a real send, so only call it after user authorization and after filling subject, body_text, a stable idempotency_key, and send_confirmation: "user_authorized".',
+    };
+}
+function recipientTargetArgument(ids, selection) {
+    if (ids !== undefined) {
+        return { type: "ids", campaign_creator_ids: [...ids] };
+    }
+    return {
+        type: "selection",
+        campaign_creator_selection: selectionBody(selection) ?? {},
     };
 }
 function selectionBody(selection) {
@@ -62,4 +80,3 @@ function numberValue(value) {
         ? value
         : undefined;
 }
-//# sourceMappingURL=tool-guidance.js.map

package/dist/tool-http-helpers.js

@@ -33,4 +33,3 @@ export function compactJsonObject(entries) {
     }
     return output;
 }
-//# sourceMappingURL=tool-http-helpers.js.map