@post-ripple/mcp 0.2.0 → 0.3.0

package/README.md

@@ -58,6 +58,8 @@ env = { POSTRIPPLE_API_KEY = "pr_..." }
 | `list_videos` | read | Video library (status, source) |
 | `list_video_groups` / `get_video_group` | read | Rotation groups and their posting rules |
 | `list_slideshows` | read | Photo-carousel slideshows |
+| `list_slideshow_templates` | read | Slideshow layout templates, fonts, and text treatments |
+| `get_slideshow` | read | One slideshow with per-slide render state and progress |
 | `list_posts` | read | Posts with status, schedule, errors |
 | `get_post_metrics` | read | Per-post engagement time series |
 | `get_account_metrics` | read | Follower growth history |
@@ -67,13 +69,19 @@ env = { POSTRIPPLE_API_KEY = "pr_..." }
 | `create_video_group` | content:write | Create a rotation group |
 | `add_videos_to_group` | content:write | Fill a group's rotation |
 | `update_group_schedule` | content:write | Attach accounts / set posts-per-day and time windows |
+| `get_image_upload_url` | content:write | Upload a slide image (JPEG 1080×1350 recommended) |
+| `import_image_from_url` | content:write | Import a slide image from a URL (synchronous) |
+| `create_slideshow` | content:write | Create a slideshow from pre-rendered images and/or template slides (server-side rendered) |
 | `schedule_post` | publish | Queue a video to publish at a future time (idempotent via `idempotencyKey`) |
+| `publish_slideshow` | publish | Publish or schedule a slideshow to Instagram/TikTok (supports TikTok drafts-inbox mode) |
 | `reschedule_post` | publish | Move a scheduled post |
 | `cancel_post` | publish | Cancel a scheduled post (refunds the credit) |
 
 Notes for agents:
 
-- `schedule_post` publishes to a **real** social account. Always pass `idempotencyKey`, and pass `tiktokSettings` if the post should be public on TikTok (the default is private/`SELF_ONLY`).
+- `schedule_post` and `publish_slideshow` publish to **real** social accounts. Always pass `idempotencyKey`, and pass `tiktokSettings` if the post should be public on TikTok (the default is private/`SELF_ONLY`).
+- The typical slideshow flow: `import_image_from_url` (or `get_image_upload_url` + PUT) per image → `create_slideshow` → poll `get_slideshow` until `ready` (template slides render server-side) → `publish_slideshow`. Pre-rendered JPEG slideshows are ready instantly.
+- TikTok `settings.postMode: "inbox"` sends the photo post to the account's TikTok app drafts inbox instead of publishing directly — useful when a human finishes posts from a real device.
 - Imports and publishes are asynchronous. Poll `list_videos` / `list_posts` to observe progress.
 - Every call is audit-logged and attributed to the member who created the key. Keys are org-bound; usage requires the Pro plan or higher.
 

package/dist/index.js

@@ -45,7 +45,7 @@ function toEpochMs(value, field) {
     }
     return parsed;
 }
