@post-ripple/mcp 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @post-ripple/mcp
+
+MCP server that lets AI agents (Claude Code, Codex, opencode, and any other MCP client) manage a [Post Ripple](https://postripple.app) workspace: import and organize videos, run rotation groups, schedule posts to TikTok / Instagram Reels / YouTube Shorts, and read engagement analytics.
+
+## Setup
+
+1. In Post Ripple, go to **Settings → API Keys** (Pro plan and up) and create a key. Pick scopes:
+   - `read` — list content, posts, accounts, analytics
+   - `content:write` — create/organize videos, groups, schedules
+   - `publish` — schedule/cancel posts to real social accounts (off by default; enable deliberately)
+2. Give your agent the key as the `POSTRIPPLE_API_KEY` environment variable. That's the only configuration needed.
+
+### Claude Code
+
+```sh
+claude mcp add postripple \
+  -e POSTRIPPLE_API_KEY=pr_... \
+  -- npx -y @post-ripple/mcp@latest
+```
+
+### Codex
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.postripple]
+command = "npx"
+args = ["-y", "@post-ripple/mcp@latest"]
+env = { POSTRIPPLE_API_KEY = "pr_..." }
+```
+
+### opencode
+
+`opencode.json`:
+
+```json
+{
+  "mcp": {
+    "postripple": {
+      "type": "local",
+      "command": ["npx", "-y", "@post-ripple/mcp@latest"],
+      "environment": {
+        "POSTRIPPLE_API_KEY": "pr_..."
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Scope | What it does |
+| --- | --- | --- |
+| `whoami` | read | Workspace overview: org, plan, accounts, key scopes |
+| `list_social_accounts` | read | Connected accounts with token health |
+| `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_posts` | read | Posts with status, schedule, errors |
+| `get_post_metrics` | read | Per-post engagement time series |
+| `get_account_metrics` | read | Follower growth history |
+| `get_engagement_summary` | read | Org-wide totals, per-platform breakdown, top posts |
+| `import_video_from_url` | content:write | Import a video from a URL (async download) |
+| `get_video_upload_url` / `register_uploaded_video` | content:write | Upload a local video file |
+| `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 |
+| `schedule_post` | publish | Queue a video to publish at a future time (idempotent via `idempotencyKey`) |
+| `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`).
+- 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.
+
+## Development
+
+The server talks to `https://api.postripple.app` by default. Set `POSTRIPPLE_API_URL` to target a dev deployment instead:
+
+```sh
+npm install
+npm run build
+POSTRIPPLE_API_KEY=pr_... POSTRIPPLE_API_URL=https://<dev-deployment>.convex.site node dist/index.js
+```

package/dist/index.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const DEFAULT_API_URL = "https://api.postripple.app";
+const API_KEY = process.env.POSTRIPPLE_API_KEY;
+// Override only for development against a non-production deployment.
+const API_URL = (process.env.POSTRIPPLE_API_URL ?? DEFAULT_API_URL).replace(/\/+$/, "");
+if (!API_KEY) {
+    console.error("POSTRIPPLE_API_KEY is not set. Create a key in Post Ripple under Settings → API Keys (Pro plan and up) and set it in the MCP server env.");
+    process.exit(1);
+}
+async function callApi(tool, body) {
+    const response = await fetch(`${API_URL}/agent/v1/${tool}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch {
+        throw new Error(`Post Ripple API returned ${response.status} with a non-JSON body`);
+    }
+    if (!payload.ok || !response.ok) {
+        const err = payload.error ?? { code: "unknown", message: `HTTP ${response.status}` };
+        throw new Error(`${err.code}: ${err.message}`);
+    }
+    return payload.data;
+}
+/** Accepts epoch ms or an ISO-8601 string and returns epoch ms. */
+function toEpochMs(value, field) {
+    if (typeof value === "number")
+        return value;
+    const parsed = Date.parse(value);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`${field} must be epoch milliseconds or an ISO-8601 datetime`);
+    }
+    return parsed;
+}
+const server = new McpServer({ name: "postripple", version: "0.1.0" });
+function register(name, description, shape, transform) {
+    server.tool(name, description, shape, async (args) => {
+        try {
+            const body = transform ? transform(args) : args;
+            const data = await callApi(name, body);
+            return {
+                content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: ${message}` }],
+            };
+        }
+    });
+}
+const platformEnum = z.enum(["tiktok", "instagram", "youtube", "other"]);
+const postStatusEnum = z.enum([
+    "scheduled",
+    "pending",
+    "uploading",
+    "processing",
+    "published",
+    "failed",
+    "canceled",
+]);
+const videoStatusEnum = z.enum(["pending", "downloading", "completed", "failed"]);
+const scheduledForSchema = z
+    .union([z.number(), z.string()])
+    .describe("When to publish: epoch milliseconds or ISO-8601 datetime. Must be in the future.");
+const postingWindowSchema = z.object({
+    startHour: z.number().min(0).max(23),
+    startMinute: z.number().min(0).max(59),
+    endHour: z.number().min(0).max(23),
+    endMinute: z.number().min(0).max(59),
+});
+const tiktokSettingsSchema = z
+    .object({
+    privacyLevel: z.enum([
+        "PUBLIC_TO_EVERYONE",
+        "MUTUAL_FOLLOW_FRIENDS",
+        "FOLLOWER_OF_CREATOR",
+        "SELF_ONLY",
+    ]),
+    disableComment: z.boolean(),
+    disableDuet: z.boolean(),
+    disableStitch: z.boolean(),
+    brandOrganicToggle: z.boolean(),
+    brandContentToggle: z.boolean(),
+})
+    .describe("TikTok compliance settings. If omitted, the post publishes as SELF_ONLY (private).");
+// ---- read tools ----
+register("whoami", "Get the connected Post Ripple workspace: organization name, plan, connected social accounts, active group count, scheduled post count, and this key's scopes. Call this first to orient yourself.", {});
+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.", {});
+register("list_videos", "List videos in the workspace library, newest first. Videos with status 'completed' are publishable; 'pending'/'downloading' are still being imported.", {
+    status: videoStatusEnum.optional(),
+    limit: z.number().min(1).max(200).optional().describe("Default 50, max 200"),
+});
+register("list_video_groups", "List video groups (rotation playlists that auto-post on a schedule) with video/account counts and status.", {});
+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).", { groupId: z.string() });
+register("list_slideshows", "List photo-carousel slideshows with status ('draft' = still being composed, 'ready' = publishable).", { limit: z.number().min(1).max(200).optional() });
+register("list_posts", "List posts (scheduled, publishing, published, failed, canceled), newest first. Scheduled posts include scheduledFor; published posts include platformPostId and publishedAt.", {
+    status: postStatusEnum.optional(),
+    platform: platformEnum.optional(),
+    limit: z.number().min(1).max(200).optional(),
+});
+register("get_post_metrics", "Get engagement for one published post: latest snapshot (views/likes/comments/shares) plus the time series of scraped metrics.", {
+    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).", {
+    accountId: z.string(),
+    limit: z.number().min(1).max(200).optional(),
+});
+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?'", { days: z.number().min(1).max(90).optional().describe("Window in days, default 30") });
+// ---- content:write tools ----
+register("import_video_from_url", "Import a video into the library from a public URL (e.g. a TikTok/Instagram/YouTube link or a direct file URL). Download happens asynchronously — poll list_videos until its status is 'completed' before scheduling it.", {
+    url: z.string().url(),
+    platform: platformEnum
+        .optional()
+        .describe("Source platform of the URL; helps the downloader. Defaults to 'other'."),
+});
+register("get_video_upload_url", "Get a presigned upload URL for pushing a local video file into the library. PUT the raw video bytes to the returned uploadUrl, then call register_uploaded_video with the returned fileId.", {});
+register("register_uploaded_video", "Register a video after uploading its bytes to a presigned URL from get_video_upload_url. The video becomes immediately publishable.", {
+    fileId: z.string().describe("The fileId returned by get_video_upload_url"),
+    title: z.string(),
+});
+register("create_video_group", "Create a video group (a shuffle rotation playlist). Attach accounts with update_group_schedule and add videos with add_videos_to_group to start auto-posting. Uses one 'groups' credit from the plan.", {
+    name: z.string(),
+    description: z.string().optional(),
+});
+register("add_videos_to_group", "Add up to 100 library videos to a group's rotation. Returns which were added and which were skipped (already present / not found).", {
+    groupId: z.string(),
+    videoIds: z.array(z.string()).min(1).max(100),
+});
+register("update_group_schedule", "Attach a social account to a group or update its posting rules: posts per day (1-24), active/paused, and optional posting time windows (hours in the org's timezone). First call for an account must include postsPerDay.", {
+    groupId: z.string(),
+    accountId: z.string(),
+    postsPerDay: z.number().min(1).max(24).optional(),
+    status: z.enum(["active", "paused"]).optional(),
+    postingWindows: z.array(postingWindowSchema).optional(),
+});
+// ---- 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.", {
+    videoId: z.string(),
+    accountId: z.string(),
+    scheduledFor: scheduledForSchema,
+    caption: z.string().optional(),
+    title: z.string().optional().describe("YouTube title (ignored elsewhere)"),
+    tiktokSettings: tiktokSettingsSchema.optional(),
+    idempotencyKey: z
+        .string()
+        .optional()
+        .describe("Unique string for safe retries — strongly recommended"),
+}, (args) => ({
+    ...args,
+    scheduledFor: toEpochMs(args.scheduledFor, "scheduledFor"),
+}));
+register("reschedule_post", "Move a still-scheduled post to a new future time. Fails once publishing has started.", {
+    postId: z.string(),
+    scheduledFor: scheduledForSchema,
+}, (args) => ({
+    ...args,
+    scheduledFor: toEpochMs(args.scheduledFor, "scheduledFor"),
+}));
+register("cancel_post", "Cancel a still-scheduled post and refund its credit. Fails once publishing has started.", { postId: z.string() });
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`Post Ripple MCP server connected (${API_URL})`);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@post-ripple/mcp",
+  "version": "0.1.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": {
+    "postripple-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@types/node": "^22.10.2"
+  }
+}