@hyperstar/mcp 0.1.11 → 0.1.12

package/dist/tool-guidance.d.ts

@@ -8,3 +8,5 @@ export declare function campaignImportGuidance(payload: JsonObject, campaignId:
 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;
+/** Add deterministic next-step guidance after listing inbox threads. */
+export declare function inboxThreadListGuidance(payload: JsonObject): JsonObject;

package/dist/tool-guidance.js

@@ -63,6 +63,18 @@ export function readinessGuidance(payload, input) {
         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".',
     };
 }
+/** Add deterministic next-step guidance after listing inbox threads. */
+export function inboxThreadListGuidance(payload) {
+    return {
+        ...payload,
+        next_tools: [
+            "get_inbox_aggregates",
+            "update_inbox_thread_state",
+            "send_inbox_reply",
+        ],
+        agent_guidance: "Use get_inbox_aggregates for counts, update_inbox_thread_state for archive/star/snooze/read-state changes, and send_inbox_reply only after explicit user authorization because send_inbox_reply performs a real send.",
+    };
+}
 function recipientTargetArgument(ids, selection) {
     if (ids !== undefined) {
         return { type: "ids", campaign_creator_ids: [...ids] };

package/dist/tools.js

@@ -2,7 +2,7 @@ import { bulkEmailQueuedResult } from "./bulk-email-guidance.js";
 import { readinessRequestBody, startBulkEmailRequestBody, } from "./bulk-email-tool-body.js";
 import { projectSearchResultPage } from "./search-result-projection.js";
 import { TOOL_DESCRIPTIONS } from "./tool-descriptions.js";
-import { campaignImportGuidance, campaignRosterGuidance, readinessGuidance, searchGuidance, } from "./tool-guidance.js";
+import { campaignImportGuidance, campaignRosterGuidance, inboxThreadListGuidance, readinessGuidance, searchGuidance, } from "./tool-guidance.js";
 import { toolResult } from "./tool-result.js";
 import { compactJsonObject, pathSegment, queryFrom, } from "./tool-http-helpers.js";
 import { BulkEmailJobResponseSchema, BulkEmailReadinessResponseSchema, CampaignDetailResponseSchema, CampaignCreatorsResponseSchema, CampaignImportResponseSchema, CampaignsResponseSchema, InboxAggregatesResponseSchema, InboxThreadPageResponseSchema, InboxWorkspaceStateResponseSchema, JsonObjectSchema, SearchCreatedResponseSchema, SearchResultsResponseSchema, WhoamiResponseSchema, } from "./schemas.js";
@@ -112,7 +112,7 @@ export function createToolHandlers(client, options = {}) {
         },
         listInboxThreads: async (input) => {
             const parsedInput = ListInboxThreadsInputSchema.parse(input);
-            return InboxThreadPageResponseSchema.parse(await client.get("/v1/inbox/threads", queryFrom(parsedInput)));
+            return inboxThreadListGuidance(InboxThreadPageResponseSchema.parse(await client.get("/v1/inbox/threads", queryFrom(parsedInput))));
         },
         getInboxAggregates: async (input) => {
             const parsedInput = InboxFiltersInputSchema.parse(input);

package/dist/workflow-content.d.ts

@@ -11,6 +11,7 @@ export declare const CLI_WORKFLOW_SEQUENCE: readonly ["list_workspaces", "select
 export declare const SERVICE_ACCOUNT_WORKFLOW_SEQUENCE: readonly ["list_workspaces", "hyperstar_whoami", "search_creators", "list_campaigns or create_campaign", "save_search_results_to_campaign", "list_campaign_creators", "check_bulk_email_readiness", "WARNING: start_bulk_email and send_inbox_reply perform real sends."];
 export declare const CLI_SAFETY_NOTES: readonly ["Run list_workspaces and select_workspace before Product API calls that require workspace scope.", "Run hyperstar_whoami after selecting a workspace to confirm the authenticated principal.", "Run list_campaigns or create_campaign before save_search_results_to_campaign when the user has not supplied a campaign_id.", "check_bulk_email_readiness is the final dry-run gate before any bulk send.", "start_bulk_email and send_inbox_reply perform real sends."];
 export declare const SERVICE_ACCOUNT_SAFETY_NOTES: readonly ["Service-account auth is already workspace-scoped; select_workspace is only for local browser CLI auth.", "Run list_workspaces and hyperstar_whoami before workflow tools to confirm the authenticated workspace.", "Run list_campaigns or create_campaign before save_search_results_to_campaign when the user has not supplied a campaign_id.", "check_bulk_email_readiness is the final dry-run gate before any bulk send.", "start_bulk_email and send_inbox_reply perform real sends."];
+export declare const WORKFLOW_DATA_FLOW_NOTES: readonly ["search_creators returns a search_id plus compact creator summaries; save_search_results_to_campaign consumes search_id server-side, so agents do not need to load every creator row into context.", "check_bulk_email_readiness and start_bulk_email require recipient_target, either exact campaign_creator_ids or a narrowed campaign_creator_selection.", "Use list_campaign_creators after saving search results to find campaign_creator_ids for explicit recipient_target calls.", "Use list_inbox_threads for triage, update_inbox_thread_state for non-send state changes, and send_inbox_reply only after explicit user authorization."];
 export declare const SEARCH_FILTER_GUIDANCE: readonly ["filters is a structured JSON object validated by the MCP before it is forwarded to Product API search.", "Use range objects such as `follower_range: {\"min\": 1000, \"max\": 100000}`, `avg_engagement_rate`, `avg_views`, `gmv`, and `gpm`.", "Use boolean/string filters such as `has_email`, `email_contactability`, `is_verified`, `has_tiktok_shop`, `creator_gender`, `creator_language`, `category_1`, and Instagram `category_name`.", "Put broad niches, verticals, and countries in `query`/`region` unless a named structured filter applies; do not invent `country`, `categories`, `follower_count`, or `engagement_rate` filter keys.", "Use sort_by for relevance, follower_count, engagement_rate, avg_views, views_growth_rate, gmv, or gpm; gmv and gpm are TikTok-only.", "Keep filters narrow and serializable; use get_search_results pagination instead of loading every creator row into context."];
 export declare const workflowGuideResourceDefinitions: readonly [{
     readonly kind: "headless-workflow";

package/dist/workflow-content.js

@@ -33,6 +33,12 @@ export const SERVICE_ACCOUNT_SAFETY_NOTES = [
     "check_bulk_email_readiness is the final dry-run gate before any bulk send.",
     "start_bulk_email and send_inbox_reply perform real sends.",
 ];
+export const WORKFLOW_DATA_FLOW_NOTES = [
+    "search_creators returns a search_id plus compact creator summaries; save_search_results_to_campaign consumes search_id server-side, so agents do not need to load every creator row into context.",
+    "check_bulk_email_readiness and start_bulk_email require recipient_target, either exact campaign_creator_ids or a narrowed campaign_creator_selection.",
+    "Use list_campaign_creators after saving search results to find campaign_creator_ids for explicit recipient_target calls.",
+    "Use list_inbox_threads for triage, update_inbox_thread_state for non-send state changes, and send_inbox_reply only after explicit user authorization.",
+];
 export const SEARCH_FILTER_GUIDANCE = [
     "filters is a structured JSON object validated by the MCP before it is forwarded to Product API search.",
     'Use range objects such as `follower_range: {"min": 1000, "max": 100000}`, `avg_engagement_rate`, `avg_views`, `gmv`, and `gpm`.',
@@ -77,12 +83,14 @@ export function workflowGuideJson(authMode) {
         return {
             sequence: [...CLI_WORKFLOW_SEQUENCE],
             safety_notes: [...CLI_SAFETY_NOTES],
+            data_flow_notes: [...WORKFLOW_DATA_FLOW_NOTES],
             resources: workflowGuideResourceDefinitions.map((resource) => resource.uri),
         };
     }
     return {
         sequence: [...SERVICE_ACCOUNT_WORKFLOW_SEQUENCE],
         safety_notes: [...SERVICE_ACCOUNT_SAFETY_NOTES],
+        data_flow_notes: [...WORKFLOW_DATA_FLOW_NOTES],
         resources: workflowGuideResourceDefinitions.map((resource) => resource.uri),
     };
 }
@@ -103,6 +111,9 @@ export function buildWorkflowMarkdown(kind) {
                 "",
                 "Always confirm workspace and scopes with `hyperstar_whoami` before mutating campaigns, sending bulk email, or replying in the inbox.",
                 "",
+                "## Data Flow",
+                unorderedList(WORKFLOW_DATA_FLOW_NOTES),
+                "",
                 "## Search Filters",
                 unorderedList(SEARCH_FILTER_GUIDANCE),
             ].join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperstar/mcp",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Local stdio MCP server and CLI for Hyperstar headless workflows.",