@jclvsh/dropspace 2.43.0 → 2.48.0

package/README.md

@@ -382,6 +382,18 @@ Reddit engagement (drafted comments in other communities) is paused: its tools a
 | `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
 
 | Parameter     | Type   | Required | Description                               |

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/server.js

@@ -18,6 +18,7 @@ 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 {
@@ -48,5 +49,10 @@ export function createDropspaceServer({ client, version, profile }) {
     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

@@ -133,6 +133,9 @@ const FULL_TOOL_POLICY = {
     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/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.js

@@ -28,6 +28,11 @@ export function registerTrialReelTools(server, client) {
             .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));
@@ -48,13 +53,17 @@ export function registerTrialReelTools(server, client) {
         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, remove, approve_all }) => {
+    }, async ({ id, approved, caption, kind, remove, approve_all }) => {
         try {
             if (approve_all) {
                 return text(await client.post(`/trial-reels/programs/${approve_all}/approve-all`));
@@ -68,6 +77,7 @@ export function registerTrialReelTools(server, client) {
             return text(await client.patch(`/trial-reels/items/${id}`, {
                 ...(approved !== undefined ? { approved } : {}),
                 ...(caption !== undefined ? { caption } : {}),
+                ...(kind !== undefined ? { kind } : {}),
             }));
         }
         catch (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.43.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": {