posterly-mcp-server 0.33.2 → 0.34.0

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 {
@@ -737,6 +760,17 @@ export interface ConnectSession {
   expires_at: string;
 }
 
+export interface ConnectAccountCredentialsResponse {
+  connected: boolean;
+  account: {
+    id: number;
+    platform: string;
+    username: string;
+    [extra: string]: unknown;
+  };
+  workspace_id: string;
+}
+
 export interface OAuthDeveloperClient {
   id: string;
   client_id: string;
@@ -1067,6 +1101,19 @@ export class PosterlyClient {
     return this.request('GET', `/connect/sessions/${encodeURIComponent(sessionId)}`);
   }
 
+  async connectAccountCredentials(data: {
+    platform: string;
+    credentials: Record<string, string>;
+    workspace_id?: string;
+    connect_session_id?: string;
+  }): Promise<ConnectAccountCredentialsResponse> {
+    const { platform, credentials, workspace_id, connect_session_id } = data;
+    const body: Record<string, unknown> = { credentials };
+    if (workspace_id) body.workspace_id = workspace_id;
+    if (connect_session_id) body.connect_session_id = connect_session_id;
+    return this.request('POST', `/connect/${encodeURIComponent(platform)}/credentials`, body);
+  }
+
   async listOAuthClients(): Promise<{ clients: OAuthDeveloperClient[] }> {
     return this.request('GET', '/oauth/clients');
   }
@@ -1375,6 +1422,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 +1431,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.34.0';

package/src/tools/connect-account.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+const CREDENTIAL_PLATFORMS = [
+  'telegram',
+  'bluesky',
+  'discord',
+  'wordpress',
+  'devto',
+  'hashnode',
+  'lemmy',
+] as const;
+
+/**
+ * Per-platform credential field whitelist. Duplicated in the hosted tool
+ * (lib/mcp/http-tools.ts) on purpose: the platform manifest does not carry
+ * credential fields, and the v1 endpoint rejects unknown keys, so each tool
+ * must whitelist before building the credentials object. The MCP parity and
+ * payload checks guard the duplication.
+ */
+const PLATFORM_CREDENTIAL_FIELDS: Record<string, string[]> = {
+  telegram: ['bot_token', 'chat_id'],
+  bluesky: ['handle', 'app_password'],
+  discord: ['webhook_url'],
+  wordpress: ['site_url', 'username', 'app_password'],
+  devto: ['api_key'],
+  hashnode: ['pat'],
+  lemmy: ['instance', 'username', 'password'],
+};
+
+export const connectAccountTool = {
+  name: 'connect_account',
+  description:
+    'Connect a credential-based social account (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) directly, without a browser session. Call get_connect_link first to discover the exact credential fields the platform needs. Prefer scoped secrets: app passwords (Bluesky, WordPress), bot tokens (Telegram), webhook URLs (Discord), and API tokens (Dev.to, Hashnode) over primary passwords. Warn the user that any credential they share passes through this conversation. For OAuth platforms (Instagram, X, LinkedIn, ...) use create_connect_session instead.',
+  inputSchema: z.object({
+    platform: z
+      .enum(CREDENTIAL_PLATFORMS)
+      .describe('Credential-based connection target: telegram, bluesky, discord, wordpress, devto, hashnode, or lemmy.'),
+    bot_token: z.string().optional().describe('Telegram: bot token from BotFather.'),
+    chat_id: z.string().optional().describe('Telegram: target channel or group chat ID.'),
+    handle: z.string().optional().describe('Bluesky: handle, for example posterly.bsky.social.'),
+    app_password: z.string().optional().describe('Bluesky: app password from account settings. WordPress: application password from wp-admin Users, Profile, Application Passwords.'),
+    webhook_url: z.string().optional().describe('Discord: channel webhook URL from channel settings, Integrations, Webhooks.'),
+    site_url: z.string().optional().describe('WordPress: site URL, e.g. https://blog.example.com.'),
+    username: z.string().optional().describe('WordPress: username the application password belongs to. Lemmy: username or email.'),
+    password: z.string().optional().describe('Lemmy: account password (TOTP-enabled accounts are not supported).'),
+    api_key: z.string().optional().describe('Dev.to: API key from Settings, Extensions, DEV Community API Keys.'),
+    pat: z.string().optional().describe('Hashnode: personal access token from Account Settings, Developer.'),
+    instance: z.string().optional().describe('Lemmy: instance domain, for example lemmy.world.'),
+    workspace_id: z.string().optional().describe('Workspace to connect the account into. Workspace-scoped API keys ignore this.'),
+    connect_session_id: z.string().optional().describe('Optional connect session ID to mark connected or failed based on the outcome.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      platform: (typeof CREDENTIAL_PLATFORMS)[number];
+      workspace_id?: string;
+      connect_session_id?: string;
+    } & Record<string, string | undefined>,
+  ) {
+    const allowedFields = PLATFORM_CREDENTIAL_FIELDS[input.platform] || [];
+    const credentials: Record<string, string> = {};
+    for (const field of allowedFields) {
+      const value = input[field];
+      if (typeof value === 'string' && value.trim()) {
+        credentials[field] = value;
+      }
+    }
+
+    const missing = allowedFields.filter((field) => !(field in credentials));
+    if (missing.length > 0) {
+      return `Missing credential field(s) for ${input.platform}: ${missing.join(', ')}. Call get_connect_link with platform=${input.platform} to see field descriptions.`;
+    }
+
+    const result = await client.connectAccountCredentials({
+      platform: input.platform,
+      credentials,
+      workspace_id: input.workspace_id,
+      connect_session_id: input.connect_session_id,
+    });
+
+    const account = result.account || {};
+    const lines = [
+      `Connected ${input.platform} account: ${account.username || 'unknown'} (id ${account.id})`,
+      `Workspace: ${result.workspace_id}`,
+      'Reconnecting the same account updates it in place.',
+    ];
+    return lines.join('\n');
+  },
+};

package/src/tools/get-connect-link.ts

@@ -5,7 +5,7 @@ import { CONNECT_INPUTS, PLANNED_PLATFORM_IDS } from '../generated/platform-mani
 export const getConnectLinkTool = {
   name: 'get_connect_link',
   description:
-    'List dashboard handoff links/readiness for connecting social accounts, or get one platform connection URL. Use connection_url in a logged-in browser. Direct OAuth URLs are intentionally not exposed because provider callbacks rely on browser state.',
+    'List dashboard handoff links/readiness for connecting social accounts, or get one platform connection URL. Use connection_url in a logged-in browser. Direct OAuth URLs are intentionally not exposed because provider callbacks rely on browser state. Credential-based platforms (telegram, bluesky, discord, wordpress, devto, hashnode, lemmy) can instead be connected headlessly with connect_account; this tool shows their credential_fields.',
   inputSchema: z.object({
     platform: z
       .enum(CONNECT_INPUTS)

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(', ')}`;
+}

package/tool-annotations.json

@@ -8,6 +8,7 @@
     "list_accounts",
     "disconnect_account",
     "get_connect_link",
+    "connect_account",
     "create_connect_session",
     "get_connect_session",
     "create_api_key",
@@ -138,6 +139,7 @@
     "delete_webhook"
   ],
   "idempotentMutationTools": [
+    "connect_account",
     "disconnect_account",
     "delete_api_key",
     "cancel_subscription",
@@ -163,6 +165,7 @@
     "get_signup_session",
     "get_mcp_status",
     "disconnect_account",
+    "connect_account",
     "create_connect_session",
     "get_connect_session",
     "get_credits",