posterly-mcp-server 0.33.2 → 0.33.3

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.33.2` exposes 77 tools.
+`posterly-mcp-server@0.33.3` exposes 77 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 

package/dist/lib/api-client.d.ts

@@ -568,10 +568,32 @@ export interface GoogleBusinessReview {
     socialAccountId?: number;
     account_id?: number;
 }
+export interface GoogleBusinessLocationReviewSummary {
+    id: number;
+    location_id: string | null;
+    name: string | null;
+    business_name: string | null;
+    workspace_id: string | null;
+    /** Google's own review count for this location, or null when Google didn't report one. */
+    total_review_count: number | null;
+    average_rating: number | null;
+    fetched_review_count: number;
+    /** Why this location's reviews are missing or incomplete, else null. */
+    error: string | null;
+}
 export interface GoogleBusinessReviewsResponse {
     reviews: GoogleBusinessReview[];
+    /** Reviews matching the filters across every page, not just the ones returned. */
     total: number;
-    locations: Array<Record<string, unknown>>;
+    returned?: number;
+    limit?: number;
+    offset?: number;
+    has_more?: boolean;
+    /** Reviews fetched from Google before rating/unanswered filters. */
+    fetched?: number;
+    /** Google's reported review count summed across the selected locations. */
+    total_review_count?: number | null;
+    locations: Array<GoogleBusinessLocationReviewSummary | Record<string, unknown>>;
 }
 export interface GoogleBusinessMediaItem {
     name: string;
@@ -1051,6 +1073,8 @@ export declare class PosterlyClient {
         location_id?: string;
         rating?: number;
         unanswered?: boolean;
+        limit?: number;
+        offset?: number;
     }): Promise<GoogleBusinessReviewsResponse>;
     getGoogleBusinessReviewLink(params: {
         workspace_id?: string;

package/dist/lib/api-client.js

@@ -364,6 +364,10 @@ export class PosterlyClient {
             searchParams.set('rating', String(params.rating));
         if (params?.unanswered)
             searchParams.set('unanswered', 'true');
+        if (params?.limit)
+            searchParams.set('limit', String(params.limit));
+        if (params?.offset)
+            searchParams.set('offset', String(params.offset));
         const qs = searchParams.toString();
         return this.request('GET', `/google-business/reviews${qs ? `?${qs}` : ''}`);
     }

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.33.2";
+export declare const POSTERLY_MCP_VERSION = "0.33.3";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.33.2';
+export const POSTERLY_MCP_VERSION = '0.33.3';

package/dist/tools/list-google-business-reviews.d.ts

@@ -9,15 +9,21 @@ export declare const listGoogleBusinessReviewsTool: {
         location_id: z.ZodOptional<z.ZodString>;
         rating: z.ZodOptional<z.ZodNumber>;
         unanswered: z.ZodOptional<z.ZodBoolean>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         workspace_id?: string | undefined;
         account_id?: number | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
         location_id?: string | undefined;
         rating?: number | undefined;
         unanswered?: boolean | undefined;
     }, {
         workspace_id?: string | undefined;
         account_id?: number | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
         location_id?: string | undefined;
         rating?: number | undefined;
         unanswered?: boolean | undefined;
@@ -28,5 +34,7 @@ export declare const listGoogleBusinessReviewsTool: {
         location_id?: string;
         rating?: number;
         unanswered?: boolean;
+        limit?: number;
+        offset?: number;
     }): Promise<string>;
 };

package/dist/tools/list-google-business-reviews.js

@@ -1,28 +1,108 @@
 import { z } from 'zod';
+import { formatDate } from '../lib/format.js';
+/** Matches GOOGLE_BUSINESS_REVIEWS_MAX_LIMIT in lib/api-v1-google-business.ts. */
+const MAX_LIMIT = 1000;
 export const listGoogleBusinessReviewsTool = {
     name: 'list_google_business_reviews',
-    description: 'List Google Business Profile reviews for one location/account or every accessible GBP location. Supports rating and unanswered-only filters.',
+    description: 'List Google Business Profile reviews for one location/account or every accessible GBP location. Pages through all reviews Google has (not just the first 50), returns the full untruncated review text with its date, and reports each location\'s total review count. Supports rating and unanswered-only filters plus limit/offset paging.',
     inputSchema: z.object({
         workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
         account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
         location_id: z.string().optional().describe('Google Business numeric location id (the location_id/platform_user_id from list_accounts, e.g. "197940849675145390"). NOT the ChIJ... Place ID returned by get_google_business_review_link. Prefer account_id.'),
         rating: z.number().int().min(1).max(5).optional().describe('Filter to a 1-5 star rating.'),
         unanswered: z.boolean().optional().describe('Only return reviews without owner replies.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_LIMIT)
+            .optional()
+            .describe(`Maximum reviews to return in this call (default 200, max ${MAX_LIMIT}). Every returned review is listed in full.`),
+        offset: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .describe('Skip this many reviews before returning results. Use with limit to page through a location with more reviews than one call returns.'),
     }),
     async execute(client, input) {
         const result = await client.listGoogleBusinessReviews(input);
+        const locations = (result.locations || []);
+        const offset = result.offset ?? 0;
         if (result.reviews.length === 0) {
-            return 'No Google Business reviews found matching your filters.';
+            // Distinguish "no reviews exist" from "we couldn't read them" — a silent
+            // zero used to be indistinguishable from a broken connection.
+            const lines = ['No Google Business reviews found matching your filters.'];
+            const locationLines = locations.map((location) => formatLocationLine(location));
+            if (locationLines.length > 0) {
+                lines.push('', 'Locations checked:', ...locationLines);
+            }
+            return lines.join('\n');
         }
-        const lines = [`Google Business reviews (${result.reviews.length} of ${result.total}):`];
-        for (const review of result.reviews.slice(0, 25)) {
+        const header = [`Google Business reviews (showing ${result.reviews.length} of ${result.total} matching`];
+        if (offset > 0)
+            header.push(`, from offset ${offset}`);
+        if (typeof result.total_review_count === 'number') {
+            header.push(`; ${result.total_review_count} total on Google`);
+        }
+        header.push('):');
+        const lines = [header.join('')];
+        for (const location of locations) {
+            if (location.error) {
+                lines.push(`! ${location.business_name || location.name || location.location_id || 'location'}: ${location.error}`);
+            }
+        }
+        lines.push('');
+        for (const review of result.reviews) {
             const name = review.reviewer?.displayName || 'Anonymous';
             const rating = review.starRating ? `${review.starRating} stars` : 'unrated';
             const location = review.businessName || review.locationName || review.locationId || 'location';
-            const text = review.comment ? ` - ${review.comment.replace(/\s+/g, ' ').slice(0, 180)}` : '';
-            const replied = review.reviewReply ? ' replied' : ' unanswered';
-            lines.push(`- ${name} (${rating}, ${location},${replied})${text}`);
+            const date = formatReviewDate(review);
+            const replied = review.reviewReply ? 'replied' : 'unanswered';
+            lines.push(`- ${name} (${rating}, ${date}, ${location}, ${replied})`);
+            // Full review text, no truncation — collapse whitespace only so the
+            // bullet list stays readable for multi-paragraph reviews.
+            if (review.comment) {
+                lines.push(`  ${review.comment.replace(/\s+/g, ' ').trim()}`);
+            }
+        }
+        if (result.has_more) {
+            const nextOffset = offset + result.reviews.length;
+            lines.push('', `More reviews available — call again with offset: ${nextOffset} to continue.`);
         }
+        lines.push('', 'Locations:', ...locations.map((location) => formatLocationLine(location)));
         return lines.join('\n');
     },
 };
+/**
+ * When a review was written, plus when it was last edited if that differs.
+ * The list is ordered by last activity (updateTime), so showing only the
+ * original date would make an edited review look out of order.
+ */
+function formatReviewDate(review) {
+    const created = review.createTime || review.updateTime;
+    const createdLabel = formatDate(created);
+    if (!review.updateTime || !review.createTime)
+        return createdLabel;
+    const updatedLabel = formatDate(review.updateTime);
+    if (updatedLabel === createdLabel)
+        return createdLabel;
+    return `${createdLabel}, edited ${updatedLabel}`;
+}
+function formatLocationLine(location) {
+    const label = location.business_name || location.name || location.location_id || `account ${location.id}`;
+    const parts = [];
+    if (typeof location.total_review_count === 'number') {
+        parts.push(`${location.total_review_count} reviews on Google`);
+    }
+    else if (!location.error) {
+        parts.push('review count not reported by Google');
+    }
+    if (typeof location.average_rating === 'number') {
+        parts.push(`${location.average_rating.toFixed(1)} avg`);
+    }
+    parts.push(`${location.fetched_review_count} fetched`);
+    if (location.error)
+        parts.push(`ERROR: ${location.error}`);
+    return `- ${label} (account_id ${location.id}): ${parts.join(', ')}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.33.2",
+  "version": "0.33.3",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.33.2",
+  "version": "0.33.3",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.33.2",
+      "version": "0.33.3",
       "transport": {
         "type": "stdio"
       },

package/src/lib/api-client.ts

@@ -572,10 +572,33 @@ export interface GoogleBusinessReview {
   account_id?: number;
 }
 
+export interface GoogleBusinessLocationReviewSummary {
+  id: number;
+  location_id: string | null;
+  name: string | null;
+  business_name: string | null;
+  workspace_id: string | null;
+  /** Google's own review count for this location, or null when Google didn't report one. */
+  total_review_count: number | null;
+  average_rating: number | null;
+  fetched_review_count: number;
+  /** Why this location's reviews are missing or incomplete, else null. */
+  error: string | null;
+}
+
 export interface GoogleBusinessReviewsResponse {
   reviews: GoogleBusinessReview[];
+  /** Reviews matching the filters across every page, not just the ones returned. */
   total: number;
-  locations: Array<Record<string, unknown>>;
+  returned?: number;
+  limit?: number;
+  offset?: number;
+  has_more?: boolean;
+  /** Reviews fetched from Google before rating/unanswered filters. */
+  fetched?: number;
+  /** Google's reported review count summed across the selected locations. */
+  total_review_count?: number | null;
+  locations: Array<GoogleBusinessLocationReviewSummary | Record<string, unknown>>;
 }
 
 export interface GoogleBusinessMediaItem {
@@ -1375,6 +1398,8 @@ export class PosterlyClient {
     location_id?: string;
     rating?: number;
     unanswered?: boolean;
+    limit?: number;
+    offset?: number;
   }): Promise<GoogleBusinessReviewsResponse> {
     const searchParams = new URLSearchParams();
     if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
@@ -1382,6 +1407,8 @@ export class PosterlyClient {
     if (params?.location_id) searchParams.set('location_id', params.location_id);
     if (params?.rating) searchParams.set('rating', String(params.rating));
     if (params?.unanswered) searchParams.set('unanswered', 'true');
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset) searchParams.set('offset', String(params.offset));
     const qs = searchParams.toString();
     return this.request('GET', `/google-business/reviews${qs ? `?${qs}` : ''}`);
   }

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.33.2';
+export const POSTERLY_MCP_VERSION = '0.33.3';

package/src/tools/list-google-business-reviews.ts

@@ -1,16 +1,33 @@
 import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
+import type { PosterlyClient, GoogleBusinessLocationReviewSummary } from '../lib/api-client.js';
+import { formatDate } from '../lib/format.js';
+
+/** Matches GOOGLE_BUSINESS_REVIEWS_MAX_LIMIT in lib/api-v1-google-business.ts. */
+const MAX_LIMIT = 1000;
 
 export const listGoogleBusinessReviewsTool = {
   name: 'list_google_business_reviews',
   description:
-    'List Google Business Profile reviews for one location/account or every accessible GBP location. Supports rating and unanswered-only filters.',
+    'List Google Business Profile reviews for one location/account or every accessible GBP location. Pages through all reviews Google has (not just the first 50), returns the full untruncated review text with its date, and reports each location\'s total review count. Supports rating and unanswered-only filters plus limit/offset paging.',
   inputSchema: z.object({
     workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
     account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
     location_id: z.string().optional().describe('Google Business numeric location id (the location_id/platform_user_id from list_accounts, e.g. "197940849675145390"). NOT the ChIJ... Place ID returned by get_google_business_review_link. Prefer account_id.'),
     rating: z.number().int().min(1).max(5).optional().describe('Filter to a 1-5 star rating.'),
     unanswered: z.boolean().optional().describe('Only return reviews without owner replies.'),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_LIMIT)
+      .optional()
+      .describe(`Maximum reviews to return in this call (default 200, max ${MAX_LIMIT}). Every returned review is listed in full.`),
+    offset: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe('Skip this many reviews before returning results. Use with limit to page through a location with more reviews than one call returns.'),
   }),
 
   async execute(
@@ -21,23 +38,99 @@ export const listGoogleBusinessReviewsTool = {
       location_id?: string;
       rating?: number;
       unanswered?: boolean;
+      limit?: number;
+      offset?: number;
     },
   ) {
     const result = await client.listGoogleBusinessReviews(input);
+    const locations = (result.locations || []) as GoogleBusinessLocationReviewSummary[];
+    const offset = result.offset ?? 0;
+
     if (result.reviews.length === 0) {
-      return 'No Google Business reviews found matching your filters.';
+      // Distinguish "no reviews exist" from "we couldn't read them" — a silent
+      // zero used to be indistinguishable from a broken connection.
+      const lines = ['No Google Business reviews found matching your filters.'];
+      const locationLines = locations.map((location) => formatLocationLine(location));
+      if (locationLines.length > 0) {
+        lines.push('', 'Locations checked:', ...locationLines);
+      }
+      return lines.join('\n');
+    }
+
+    const header = [`Google Business reviews (showing ${result.reviews.length} of ${result.total} matching`];
+    if (offset > 0) header.push(`, from offset ${offset}`);
+    if (typeof result.total_review_count === 'number') {
+      header.push(`; ${result.total_review_count} total on Google`);
+    }
+    header.push('):');
+
+    const lines = [header.join('')];
+
+    for (const location of locations) {
+      if (location.error) {
+        lines.push(`! ${location.business_name || location.name || location.location_id || 'location'}: ${location.error}`);
+      }
     }
 
-    const lines = [`Google Business reviews (${result.reviews.length} of ${result.total}):`];
-    for (const review of result.reviews.slice(0, 25)) {
+    lines.push('');
+
+    for (const review of result.reviews) {
       const name = review.reviewer?.displayName || 'Anonymous';
       const rating = review.starRating ? `${review.starRating} stars` : 'unrated';
       const location = review.businessName || review.locationName || review.locationId || 'location';
-      const text = review.comment ? ` - ${review.comment.replace(/\s+/g, ' ').slice(0, 180)}` : '';
-      const replied = review.reviewReply ? ' replied' : ' unanswered';
-      lines.push(`- ${name} (${rating}, ${location},${replied})${text}`);
+      const date = formatReviewDate(review);
+      const replied = review.reviewReply ? 'replied' : 'unanswered';
+      lines.push(`- ${name} (${rating}, ${date}, ${location}, ${replied})`);
+      // Full review text, no truncation — collapse whitespace only so the
+      // bullet list stays readable for multi-paragraph reviews.
+      if (review.comment) {
+        lines.push(`  ${review.comment.replace(/\s+/g, ' ').trim()}`);
+      }
+    }
+
+    if (result.has_more) {
+      const nextOffset = offset + result.reviews.length;
+      lines.push('', `More reviews available — call again with offset: ${nextOffset} to continue.`);
     }
 
+    lines.push('', 'Locations:', ...locations.map((location) => formatLocationLine(location)));
+
     return lines.join('\n');
   },
 };
+
+/**
+ * When a review was written, plus when it was last edited if that differs.
+ * The list is ordered by last activity (updateTime), so showing only the
+ * original date would make an edited review look out of order.
+ */
+function formatReviewDate(review: { createTime?: string; updateTime?: string }): string {
+  const created = review.createTime || review.updateTime;
+  const createdLabel = formatDate(created);
+  if (!review.updateTime || !review.createTime) return createdLabel;
+
+  const updatedLabel = formatDate(review.updateTime);
+  if (updatedLabel === createdLabel) return createdLabel;
+  return `${createdLabel}, edited ${updatedLabel}`;
+}
+
+function formatLocationLine(location: GoogleBusinessLocationReviewSummary): string {
+  const label = location.business_name || location.name || location.location_id || `account ${location.id}`;
+  const parts: string[] = [];
+
+  if (typeof location.total_review_count === 'number') {
+    parts.push(`${location.total_review_count} reviews on Google`);
+  } else if (!location.error) {
+    parts.push('review count not reported by Google');
+  }
+
+  if (typeof location.average_rating === 'number') {
+    parts.push(`${location.average_rating.toFixed(1)} avg`);
+  }
+
+  parts.push(`${location.fetched_review_count} fetched`);
+
+  if (location.error) parts.push(`ERROR: ${location.error}`);
+
+  return `- ${label} (account_id ${location.id}): ${parts.join(', ')}`;
+}