-const server = new McpServer({ name: "postripple", version: "0.2.0" });
+const server = new McpServer({ name: "postripple", version: "0.3.0" });
 function register(name, description, shape, transform) {
     server.tool(name, description, shape, async (args) => {
         try {
@@ -108,8 +108,68 @@ const tiktokSettingsSchema = z
     disableStitch: z.boolean(),
     brandOrganicToggle: z.boolean(),
     brandContentToggle: z.boolean(),
+    autoAddMusic: z
+        .boolean()
+        .optional()
+        .describe("Photo (slideshow) posts only: let TikTok auto-pick background music. Defaults to true."),
+    postMode: z
+        .enum(["direct", "inbox"])
+        .optional()
+        .describe("Photo (slideshow) posts only. 'direct' (default) publishes immediately; 'inbox' sends a draft to the account's TikTok app inbox — the creator finishes it in the app, and privacy/comment/brand fields are ignored by TikTok in that mode."),
 })
     .describe("TikTok compliance settings. If omitted, the post publishes as SELF_ONLY (private).");
+/** One slide for create_slideshow: EITHER a finished image (prerenderedFileId)
+ *  OR a background + text fields rendered server-side from the template. */
+const slideTextStyleSchema = z
+    .object({
+    font: z
+        .enum(["classic", "impact", "serif", "typewriter", "handwriting"])
+        .optional(),
+    color: z.string().optional().describe("Text color (hex)"),
+    treatment: z
+        .enum(["none", "shadow", "outline", "highlight"])
+        .optional()
+        .describe("'highlight' = solid box behind each line (classic TikTok caption)"),
+    accentColor: z
+        .string()
+        .optional()
+        .describe("Box color for 'highlight' / stroke color for 'outline' (hex)"),
+    fontScale: z.number().min(0.5).max(2.5).optional(),
+    x: z.number().min(0).max(1).optional().describe("Anchor x (0..1 of canvas width)"),
+    y: z.number().min(0).max(1).optional().describe("Top y (0..1 of canvas height)"),
+    maxWidth: z.number().min(0.2).max(1).optional().describe("Text width (fraction of canvas width)"),
+    align: z.enum(["left", "center", "right"]).optional(),
+    rotation: z.number().min(-45).max(45).optional().describe("Degrees clockwise"),
+})
+    .describe("Optional per-field style overrides; anything omitted uses the template slot's defaults");
+const slideSchema = z.object({
+    prerenderedFileId: z
+        .string()
+        .optional()
+        .describe("A finished slide image (from get_image_upload_url or import_image_from_url) used as-is. JPEG at 1080x1350 recommended — other formats are re-encoded and cover-cropped to the canvas."),
+    backgroundFileId: z
+        .string()
+        .optional()
+        .describe("Background image for a template slide; text is rendered on top server-side."),
+    textFields: z
+        .array(z.object({
+        key: z
+            .string()
+            .describe("A template slot key (see list_slideshow_templates) or a 'custom-' prefixed key for a free text box"),
+        text: z.string(),
+        style: slideTextStyleSchema.optional(),
+    }))
+        .optional()
+        .describe("Template slides only"),
+    overlay: z
+        .object({
+        opacity: z.number().min(0).max(1),
+        direction: z.enum(["none", "bottom", "top", "full"]),
+        color: z.string().optional().describe("Hex, default #000000"),
+    })
+        .optional()
+        .describe("Darkening scrim over the background (template slides only); omit to use the template's default"),
+});
 // ---- read tools ----
 register("whoami", "Get who this key acts as and which organizations it can work in, plus the key's scopes. When an organization is selected (single-org key, organizationId argument, or POSTRIPPLE_ORG), also returns that workspace's overview: connected accounts, active groups, scheduled posts. Call this first to orient yourself.", { ...orgParam });
 register("list_social_accounts", "List the workspace's connected social accounts (TikTok / Instagram / YouTube) with connection health: status (active/expired/revoked/error), token expiry, and last error. Use the returned accountId for scheduling and metrics tools.", { ...orgParam });
@@ -121,6 +181,8 @@ register("list_videos", "List videos in the workspace library, newest first. Vid
 register("list_video_groups", "List video groups (rotation playlists that auto-post on a schedule) with video/account counts and status.", { ...orgParam });
 register("get_video_group", "Get one video group in detail: its videos and the per-account posting rules (posts per day, posting windows, next scheduled post).", { ...orgParam, groupId: z.string() });
 register("list_slideshows", "List photo-carousel slideshows with status ('draft' = still being composed, 'ready' = publishable).", { ...orgParam, limit: z.number().min(1).max(200).optional() });
+register("list_slideshow_templates", "List the slideshow layout templates: canvas size, each template's text slots (keys, defaults), available fonts and text treatments, and the max slide count. Call before create_slideshow when composing template-based slides.", {});
+register("get_slideshow", "Get one slideshow: per-slide render state and overall status, plus server-side render progress ({state, error}). Poll this after create_slideshow returns status 'rendering' — publish once status is 'ready'.", { ...orgParam, slideshowId: z.string() });
 register("list_posts", "List posts (scheduled, publishing, published, failed, canceled), newest first. Scheduled posts include scheduledFor; published posts include platformPostId and publishedAt.", {
     ...orgParam,
     status: postStatusEnum.optional(),
@@ -132,10 +194,18 @@ register("get_post_metrics", "Get engagement for one published post: latest snap
     postId: z.string(),
     limit: z.number().min(1).max(200).optional().describe("Max series points, default 50"),
 });
-register("get_account_metrics", "Get follower/profile growth history for one connected social account (daily snapshots).", {
+register("get_account_metrics", "Get follower/profile growth history (daily snapshots) for connected social accounts. Omit accountId to get every account in the organization at once; pass it to get a single account.", {
     ...orgParam,
-    accountId: z.string(),
-    limit: z.number().min(1).max(200).optional(),
+    accountId: z
+        .string()
+        .optional()
+        .describe("Omit for all accounts in the organization"),
+    limit: z
+        .number()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Max series points per account, default 50"),
 });
 register("get_engagement_summary", "Get an org-wide engagement overview for the last N days: totals, per-platform breakdown, top 5 posts by views, and current follower counts per account. The best starting point for 'how is content performing?'", { ...orgParam, days: z.number().min(1).max(90).optional().describe("Window in days, default 30") });
 // ---- content:write tools ----
@@ -170,6 +240,17 @@ register("update_group_schedule", "Attach a social account to a group or update
     status: z.enum(["active", "paused"]).optional(),
     postingWindows: z.array(postingWindowSchema).optional(),
 });
+register("get_image_upload_url", "Get a presigned upload URL for pushing a slide image into storage. PUT the raw image bytes to the returned uploadUrl with a Content-Type header, then use the returned fileId in create_slideshow. JPEG at 1080x1350 (4:5) strongly recommended.", { ...orgParam });
+register("import_image_from_url", "Import an image into storage from a public URL (synchronous — the returned fileId is immediately usable in create_slideshow). Accepts JPEG/PNG/WebP up to 15MB; JPEG is recommended since other formats get re-encoded and cover-cropped to the 1080x1350 canvas.", { ...orgParam, url: z.string().url() });
+register("create_slideshow", "Create a photo slideshow (1-10 slides). Each slide is EITHER {prerenderedFileId} — a finished image you composed — OR {backgroundFileId, textFields, overlay} rendered server-side using templateId's layout. Pre-rendered JPEG slides are ready instantly; template slides return status 'rendering' — poll get_slideshow until 'ready', then call publish_slideshow. Requires the slideshows plan feature.", {
+    ...orgParam,
+    title: z.string().optional(),
+    templateId: z
+        .string()
+        .optional()
+        .describe("Layout template id (see list_slideshow_templates). Default 'bold-bottom'; use 'blank' for custom-only text."),
+    slides: z.array(slideSchema).min(1).max(10),
+});
 // ---- publish tools ----
 register("schedule_post", "Schedule a completed library video to publish on a connected account at a future time. This posts to a REAL social account when the time arrives. The platform is derived from the account. Uses one 'posts' credit (refunded if canceled). ALWAYS pass idempotencyKey (any unique string) so retries can't double-post. For TikTok, pass tiktokSettings to control privacy — omitting it publishes as private (SELF_ONLY). For YouTube, pass title.", {
     ...orgParam,
@@ -195,6 +276,28 @@ register("reschedule_post", "Move a still-scheduled post to a new future time. F
     ...args,
     scheduledFor: toEpochMs(args.scheduledFor, "scheduledFor"),
 }));
+register("publish_slideshow", "Publish or schedule a READY slideshow to one or more Instagram/TikTok accounts as a native carousel / photo post. This posts to REAL social accounts. Omit scheduledFor to publish immediately; pass it to schedule (uses one 'posts' credit per account, refunded if canceled). ALWAYS pass idempotencyKey so retries can't double-post. TikTok targets without settings publish as SELF_ONLY (private); pass settings with postMode 'inbox' to send a draft to the account's TikTok app inbox instead.", {
+    ...orgParam,
+    slideshowId: z.string(),
+    targets: z
+        .array(z.object({
+        accountId: z.string(),
+        settings: tiktokSettingsSchema.optional(),
+    }))
+        .min(1)
+        .describe("Accounts to post to. settings applies to TikTok accounts only."),
+    caption: z.string().optional(),
+    scheduledFor: scheduledForSchema.optional(),
+    idempotencyKey: z
+        .string()
+        .optional()
+        .describe("Unique string for safe retries — strongly recommended"),
+}, (args) => args.scheduledFor === undefined
+    ? args
+    : {
+        ...args,
+        scheduledFor: toEpochMs(args.scheduledFor, "scheduledFor"),
+    });
 register("cancel_post", "Cancel a still-scheduled post and refund its credit. Fails once publishing has started.", { ...orgParam, postId: z.string() });
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@post-ripple/mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server that lets AI agents (Claude Code, Codex, opencode) manage a Post Ripple workspace: content, scheduling, publishing, and analytics.",
   "type": "module",
   "bin": {