@jclvsh/dropspace 2.43.0 → 2.49.0

package/README.md

@@ -382,6 +382,23 @@ 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) |
+| `list_songs` | Your songs for song to reels, newest first (pro and premium; local package only) |
+| `get_song` | One song with its waveform peaks (local package only) |
+| `add_song` | Add a song from a YouTube or SoundCloud link, or a public audio file url (local package only) |
+| `get_song_lyrics` | The song's lyrics with word timings, transcribed once (local package only) |
+| `delete_song` | Delete a song and its audio file (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/cli.js

@@ -19,6 +19,7 @@ import { registerAutopilotCommands } from "./commands/autopilot.js";
 import { registerRecommendationCommands } from "./commands/recommendations.js";
 import { registerAudienceCommands } from "./commands/audience.js";
 import { registerAccountCommands } from "./commands/account.js";
+import { registerSongCommands } from "./commands/songs.js";
 const program = new Command()
     .name("dropspace")
     .description("dropspace CLI - manage launches, personas, boosts, and more")
@@ -42,6 +43,7 @@ try {
     registerRecommendationCommands(program, client);
     registerRedditCommands(program, client);
     registerAccountCommands(program, client);
+    registerSongCommands(program, client);
     await program.parseAsync(process.argv);
 }
 catch (error) {

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

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { DropspaceClient } from "../client.js";
+export declare function registerSongCommands(program: Command, client: DropspaceClient): void;

package/dist/commands/songs.js

@@ -0,0 +1,97 @@
+import { formatOutput, handleError, getFormat } from "../cli-utils.js";
+export function registerSongCommands(program, client) {
+    const songs = program.command("songs").description("your songs for song-to-reels (pro and premium)");
+    songs
+        .command("list")
+        .description("your songs, newest first")
+        .option("--page <n>", "page number")
+        .option("--page-size <n>", "songs per page (max 100)")
+        .action(async (opts) => {
+        try {
+            const params = {};
+            if (opts.page)
+                params.page = opts.page;
+            if (opts.pageSize)
+                params.page_size = opts.pageSize;
+            formatOutput(await client.get("/songs", params), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    songs
+        .command("get <id>")
+        .description("one song, with its waveform peaks")
+        .action(async (id) => {
+        try {
+            formatOutput(await client.get(`/songs/${id}`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    songs
+        .command("add")
+        .description("add a song from a youtube or soundcloud link, or a public audio file url")
+        .option("--link <url>", "a youtube or soundcloud link")
+        .option("--audio <url>", "a public audio file url (mp3, m4a, wav, aac, flac, ogg)")
+        .option("-t, --title <text>", "the title; the link's or file's name otherwise")
+        .action(async (opts) => {
+        try {
+            if (!opts.link && !opts.audio)
+                throw new Error("give --link or --audio");
+            const body = opts.link ? { link_url: opts.link } : { audio_url: opts.audio };
+            if (opts.title)
+                body.title = opts.title;
+            formatOutput(await client.post("/songs", body), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    songs
+        .command("lyrics <id>")
+        .description("the song's lyrics with word timings (transcribed on first request)")
+        .action(async (id) => {
+        try {
+            formatOutput(await client.get(`/songs/${id}/lyrics`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    songs
+        .command("rename <id>")
+        .description("rename a song")
+        .requiredOption("-t, --title <text>", "the new title")
+        .action(async (id, opts) => {
+        try {
+            formatOutput(await client.patch(`/songs/${id}`, { title: opts.title }), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    songs
+        .command("retry <id>")
+        .description("run a failed import again")
+        .action(async (id) => {
+        try {
+            formatOutput(await client.post(`/songs/${id}/retry`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    songs
+        .command("delete <id>")
+        .description("delete a song and its audio file")
+        .action(async (id) => {
+        try {
+            formatOutput(await client.delete(`/songs/${id}`), getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/server.js

@@ -18,6 +18,8 @@ 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";
+import { registerSongTools } from "./tools/songs.js";
 /** Drops tools whose feature is paused before the policy registrar sees them (see PAUSED_TOOLS). */
 function skipPausedTools(registrar) {
     return {
@@ -48,5 +50,11 @@ export function createDropspaceServer({ client, version, profile }) {
     registerCommentTools(registrar, client);
     registerAccountTools(registrar, client);
     registerTrialReelTools(registrar, client);
+    registerReportTools(registrar, client);
+    registerSongTools(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,15 @@ 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"),
+    // songs (song to reels): local-only while the hosted set is frozen for the Meta review
+    list_songs: localOnly("media", "read"),
+    get_song: localOnly("media", "read"),
+    add_song: localOnly("media", "write"),
+    get_song_lyrics: localOnly("media", "read"),
+    delete_song: localOnly("media", "write"),
     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/songs.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DropspaceClient } from "../client.js";
+/** Songs for song-to-reels (pro and premium). Local package only. */
+export declare function registerSongTools(server: McpServer, client: DropspaceClient): void;

package/dist/tools/songs.js

@@ -0,0 +1,71 @@
+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,
+    };
+}
+/** Songs for song-to-reels (pro and premium). Local package only. */
+export function registerSongTools(server, client) {
+    server.tool("list_songs", "the user's songs, newest first: id, title, source (upload, link, or url), source_url (the link or audio url it came from), status (pending while the audio is fetched and converted, ready, or failed with error), duration_seconds, size_bytes, audio_url once ready, lyrics_status (none until lyrics are first requested, ready, or failed), created_at. at most 100 songs per user. pro and premium plans.", {
+        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("/songs", params));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("get_song", "one song with its waveform: everything list_songs shows plus peaks (400 numbers from 0 to 1 across the song, for picking a snippet by ear and eye).", { song_id: z.string().uuid() }, async ({ song_id }) => {
+        try {
+            return text(await client.get(`/songs/${song_id}`));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("add_song", "add a song from a youtube or soundcloud link, or from a public audio file url (mp3, m4a, wav, aac, flac, ogg, up to 50 MB). the audio is fetched and converted in the background (longer than 15 minutes is cut there): the song comes back pending; read it again with get_song until it is ready or failed (a youtube refusal says to upload the file instead). the song must be the user's own. pro and premium plans; at most 100 songs.", {
+        link_url: z.string().url().optional().describe("a youtube or soundcloud link"),
+        audio_url: z.string().url().optional().describe("a public audio file url, when not using a link"),
+        title: z.string().min(1).max(200).optional().describe("the title; the link's or file's name otherwise"),
+    }, async ({ link_url, audio_url, title }) => {
+        try {
+            if (!link_url && !audio_url)
+                throw new Error("give link_url or audio_url");
+            const body = link_url ? { link_url } : { audio_url };
+            if (title)
+                body.title = title;
+            return text(await client.post("/songs", body));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("get_song_lyrics", "the song's lyrics with word timings, transcribed on first request (takes up to a minute for a long song) and kept: language, text, and words with start and end seconds. a song with no recognizable words comes back with empty words. the song must be ready.", { song_id: z.string().uuid() }, async ({ song_id }) => {
+        try {
+            return text(await client.get(`/songs/${song_id}/lyrics`));
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.tool("delete_song", "delete a song and its audio file.", { song_id: z.string().uuid() }, async ({ song_id }) => {
+        try {
+            await client.delete(`/songs/${song_id}`);
+            return text({ id: song_id, deleted: true });
+        }
+        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.49.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": {