@jclvsh/dropspace 2.22.2 → 2.24.0

package/README.md

@@ -107,6 +107,21 @@ Add to your `.cursor/mcp.json`:
 }
 ```
 
+## Hosted Endpoint
+
+Clients that connect to a remote MCP server over HTTPS can skip the install and use:
+
+```
+https://api.dropspace.dev/mcp
+```
+
+- Transport: MCP streamable HTTP, `POST` only, stateless, JSON responses.
+- Auth: `Authorization: Bearer ds_live_...` (the same API key; its scopes apply).
+- Tools: a subset of this package. API key, webhook, boost, credit, and reddit engagement tools are only available through the npm package.
+- Every tool is annotated by class: `read` (`readOnlyHint: true`), `write`, or `sensitive` (`destructiveHint: true`: it publishes, schedules, or deletes on a connected platform, or deletes a launch or persona with no restore). The class of each hosted tool is listed at https://www.dropspace.dev/docs#mcp-hosted, and the source of truth is `src/tool-policy.ts`.
+- `create_launch` sends a content-derived `Idempotency-Key`, so a retry after a timeout returns the launch already created instead of creating a second one (the result says so).
+- Each MCP request counts once against the key's rate limit, and each tool call counts once more when it reaches the REST API.
+
 ## Available Tools
 
 ### Launches
@@ -139,7 +154,7 @@ Add to your `.cursor/mcp.json`:
 | `dropspace_platforms`         | string[]           | No       | Platforms to post via official dropspace accounts                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `media_mode`                  | string             | No       | `"images"` or `"video"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `user_platform_accounts`      | object             | No       | Map of platform key to token_id (UUID). Simple keys: `twitter`, `reddit`, `instagram`, `tiktok`, `youtube`. LinkedIn: `linkedin:personal` or `linkedin:organization:<org_id>`. Facebook: a bare `facebook` key works when you have exactly one Page (send any connection id from `connections list` as the value); to target a specific Page among several, use `facebook:page:<page_id>` or `facebook:<page_id>`, where `page_id` is the entity_id of that Page from `connections list`; several Pages with no `page_id` returns a 400 listing them |
