postproxy-mcp 1.0.0 → 1.0.2

package/README.md

@@ -94,6 +94,35 @@ List all available social media profiles for posting.
 }
 ```
 
+#### `profiles.placements`
+
+List available placements for a profile. For Facebook profiles, placements are business pages. For LinkedIn profiles, placements include the personal profile and organizations. For Pinterest profiles, placements are boards. Available for `facebook`, `linkedin`, and `pinterest` profiles.
+
+**Parameters**:
+- `profile_id` (string, required): Profile hashid
+
+**Returns** (LinkedIn example):
+```json
+{
+  "placements": [
+    {
+      "id": null,
+      "name": "Personal Profile"
+    },
+    {
+      "id": "108520199",
+      "name": "Acme Marketing"
+    }
+  ]
+}
+```
+
+**Notes**:
+- If no placement is specified when creating a post:
+  - **LinkedIn**: defaults to the personal profile
+  - **Facebook**: defaults to a random connected page (if only one page is connected, no need to set a placement ID)
+  - **Pinterest**: it fails
+
 ### Post Management
 
 #### `post.publish`
@@ -207,6 +236,57 @@ Delete a post by job ID.
 }
 ```
 
+#### `post.stats`
+
+Get stats snapshots for one or more posts. Returns all matching snapshots so you can see trends over time. Supports filtering by profiles/networks and timespan.
+
+**Parameters**:
+- `post_ids` (string[], required): Array of post hashids (max 50)
+- `profiles` (string, optional): Comma-separated list of profile hashids or network names (e.g. `instagram,twitter` or `abc123,def456` or mixed)
+- `from` (string, optional): ISO 8601 timestamp — only include snapshots recorded at or after this time
+- `to` (string, optional): ISO 8601 timestamp — only include snapshots recorded at or before this time
+
+**Returns**:
+```json
+{
+  "data": {
+    "abc123": {
+      "platforms": [
+        {
+          "profile_id": "prof_abc",
+          "platform": "instagram",
+          "records": [
+            {
+              "stats": {
+                "impressions": 1200,
+                "likes": 85,
+                "comments": 12,
+                "saved": 8
+              },
+              "recorded_at": "2026-02-20T12:00:00Z"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+**Stats fields by platform**:
+| Platform | Fields |
+|----------|--------|
+| Instagram | `impressions`, `likes`, `comments`, `saved`, `profile_visits`, `follows` |
+| Facebook | `impressions`, `clicks`, `likes` |
+| Threads | `impressions`, `likes`, `replies`, `reposts`, `quotes`, `shares` |
+| Twitter | `impressions`, `likes`, `retweets`, `comments`, `quotes`, `saved` |
+| YouTube | `impressions`, `likes`, `comments`, `saved` |
+| LinkedIn | `impressions` |
+| TikTok | `impressions`, `likes`, `comments`, `shares` |
+| Pinterest | `impressions`, `likes`, `comments`, `saved`, `outbound_clicks` |
+
+**Notes**: Instagram stories do not return stats. TikTok stats require the post to have a public ID.
+
 ### History
 
 #### `history.list`
@@ -561,6 +641,22 @@ This will show detailed status including draft status, platform-specific errors,
 Delete post job-123
 ```
 
+### Get Post Stats
+
+```
+Show me the stats for post abc123
+```
+
+```
+Get stats for posts abc123 and def456 filtered to Instagram only, from February 1st to today
+```
+
+### List Placements
+
+```
+Show me the placements for my LinkedIn profile prof123
+```
+
 ### View History
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postproxy-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server for Postproxy API integration with Claude Code",
   "type": "module",
   "main": "./dist/index.js",

package/worker/index.ts

@@ -676,6 +676,61 @@ export default class PostProxyMCP extends WorkerEntrypoint<Env> {
     return JSON.stringify({ jobs }, null, 2);
   }
 
+  /**
+   * Get stats snapshots for one or more posts
+   * @param post_ids {string} Comma-separated list of post hashids (max 50)
+   * @param profiles {string} Optional comma-separated list of profile hashids or network names
+   * @param from {string} Optional ISO 8601 timestamp — only include snapshots at or after this time
+   * @param to {string} Optional ISO 8601 timestamp — only include snapshots at or before this time
+   * @return {Promise<string>} Post stats as JSON
+   */
+  async postStats(
+    post_ids: string,
+    profiles?: string,
+    from?: string,
+    to?: string
+  ): Promise<string> {
+    if (!post_ids || post_ids.trim() === "") {
+      throw new Error("post_ids is required");
+    }
+
+    const ids = post_ids.split(",").map((id) => id.trim()).filter(Boolean);
+    if (ids.length > 50) {
+      throw new Error("Maximum 50 post IDs allowed");
+    }
+
+    const queryParams = new URLSearchParams();
+    queryParams.append("post_ids", ids.join(","));
+    if (profiles) {
+      queryParams.append("profiles", profiles);
+    }
+    if (from) {
+      queryParams.append("from", from);
+    }
+    if (to) {
+      queryParams.append("to", to);
+    }
+
+    const response = await this.apiRequest<any>("GET", `/posts/stats?${queryParams.toString()}`);
+    return JSON.stringify(response, null, 2);
+  }
+
+  /**
+   * List available placements for a profile (Facebook pages, LinkedIn orgs, Pinterest boards)
+   * @param profile_id {string} Profile hashid
+   * @return {Promise<string>} List of placements as JSON
+   */
+  async profilesPlacements(profile_id: string): Promise<string> {
+    if (!profile_id) {
+      throw new Error("profile_id is required");
+    }
+
+    const response = await this.apiRequest<any>("GET", `/profiles/${profile_id}/placements`);
+    const placements = this.extractArray<{ id: string | null; name: string }>(response);
+
+    return JSON.stringify({ placements }, null, 2);
+  }
+
   /**
    * MCP tool definitions
    */
@@ -754,6 +809,31 @@ export default class PostProxyMCP extends WorkerEntrypoint<Env> {
           required: [],
         },
       },
+      {
+        name: "postStats",
+        description: "Get stats snapshots for one or more posts. Returns all matching snapshots so you can see trends over time. Supports filtering by profiles/networks and timespan.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            post_ids: { type: "string", description: "Comma-separated list of post hashids (max 50)" },
+            profiles: { type: "string", description: "Optional comma-separated list of profile hashids or network names (e.g. 'instagram,twitter')" },
+            from: { type: "string", description: "Optional ISO 8601 timestamp — only include snapshots at or after this time" },
+            to: { type: "string", description: "Optional ISO 8601 timestamp — only include snapshots at or before this time" },
+          },
+          required: ["post_ids"],
+        },
+      },
+      {
+        name: "profilesPlacements",
+        description: "List available placements for a profile. For Facebook: business pages. For LinkedIn: personal profile and organizations. For Pinterest: boards. Available for facebook, linkedin, and pinterest profiles.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            profile_id: { type: "string", description: "Profile hashid" },
+          },
+          required: ["profile_id"],
+        },
+      },
     ];
   }
 
@@ -825,6 +905,12 @@ export default class PostProxyMCP extends WorkerEntrypoint<Env> {
             case "historyList":
               result = await this.historyList(args?.limit);
               break;
+            case "postStats":
+              result = await this.postStats(args.post_ids, args.profiles, args.from, args.to);
+              break;
+            case "profilesPlacements":
+              result = await this.profilesPlacements(args.profile_id);
+              break;
             default:
               return {
                 jsonrpc: "2.0",