postfast-mcp 0.3.0 → 0.3.1

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "postfast",
       "description": "Schedule, manage, and analyze social media posts via PostFast. Supports Facebook, Instagram, X, TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, and Google Business Profile.",
-      "version": "0.3.0",
+      "version": "0.3.1",
       "author": {
         "name": "PostFast",
         "email": "me@peturgeorgievv.com"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "postfast",
   "description": "Schedule, manage, and analyze social media posts via PostFast. Supports Facebook, Instagram, X, TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, and Google Business Profile. After installing, tell Cowork: 'Set my PostFast API key' — get your key at https://app.postfa.st/dashboard → API.",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": {
     "name": "PostFast",
     "email": "me@peturgeorgievv.com"

package/README.md

@@ -133,6 +133,23 @@ Ask your AI assistant things like:
 | `get_post_analytics` | Fetch published posts with performance metrics — Instagram, Facebook, TikTok, Threads, YouTube, LinkedIn (company pages), Pinterest (Business accounts) |
 | `get_follower_history` | Daily follower-count history for an account (current count + `delta` over a date range) — Facebook Pages, Instagram, YouTube, Pinterest, Threads, Bluesky, Telegram, LinkedIn (company pages), TikTok |
 
+### Social Inbox (comments)
+
+Comments on your posts — TikTok (Business connections), Instagram, Facebook Pages, and Threads — in one inbox. Comments only (no direct messages), from connect onward (no history backfill). Reply capability is always server-computed per conversation (`canReply`, `maxReplyLength`, `windowState`, `disabledReason`) — render from those fields, never platform assumptions.
+
+| Tool | Description |
+|------|-------------|
+| `list_inbox_conversations` | List comment conversations (filters: platforms, accounts, statuses, unread-only, assignee) |
+| `get_inbox_conversation` | Fetch one conversation with its reply-capability fields |
+| `list_inbox_items` | List a conversation's comments and replies (with `state` and, on Instagram, `canPrivateReply`) |
+| `get_inbox_unread_count` | Total unread comment count across the workspace |
+| `reply_to_inbox_item` | Reply publicly under a specific comment |
+| `send_inbox_private_reply` | Instagram only: one private reply per comment, within 7 days |
+| `set_inbox_item_state` | HIDE / UNHIDE / DELETE a comment on the platform (DELETE cannot be undone) |
+| `mark_inbox_conversation_read` | Zero a conversation's unread count |
+| `set_inbox_conversation_status` | Triage: OPEN / SNOOZED / CLOSED |
+| `assign_inbox_conversation` | Assign a conversation to a workspace member (or unassign) |
+
 ## Supported Platforms
 
 Facebook, Instagram, X (Twitter), TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, Google Business Profile

package/dist/core/instructions.js

@@ -38,7 +38,9 @@ Platform-specific options go in the controls object, e.g.:
 - X: controls.xRetweetUrl reposts an existing tweet (content/media are ignored).
 Note: list_pinterest_boards / list_youtube_playlists / list_gbp_locations take the account's socialMediaId; each returned item has BOTH an internal id and the platform id (boardId / playlistId / locationId) — pass the PLATFORM id to controls, not the internal id or the account id.
 
-Failed posts carry lastError — usually a disconnected account (reconnect, then retry) or platform-rejected media.`;
+Failed posts carry lastError — usually a disconnected account (reconnect, then retry) or platform-rejected media.
+
+Social inbox (comments on your posts — TikTok Business connections, Instagram, Facebook Pages, Threads): read with list_inbox_conversations → list_inbox_items (get_inbox_unread_count for the total), reply with reply_to_inbox_item (public, under a specific comment item) or send_inbox_private_reply (Instagram only: one per comment, within 7 days). Whether and how long a reply can be comes ONLY from the conversation's server-computed canReply / maxReplyLength / windowState / disabledReason — never assume platform rules. Moderate with set_inbox_item_state (HIDE / UNHIDE / DELETE — DELETE removes the comment on the platform and cannot be undone), triage with set_inbox_conversation_status and assign_inbox_conversation, and call mark_inbox_conversation_read after presenting a thread. It is a comments inbox — never present it as DMs or messages.`;
 const STDIO_INSTRUCTIONS = `PostFast schedules and publishes social posts across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram, and Google Business Profile.
 
 Flow: list_accounts to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_media (a local file, by absolute path) or get_upload_urls (signed PUT upload for raw bytes) → a post publishes when status=SCHEDULED and approvalStatus=APPROVED.

package/dist/core/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/core/instructions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kHA8B8F,CAAC;AAEnH,MAAM,kBAAkB,GAAG;;;;;;EAMzB,WAAW,EAAE,CAAC;AAEhB,MAAM,mBAAmB,GAAG;;;;;;EAM1B,WAAW,EAAE,CAAC;AAEhB,MAAM,CAAC,MAAM,mBAAmB,GAA4B;IAC1D,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;CAC5B,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/core/instructions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;k1BAgC8zB,CAAC;AAEn1B,MAAM,kBAAkB,GAAG;;;;;;EAMzB,WAAW,EAAE,CAAC;AAEhB,MAAM,mBAAmB,GAAG;;;;;;EAM1B,WAAW,EAAE,CAAC;AAEhB,MAAM,CAAC,MAAM,mBAAmB,GAA4B;IAC1D,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;CAC5B,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}

package/dist/stdio/index.js

@@ -6,7 +6,7 @@ import { instructionsFor } from '../core/instructions.js';
 import { RestAdapter } from './rest-adapter.js';
 const server = new McpServer({
     name: 'postfast',
-    version: '0.3.0',
+    version: '0.3.1',
 }, { instructions: instructionsFor('stdio') });
 const port = new RestAdapter();
 registerCatalogTools(server, { binding: 'stdio', port });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postfast-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "mcpName": "io.github.peturgeorgievv-factory/postfast-mcp",
   "description": "MCP server for the PostFast API — schedule and manage social media posts via AI tools",
   "type": "module",

package/skills/social-inbox/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: social-inbox
+description: Read, reply to, moderate, and triage comments on social posts using the PostFast social inbox. Use when the user wants to see new comments, reply to a comment (publicly or with an Instagram private reply), hide or delete a comment, or triage/assign comment conversations on TikTok, Instagram, Facebook, or Threads.
+---
+
+# Social Inbox (comments) via PostFast
+
+You have access to PostFast MCP inbox tools — a **comments** inbox for the workspace's own posts. It is never a DM/messages inbox. Covered platforms: TikTok (Business connections), Instagram, Facebook Pages, Threads. Not covered: X, YouTube, Pinterest, Bluesky, Telegram, Google Business Profile, LinkedIn (yet). Comments appear from connect/launch onward — there is no history backfill.
+
+## The one rule that overrides everything
+
+Reply capability is **server-computed per conversation**: `canReply`, `maxReplyLength`, `windowState`, `disabledReason`. Always read and obey these fields — never assume a platform allows replying or guess a length limit. If `canReply` is false, tell the user why via `disabledReason` instead of attempting the call.
+
+## Reading workflow
+
+1. **Unread check** — `get_inbox_unread_count` for the workspace total.
+2. **List conversations** — `list_inbox_conversations` (newest activity first). Filter by `platforms`, `socialMediaIds`, `statuses` (OPEN/SNOOZED/CLOSED), `unreadOnly`, or `assignedToUserId`. Each row carries the capability fields plus `unreadCount` and `status`.
+3. **Open a thread** — `list_inbox_items` with the `conversationId` (oldest first; `order: "DESC"` for newest first). Items have `direction` (INBOUND/OUTBOUND), `state` (VISIBLE/HIDDEN/DELETED), author info, and on Instagram comments `canPrivateReply`.
+4. **Mark it read** — call `mark_inbox_conversation_read` after presenting a thread to the user.
+
+## Replying
+
+- **Public reply** — `reply_to_inbox_item` with the **comment item's id** (not the conversation id). Respect `maxReplyLength` (platform caps as context: TikTok 150, Instagram 2,200, Facebook 8,000, Threads 500 — the fields are authoritative). Confirm the reply text with the user before sending; it posts publicly.
+- **Instagram private reply** — `send_inbox_private_reply`, only where the item's `canPrivateReply` is true: exactly one per comment, within 7 days of the comment, up to 1,000 bytes (emoji count multi-byte), and it may land in the recipient's Message Requests. A second attempt fails with `inbox.privateReplyAlreadySent`.
+- Replies sent through PostFast appear once in the thread — no duplicates when the platform confirms them.
+
+## Moderating & triage
+
+- `set_inbox_item_state` — `HIDE` / `UNHIDE` a comment on the platform; `DELETE` **removes the comment on the platform and cannot be undone** — always confirm with the user first. DELETE is not available on Threads.
+- `set_inbox_conversation_status` — OPEN / SNOOZED / CLOSED (internal triage; nothing changes on the platform).
+- `assign_inbox_conversation` — hand a conversation to a workspace member (omit `assigneeUserId` to unassign).
+
+## Tips
+
+- Failures come back as `inbox.*` codes (e.g. `replyTooLong`, `replyNotSupported`, `privateReplyWindowExpired`, `rateLimited`) — surface them plainly to the user.
+- Two-way sync: hiding/deleting a comment on the platform itself updates the inbox automatically.
+- TikTok quirks: Business connections only; commenter names can take about a minute to appear.
+- Threads quirks: usernames only (no commenter avatars); replies up to 500 characters; no delete.
+- For drafting many replies, read the whole thread first (`list_inbox_items`) so replies land under the right comment items.