@post-ripple/mcp 0.1.0 → 0.2.1

package/README.md

@@ -10,6 +10,8 @@ MCP server that lets AI agents (Claude Code, Codex, opencode, and any other MCP
    - `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.
 
+Keys are personal: one key works in **every organization you belong to** (unless you restricted it at creation). Agents discover your organizations via `whoami` and pass `organizationId` per call — or set the optional `POSTRIPPLE_ORG` environment variable to pin a default organization (handy for pinning one brand per repo).
+
 ### Claude Code
 
 ```sh

package/dist/index.js

@@ -6,6 +6,9 @@ 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(/\/+$/, "");
+// Optional default organization for keys that span several. A per-call
+// organizationId argument always wins over this.
+const DEFAULT_ORG = process.env.POSTRIPPLE_ORG;
 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);
@@ -42,11 +45,14 @@ function toEpochMs(value, field) {
     }
     return parsed;
 }
-const server = new McpServer({ name: "postripple", version: "0.1.0" });
+const server = new McpServer({ name: "postripple", version: "0.2.1" });
 function register(name, description, shape, transform) {
     server.tool(name, description, shape, async (args) => {
         try {
-            const body = transform ? transform(args) : args;
+            let body = transform ? transform(args) : args;
+            if (DEFAULT_ORG && body.organizationId === undefined) {
+                body = { ...body, organizationId: DEFAULT_ORG };
+            }
             const data = await callApi(name, body);
             return {
                 content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -61,6 +67,14 @@ function register(name, description, shape, transform) {
         }
     });
 }
+// Keys are personal and can span several organizations. Every org-scoped
+// tool accepts this; whoami lists the available organizations.
+const orgParam = {
+    organizationId: z
+        .string()
+        .optional()
+        .describe("Target organization id (see whoami's organizations list). Optional when the key has access to a single organization or POSTRIPPLE_ORG is set."),
+};
 const platformEnum = z.enum(["tiktok", "instagram", "youtube", "other"]);
 const postStatusEnum = z.enum([
     "scheduled",
@@ -97,50 +111,67 @@ const tiktokSettingsSchema = z
 })
     .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("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 });
 register("list_videos", "List videos in the workspace library, newest first. Videos with status 'completed' are publishable; 'pending'/'downloading' are still being imported.", {
+    ...orgParam,
     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_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_posts", "List posts (scheduled, publishing, published, failed, canceled), newest first. Scheduled posts include scheduledFor; published posts include platformPostId and publishedAt.", {
+    ...orgParam,
     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.", {
+    ...orgParam,
     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_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()
+        .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?'", { days: z.number().min(1).max(90).optional().describe("Window in days, default 30") });
+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 ----
 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.", {
+    ...orgParam,
     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("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.", { ...orgParam });
 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.", {
+    ...orgParam,
     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.", {
+    ...orgParam,
     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).", {
+    ...orgParam,
     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.", {
+    ...orgParam,
     groupId: z.string(),
     accountId: z.string(),
     postsPerDay: z.number().min(1).max(24).optional(),
@@ -149,6 +180,7 @@ register("update_group_schedule", "Attach a social account to a group or update
 });
 // ---- 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,
     videoId: z.string(),
     accountId: z.string(),
     scheduledFor: scheduledForSchema,
@@ -164,13 +196,14 @@ register("schedule_post", "Schedule a completed library video to publish on a co
     scheduledFor: toEpochMs(args.scheduledFor, "scheduledFor"),
 }));
 register("reschedule_post", "Move a still-scheduled post to a new future time. Fails once publishing has started.", {
+    ...orgParam,
     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() });
+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);
 console.error(`Post Ripple MCP server connected (${API_URL})`);

package/package.json

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