@jclvsh/dropspace 2.42.0 → 2.48.0

package/README.md

@@ -377,6 +377,22 @@ Reddit engagement (drafted comments in other communities) is paused: its tools a
 | `get_audience_demographics` | Age, gender, country, and city of your Instagram followers and engaged audience (local package only, not the hosted endpoint) |
 | `get_reels_read` | Each Instagram account's latest reels read (local package only, not the hosted endpoint) |
 | `generate_reels_read` | Claude compares your top, middle, and bottom reels of the last 90 days; pro and premium, one a day per account (local package only, not the hosted endpoint) |
+| `list_trial_reels` | Trial reel programs: each Instagram account's program, posting hours, and reshared reels with their 1/3/7-day numbers; pro and premium (local package only) |
+| `update_trial_reel_program` | Turn an account's trial reel program on or off, or change reels per day, auto-approve, skip terms, timezone (send scope to turn on; local package only) |
+| `scan_trial_reels` | Scan an account's reels again and queue the strong ones (local package only) |
+| `update_trial_reel` | Approve, hold, re-caption, or remove a waiting reel, or approve all (send scope to approve; local package only) |
+
+### Reports and workflows
+
+| Tool | Description |
+| ---- | ----------- |
+| `save_report` | Save a markdown report to the user's reports page (local package only) |
+| `list_reports` | Saved reports, newest first, without bodies (local package only) |
+| `get_report` | One report with its markdown body (local package only) |
+
+Prompts (local package only): `instagram_audit`, `best_times_plan`, `winners_report`. Each tells the AI app which tools to call and ends with `save_report`.
+
+CLI: `dropspace reports list|get|delete`.
 
 #### `get_audience` Parameters
 
@@ -385,7 +401,7 @@ Reddit engagement (drafted comments in other communities) is paused: its tools a
 | `window_days` | number | No       | Growth window in days (1-365, default 30) |
 | `include_instagram_insights` | boolean | No | Add Instagram growth analytics to each Instagram entry (default false) |
 
-CLI: `dropspace audience [-w, --window-days <n>] [--instagram-insights]`, `dropspace trial-reels`, `dropspace best-hours [--timezone <zone>]`, `dropspace demographics [--timeframe <this_week|this_month|last_90_days>]`, and `dropspace reels-read [--generate] [--connection-id <id>]`.
+CLI: `dropspace audience [-w, --window-days <n>] [--instagram-insights]`, `dropspace trial-reels`, `dropspace best-hours [--timezone <zone>]`, `dropspace demographics [--timeframe <this_week|this_month|last_90_days>]`, `dropspace reels-read [--generate] [--connection-id <id>]`, and `dropspace trial-reel-program list|set|scan|approve|approve-all|remove`.
 
 With `include_instagram_insights`, each Instagram entry carries `instagram_insights`: follows, unfollows, net, and reach split into followers and non-followers per Pacific-time day, an estimated followers-over-time series rebuilt back from the current count, weekly growth velocity, the share of reach from non-followers, and contact-button taps. Instagram revises the last 7 days (`settled: false`). Each call reads up to 31 days, newest first, so a 90-day window fills over a few calls (`days_pending`). Instagram reports none of this for accounts under 100 followers (`available: false`).
 

package/dist/commands/account.js

@@ -39,4 +39,46 @@ export function registerAccountCommands(program, client) {
             handleError(error);
         }
     });
