@hyperstar/mcp 0.1.6 → 0.1.10

package/dist/bulk-email-tool-body.js

@@ -0,0 +1,37 @@
+import { campaignCreatorSelectionBody } from "./campaign-creator-selection.js";
+import { compactJsonObject } from "./tool-http-helpers.js";
+/** Build the campaign bulk-email readiness request body. */
+export function readinessRequestBody(input) {
+    return campaignRecipientTargetBody(input);
+}
+/** Build the campaign bulk-email job request body. */
+export function startBulkEmailRequestBody(input) {
+    return compactJsonObject([
+        ["subject", input.subject],
+        ["body_text", input.body_text],
+        ["from_email", input.from_email],
+        ["attachments", input.attachments],
+        ...campaignRecipientTargetEntries(input),
+        ["form_id", input.form_id],
+        ["form_language", input.form_language],
+        ["idempotency_key", input.idempotency_key],
+        ["send_confirmation", input.send_confirmation],
+    ]);
+}
+function campaignRecipientTargetBody(input) {
+    return compactJsonObject(campaignRecipientTargetEntries(input));
+}
+function campaignRecipientTargetEntries(input) {
+    return [
+        [
+            "campaign_creator_ids",
+            "campaign_creator_ids" in input ? input.campaign_creator_ids : undefined,
+        ],
+        [
+            "campaign_creator_selection",
+            campaignCreatorSelectionBody("campaign_creator_selection" in input
+                ? input.campaign_creator_selection
+                : undefined),
+        ],
+    ];
+}

package/dist/campaign-creator-selection.js

@@ -15,4 +15,3 @@ export function campaignCreatorSelectionBody(selection) {
         ["excluded_ids", selection.excluded_ids],
     ]);
 }
-//# sourceMappingURL=campaign-creator-selection.js.map

package/dist/cli.js

@@ -278,19 +278,16 @@ function resolveLoginAppBaseUrl(env, apiBaseUrl) {
     }
     return appBaseUrlForApiBaseUrl(apiBaseUrl);
 }
-/** Map known deployed Product API origins to their matching frontend origins. */
+/** Map public Product API origins to their matching frontend origins. */
 function appBaseUrlForApiBaseUrl(apiBaseUrl) {
     const origin = new URL(apiBaseUrl).origin;
-    if (origin === "https://autopilot.dev.hyper-star.org") {
-        return "https://app.dev.hyper-star.org";
-    }
     if (origin === "https://autopilot.hyper-star.org") {
         return DEFAULT_APP_BASE_URL;
     }
     if (origin === DEFAULT_API_BASE_URL) {
         return DEFAULT_APP_BASE_URL;
     }
-    throw new Error("Set HYPERSTAR_APP_BASE_URL when HYPERSTAR_API_BASE_URL does not use a known Hyperstar API origin");
+    throw new Error("Set HYPERSTAR_APP_BASE_URL when HYPERSTAR_API_BASE_URL does not use the production Hyperstar API origin");
 }
 /** Open the system browser for the authorization request. */
 async function openBrowser(url) {
@@ -323,4 +320,3 @@ if (isDirectCliInvocation(import.meta.url, process.argv[1])) {
         process.exitCode = exitCode;
     });
 }
-//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export type HyperstarDiscoveryOptions = {
+    readonly apiBaseUrl: string;
+};
+/** Register static MCP resources and prompts that explain Hyperstar workflows. */
+export declare function registerHyperstarDiscovery(server: McpServer, options: HyperstarDiscoveryOptions): void;

package/dist/discovery.js