-| `platform_contents`           | object             | No       | Per-platform content (mutually exclusive with `custom_content`). Reddit accepts `metadata.subreddits` (string[], max 10, no `r/` prefix — one post per subreddit, each retryable) and `metadata.first_comment` (max 1500)                                                                                                                                                                                                                                                                                                                            |
+| `platform_contents`           | object             | No       | Per-platform content (mutually exclusive with `custom_content`). Reddit accepts `metadata.subreddits` (string[], max 10, no `r/` prefix — one post per subreddit, each retryable) and `metadata.first_comment` (max 1500). Instagram accepts `instagram_settings.post_type`: `"feed"` (default), `"story"`, or `"carousel"` (every attached image and the video as one carousel, 2 to 10 items)                                                                                                                                                      |
 | `custom_content`              | string \| string[] | No       | Single content for all platforms, or array of tweets for twitter thread mode (mutually exclusive with `platform_contents`)                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `custom_content_reddit_title` | string             | No       | Reddit title (required with `custom_content` + reddit)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `media`                       | object[]           | No       | Inline media, URL or base64 (1-10 items, mutually exclusive with `media_assets`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -154,7 +169,7 @@ Add to your `.cursor/mcp.json`:
 | `id`                     | string         | Yes      | Launch ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `scheduled_date`         | string \| null | No       | ISO 8601 datetime or null to clear                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `status`                 | string         | No       | `"draft"`, `"manual"`, `"trigger"`, `"scheduled"`, `"cancelled"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `platform_contents`      | object         | No       | Per-platform content overrides                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `platform_contents`      | object         | No       | Per-platform content overrides (Instagram: `instagram_settings.post_type` `"feed"`, `"story"`, or `"carousel"`)                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `dropspace_platforms`    | string[]       | No       | Official dropspace account platforms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `user_platform_accounts` | object         | No       | Map of platform key to token_id (UUID). Simple keys: `twitter`, `reddit`, `instagram`, `tiktok`, `youtube`. LinkedIn: `linkedin:personal` or `linkedin:organization:<org_id>`. Facebook: a bare `facebook` key works when you have exactly one Page (send any connection id from `connections list` as the value); to target a specific Page among several, use `facebook:page:<page_id>` or `facebook:<page_id>`, where `page_id` is the entity_id of that Page from `connections list`; several Pages with no `page_id` returns a 400 listing them |
 | `media`                  | object[]       | No       | Inline media (URL or base64, 1-10 items)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

package/dist/client.d.ts

@@ -1,12 +1,30 @@
+export interface DropspaceClientOptions {
+    /** API key to send. Defaults to the DROPSPACE_API_KEY environment variable. */
+    apiKey?: string;
+    /** REST base URL. Defaults to DROPSPACE_API_URL, then https://api.dropspace.dev. */
+    baseUrl?: string;
+}
 export declare class DropspaceClient {
     private apiKey;
     private baseUrl;
-    constructor();
+    /** True when the base URL was injected; the network-error hint then names the URL, not an env var. */
+    private hasInjectedBaseUrl;
+    constructor(options?: DropspaceClientOptions);
     get<T>(path: string, params?: Record<string, string>): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     patch<T>(path: string, body: unknown): Promise<T>;
     delete(path: string): Promise<void>;
+    /**
+     * POST with an Idempotency-Key. The API answers a repeat of the same key within 24 hours
+     * with the original response and `Idempotent-Replayed: true`; `replayed` surfaces that so
+     * the caller can say "nothing new was created".
+     */
+    postIdempotent<T>(path: string, body: unknown, idempotencyKey: string): Promise<{
+        result: T;
+        replayed: boolean;
+    }>;
     private request;
+    private send;
     private handleError;
 }

package/dist/client.js

@@ -2,8 +2,10 @@ const REQUEST_TIMEOUT_MS = 30_000;
 export class DropspaceClient {
     apiKey;
     baseUrl;
-    constructor() {
-        const apiKey = process.env.DROPSPACE_API_KEY;
+    /** True when the base URL was injected; the network-error hint then names the URL, not an env var. */
+    hasInjectedBaseUrl;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? process.env.DROPSPACE_API_KEY;
         if (!apiKey) {
             throw new Error("DROPSPACE_API_KEY environment variable is required");
         }
@@ -11,7 +13,8 @@ export class DropspaceClient {
             throw new Error("DROPSPACE_API_KEY must start with 'ds_live_'. Get one at https://www.dropspace.dev/settings");
         }
         this.apiKey = apiKey;
-        this.baseUrl = (process.env.DROPSPACE_API_URL || "https://api.dropspace.dev").replace(/\/$/, "");
+        this.hasInjectedBaseUrl = Boolean(options.baseUrl);
+        this.baseUrl = (options.baseUrl || process.env.DROPSPACE_API_URL || "https://api.dropspace.dev").replace(/\/$/, "");
     }
     async get(path, params) {
         const url = new URL(`${this.baseUrl}${path}`);
@@ -63,7 +66,27 @@ export class DropspaceClient {
             throw error;
         }
     }
+    /**
+     * POST with an Idempotency-Key. The API answers a repeat of the same key within 24 hours
+     * with the original response and `Idempotent-Replayed: true`; `replayed` surfaces that so
+     * the caller can say "nothing new was created".
+     */
+    async postIdempotent(path, body, idempotencyKey) {
+        const response = await this.send(`${this.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
+            body: JSON.stringify(body),
+        });
+        return {
+            result: (await response.json()),
+            replayed: response.headers.get("Idempotent-Replayed") === "true",
+        };
+    }
     async request(url, init) {
+        const response = await this.send(url, init);
+        return (await response.json());
+    }
+    async send(url, init) {
         let response;
         try {
             response = await fetch(url, {
@@ -80,14 +103,16 @@ export class DropspaceClient {
                 throw new Error("request timed out after 30s");
             }
             if (error instanceof TypeError) {
-                throw new Error(`network error: ${error.message}. check DROPSPACE_API_URL and your connection`);
+                throw new Error(this.hasInjectedBaseUrl
+                    ? `network error: ${error.message} reaching ${this.baseUrl}`
+                    : `network error: ${error.message}. check DROPSPACE_API_URL and your connection`);
             }
             throw error;
         }
         if (!response.ok) {
             await this.handleError(response);
         }
-        return (await response.json());
+        return response;
     }
     async handleError(response) {
         let errorMessage;

package/dist/commands/launches.js

@@ -31,7 +31,7 @@ export function registerLaunchCommands(program, client) {
         .option("--persona <id>", "persona ID for tone/style")
         .option("--dropspace-platforms <list>", "platforms for official dropspace accounts", parseList)
         .option("--media-mode <mode>", "media mode: images or video")
-        .option("--platform-contents <json>", 'per-platform content as JSON string. reddit supports metadata.subreddits (string[], max 10, no r/ prefix — one post per subreddit) and metadata.first_comment (max 1500). e.g. \'{"reddit":{"title":"...","content":"...","metadata":{"subreddits":["SideProject"],"first_comment":"..."}}}\'')
+        .option("--platform-contents <json>", 'per-platform content as JSON string. reddit supports metadata.subreddits (string[], max 10, no r/ prefix — one post per subreddit) and metadata.first_comment (max 1500). instagram supports instagram_settings.post_type: feed, story, or carousel (every attached image and the video as one carousel, 2 to 10 items). e.g. \'{"reddit":{"title":"...","content":"...","metadata":{"subreddits":["SideProject"],"first_comment":"..."}}}\'')
         .option("--custom-content <text>", "single content string for all platforms")
         .option("--reddit-title <title>", "reddit title (with custom-content)")
         .option("--user-accounts <json>", 'platform→token_id map as JSON. simple key = primary account ("instagram"); composite key targets a specific account when you have several ("instagram:<account_id>", ids from `connections list`) - works for instagram/tiktok/youtube/twitter/reddit. facebook: bare "facebook" for your one Page, or "facebook:page:<page_id>" / "facebook:<page_id>" for a specific one (id from `connections list`); several Pages and no page_id returns a 400. linkedin: "linkedin:personal" or "linkedin:organization:<org_id>"')
@@ -101,7 +101,7 @@ export function registerLaunchCommands(program, client) {
         .option("--schedule <datetime>", "ISO 8601 schedule datetime (empty to clear)")
         .option("--status <status>", "status: draft, manual, trigger, scheduled, cancelled")
         .option("--persona <id>", "persona ID (empty to clear)")
-        .option("--platform-contents <json>", 'per-platform content as JSON string. reddit supports metadata.subreddits (string[], max 10, no r/ prefix — one post per subreddit) and metadata.first_comment (max 1500). e.g. \'{"reddit":{"title":"...","content":"...","metadata":{"subreddits":["SideProject"],"first_comment":"..."}}}\'')
+        .option("--platform-contents <json>", 'per-platform content as JSON string. reddit supports metadata.subreddits (string[], max 10, no r/ prefix — one post per subreddit) and metadata.first_comment (max 1500). instagram supports instagram_settings.post_type: feed, story, or carousel (every attached image and the video as one carousel, 2 to 10 items). e.g. \'{"reddit":{"title":"...","content":"...","metadata":{"subreddits":["SideProject"],"first_comment":"..."}}}\'')
         .option("--dropspace-platforms <list>", "official dropspace account platforms", parseList)
         .option("--attribution-mode <mode>", 'how official-account posts credit you: "handle" (default) or "anonymous"')
         .option("--user-accounts <json>", 'platform→token_id map as JSON. simple key = primary account ("instagram"); composite key targets a specific account when you have several ("instagram:<account_id>", ids from `connections list`) - works for instagram/tiktok/youtube/twitter/reddit. facebook: bare "facebook" for your one Page, or "facebook:page:<page_id>" / "facebook:<page_id>" for a specific one (id from `connections list`); several Pages and no page_id returns a 400. linkedin: "linkedin:personal" or "linkedin:organization:<org_id>"')

package/dist/hosted.d.ts

@@ -0,0 +1,15 @@
+export interface HostedMcpOptions {
+    /** The caller's dropspace API key. The host authenticates it before calling in. */
+    apiKey: string;
+    /** REST base URL the tools call, e.g. https://api.dropspace.dev */
+    baseUrl: string;
+    /** Reported as serverInfo.version */
+    version: string;
+}
+/**
+ * Serve one MCP request over HTTP. Stateless: a fresh server and transport per request,
+ * no sessions, JSON responses - so it runs on serverless functions where consecutive
+ * requests from one client can land on different instances. Only POST is meaningful;
+ * the host must not route GET here (a stateless GET opens an event stream that never ends).
+ */
+export declare function handleHostedMcpRequest(request: Request, options: HostedMcpOptions): Promise<Response>;

package/dist/hosted.js

@@ -0,0 +1,19 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { DropspaceClient } from "./client.js";
+import { createDropspaceServer } from "./server.js";
+/**
+ * Serve one MCP request over HTTP. Stateless: a fresh server and transport per request,
+ * no sessions, JSON responses - so it runs on serverless functions where consecutive
+ * requests from one client can land on different instances. Only POST is meaningful;
+ * the host must not route GET here (a stateless GET opens an event stream that never ends).
+ */
+export async function handleHostedMcpRequest(request, options) {
+    const client = new DropspaceClient({ apiKey: options.apiKey, baseUrl: options.baseUrl });
+    const server = createDropspaceServer({ client, version: options.version, profile: "hosted" });
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    await server.connect(transport);
+    return transport.handleRequest(request);
+}

package/dist/idempotency.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A content-derived Idempotency-Key for create calls.
+ *
+ * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
+ * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
+ * key from the arguments means a retry after a timeout - by an agent, or by a person
+ * pressing "try again" in an MCP client - returns the launch that was already created
+ * instead of creating a second one.
+ */
+export declare function contentIdempotencyKey(args: unknown): Promise<string>;

package/dist/idempotency.js

@@ -0,0 +1,28 @@
+/**
+ * A content-derived Idempotency-Key for create calls.
+ *
+ * The REST API dedupes a request that repeats a key within 24 hours (per key + endpoint)
+ * and answers with the original response plus `Idempotent-Replayed: true`. Deriving the
+ * key from the arguments means a retry after a timeout - by an agent, or by a person
+ * pressing "try again" in an MCP client - returns the launch that was already created
+ * instead of creating a second one.
+ */
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort()) {
+            if (source[key] !== undefined)
+                sorted[key] = stable(source[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+export async function contentIdempotencyKey(args) {
+    const bytes = new TextEncoder().encode(JSON.stringify(stable(args)));
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/index.js

@@ -1,42 +1,10 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { DropspaceClient } from "./client.js";
-import { registerLaunchTools } from "./tools/launches.js";
-import { registerPersonaTools } from "./tools/personas.js";
-import { registerConnectionTools } from "./tools/connections.js";
-import { registerKeyTools } from "./tools/keys.js";
-import { registerWebhookTools } from "./tools/webhooks.js";
-import { registerDropspaceTools } from "./tools/dropspace.js";
-import { registerUsageTools } from "./tools/usage.js";
-import { registerCreditTools } from "./tools/credits.js";
-import { registerMediaTools } from "./tools/media.js";
-import { registerBoostTools } from "./tools/boosts.js";
-import { registerAutopilotTools } from "./tools/autopilot.js";
-import { registerRecommendationTools } from "./tools/recommendations.js";
-import { registerRedditTools } from "./tools/reddit.js";
-import { registerAudienceTools } from "./tools/audience.js";
+import { createDropspaceServer } from "./server.js";
 const requireFromHere = createRequire(import.meta.url);
 const pkg = requireFromHere("../package.json");
-const server = new McpServer({
-    name: "dropspace",
-    version: pkg.version,
-});
-const client = new DropspaceClient();
-registerLaunchTools(server, client);
-registerPersonaTools(server, client);
-registerConnectionTools(server, client);
-registerKeyTools(server, client);
-registerWebhookTools(server, client);
-registerDropspaceTools(server, client);
-registerUsageTools(server, client);
-registerCreditTools(server, client);
-registerMediaTools(server, client);
-registerBoostTools(server, client);
-registerAutopilotTools(server, client);
-registerRecommendationTools(server, client);
-registerRedditTools(server, client);
-registerAudienceTools(server, client);
+const server = createDropspaceServer({ client: new DropspaceClient(), version: pkg.version, profile: "full" });
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { DropspaceClient } from "./client.js";
+import { type ToolProfile } from "./tool-policy.js";
+export interface CreateDropspaceServerOptions {
+    client: DropspaceClient;
+    version: string;
+    /** "full" serves every tool (stdio). "hosted" serves the tools marked hosted in tool-policy.ts. */
+    profile: ToolProfile;
+}
+export declare function createDropspaceServer({ client, version, profile }: CreateDropspaceServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,44 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { isToolEnabled, toolAnnotations } from "./tool-policy.js";
+import { registerLaunchTools } from "./tools/launches.js";
+import { registerPersonaTools } from "./tools/personas.js";
+import { registerConnectionTools } from "./tools/connections.js";
+import { registerKeyTools } from "./tools/keys.js";
+import { registerWebhookTools } from "./tools/webhooks.js";
+import { registerDropspaceTools } from "./tools/dropspace.js";
+import { registerUsageTools } from "./tools/usage.js";
+import { registerCreditTools } from "./tools/credits.js";
+import { registerMediaTools } from "./tools/media.js";
+import { registerBoostTools } from "./tools/boosts.js";
+import { registerAutopilotTools } from "./tools/autopilot.js";
+import { registerRecommendationTools } from "./tools/recommendations.js";
+import { registerRedditTools } from "./tools/reddit.js";
+import { registerAudienceTools } from "./tools/audience.js";
+export function createDropspaceServer({ client, version, profile }) {
+    const server = new McpServer({ name: "dropspace", version });
+    const registerAnnotated = server.tool.bind(server);
+    // Every register*Tools function calls server.tool(name, description, schema, handler).
+    // This stand-in is the one place a tool is filtered by profile and given its annotations.
+    const registrar = {
+        tool(name, description, schema, handler) {
+            if (!isToolEnabled(name, profile))
+                return;
+            registerAnnotated(name, description, schema, toolAnnotations(name), handler);
+        },
+    };
+    registerLaunchTools(registrar, client);
+    registerPersonaTools(registrar, client);
+    registerConnectionTools(registrar, client);
+    registerKeyTools(registrar, client);
+    registerWebhookTools(registrar, client);
+    registerDropspaceTools(registrar, client);
+    registerUsageTools(registrar, client);
+    registerCreditTools(registrar, client);
+    registerMediaTools(registrar, client);
+    registerBoostTools(registrar, client);
+    registerAutopilotTools(registrar, client);
+    registerRecommendationTools(registrar, client);
+    registerRedditTools(registrar, client);
+    registerAudienceTools(registrar, client);
+    return server;
+}

package/dist/tool-policy.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The one place a tool is classified.
+ *
+ * class:
+ *   read      - retrieves information; changes nothing.
+ *   write     - changes dropspace data only, reversibly; nothing leaves dropspace.
+ *   sensitive - publishes, schedules, or deletes on a social platform, deletes a record
+ *               inside dropspace with no user-facing restore, spends money, handles
+ *               credentials, or switches on something that will publish later.
+ *
+ * hosted: whether the hosted endpoint (https://api.dropspace.dev/mcp) serves the tool.
+ * The stdio server serves every tool. Left off hosted: credits and boosts (payments and
+ * ad spend), API keys and webhooks (developer plumbing and credentials), and reddit
+ * engagement.
+ *
+ * category: the documentation grouping. Every tool count and category list in the docs
+ * page, llms.txt, and llms-full.txt is computed from this table.
+ *
+ * Registering a tool with no entry here throws, and __tests__/server.test.ts fails on
+ * any mismatch between this table and what the package registers.
+ */
+export type ToolClass = "read" | "write" | "sensitive";
+export type ToolProfile = "full" | "hosted";
+export declare const TOOL_CATEGORIES: readonly ["launches", "posts", "personas", "media", "connections", "boosts", "credits", "API keys", "webhooks", "dropspace", "usage", "autopilot", "recommendations", "reddit engagement", "audience"];
+export type ToolCategory = (typeof TOOL_CATEGORIES)[number];
+export interface ToolPolicy {
+    class: ToolClass;
+    hosted: boolean;
+    category: ToolCategory;
+}
+export declare const TOOL_POLICY: Record<string, ToolPolicy>;
+export declare function toolPolicy(name: string): ToolPolicy;
+export declare function isToolEnabled(name: string, profile: ToolProfile): boolean;
+export declare function toolAnnotations(name: string): {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+};
+/** Tool names in a category, in table order. */
+export declare function toolsInCategory(category: ToolCategory): string[];

package/dist/tool-policy.js

@@ -0,0 +1,162 @@
+/**
+ * The one place a tool is classified.
+ *
+ * class:
+ *   read      - retrieves information; changes nothing.
+ *   write     - changes dropspace data only, reversibly; nothing leaves dropspace.
+ *   sensitive - publishes, schedules, or deletes on a social platform, deletes a record
+ *               inside dropspace with no user-facing restore, spends money, handles
+ *               credentials, or switches on something that will publish later.
+ *
+ * hosted: whether the hosted endpoint (https://api.dropspace.dev/mcp) serves the tool.
+ * The stdio server serves every tool. Left off hosted: credits and boosts (payments and
+ * ad spend), API keys and webhooks (developer plumbing and credentials), and reddit
+ * engagement.
+ *
+ * category: the documentation grouping. Every tool count and category list in the docs
+ * page, llms.txt, and llms-full.txt is computed from this table.
+ *
+ * Registering a tool with no entry here throws, and __tests__/server.test.ts fails on
+ * any mismatch between this table and what the package registers.
+ */
+export const TOOL_CATEGORIES = [
+    "launches",
+    "posts",
+    "personas",
+    "media",
+    "connections",
+    "boosts",
+    "credits",
+    "API keys",
+    "webhooks",
+    "dropspace",
+    "usage",
+    "autopilot",
+    "recommendations",
+    "reddit engagement",
+    "audience",
+];
+const hosted = (category, toolClass) => ({
+    class: toolClass,
+    hosted: true,
+    category,
+});
+const localOnly = (category, toolClass) => ({
+    class: toolClass,
+    hosted: false,
+    category,
+});
+export const TOOL_POLICY = {
+    // launches
+    list_launches: hosted("launches", "read"),
+    get_launch: hosted("launches", "read"),
+    get_launch_status: hosted("launches", "read"),
+    get_launch_analytics: hosted("launches", "read"),
+    get_batch_launch_analytics: hosted("launches", "read"),
+    // create and update accept `publish` / `scheduled_date`, so either can put a post out
+    create_launch: hosted("launches", "sensitive"),
+    update_launch: hosted("launches", "sensitive"),
+    // a soft delete with no user-facing restore
+    delete_launch: hosted("launches", "sensitive"),
+    generate_content: hosted("launches", "write"),
+    retry_launch_content: hosted("launches", "write"),
+    publish_launch: hosted("launches", "sensitive"),
+    retry_launch: hosted("launches", "sensitive"),
+    // posts
+    delete_post: hosted("posts", "sensitive"),
+    delete_all_posts: hosted("posts", "sensitive"),
+    // personas
+    list_personas: hosted("personas", "read"),
+    get_persona: hosted("personas", "read"),
+    create_persona: hosted("personas", "write"),
+    update_persona: hosted("personas", "write"),
+    // a soft delete with no user-facing restore
+    delete_persona: hosted("personas", "sensitive"),
+    analyze_persona: hosted("personas", "write"),
+    finalize_persona: hosted("personas", "write"),
+    discard_persona_analysis: hosted("personas", "write"),
+    // media
+    generate_media: hosted("media", "write"),
+    get_media_job: hosted("media", "read"),
+    // connections
+    list_connections: hosted("connections", "read"),
+    // edits the profile ON the platform (youtube channel description)
+    update_connection_profile: hosted("connections", "sensitive"),
+    // autopilot
+    get_autopilot: hosted("autopilot", "read"),
+    list_autopilot_review: hosted("autopilot", "read"),
+    list_autopilot_runs: hosted("autopilot", "read"),
+    // deletes the draft launch with no restore
+    reject_autopilot_draft: hosted("autopilot", "sensitive"),
+    // enabling autopilot leads to posts with no further per-post step
+    configure_autopilot: hosted("autopilot", "sensitive"),
+    approve_autopilot_draft: hosted("autopilot", "sensitive"),
+    run_autopilot_now: hosted("autopilot", "sensitive"),
+    // recommendations
+    list_recommendations: hosted("recommendations", "read"),
+    // creates a DRAFT launch or a PAUSED boost; nothing publishes or spends
+    apply_recommendation: hosted("recommendations", "write"),
+    dismiss_recommendation: hosted("recommendations", "write"),
+    // audience, usage, status
+    get_audience: hosted("audience", "read"),
+    get_usage: hosted("usage", "read"),
+    get_changelog: hosted("usage", "read"),
+    get_dropspace_status: hosted("dropspace", "read"),
+    // reddit engagement
+    suggest_subreddits: localOnly("reddit engagement", "read"),
+    get_engagement_config: localOnly("reddit engagement", "read"),
+    get_engagement_standing: localOnly("reddit engagement", "read"),
+    list_engagement_comments: localOnly("reddit engagement", "read"),
+    update_engagement_config: localOnly("reddit engagement", "write"),
+    discover_engagement: localOnly("reddit engagement", "write"),
+    reject_engagement_comment: localOnly("reddit engagement", "write"),
+    activate_engagement_subreddit: localOnly("reddit engagement", "write"),
+    deactivate_engagement_subreddit: localOnly("reddit engagement", "write"),
+    approve_engagement_comment: localOnly("reddit engagement", "sensitive"),
+    // credits
+    get_credit_balance: localOnly("credits", "read"),
+    purchase_credit_pack: localOnly("credits", "sensitive"),
+    // boosts
+    list_boosts: localOnly("boosts", "read"),
+    get_boost: localOnly("boosts", "read"),
+    get_boost_performance: localOnly("boosts", "read"),
+    create_boost: localOnly("boosts", "write"),
+    activate_boost: localOnly("boosts", "sensitive"),
+    cancel_boost: localOnly("boosts", "sensitive"),
+    // api keys
+    get_current_api_key: localOnly("API keys", "read"),
+    list_api_keys: localOnly("API keys", "read"),
+    rename_api_key: localOnly("API keys", "write"),
+    create_api_key: localOnly("API keys", "sensitive"),
+    revoke_api_key: localOnly("API keys", "sensitive"),
+    rotate_api_key: localOnly("API keys", "sensitive"),
+    // webhooks
+    list_webhooks: localOnly("webhooks", "read"),
+    get_webhook: localOnly("webhooks", "read"),
+    list_webhook_deliveries: localOnly("webhooks", "read"),
+    create_webhook: localOnly("webhooks", "write"),
+    update_webhook: localOnly("webhooks", "write"),
+    // a hard delete with no restore
+    delete_webhook: localOnly("webhooks", "sensitive"),
+    test_webhook: localOnly("webhooks", "write"),
+    rotate_webhook_secret: localOnly("webhooks", "sensitive"),
+};
+export function toolPolicy(name) {
+    const policy = TOOL_POLICY[name];
+    if (!policy) {
+        throw new Error(`tool "${name}" has no entry in tool-policy.ts - classify it before registering`);
+    }
+    return policy;
+}
+export function isToolEnabled(name, profile) {
+    const policy = toolPolicy(name);
+    return profile === "full" || policy.hosted;
+}
+export function toolAnnotations(name) {
+    const toolClass = toolPolicy(name).class;
+    return { readOnlyHint: toolClass === "read", destructiveHint: toolClass === "sensitive" };
+}
+/** Tool names in a category, in table order. */
+export function toolsInCategory(category) {
+    return Object.keys(TOOL_POLICY).filter((name) => TOOL_POLICY[name].category === category);
+}

package/dist/tools/launches.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { contentIdempotencyKey } from "../idempotency.js";
 // 11 enum values but only 10 distinct platforms — linkedin-community is a LinkedIn variant, not a separate platform.
 // auto-post (7): facebook, linkedin, twitter, reddit, instagram, tiktok, youtube
 // guided  (3): substack, producthunt, hackernews
@@ -110,7 +111,7 @@ export function registerLaunchTools(server, client) {
         platform_contents: z
             .record(z.string(), z.record(z.string(), z.unknown()))
             .optional()
-            .describe('per-platform content — each value needs "content" (string). Reddit also requires "title" (max 300) and supports "metadata": { "subreddits": string[] (max 10, names without the r/ prefix — posts the launch once per subreddit, each tracked and retryable on its own; omit to post to the default community), "first_comment": string (max 1500 — posted as a comment under each reddit post once it goes live) }. for multi-account reddit, each connected account can target its own subreddits via "reddit:<account_id>" content keys (falls back to the base "reddit" block); a subreddit is posted by at most one of your accounts per launch (first wins, others skipped as SUBREDDIT_ALREADY_TARGETED). each subreddit has its own rules: many restrict or ban promotional posts and posting where the account has no history gets filtered, so target a few genuinely relevant subreddits rather than blasting. Twitter supports "thread" (string[], max 6, each ≤280 or ≤25,000 for X Premium) instead of "content". TikTok supports "tiktok_settings": { "publish_mode"?: "direct"|"draft" (default "direct"; "draft" uploads to the TikTok inbox to finish and publish in-app), "privacy_level": "PUBLIC_TO_EVERYONE"|"FOLLOWER_OF_CREATOR"|"MUTUAL_FOLLOW_FRIENDS"|"SELF_ONLY" (required before publish in direct mode; not required for draft), "allow_comments"?, "allow_duet"?, "allow_stitch"?, "is_commercial"?, "is_your_brand"?, "is_branded_content"?, "auto_add_music"? (booleans, direct mode), "cover_timestamp_ms"? (integer 0-600000 — which frame TikTok uses as the cover, in ms from the start; VIDEO posts only, photo posts take their cover by index; omit for the first frame) }. YouTube requires video and supports "title" (max 100 chars). character limits: Twitter 280/tweet (25,000 for X Premium), LinkedIn 3000, Instagram 2200, Reddit 3000, Facebook 3000, TikTok 4000, YouTube 5000 (description). X Premium status is auto-detected from the connected account. mutually exclusive with custom_content'),
+            .describe('per-platform content — each value needs "content" (string). Instagram takes "instagram_settings": { "post_type": "feed" (default) | "carousel" | "story" } and Facebook takes "facebook_settings": { "post_type": "feed" | "story" } - "carousel" (Instagram only) posts every attached image and the launch video as ONE carousel in media order, 2 to 10 items, where "feed" would post the video as a reel and leave the images out; "story" posts each image as a 24-hour story frame with no caption. Reddit also requires "title" (max 300) and supports "metadata": { "subreddits": string[] (max 10, names without the r/ prefix — posts the launch once per subreddit, each tracked and retryable on its own; omit to post to the default community), "first_comment": string (max 1500 — posted as a comment under each reddit post once it goes live) }. for multi-account reddit, each connected account can target its own subreddits via "reddit:<account_id>" content keys (falls back to the base "reddit" block); a subreddit is posted by at most one of your accounts per launch (first wins, others skipped as SUBREDDIT_ALREADY_TARGETED). each subreddit has its own rules: many restrict or ban promotional posts and posting where the account has no history gets filtered, so target a few genuinely relevant subreddits rather than blasting. Twitter supports "thread" (string[], max 6, each ≤280 or ≤25,000 for X Premium) instead of "content". TikTok supports "tiktok_settings": { "publish_mode"?: "direct"|"draft" (default "direct"; "draft" uploads to the TikTok inbox to finish and publish in-app), "privacy_level": "PUBLIC_TO_EVERYONE"|"FOLLOWER_OF_CREATOR"|"MUTUAL_FOLLOW_FRIENDS"|"SELF_ONLY" (required before publish in direct mode; not required for draft), "allow_comments"?, "allow_duet"?, "allow_stitch"?, "is_commercial"?, "is_your_brand"?, "is_branded_content"?, "auto_add_music"? (booleans, direct mode), "cover_timestamp_ms"? (integer 0-600000 — which frame TikTok uses as the cover, in ms from the start; VIDEO posts only, photo posts take their cover by index; omit for the first frame) }. YouTube requires video and supports "title" (max 100 chars). character limits: Twitter 280/tweet (25,000 for X Premium), LinkedIn 3000, Instagram 2200, Reddit 3000, Facebook 3000, TikTok 4000, YouTube 5000 (description). X Premium status is auto-detected from the connected account. mutually exclusive with custom_content'),
         custom_content: z
             .union([z.string().min(1), z.array(z.string()).min(1).max(6)])
             .optional()
@@ -161,9 +162,20 @@ export function registerLaunchTools(server, client) {
             };
         }
         try {
-            const result = await client.post("/launches", args);
+            // A retry after a timeout (by an agent, or a person pressing "try again") must not
+            // create a second launch: the key is derived from the arguments, so the API replays
+            // the launch it already created for them.
+            const { result, replayed } = await client.postIdempotent("/launches", args, await contentIdempotencyKey(args));
+            const text = JSON.stringify(result, null, 2);
             return {
-                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                content: [
+                    {
+                        type: "text",
+                        text: replayed
+                            ? `note: an identical launch was created within the last 24 hours, so dropspace returned it - no new launch was created.\n${text}`
+                            : text,
+                    },
+                ],
             };
         }
         catch (error) {
@@ -224,7 +236,7 @@ export function registerLaunchTools(server, client) {
         platform_contents: z
             .record(z.string(), z.record(z.string(), z.unknown()))
             .optional()
-            .describe('per-platform content update (deep-merged with existing). each value can include "content" (string). Twitter supports "thread" (string[]) instead. Reddit "title" is optional on update, and "metadata" accepts "subreddits" (string[], max 10, no r/ prefix — one post per subreddit) and "first_comment" (string, max 1500). TikTok "tiktok_settings" is deep-merged — you can update individual fields (e.g. just "privacy_level") without overwriting the rest. see create_launch for full field details'),
+            .describe('per-platform content update (deep-merged with existing). each value can include "content" (string). Instagram takes "instagram_settings": { "post_type": "feed" | "carousel" | "story" } ("carousel" posts every attached image and the launch video as ONE carousel, 2 to 10 items) and Facebook takes "facebook_settings": { "post_type": "feed" | "story" }. Twitter supports "thread" (string[]) instead. Reddit "title" is optional on update, and "metadata" accepts "subreddits" (string[], max 10, no r/ prefix — one post per subreddit) and "first_comment" (string, max 1500). TikTok "tiktok_settings" is deep-merged — you can update individual fields (e.g. just "privacy_level") without overwriting the rest. see create_launch for full field details'),
         dropspace_platforms: z.array(z.enum(PLATFORMS)).optional().describe("official dropspace account platforms"),
         attribution_mode: z
             .enum(["handle", "anonymous"])
@@ -381,7 +393,7 @@ export function registerLaunchTools(server, client) {
             };
         }
     });
-    server.tool("get_launch_analytics", "get publishing analytics with per-post engagement metrics (likes, views, shares, etc.). metric fields vary by platform: facebook reports reactions, likes (mirroring reactions.total), comments and shares - it has no impressions or reach, and facebook story metrics are unavailable", {
+    server.tool("get_launch_analytics", "get publishing analytics with per-post engagement metrics (likes, views, shares, etc.). metric fields vary by platform: facebook reports reactions, likes (mirroring reactions.total), comments and shares - it has no impressions or reach, and facebook story metrics are unavailable. an instagram story reports views, reach, replies and frames only while it is live (24 hours, no backfill); under 5 viewers it returns story_insights_withheld instead of numbers", {
         id: z.string().uuid().describe("launch ID"),
     }, async ({ id }) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.22.2",
+	"version": "2.24.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"repository": {
 		"type": "git",
@@ -10,6 +10,21 @@
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./hosted": {
+			"types": "./dist/hosted.d.ts",
+			"default": "./dist/hosted.js"
+		},
+		"./tool-policy": {
+			"types": "./dist/tool-policy.d.ts",
+			"default": "./dist/tool-policy.js"
+		},
+		"./package.json": "./package.json"
+	},
 	"bin": {
 		"dropspace-mcp": "dist/index.js",
 		"dropspace": "dist/cli.js"
@@ -20,17 +35,21 @@
 	],
 	"scripts": {
 		"build": "tsc",
+		"prepare": "tsc",
 		"prepublishOnly": "npm run build",
-		"start": "node dist/index.js"
+		"start": "node dist/index.js",
+		"typecheck": "tsc -p tsconfig.test.json",
+		"test": "vitest run"
 	},
 	"dependencies": {
-		"@modelcontextprotocol/sdk": "^1.11.0",
+		"@modelcontextprotocol/sdk": "^1.26.0",
 		"commander": "^14.0.3",
 		"zod": "^3.24.0"
 	},
 	"devDependencies": {
 		"@types/node": "^22.0.0",
-		"typescript": "^5.7.0"
+		"typescript": "^5.7.0",
+		"vitest": "^4.0.18"
 	},
 	"engines": {
 		"node": ">=18"