+    const reports = program.command("reports").description("your saved reports (from the MCP workflows or the API)");
+    reports
+        .command("list")
+        .description("saved reports, newest first, without their bodies")
+        .option("--page <n>", "page number")
+        .option("--page-size <n>", "reports per page (max 100)")
+        .action(async (options) => {
+        try {
+            const params = {};
+            if (options.page)
+                params.page = options.page;
+            if (options.pageSize)
+                params.page_size = options.pageSize;
+            formatOutput(await client.get("/reports", params), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    reports
+        .command("get <id>")
+        .description("one report with its markdown body")
+        .action(async (id) => {
+        try {
+            formatOutput(await client.get(`/reports/${id}`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    reports
+        .command("delete <id>")
+        .description("delete a saved report")
+        .action(async (id) => {
+        try {
+            await client.delete(`/reports/${id}`);
+            formatOutput({ data: { id, deleted: true } }, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/audience.js

@@ -108,4 +108,96 @@ export function registerAudienceCommands(program, client) {
             }
         });
     }
+    const trial = program
+        .command("trial-reel-program")
+        .description("reshare your strongest instagram reels as trial reels (pro and premium)");
+    trial
+        .command("list")
+        .description("each instagram account with its trial reel program, posting hours, and reels")
+        .action(async () => {
+        try {
+            formatOutput(await client.get("/trial-reels"), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    trial
+        .command("set <connectionId>")
+        .description("change a program; --on needs the send scope and scans the account's reels the first time")
+        .option("--on", "turn the program on")
+        .option("--off", "turn the program off")
+        .option("--per-day <n>", "trial reels a day, 1-3")
+        .option("--auto-approve <bool>", "post queued reels without approving each one (true or false)")
+        .option("--skip <terms>", "comma-separated: never queue a reel whose caption contains one")
+        .option("--timezone <tz>", "IANA timezone for posting hours")
+        .action(async (connectionId, options) => {
+        try {
+            const body = {
+                ...(options.on ? { enabled: true } : options.off ? { enabled: false } : {}),
+                ...(options.perDay ? { reels_per_day: Number(options.perDay) } : {}),
+                ...(options.autoApprove !== undefined
+                    ? { auto_approve: ["true", "yes", "on", "1"].includes(options.autoApprove.toLowerCase()) }
+                    : {}),
+                ...(options.skip !== undefined
+                    ? {
+                        skip_caption_terms: options.skip
+                            .split(",")
+                            .map((term) => term.trim())
+                            .filter(Boolean),
+                    }
+                    : {}),
+                ...(options.timezone ? { timezone: options.timezone } : {}),
+            };
+            formatOutput(await client.put(`/trial-reels/programs/${connectionId}`, body), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    trial
+        .command("scan <connectionId>")
+        .description("scan the account's reels again and queue the strong ones")
+        .action(async (connectionId) => {
+        try {
+            formatOutput(await client.post(`/trial-reels/programs/${connectionId}/scan`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    trial
+        .command("approve <itemId>")
+        .description("approve a waiting reel so it posts at the next posting hour (send scope)")
+        .action(async (itemId) => {
+        try {
+            formatOutput(await client.patch(`/trial-reels/items/${itemId}`, { approved: true }), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    trial
+        .command("approve-all <connectionId>")
+        .description("approve every waiting reel with a caption (send scope)")
+        .action(async (connectionId) => {
+        try {
+            formatOutput(await client.post(`/trial-reels/programs/${connectionId}/approve-all`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    trial
+        .command("remove <itemId>")
+        .description("remove a waiting reel for good")
+        .action(async (itemId) => {
+        try {
+            await client.delete(`/trial-reels/items/${itemId}`);
+            formatOutput({ data: { id: itemId, status: "removed" } }, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/server.js

@@ -17,6 +17,8 @@ import { registerRedditTools } from "./tools/reddit.js";
 import { registerAudienceTools } from "./tools/audience.js";
 import { registerCommentTools } from "./tools/comments.js";
 import { registerAccountTools } from "./tools/account.js";
+import { registerTrialReelTools } from "./tools/trial-reels.js";
+import { registerReportTools, registerWorkflowPrompts } from "./tools/reports.js";
 /** Drops tools whose feature is paused before the policy registrar sees them (see PAUSED_TOOLS). */
 function skipPausedTools(registrar) {
     return {
@@ -46,5 +48,11 @@ export function createDropspaceServer({ client, version, profile }) {
     registerAudienceTools(registrar, client);
     registerCommentTools(registrar, client);
     registerAccountTools(registrar, client);
+    registerTrialReelTools(registrar, client);
+    registerReportTools(registrar, client);
+    // Prompts are not tools, so the policy registrar does not filter them: the hosted profile
+    // (frozen for the Meta review) gets none.
+    if (profile === "full")
+        registerWorkflowPrompts(server);
     return server;
 }

package/dist/tool-policy.js

@@ -128,6 +128,14 @@ const FULL_TOOL_POLICY = {
     get_reels_read: localOnly("audience", "read"),
     // spends a Claude call and up to 60 Instagram requests; changes nothing the user posted
     generate_reels_read: localOnly("audience", "write"),
+    list_trial_reels: localOnly("audience", "read"),
+    // turning a program on or approving reels leads to instagram posts
+    update_trial_reel_program: localOnly("audience", "sensitive"),
+    scan_trial_reels: localOnly("audience", "write"),
+    update_trial_reel: localOnly("audience", "sensitive"),
+    save_report: localOnly("account", "write"),
+    list_reports: localOnly("account", "read"),
+    get_report: localOnly("account", "read"),
     get_usage: hosted("usage", "read"),
     get_changelog: hosted("usage", "read"),
     get_dropspace_status: hosted("dropspace", "read"),

package/dist/tools/comments.js

@@ -76,7 +76,7 @@ export function registerCommentTools(server, client) {
             return fail(error);
         }
     });
-    server.tool("list_comment_queue", "every comment still waiting for you across your instagram and youtube posts made through dropspace in the last 30 days (newest 30 posts, newest 50 comments each), newest first, up to 200. waiting: not hidden, not written or answered by your account, and not replied to, hidden, deleted, or dismissed through dropspace. each comment carries its post (platform, post_id, launch_id, launch_name) and claude's read: kind (question, feedback, praise, spam, attack, other; null until sorted), suggested_action (reply, hide, dismiss), and reply_draft for questions and feedback; may_be_answered is true when youtube returned only some replies and none was yours. counts per kind; post_issues lists posts that could not be read. reply with reply_to_comment, delete with delete_comment (launch_id + post_id + comment id); hide or dismiss several with act_on_comments.", {}, async () => {
+    server.tool("list_comment_queue", "every comment still waiting for you across your instagram and youtube posts made through dropspace in the last 30 days (up to 30 posts, the ones with comments first; newest 50 comments each; posts_in_window says how many posts the window has), newest first, up to 200. waiting: not hidden, not written or answered by your account, and not replied to, hidden, deleted, or dismissed through dropspace. each comment carries its post (platform, post_id, launch_id, launch_name) and claude's read: kind (question, feedback, praise, spam, attack, other; null until sorted), suggested_action (reply, hide, dismiss), and reply_draft for questions and feedback; may_be_answered is true when youtube returned only some replies and none was yours. counts per kind; post_issues lists posts that could not be read. reply with reply_to_comment, delete with delete_comment (launch_id + post_id + comment id); hide or dismiss several with act_on_comments.", {}, async () => {
         try {
             return text(await client.get("/comments/queue"));
         }

package/dist/tools/reports.d.ts

@@ -0,0 +1,5 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DropspaceClient } from "../client.js";
+/** The workflow prompts (Instagram audit, best-times plan, winners report). Local package only. */
+export declare function registerWorkflowPrompts(server: McpServer): void;
+export declare function registerReportTools(server: McpServer, client: DropspaceClient): void;

package/dist/tools/reports.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { WORKFLOWS } from "../workflows.js";
+function text(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+function fail(error) {
+    return {
+        content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+    };
+}
+/** The workflow prompts (Instagram audit, best-times plan, winners report). Local package only. */
+export function registerWorkflowPrompts(server) {
+    for (const workflow of WORKFLOWS) {
+        server.registerPrompt(workflow.name, { title: workflow.title, description: workflow.description }, () => ({
+            description: workflow.description,
+            messages: [{ role: "user", content: { type: "text", text: workflow.prompt } }],
+        }));
+    }
+}
+export function registerReportTools(server, client) {
+    server.tool("save_report", "save a markdown report to the user's dropspace reports (the reports page in the app): the end step of the instagram_audit, best_times_plan, and winners_report workflows. title up to 200 characters, body up to 100,000. at most 200 saved reports; past that the save is refused and the user deletes some first. returns the saved report with its id.", {
+        title: z.string().min(1).max(200).describe("report title, e.g. 'Instagram audit - 10/29/2026'"),
+        body: z.string().min(1).max(100_000).describe("the report in markdown"),
+        kind: z.enum(["audit", "best_times", "winners", "other"]).optional().describe("which workflow made it"),
+    }, async ({ title, body, kind }) => {
+        try {
+            return text(await client.post("/reports", {
+                title,
+                body,
+                kind: kind ?? "other",
+                source: "mcp",
+            }));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("list_reports", "the user's saved reports, newest first, without their bodies: id, title, kind (audit, best_times, winners, other), source (mcp or api), created_at. read one with get_report.", {
+        page: z.number().int().min(1).optional(),
+        page_size: z.number().int().min(1).max(100).optional(),
+    }, async ({ page, page_size }) => {
+        try {
+            const params = {};
+            if (page)
+                params.page = String(page);
+            if (page_size)
+                params.page_size = String(page_size);
+            return text(await client.get("/reports", params));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("get_report", "one saved report with its markdown body.", { id: z.string().uuid().describe("report id from list_reports or save_report") }, async ({ id }) => {
+        try {
+            return text(await client.get(`/reports/${id}`));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/dist/tools/trial-reels.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DropspaceClient } from "../client.js";
+export declare function registerTrialReelTools(server: McpServer, client: DropspaceClient): void;

package/dist/tools/trial-reels.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+function text(result) {
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+}
+function fail(error) {
+    return {
+        content: [{ type: "text", text: `error: ${error instanceof Error ? error.message : String(error)}` }],
+        isError: true,
+    };
+}
+export function registerTrialReelTools(server, client) {
+    server.tool("list_trial_reels", "trial reel programs (pro and premium): each connected instagram account with eligible (instagram takes trial reels only from professional accounts with 200+ followers), its program (absent until saved: enabled, auto_approve, reels_per_day 1-3, skip_caption_terms, timezone, last_note), posting_hours (0-23 in the program's timezone: the account's best hours, else 9, 13, 18), and items, newest 100: status queued (waits for approval), posting, posted, won, retired, or failed (failure says why), with reason, caption, the source reel and its views, win_target (half the source's views, capped at 10,000), and checkpoints d1/d3/d7.", {}, async () => {
+        try {
+            return text(await client.get("/trial-reels"));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("update_trial_reel_program", "create or change the trial reel program for one instagram account. turning it on the first time scans the account's reels and queues the strong ones (returned as scan). nothing posts until a reel is approved (update_trial_reel, or auto_approve). approved reels are reshared as instagram trial reels (shown to non-followers only, graduation manual) one per posting hour, never within 2 hours of another dropspace post to that account; each is a launch on the user's plan. enabled or auto_approve true needs the send scope.", {
+        connection_id: z.string().uuid().describe("instagram connection_id from list_trial_reels"),
+        enabled: z.boolean().optional().describe("turn the program on or off"),
+        auto_approve: z.boolean().optional().describe("post queued reels without approving each one"),
+        reels_per_day: z.number().int().min(1).max(3).optional().describe("trial reels a day, 1-3"),
+        skip_caption_terms: z
+            .array(z.string().max(50))
+            .max(20)
+            .optional()
+            .describe("never queue a reel whose caption contains one of these"),
+        timezone: z.string().optional().describe("IANA timezone for posting hours, e.g. America/New_York"),
+        edit_kinds: z
+            .array(z.enum(["reshare", "background", "subtitles", "hook", "sticker"]))
+            .min(1)
+            .optional()
+            .describe("kinds new reels take in turn: reshare (the original video), background (on a colored background), subtitles (burned-in; only reels with speech and no captions on screen), hook (a strong line from later in the reel played first), or sticker (a reply-to-comment card with a comment claude writes)"),
+    }, async ({ connection_id, ...settings }) => {
+        try {
+            return text(await client.put(`/trial-reels/programs/${connection_id}`, settings));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("scan_trial_reels", "scan an instagram account's reels again (last 180 days, up to 100) and queue the ones with 1.5x the median views or more that are older than 21 days and were never queued. returns queued, rated, median_views, and note (why nothing was queued). one scan per account every 10 minutes.", { connection_id: z.string().uuid().describe("instagram connection_id with a saved program") }, async ({ connection_id }) => {
+        try {
+            return text(await client.post(`/trial-reels/programs/${connection_id}/scan`));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("update_trial_reel", "change one waiting (queued) trial reel: approved true lets it post at the next posting hour (send scope; needs a caption), false holds it; caption replaces the caption it posts with (up to 2,200 characters) and holds the reel unless approved true is sent with it; remove true takes it out of the queue for good. approve every waiting reel at once with approve_all.", {
+        id: z.string().uuid().optional().describe("item id from list_trial_reels (not needed with approve_all)"),
+        approved: z.boolean().optional(),
+        caption: z.string().max(2200).optional(),
+        kind: z
+            .enum(["reshare", "background", "subtitles", "hook", "sticker"])
+            .optional()
+            .describe("post the original (reshare) or an edited version (background, subtitles, hook, sticker); a new kind holds the reel"),
+        remove: z.boolean().optional(),
+        approve_all: z
+            .string()
+            .uuid()
+            .optional()
+            .describe("instead of one item: a connection_id whose waiting reels with captions are all approved"),
+    }, async ({ id, approved, caption, kind, remove, approve_all }) => {
+        try {
+            if (approve_all) {
+                return text(await client.post(`/trial-reels/programs/${approve_all}/approve-all`));
+            }
+            if (!id)
+                return fail(new Error("send id, or approve_all with a connection_id"));
+            if (remove) {
+                await client.delete(`/trial-reels/items/${id}`);
+                return text({ data: { id, status: "removed" } });
+            }
+            return text(await client.patch(`/trial-reels/items/${id}`, {
+                ...(approved !== undefined ? { approved } : {}),
+                ...(caption !== undefined ? { caption } : {}),
+                ...(kind !== undefined ? { kind } : {}),
+            }));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+}

package/dist/workflows.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workflow prompts: ready-made instructions an AI app (Claude, ChatGPT, any MCP client) runs
+ * against the dropspace MCP tools, ending with save_report. The MCP server serves them as MCP
+ * prompts, and the docs page imports this file (@jclvsh/dropspace/workflows) to show the same text.
+ */
+export interface Workflow {
+    /** MCP prompt name. */
+    name: string;
+    title: string;
+    description: string;
+    /** The report kind save_report is asked to use. */
+    kind: "audit" | "best_times" | "winners";
+    prompt: string;
+}
+export declare const WORKFLOWS: Workflow[];

package/dist/workflows.js

@@ -0,0 +1,50 @@
+/**
+ * Workflow prompts: ready-made instructions an AI app (Claude, ChatGPT, any MCP client) runs
+ * against the dropspace MCP tools, ending with save_report. The MCP server serves them as MCP
+ * prompts, and the docs page imports this file (@jclvsh/dropspace/workflows) to show the same text.
+ */
+export const WORKFLOWS = [
+    {
+        name: "instagram_audit",
+        title: "Instagram audit",
+        description: "where the account stands: growth, who it reaches, what its reels have in common, what to fix first",
+        kind: "audit",
+        prompt: [
+            "Audit my Instagram account using the dropspace tools.",
+            "1. Call get_audience with include_instagram_insights true and window_days 30: followers, net growth per day, follows vs unfollows, and the share of reach from non-followers.",
+            "2. Call get_audience_demographics: who follows and who engages (age, gender, top countries and cities).",
+            "3. Call get_reels_read; if there is no read from the last 7 days, call generate_reels_read. Use its findings on what the strong and weak reels share.",
+            "4. Call get_best_posting_hours for when followers are online.",
+            "Write the audit in markdown with these sections: Where the account stands (numbers, with dates), Who it reaches, What works, What doesn't, The three changes to make this week. Quote numbers exactly as the tools returned them and say when a tool had no data.",
+            'Then call save_report with kind "audit" and a title like "Instagram audit - <today\'s date>".',
+        ].join("\n"),
+    },
+    {
+        name: "best_times_plan",
+        title: "Best-times plan",
+        description: "a weekly posting schedule built from when the followers are online",
+        kind: "best_times",
+        prompt: [
+            "Build my weekly Instagram posting plan using the dropspace tools.",
+            "1. Call get_best_posting_hours with my timezone: the hourly averages, the weekday-by-hour grid, and the busiest hours.",
+            "2. Call get_autopilot to see the posting times autopilot uses now, if it is set up.",
+            "3. Call list_launches for the last 30 days to see when I actually posted.",
+            "Write the plan in markdown: a table of days and times (at most 2 a day, at least 2 hours apart), why each time was picked (followers online at that hour), and what to change from the current schedule. Say plainly if Instagram had no online-followers numbers (accounts under 100 followers) and fall back to 9 am, 1 pm, and 6 pm.",
+            'Then call save_report with kind "best_times" and a title like "Posting plan - week of <date>".',
+        ].join("\n"),
+    },
+    {
+        name: "winners_report",
+        title: "Winners report",
+        description: "the posts and trial reels that won lately, what they share, and what to make next",
+        kind: "winners",
+        prompt: [
+            "Find my recent winners using the dropspace tools.",
+            "1. Call list_launches for the last 30 days, then get_launch_analytics on the posted ones to get views, likes, comments, shares, and saves.",
+            "2. Call get_trial_reel_analytics and list_trial_reels for trial reels and their 1, 3, and 7-day results (won or retired).",
+            "3. Call get_reels_read for the latest read of the account's reels.",
+            "Rank posts by views relative to the account's usual (the median of the posts you read). Write the report in markdown: the top five with their numbers and links, what they share (topic, hook, format, length, posting time), the bottom three and what they share, and three posts to make next. Use only the numbers the tools returned.",
+            'Then call save_report with kind "winners" and a title like "Winners - <month>".',
+        ].join("\n"),
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.42.0",
+	"version": "2.48.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"repository": {
 		"type": "git",
@@ -27,6 +27,10 @@
 			"types": "./dist/tool-policy.d.ts",
 			"default": "./dist/tool-policy.js"
 		},
+		"./workflows": {
+			"types": "./dist/workflows.d.ts",
+			"default": "./dist/workflows.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"bin": {