@omnisocials/mcp-server 1.39.0 → 1.46.0

package/build/tools/automations.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { formatDateTime, truncate } from "../client.js";
+const SCOPE_HINT = "The API key needs the opt-in Automations scopes (OmniSocials Settings > API > create a key with Automations on: automations:read and automations:write).";
+const errorText = (error) => `Error (${error.code}): ${error.message}${error.code === "insufficient_scope" ? `\n\n${SCOPE_HINT}` : ""}`;
+const PLATFORM = z.enum(["instagram", "facebook"]);
+const KINDS = z.enum(["comment", "dm", "story_reply"]);
+// How the channel reads in a table or a sentence.
+export const automationChannelLabel = (platform) => platform === "facebook" ? "Facebook Page" : "Instagram";
+const MATCH = z.enum(["word", "contains", "any"]);
+const SCOPE = z.enum(["post", "next_post", "any"]);
+// The shared fields of create_automation and update_automation, flat so an
+// assistant fills them from one sentence ("DM everyone who comments guide").
+const AUTOMATION_FIELDS = {
+    platform: PLATFORM.optional().describe("Where the automation runs: 'instagram' (default) = the connected Instagram account, 'facebook' = the connected Facebook Page (the DM lands in Messenger). instagram_media_id implies 'instagram', facebook_post_id implies 'facebook'. It cannot change after create."),
+    name: z.string().max(120).optional().describe("A label for the automations list, e.g. 'Free guide'."),
+    keywords: z.array(z.string()).max(20).optional().describe("Keywords that start the automation (up to 20, matched case-insensitively), e.g. [\"guide\", \"link\"]. Required unless match is 'any'."),
+    match: MATCH.optional().describe("word (default): the keyword stands on its own ('guide', 'Guide!' match; 'linkedin' does not match 'link'). contains: the keyword appears anywhere. any: every comment or message with text (ask the user before using it)."),
+    dm_text: z.string().max(1000).optional().describe("The DM sent to the person (max 1000 characters), once per person. On Facebook it lands in Messenger. Required on create. Confirm the text with the user before creating the automation: it goes out in the account's name."),
+    public_replies: z.array(z.string().max(300)).max(10).optional().describe("Optional public replies posted under the comment (one is picked at random per comment), e.g. [\"Sent you a DM!\", \"Check your inbox\"]. Comment trigger only. An empty array turns the public reply off."),
+    triggers: z.array(KINDS).min(1).optional().describe("What starts the automation. 'comment' (default) = a comment on an Instagram post or reel, or on a Facebook Page post; 'dm' = a keyword in a DM to the Instagram account, or in a Messenger message to the Facebook Page; 'story_reply' = a keyword in a reply to an Instagram story (Instagram only: Facebook has no story replies). One automation can listen to several."),
+    scope: SCOPE.optional().describe("For the comment trigger: 'post' (default) = one post (pass post_id, instagram_media_id or facebook_post_id), 'next_post' = the next post the workspace publishes on this platform, 'any' = every post of the account or Page."),
+    post_id: z.string().optional().describe("For scope 'post': the OmniSocials post id (from list_posts) that goes to the automation's platform. A scheduled post starts listening once it is live. One automation per post and platform: a post that goes to Instagram and Facebook can have one of each."),
+    instagram_media_id: z.string().optional().describe("For scope 'post' on Instagram: the numeric Instagram media id of a post or reel that was NOT published through OmniSocials. OmniSocials reads it from Instagram to check it belongs to the connected account. Pass only one of post_id, instagram_media_id or facebook_post_id."),
+    facebook_post_id: z.string().optional().describe("For scope 'post' on Facebook: the id of a Facebook Page post that was NOT published through OmniSocials ({page-id}_{post-id}, or the post id alone). OmniSocials reads it from Facebook to check it belongs to the connected Page. Implies platform 'facebook'. Pass only one of post_id, instagram_media_id or facebook_post_id."),
+    max_sends: z.number().int().positive().nullable().optional().describe("Stop after this many DMs (the automation becomes 'completed'). null = no limit."),
+    stop_at: z.string().nullable().optional().describe("Stop at this time (ISO 8601). null = no end."),
+};
+// Turn the flat tool fields into the API body. Only the sections that were
+// given are sent, so update_automation leaves the rest untouched.
+export function buildAutomationBody(f, { create }) {
+    const body = {};
+    if (f.name !== undefined)
+        body.name = f.name;
+    if (f.post_id !== undefined)
+        body.post_id = f.post_id;
+    if (f.platform !== undefined)
+        body.platform = f.platform;
+    if (f.instagram_media_id !== undefined)
+        body.instagram_media_id = f.instagram_media_id;
+    if (f.facebook_post_id !== undefined)
+        body.facebook_post_id = f.facebook_post_id;
+    if (create || f.keywords !== undefined || f.match !== undefined || f.triggers !== undefined || f.scope !== undefined) {
+        body.trigger = {};
+        if (f.triggers !== undefined)
+            body.trigger.kinds = f.triggers;
+        if (f.scope !== undefined)
+            body.trigger.scope = f.scope;
+        if (f.keywords !== undefined)
+            body.trigger.keywords = f.keywords;
+        if (f.match !== undefined)
+            body.trigger.match = f.match;
+    }
+    if (create || f.dm_text !== undefined || f.public_replies !== undefined) {
+        body.actions = {
+            dm: { text: f.dm_text ?? "" },
+            ...(f.public_replies !== undefined
+                ? { public_reply: { enabled: f.public_replies.length > 0, variations: f.public_replies } }
+                : {}),
+        };
+    }
+    if (f.max_sends !== undefined || f.stop_at !== undefined) {
+        body.limits = {};
+        if (f.max_sends !== undefined)
+            body.limits.max_sends = f.max_sends;
+        if (f.stop_at !== undefined)
+            body.limits.stop_at = f.stop_at;
+    }
+    return body;
+}
+export function describeAutomation(a) {
+    const kinds = a.trigger.kinds.join(", ");
+    const scope = a.trigger.scope ? ` on ${a.trigger.scope === "post" ? "one post" : a.trigger.scope === "next_post" ? "the next post" : "every post"}` : "";
+    const keywords = a.trigger.match === "any" ? "any text" : a.trigger.keywords.map((k) => `"${k}"`).join(", ");
+    let md = `## Automation \`${a.id}\`${a.name ? ` "${a.name}"` : ""}\n\n`;
+    md += `| Field | Value |\n|-------|-------|\n`;
+    md += `| **Platform** | ${automationChannelLabel(a.platform)} |\n`;
+    md += `| **Status** | ${a.status} |\n`;
+    md += `| **Trigger** | ${kinds}${scope}, keywords ${keywords} (${a.trigger.match}) |\n`;
+    if (a.post) {
+        const label = a.post.caption ? truncate(a.post.caption, 60) : a.post.permalink || a.post.id;
+        md += `| **Post** | ${label}${a.post.permalink ? ` (${a.post.permalink})` : ""}${a.post.live === false ? " (not live yet)" : ""} |\n`;
+    }
+    else if (a.post_id) {
+        md += `| **Post** | OmniSocials post \`${a.post_id}\` |\n`;
+    }
+    md += `| **DM** | ${truncate(a.actions.dm.text, 120)} |\n`;
+    if (a.actions.public_reply.enabled && a.actions.public_reply.variations.length) {
+        md += `| **Public reply** | ${a.actions.public_reply.variations.map((v) => `"${truncate(v, 40)}"`).join(", ")} |\n`;
+    }
+    const limits = [a.limits.max_sends ? `max ${a.limits.max_sends} DMs` : null, a.limits.stop_at ? `until ${formatDateTime(a.limits.stop_at)}` : null].filter(Boolean);
+    if (limits.length)
+        md += `| **Limits** | ${limits.join(", ")} |\n`;
+    md += `| **Sent** | ${a.stats.sent} DMs (${a.stats.matched} matched, ${a.stats.skipped} skipped, ${a.stats.failed} failed) |\n`;
+    return md;
+}
+export function registerAutomationTools(server, getClient) {
+    server.tool("list_automations", "List the comment-to-DM automations of this workspace, on Instagram and on the Facebook Page. An automation DMs a person once when they comment a keyword on a post (or send it in a DM, or in an Instagram story reply), with an optional public reply under the comment. Use it to answer 'which automations run', before creating one on a post that may have one already, or to find the id for update_automation / get_automation_activity.", {
+        status: z.enum(["active", "paused", "completed"]).optional().describe("Only automations with this status."),
+        post_id: z.string().optional().describe("Only the automations bound to this OmniSocials post (one per platform at most)."),
+        platform: PLATFORM.optional().describe("Only the automations of this platform."),
+    }, { title: "List Automations", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async (params) => {
+        const result = await getClient().listAutomations(params);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        const items = Array.isArray(result.data) ? result.data : [];
+        if (!items.length) {
+            return { content: [{ type: "text", text: "No comment-to-DM automations yet. Create one with create_automation, or pass comment_dm_automation on create_post." }] };
+        }
+        let md = `## Automations (${items.length})\n\n`;
+        md += `| ID | Platform | Status | Trigger | Keywords | Post | Sent |\n|----|----------|--------|---------|----------|------|------|\n`;
+        for (const a of items) {
+            const post = a.post ? truncate(a.post.caption || a.post.permalink || a.post.id, 40) : a.post_id ? `post ${a.post_id}` : a.trigger.scope === "next_post" ? "next post" : a.trigger.scope === "any" ? "every post" : "";
+            const keywords = a.trigger.match === "any" ? "any text" : a.trigger.keywords.join(", ");
+            md += `| \`${a.id}\`${a.name ? ` ${a.name}` : ""} | ${automationChannelLabel(a.platform)} | ${a.status} | ${a.trigger.kinds.join(", ")} | ${keywords} | ${post} | ${a.stats.sent} |\n`;
+        }
+        md += `\nDetails with get_automation, activity with get_automation_activity, pause or edit with update_automation.`;
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("get_automation", "Get one comment-to-DM automation: its platform (Instagram or the Facebook Page), its trigger, the DM text, the public replies, the limits and the counts.", { automation_id: z.string().describe("The automation id (from list_automations).") }, { title: "Get Automation", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ automation_id }) => {
+        const result = await getClient().getAutomation(automation_id);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        if (!result.data)
+            return { content: [{ type: "text", text: "The API returned no automation." }] };
+        return { content: [{ type: "text", text: describeAutomation(result.data) }] };
+    });
+    server.tool("create_automation", "Create a comment-to-DM automation on the connected Instagram account (default) or on the connected Facebook Page (platform 'facebook'): when somebody comments one of the keywords on the post (or sends it in a DM, or in an Instagram story reply, see triggers), the account DMs them dm_text once, and optionally posts one of public_replies under the comment. On Facebook the DM lands in Messenger. Before creating one, show the user the keyword(s) and the exact DM text and get a yes: the DM goes out in their name. Meta rules, the same on both: one private reply per comment, within 7 days of the comment; a follow-up only after the person answers (24-hour window); OmniSocials caps sends at 180 DMs an hour per account and platform. For scope 'post' pass one of post_id (an OmniSocials post, scheduled or live), instagram_media_id (an Instagram post published outside OmniSocials) or facebook_post_id (a Page post published outside OmniSocials). To attach automations to a NEW post, pass comment_dm_automation on create_post instead.", AUTOMATION_FIELDS, { title: "Create Automation", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async (params) => {
+        if (!params.dm_text)
+            return { content: [{ type: "text", text: "dm_text is required: the DM the person receives." }] };
+        const result = await getClient().createAutomation(buildAutomationBody(params, { create: true }));
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        if (!result.data)
+            return { content: [{ type: "text", text: "Automation created, but the API returned no details. List it with list_automations." }] };
+        const a = result.data;
+        let md = `Created automation \`${a.id}\` (${a.status}).\n\n${describeAutomation(a)}`;
+        if (a.post && a.post.live === false)
+            md += `\n_The post is not live on ${a.platform === "facebook" ? "the Facebook Page" : "Instagram"} yet; the automation starts listening at publish._`;
+        return { content: [{ type: "text", text: md }] };
+    });
+    server.tool("update_automation", "Change a comment-to-DM automation: pause or resume it (status), new keywords or match, a new DM text or public replies, new limits, or move it to another post (post_id, instagram_media_id or facebook_post_id). Only the fields you pass change. The platform cannot change: to move from Instagram to the Facebook Page, create a new automation. A 'completed' automation starts again when its limits or trigger change.", {
+        automation_id: z.string().describe("The automation id (from list_automations)."),
+        status: z.enum(["active", "paused"]).optional().describe("'paused' stops it without deleting it; 'active' resumes it."),
+        ...AUTOMATION_FIELDS,
+    }, { title: "Update Automation", readOnlyHint: false, destructiveHint: false, openWorldHint: false }, async ({ automation_id, status, ...fields }) => {
+        const body = buildAutomationBody(fields, { create: false });
+        if (status)
+            body.status = status;
+        if (Object.keys(body).length === 0)
+            return { content: [{ type: "text", text: "Nothing to change: pass status, keywords, dm_text, public_replies, limits or a post." }] };
+        const result = await getClient().updateAutomation(automation_id, body);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        if (!result.data)
+            return { content: [{ type: "text", text: "Automation updated, but the API returned no details. Read it with get_automation." }] };
+        return { content: [{ type: "text", text: `Updated automation \`${automation_id}\`.\n\n${describeAutomation(result.data)}` }] };
+    });
+    server.tool("delete_automation", "Delete a comment-to-DM automation (Instagram or Facebook Page) and its activity log. DMs that were already sent stay sent. To stop it for a while, use update_automation with status 'paused' instead. Confirm with the user first.", { automation_id: z.string().describe("The automation id (from list_automations).") }, { title: "Delete Automation", readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ automation_id }) => {
+        const result = await getClient().deleteAutomation(automation_id);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        return { content: [{ type: "text", text: `Deleted automation \`${automation_id}\`.` }] };
+    });
+    server.tool("get_automation_activity", "The activity of a comment-to-DM automation, newest first: one row per comment or message it acted on, with the DM sent, a skip and its reason (already got the DM, limit reached, comment older than 7 days, hourly cap), or a failure with the platform's error. On the Facebook Page the person shows by name (Facebook has no @handle). Use it to answer 'how many people got the DM' or 'why did this person not get it'.", {
+        automation_id: z.string().describe("The automation id (from list_automations)."),
+        outcome: z.enum(["sent", "skipped", "failed", "pending"]).optional().describe("Only rows with this outcome."),
+        limit: z.number().int().min(1).max(100).optional().describe("Rows per page (default 25, max 100)."),
+        offset: z.number().int().min(0).optional().describe("Rows to skip (for the next page)."),
+    }, { title: "Get Automation Activity", readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ automation_id, ...params }) => {
+        // The automation's platform decides how a person shows: an Instagram
+        // @handle, or a Facebook name.
+        const [result, automation] = await Promise.all([
+            getClient().listAutomationEvents(automation_id, params),
+            getClient().getAutomation(automation_id).catch(() => null),
+        ]);
+        if (result.error)
+            return { content: [{ type: "text", text: errorText(result.error) }] };
+        const onFacebook = automation?.data?.platform === "facebook";
+        const rows = Array.isArray(result.data) ? result.data : [];
+        const counts = result.counts || {};
+        const countLine = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ") || "nothing yet";
+        if (!rows.length) {
+            return { content: [{ type: "text", text: `## Activity of automation \`${automation_id}\`\n\nTotals: ${countLine}.\n\nNo rows${params.outcome ? ` with outcome ${params.outcome}` : ""}.` }] };
+        }
+        let md = `## Activity of automation \`${automation_id}\`\n\nTotals: ${countLine}.\n\n`;
+        md += `| When | Who | Did | Outcome | Text |\n|------|-----|-----|---------|------|\n`;
+        for (const e of rows) {
+            const who = e.person.username ? (onFacebook ? e.person.username : `@${e.person.username}`) : e.person.id;
+            const did = e.kind === "comment" ? "commented" : e.kind === "dm" ? (onFacebook ? "sent a Messenger message" : "sent a DM") : "replied to a story";
+            const outcome = e.outcome === "skipped" ? `skipped: ${e.reason_label || e.reason || ""}` : e.outcome === "failed" ? `failed: ${truncate(e.reason || "", 60)}` : e.outcome;
+            const text = e.trigger_text ? `"${truncate(e.trigger_text, 50)}"` : "";
+            md += `| ${formatDateTime(e.sent_at || e.created_at)} | ${who} | ${did} | ${outcome} | ${text} |\n`;
+        }
+        const p = result.pagination;
+        if (p?.has_more)
+            md += `\n_${p.total} rows in total; pass offset ${p.offset + p.limit} for the next page._`;
+        return { content: [{ type: "text", text: md }] };
+    });
+}

package/build/tools/media.js

@@ -188,7 +188,7 @@ When the user provides an image in the conversation (not a URL), use base64_data
     });
     server.tool("check_media_compatibility", `Check whether a video/image will be accepted by the platforms CONNECTED to this workspace, BEFORE uploading or posting. Use this when the user gives you a file (URL) so you can warn them upfront — e.g. "this 995 MB video won't post to Instagram (max 300 MB), continue?" — and confirm before uploading.
 
-Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an existing 'media_id', or explicit 'size_bytes' + 'mime'. Returns the connected platforms and any that would reject the file by size or format.`, {
+Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an existing 'media_id', or explicit 'size_bytes' + 'mime'. Returns the connected platforms and any that would reject the file by size or format, plus IMAGE FIT rows for an image whose size is known (a library file): per connected channel, whether its feed shows the image uncropped and what a post does by default (Instagram crops a 9:16 / wide image to 4:5 / 1.91:1 around the subject; Pinterest keeps a tall Pin and reports it). When a fit row says fits: false, ask the user "crop to <target> (recommended for Instagram: Meta can boost it) or keep the original (the channel cuts it itself)?" and pass the answer as media_fit on create_post.`, {
         url: z.string().optional().describe("Public URL of the file to check. Use this OR media_id OR size_bytes+mime."),
         media_id: z.string().optional().describe("Id of an already-uploaded library item to check."),
         size_bytes: z.number().optional().describe("File size in bytes (use with mime when you already know them)."),
@@ -225,6 +225,19 @@ Provide ONE of: a public 'url' (its size/type is read via a HEAD request), an ex
             }
             md += `\nAsk the user whether to continue. It will still post to the platforms not listed above.`;
         }
+        const outside = (r.fit || []).filter((f) => !f.fits);
+        if (outside.length) {
+            const dims = r.file?.width && r.file?.height ? ` (${r.file.width}x${r.file.height})` : "";
+            md += `\n\n**Image fit**${dims}: how these channels show it in the feed\n\n| Platform | Ratio | In the feed | A post does |\n|----------|-------|-------------|-------------|\n`;
+            for (const f of outside) {
+                const does = f.default_action === "crop" ? `crops it to ${f.target} (media_fit "keep" sends the original)` : `keeps it and reports it (media_fit "crop" crops to ${f.target})`;
+                md += `| ${f.display_name} | ${f.ratio} | cut to ${f.target} | ${does} |\n`;
+            }
+            md += `\nAsk the user per channel above: crop to the target (Instagram: Meta can then boost the post) or keep the original (the channel cuts it itself)? Pass the answer as \`media_fit\` on create_post. Stories, reels and the other channels are not affected.`;
+        }
+        else if ((r.fit || []).length) {
+            md += `\n\nImage fit: this image shows uncropped in every connected feed with a rule (${(r.fit || []).map((f) => f.display_name).join(", ")}).`;
+        }
         return { content: [{ type: "text", text: md }] };
     });
     server.tool("update_media", "Rename an existing media file or move it into a folder (so it's findable later instead of re-uploading it). Only the fields you pass are changed.", {