@post-ripple/mcp 0.2.1 → 0.5.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.1" });
+const server = new McpServer({ name: "postripple", version: "0.5.0" });
 function register(name, description, shape, transform) {
     server.tool(name, description, shape, async (args) => {
         try {
@@ -108,8 +108,72 @@ 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({
+    imageId: z
+        .string()
+        .optional()
+        .describe("A library image (from list_images / register_uploaded_image / import_image_from_url) used as the slide background; text is rendered on top server-side. Provide exactly one of imageId, prerenderedFileId, or backgroundFileId per slide."),
+    prerenderedFileId: z
+        .string()
+        .optional()
+        .describe("A finished slide image (a fileId from get_image_upload_url, import_image_from_url, or list_images) 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 (raw fileId) for a template slide; text is rendered on top server-side. Prefer imageId when the image is in the library."),
+    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 });
@@ -120,7 +184,24 @@ 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_images", "List/search the workspace's image library, newest first (relevance order when text is passed). Every image ever uploaded, imported, or generated lives here until deleted — CHECK THIS BEFORE generating or re-uploading images; reusing an existing image is free and instant. Each result has an imageId (pass to create_slideshow slides), its raw fileId, a signed preview url (~1h), and its title/description/tags/prompt metadata.", {
+    ...orgParam,
+    text: z
+        .string()
+        .optional()
+        .describe("Free-text search over title, description, tags, and generation prompt"),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe("Only images carrying ALL of these tags"),
+    source: z
+        .enum(["upload", "agent_upload", "agent_import", "generated"])
+        .optional(),
+    limit: z.number().min(1).max(200).optional().describe("Default 100, max 200"),
+});
+register("list_slideshows", "List photo-carousel slideshows with status ('draft' = still being composed, 'ready' = publishable) and a signed coverUrl thumbnail (first rendered slide, or a background for drafts).", { ...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 with exact geometry (x/y anchor, maxWidth, fontSize, lineHeight — all normalized to the canvas) and defaults (font, color, treatment), the template's default overlay scrim, available fonts and text treatments, and the max slide count. Call before create_slideshow when composing template-based slides — use the slot geometry rather than inventing your own placement.", {});
+register("get_slideshow", "Get one slideshow in full detail: per-slide render state, each text field's text AND its style overrides (font, color, treatment, fontScale, x/y position, maxWidth, align, rotation — null style means the template slot defaults apply), the slide's overlay scrim, and signed image URLs (renderedUrl = the finished slide, backgroundUrl = the photo behind it; both expire in ~1h). Use it to study how existing slides are actually styled before composing new ones, or poll it 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(),
@@ -178,6 +259,42 @@ 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 an image into the workspace library. PUT the raw image bytes to the returned uploadUrl with a Content-Type header, then call register_uploaded_image with the returned fileId (plus a title/tags so the image is findable later). JPEG at 1080x1350 (4:5) strongly recommended.", { ...orgParam });
+register("register_uploaded_image", "Register an image after uploading its bytes to a presigned URL from get_image_upload_url. This saves it to the workspace image library — it persists until deleted and can be reused in any slideshow (via list_images). Give it a descriptive title and tags so it's easy to find again.", {
+    ...orgParam,
+    fileId: z.string().describe("The fileId returned by get_image_upload_url"),
+    title: z.string().optional().describe("Descriptive title — strongly recommended for later discovery"),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional().describe("Lowercase keywords for filtering in list_images"),
+});
+register("import_image_from_url", "Import an image into the workspace library from a public URL (synchronous — the returned imageId/fileId are immediately usable in create_slideshow, and the image persists in the library for reuse via list_images). Accepts JPEG/PNG/WebP up to 15MB; JPEG is recommended since other formats get re-encoded and cover-cropped to the 1080x1350 canvas. Give it a title/tags so it's findable later.", {
+    ...orgParam,
+    url: z.string().url(),
+    title: z.string().optional().describe("Descriptive title — strongly recommended for later discovery"),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional().describe("Lowercase keywords for filtering in list_images"),
+});
+register("update_image", "Update a library image's title, description, or tags (e.g. to make older images easier to rediscover via list_images).", {
+    ...orgParam,
+    imageId: z.string(),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    tags: z.array(z.string()).optional().describe("Replaces the existing tag list"),
+});
+register("delete_image", "Delete a library image and its stored file. If the image is still used as a slide background or character thumbnail, the call returns the references instead of deleting; retry with force: true to delete anyway (those draft slides lose their background). Images that ARE a slideshow's final rendered content can't be deleted at all — delete the slideshow first.", {
+    ...orgParam,
+    imageId: z.string(),
+    force: z.boolean().optional(),
+});
+register("create_slideshow", "Create a photo slideshow (1-10 slides). Each slide is EXACTLY ONE OF: {imageId} — a library image (see list_images) as the background, optionally with textFields/overlay; {prerenderedFileId} — a finished image you composed, used as-is; or {backgroundFileId, textFields, overlay} rendered server-side using templateId's layout. Reuse library images via list_images before generating or uploading new ones. Pre-rendered JPEG slides are ready instantly; other 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,
@@ -203,6 +320,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.1",
+  "version": "0.5.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": {