@jclvsh/dropspace 2.26.0 → 2.28.0

package/README.md

@@ -124,6 +124,18 @@ https://api.dropspace.dev/mcp
 - `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.
 
+## Agent Skill
+
+The package ships `skills/dropspace/SKILL.md`, which teaches an agent the dropspace workflow: check connections and usage, create a launch, review the copy, publish, read analytics, and ask before anything that spends money. Every tool it names is checked against this package's tool table in the test suite.
+
+Install it for Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills/dropspace && curl -fsSL https://unpkg.com/@jclvsh/dropspace/skills/dropspace/SKILL.md -o ~/.claude/skills/dropspace/SKILL.md
+```
+
+Other agents that read skill files can use the same file from `node_modules/@jclvsh/dropspace/skills/dropspace/SKILL.md`.
+
 ## Available Tools
 
 ### Launches

package/dist/tools/webhooks.js

@@ -37,7 +37,7 @@ export function registerWebhookTools(server, client) {
             .refine((u) => u.startsWith("https://"), {
             message: "webhook url must use https",
         })
-            .describe("HTTPS webhook URL"),
+            .describe("HTTPS webhook URL. a Slack incoming webhook URL (hooks.slack.com/services/...) gets readable Slack messages instead of signed JSON"),
         events: z
             .array(z.enum(WEBHOOK_EVENTS))
             .min(1)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/dropspace",
-	"version": "2.26.0",
+	"version": "2.28.0",
 	"description": "MCP server and CLI for the Dropspace API",
 	"repository": {
 		"type": "git",
@@ -35,6 +35,7 @@
 	},
 	"files": [
 		"dist",
+		"skills",
 		"README.md"
 	],
 	"scripts": {

package/skills/dropspace/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: dropspace
+description: Use when the user wants to post or schedule content across social platforms (X/Twitter, LinkedIn, Reddit, Facebook, Instagram, TikTok, YouTube, Snapchat), check how posts performed, run the autopilot content engine, generate AI images or short videos for a post, or boost a Facebook post - through Dropspace's MCP server (`dropspace-mcp`) or CLI (`dropspace`).
+---
+
+# dropspace
+
+Dropspace turns one brief into per-platform posts and publishes them on the user's own connected accounts. The unit of work is a **launch**: one brief, many platforms. Each platform's published item is a **post**.
+
+## Setup
+
+- MCP over stdio: `npx -y -p @jclvsh/dropspace dropspace-mcp` with `DROPSPACE_API_KEY=ds_live_...` in the environment. Every tool is available.
+- Hosted MCP: `https://api.dropspace.dev/mcp` (streamable HTTP, POST, `Authorization: Bearer ds_live_...`). Serves a subset: no credits, boosts, API keys, webhooks, or reddit engagement tools.
+- CLI: `npx -y @jclvsh/dropspace <command>` (the same key). `dropspace --help` lists commands.
+- No key? The user creates one at https://www.dropspace.dev/settings/api. A key's scopes limit what it can do (`read`, `write`, `generate`, `send`, `admin`); a 403 names the missing scope.
+
+## Before posting
+
+1. `list_connections` - which accounts are connected. Posting goes only to connected accounts; a platform with no connection needs the user to connect it in the dropspace app first. Never guess an account.
+2. `get_usage` - what the plan still allows this period (launches, AI images and videos, personas). Plan the batch inside it instead of discovering limits at the error.
+3. Optional voice: `list_personas`. A persona carries the user's writing style; pass its id as `persona_id`.
+
+## Launch lifecycle
+
+1. `create_launch` with `product_url` and/or `product_description` and `platforms`. Dropspace reads the product page and writes copy per platform.
+   - Use `platform_contents` or `custom_content` when the user already wrote the copy.
+   - `track_links: true` posts the product URL as a tracked redirect on X, LinkedIn, Facebook, Reddit, and YouTube; clicks then appear in analytics. Tell the user their posts will show a dropspace.dev link.
+   - `scheduled_date` (ISO 8601, at least 15 minutes out) schedules it; without one, the launch waits for `publish_launch`.
+2. Review: `get_launch` shows the generated copy per platform. Show it to the user before publishing anything they have not seen. Edit with `update_launch`; regenerate one platform with `retry_launch_content`.
+3. Media (optional): `generate_media` with `type: "image"` and `use_product_image: true` makes an image of the real product from its page; `get_media_job` polls it. Videos are 8-second clips (`type: "video"` or `"script_video"`).
+4. `publish_launch`, then `get_launch_status` until it settles. Failed platforms: `retry_launch`.
+5. Results: `get_launch_analytics` (or `get_batch_launch_analytics` for many). `metrics.tracked_clicks` is clicks on the tracked link.
+
+## Ongoing
+
+- Recommendations: `list_recommendations` after posts have run a day or two; `apply_recommendation` turns one into a draft launch, an autopilot post, or a paused boost. Nothing publishes or spends on apply.
+- Autopilot (pro and premium plans): `get_autopilot`, `configure_autopilot`, `run_autopilot_now`. In review mode it drafts posts for approval: `list_autopilot_review`, `approve_autopilot_draft`, `reject_autopilot_draft`.
+- Audience: `get_audience` for follower counts on Instagram, TikTok, and YouTube.
+
+## Spending money - confirm first
+
+These cost the user money. Get an explicit yes for the amount before calling them:
+
+- `activate_boost` starts real ad spend on the user's Meta ad account. `create_boost` makes it paused; activation is the spend.
+- `purchase_credit_pack`.
+
+## Errors that need the user
+
+- `BILLING_*`: a plan limit or subscription problem. Report the limit and stop; do not retry.
+- `PLATFORM_002` (a connection expired): the user reconnects that account in the dropspace app. Retrying will not help.
+- `RATE_001`: wait for the `Retry-After` header, then retry once.
+- A response header `X-Dropspace-Notice` announces an API change; mention it to the user when it changes. `get_changelog` has the history.