@@ -0,0 +1,62 @@
+import { buildWorkflowMarkdown, workflowGuideResourceDefinitions, } from "./workflow-content.js";
+const workflowPromptDefinitions = [
+    {
+        name: "hyperstar_headless_workflow",
+        title: "Hyperstar Headless Workflow",
+        description: "Use Hyperstar search, campaign, bulk email, and inbox tools in the recommended order.",
+        kind: "headless-workflow",
+    },
+    {
+        name: "hyperstar_search_to_campaign",
+        title: "Hyperstar Search To Campaign",
+        description: "Search creators with compact results and save selected results to a campaign.",
+        kind: "search-to-campaign",
+    },
+    {
+        name: "hyperstar_bulk_email_safety",
+        title: "Hyperstar Bulk Email Safety",
+        description: "Check readiness and idempotency before a real bulk-email send.",
+        kind: "bulk-email-safety",
+    },
+    {
+        name: "hyperstar_inbox_workflow",
+        title: "Hyperstar Inbox Workflow",
+        description: "Read, triage, and reply to inbox threads safely.",
+        kind: "inbox",
+    },
+];
+/** Register static MCP resources and prompts that explain Hyperstar workflows. */
+export function registerHyperstarDiscovery(server, options) {
+    void options;
+    for (const resource of workflowGuideResourceDefinitions) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: "text/markdown",
+        }, (uri) => ({
+            contents: [
+                {
+                    uri: uri.toString(),
+                    mimeType: "text/markdown",
+                    text: buildWorkflowMarkdown(resource.kind),
+                },
+            ],
+        }));
+    }
+    for (const prompt of workflowPromptDefinitions) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description,
+        }, () => ({
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: buildWorkflowMarkdown(prompt.kind),
+                    },
+                },
+            ],
+        }));
+    }
+}

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,12 +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

@@ -0,0 +1,19 @@
+export declare const TOOL_DESCRIPTIONS: {
+    readonly hyperstarWhoami: "Inspect the authenticated Hyperstar principal, workspace, scopes, and capabilities before running workflow tools.";
+    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. 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. 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 user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key.";
+};

package/dist/tool-descriptions.js

@@ -0,0 +1,19 @@
+export const TOOL_DESCRIPTIONS = {
+    hyperstarWhoami: "Inspect the authenticated Hyperstar principal, workspace, scopes, and capabilities before running workflow tools.",
+    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. 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. 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 user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key.",
+};

package/dist/tool-guidance.d.ts

@@ -0,0 +1,10 @@
+import type { JsonObject } from "./http.js";
+import type { CheckBulkEmailReadinessInput } from "./tool-inputs.js";
+/** Add next-step guidance after creator search. */
+export declare function searchGuidance(page: JsonObject): JsonObject;
+/** Add deterministic next-step guidance after campaign import. */
+export declare function campaignImportGuidance(payload: JsonObject, campaignId: number): JsonObject;
+/** Add deterministic next-step guidance after listing campaign creators. */
+export declare function campaignRosterGuidance(payload: JsonObject, campaignId: number): JsonObject;
+/** Add send or no-send guidance after the readiness dry run. */
+export declare function readinessGuidance(payload: JsonObject, input: CheckBulkEmailReadinessInput): JsonObject;

package/dist/tool-guidance.js

@@ -0,0 +1,82 @@
+import { campaignCreatorSelectionBody } from "./campaign-creator-selection.js";
+import { compactJsonObject } from "./tool-http-helpers.js";
+/** Add next-step guidance after creator search. */
+export function searchGuidance(page) {
+    return {
+        ...page,
+        next_tools: [
+            "list_campaigns",
+            "create_campaign",
+            "save_search_results_to_campaign",
+        ],
+        agent_guidance: "Use list_campaigns or create_campaign to choose a campaign_id. If the user already supplied a campaign_id, call save_search_results_to_campaign with this search_id; do not load every creator into context.",
+    };
+}
+/** Add deterministic next-step guidance after campaign import. */
+export function campaignImportGuidance(payload, campaignId) {
+    return {
+        ...payload,
+        next_tool: "list_campaign_creators",
+        next_arguments: { campaign_id: campaignId },
+        agent_guidance: "Search results were saved server-side. Call list_campaign_creators to inspect the campaign roster before outreach.",
+    };
+}
+/** Add deterministic next-step guidance after listing campaign creators. */
+export function campaignRosterGuidance(payload, campaignId) {
+    return {
+        ...payload,
+        next_tool: "check_bulk_email_readiness",
+        next_arguments: { campaign_id: campaignId },
+        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,
+            agent_guidance: "Do not call start_bulk_email: no selected recipients are currently sendable. Adjust the campaign roster or recipient selection, then run check_bulk_email_readiness again.",
+        };
+    }
+    return {
+        ...payload,
+        next_tool: "start_bulk_email",
+        next_arguments: compactJsonObject([
+            ["campaign_id", input.campaign_id],
+            [
+                "recipient_target",
+                recipientTargetArgument(campaignCreatorIds, campaignCreatorSelection),
+            ],
+        ]),
+        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) {
+    return campaignCreatorSelectionBody(selection);
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? value
+        : undefined;
+}

package/dist/tool-http-helpers.js

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