posterly-mcp-server 0.23.0 → 0.23.2

package/README.md

@@ -108,7 +108,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.23.0` exposes 62 tools.
+`posterly-mcp-server@0.23.0` exposes 63 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -138,6 +138,7 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `get_brand`
 - `list_brand_accounts`
 - `get_brand_profile`
+- `get_learned_voice` (read the voice learned from one account's real published captions)
 - `list_posts`
 - `get_post`
 - `get_post_missing`
@@ -170,6 +171,9 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `list_google_business_media` (list the photos/videos on a GBP profile gallery)
 - `add_google_business_media` (add a photo/video to a GBP profile gallery from a public URL, after explicit confirmation)
 - `delete_google_business_media` (remove a photo/video from a GBP profile gallery after explicit confirmation)
+
+> Google Business tip: pass `account_id` (the integer `id` from `list_accounts`) to every GBP tool. If you use `location_id` instead, it is the numeric `location_id` from `list_accounts` (the GBP location id), not the `ChIJ...` Place ID that `get_google_business_review_link` returns. Passing the Place ID resolves to no account and returns "Google Business Profile account not found".
+
 - `list_activity`
 - `list_webhooks`
 - `create_webhook` (create a webhook after explicit confirmation)
@@ -178,7 +182,13 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `test_webhook` (send a signed test delivery after explicit confirmation)
 - `get_x_posting_quota`
 
-Analytics tools currently support Instagram, LinkedIn, Google Business Profile, Pinterest, and YouTube.
+Analytics tools currently support Instagram, Facebook Pages, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads.
+
+## Media uploads
+
+This npm/stdio server can read local file paths. When `upload_media` receives a larger local file, it automatically requests a signed upload URL and uploads the raw bytes before returning the public media URL.
+
+The hosted HTTP MCP endpoint cannot do that for local files by itself because MCP tool calls are JSON-only. On hosted HTTP MCP, `upload_media` is for small base64 uploads up to 5MB decoded. For larger media there, use `upload_media_from_url` for public direct media URLs, or call `create_signed_upload` only from clients that can also `PUT` the raw file bytes to the returned `upload_url`.
 
 ## What the brand tools are for
 

package/dist/index.js

@@ -13,6 +13,7 @@ import { listBrandsTool } from './tools/list-brands.js';
 import { getBrandTool } from './tools/get-brand.js';
 import { listBrandAccountsTool } from './tools/list-brand-accounts.js';
 import { getBrandProfileTool } from './tools/get-brand-profile.js';
+import { getLearnedVoiceTool } from './tools/get-learned-voice.js';
 import { createPostTool } from './tools/create-post.js';
 import { createPostsBatchTool } from './tools/create-posts-batch.js';
 import { findSlotTool } from './tools/find-slot.js';
@@ -278,6 +279,15 @@ server.tool(getBrandProfileTool.name, getBrandProfileTool.description, getBrandP
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(getLearnedVoiceTool.name, getLearnedVoiceTool.description, getLearnedVoiceTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await getLearnedVoiceTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(createPostTool.name, createPostTool.description, createPostTool.inputSchema.shape, async (input) => {
     try {
         const text = await createPostTool.execute(client, input);

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

@@ -40,6 +40,20 @@ export interface BrandProfile {
     created_at?: string | null;
     updated_at?: string | null;
     source: 'canonical' | 'legacy';
+    learned_voice?: LearnedVoice[];
+}
+export interface LearnedVoice {
+    social_account_id: number;
+    platform: string;
+    username: string | null;
+    narrative_summary: string | null;
+    summary: string | null;
+    traits: string[];
+    style_guidelines: string[];
+    observations: Record<string, unknown>;
+    sample_post_ids: number[];
+    post_count: number;
+    derived_at: string | null;
 }
 export interface Post {
     id: number;
@@ -680,6 +694,9 @@ export declare class PosterlyClient {
     getBrandProfile(id: string): Promise<{
         brand_profile: BrandProfile;
     }>;
+    getAccountLearnedVoice(id: string | number): Promise<{
+        learned_voice: LearnedVoice | null;
+    }>;
     listPosts(params?: {
         status?: string;
         platform?: string;
@@ -950,3 +967,16 @@ export declare class PosterlyClient {
     }>;
 }
 export declare function resolvePosterlyBaseUrl(baseUrl?: string): string;
+type PosterlyBaseUrlInspection = {
+    valid: boolean;
+    secure: boolean;
+    protocol?: string;
+    host?: string;
+    trustedPosterlyHost: boolean;
+    localDevelopmentHost: boolean;
+    warnings: string[];
+    message: string;
+};
+export declare function inspectPosterlyBaseUrl(baseUrl: string): PosterlyBaseUrlInspection;
+export declare function validatePosterlyBaseUrlForKeyUse(baseUrl: string): void;
+export {};

package/dist/lib/api-client.js

@@ -6,6 +6,9 @@ export class PosterlyClient {
     constructor(apiKey, baseUrl) {
         this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
         this.baseUrl = resolvePosterlyBaseUrl(baseUrl);
+        if (this.apiKey) {
+            validatePosterlyBaseUrlForKeyUse(this.baseUrl);
+        }
     }
     hasApiKey() {
         return Boolean(this.apiKey);
@@ -179,6 +182,9 @@ export class PosterlyClient {
     async getBrandProfile(id) {
         return this.request('GET', `/brands/${encodeURIComponent(id)}/profile`);
     }
+    async getAccountLearnedVoice(id) {
+        return this.request('GET', `/accounts/${encodeURIComponent(String(id))}/learned-voice`);
+    }
     async listPosts(params) {
         const searchParams = new URLSearchParams();
         if (params?.status)
@@ -482,6 +488,73 @@ export function resolvePosterlyBaseUrl(baseUrl) {
         return configured.replace(/\/api\/v1\/?$/, '').replace(/\/$/, '');
     }
 }
+const TRUSTED_POSTERLY_HOSTS = new Set(['poster.ly', 'www.poster.ly']);
+function flagEnabled(name) {
+    const value = (process.env[name] || '').trim().toLowerCase();
+    return value === 'true' || value === '1' || value === 'yes';
+}
+function normalizeHostname(hostname) {
+    return hostname.toLowerCase().replace(/^\[|\]$/g, '');
+}
+function isLocalHost(hostname) {
+    const normalized = normalizeHostname(hostname);
+    return (normalized === 'localhost' ||
+        normalized.endsWith('.localhost') ||
+        normalized === '127.0.0.1' ||
+        normalized === '::1');
+}
+export function inspectPosterlyBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        const hostname = normalizeHostname(url.hostname);
+        const local = isLocalHost(hostname);
+        const trustedPosterlyHost = TRUSTED_POSTERLY_HOSTS.has(hostname);
+        const secure = url.protocol === 'https:' || (url.protocol === 'http:' && local);
+        const warnings = [];
+        if (!trustedPosterlyHost) {
+            warnings.push(local ? 'local_development_host' : 'custom_host');
+        }
+        if (!secure) {
+            warnings.push('insecure_non_local_url');
+        }
+        return {
+            valid: true,
+            secure,
+            protocol: url.protocol.replace(/:$/, ''),
+            host: url.host,
+            trustedPosterlyHost,
+            localDevelopmentHost: local,
+            warnings,
+            message: secure
+                ? 'Base URL is secure for API-key requests.'
+                : 'Non-local HTTP URLs are blocked for API-key requests.',
+        };
+    }
+    catch {
+        return {
+            valid: false,
+            secure: false,
+            trustedPosterlyHost: false,
+            localDevelopmentHost: false,
+            warnings: ['invalid_url'],
+            message: 'Base URL must include a scheme and host, for example https://www.poster.ly.',
+        };
+    }
+}
+export function validatePosterlyBaseUrlForKeyUse(baseUrl) {
+    const check = inspectPosterlyBaseUrl(baseUrl);
+    if (!check.valid) {
+        throw new Error(`${check.message} Received: ${baseUrl}`);
+    }
+    if (!check.secure && !flagEnabled('POSTERLY_ALLOW_INSECURE_URL')) {
+        throw new Error(`Refusing to send an API key to ${baseUrl}. Use https, http://localhost for local development, or set POSTERLY_ALLOW_INSECURE_URL=true only for a trusted private development endpoint.`);
+    }
+    if (!check.trustedPosterlyHost &&
+        !check.localDevelopmentHost &&
+        !flagEnabled('POSTERLY_ALLOW_CUSTOM_BASE_URL')) {
+        throw new Error(`Refusing to send an API key to custom host ${baseUrl}. Set POSTERLY_ALLOW_CUSTOM_BASE_URL=true only for a trusted Posterly deployment.`);
+    }
+}
 function parseJson(text) {
     try {
         return text ? JSON.parse(text) : {};

package/dist/lib/format.d.ts

@@ -1,4 +1,4 @@
-import type { Account, Post } from './api-client.js';
+import type { Account, LearnedVoice, Post } from './api-client.js';
 type CellValue = string | number | boolean | null | undefined;
 export declare const DASHBOARD_CALENDAR_URL: string;
 export declare const DASHBOARD_TABLE_URL: string;
@@ -27,6 +27,11 @@ export declare function formatDateTime(value: string | null | undefined): string
 export declare function formatDate(value: string | null | undefined): string;
 export declare function formatBytes(value: number | null | undefined): string;
 export declare function compactText(value: string | null | undefined, maxLength?: number): string;
+/**
+ * Render one account's learned voice (derived from its real published captions)
+ * as a Markdown block. Returns null when there is no learned voice to show.
+ */
+export declare function mdLearnedVoice(learned: LearnedVoice | null | undefined): string | null;
 export declare function statusLabel(status: string | null | undefined): string;
 export declare function code(value: CellValue): string;
 export {};

package/dist/lib/format.js

@@ -136,6 +136,50 @@ export function compactText(value, maxLength = 90) {
         return '';
     return text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 1))}…` : text;
 }
+/**
+ * Render one account's learned voice (derived from its real published captions)
+ * as a Markdown block. Returns null when there is no learned voice to show.
+ */
+export function mdLearnedVoice(learned) {
+    if (!learned)
+        return null;
+    const obs = (learned.observations || {});
+    const num = (key) => {
+        const value = obs[key];
+        return typeof value === 'number' ? value : undefined;
+    };
+    const topEmojis = Array.isArray(obs.top_emojis) ? obs.top_emojis : [];
+    const accountLabel = learned.username
+        ? `@${learned.username}${learned.platform ? ` (${learned.platform})` : ''}`
+        : `account ${learned.social_account_id}`;
+    const habits = [];
+    const avgLen = num('avg_caption_length');
+    if (avgLen != null)
+        habits.push(`~${avgLen} chars/post`);
+    const emojiRate = num('emoji_rate');
+    if (emojiRate != null) {
+        habits.push(emojiRate >= 0.5 ? `~${emojiRate} emoji/post${topEmojis.length ? ` (${topEmojis.slice(0, 3).join(' ')})` : ''}` : 'rarely uses emoji');
+    }
+    const hashtagAvg = num('hashtag_avg');
+    if (hashtagAvg != null && hashtagAvg >= 0.5)
+        habits.push(`~${Math.round(hashtagAvg)} hashtags/post`);
+    const questionRate = num('question_rate');
+    if (questionRate != null && questionRate >= 0.3)
+        habits.push('often opens with a question');
+    const lineBreakRate = num('line_break_rate');
+    if (lineBreakRate != null && lineBreakRate >= 0.5)
+        habits.push('uses line breaks');
+    const body = mdKeyValue([
+        ['Account', accountLabel],
+        ['Summary', compactText(learned.narrative_summary || learned.summary, 240)],
+        ['Traits', learned.traits?.length ? learned.traits.join(', ') : undefined],
+        ['Style guidelines', learned.style_guidelines?.length ? learned.style_guidelines.join(' • ') : undefined],
+        ['Observed habits', habits.length ? habits.join(', ') : undefined],
+        ['Learned from', `${learned.post_count} posts`],
+        ['Last updated', learned.derived_at ? formatDateTime(learned.derived_at) : undefined],
+    ]);
+    return body || null;
+}
 export function statusLabel(status) {
     const value = String(status || 'unknown').toLowerCase();
     if (['created', 'success', 'succeeded', 'completed', 'published', 'active'].includes(value))

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.23.0";
+export declare const POSTERLY_MCP_VERSION = "0.23.1";

package/dist/lib/version.js

@@ -1 +1,8 @@
-export const POSTERLY_MCP_VERSION = '0.23.0';
+// Version of the npm stdio MCP package (posterly-mcp-server).
+//
+// MUST stay in lockstep with the hosted HTTP endpoint version in
+// lib/mcp/version.ts. The two MCP surfaces share one version namespace and
+// 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.23.1';

package/dist/tools/add-google-business-media.js

@@ -20,7 +20,7 @@ export const addGoogleBusinessMediaTool = {
     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 location/platform_user_id. Provide account_id or location_id.'),
+        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.'),
         source_url: z.string().url().describe('Public https URL of the photo or video (from upload_media / upload_media_from_url).'),
         category: z.enum(CATEGORIES).describe('Which gallery category to add the media to.'),
         media_format: z.enum(['PHOTO', 'VIDEO']).optional().describe('Defaults to PHOTO. Use VIDEO for videos (Google caps profile videos at 30s / 75MB).'),

package/dist/tools/audit-google-business-profile.js

@@ -5,7 +5,7 @@ export const auditGoogleBusinessProfileTool = {
     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 location/platform_user_id.'),
+        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.'),
     }),
     async execute(client, input) {
         const result = await client.auditGoogleBusinessProfile(input);

package/dist/tools/delete-google-business-media.js

@@ -5,7 +5,7 @@ export const deleteGoogleBusinessMediaTool = {
     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 location/platform_user_id. Provide account_id or location_id.'),
+        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.'),
         media_name: z.string().min(1).describe('Full media resource name from list_google_business_media (accounts/.../locations/.../media/...).'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
     }),

package/dist/tools/delete-google-business-review-reply.js

@@ -5,7 +5,7 @@ export const deleteGoogleBusinessReviewReplyTool = {
     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 location/platform_user_id.'),
+        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.'),
         review_name: z.string().min(1).describe('Full Google review resource name.'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
     }),

package/dist/tools/get-account-analytics.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
 export const getAccountAnalyticsTool = {
     name: 'get_account_analytics',
-    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
+    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
     inputSchema: z.object({
         account_id: z
             .number()

package/dist/tools/get-brand-profile.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { code, compactText, formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+import { code, compactText, formatDateTime, mdLearnedVoice, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
 export const getBrandProfileTool = {
     name: 'get_brand_profile',
     description: 'Get the extended brand profile for a brand/client. Returns voice/tone guidance, audience, keywords, dos and don’ts, visual notes, and other saved brand context.',
@@ -38,10 +38,16 @@ export const getBrandProfileTool = {
                 ['Voice examples', formatStructuredValue(profile.voice_examples)],
             ])),
         ].filter(Boolean).join('\n\n');
+        const learnedVoices = (Array.isArray(profile.learned_voice) ? profile.learned_voice : []);
+        const learnedBody = learnedVoices.length
+            ? mdSection('Learned voice (from published captions)', learnedVoices.map((voice) => mdLearnedVoice(voice)).filter(Boolean).join('\n\n'))
+            : '';
         return [
             mdTitle(`Brand profile: ${profile.brand_name}`),
             profileBody || 'No extended brand profile fields have been saved yet.',
-        ].join('\n\n');
+            learnedBody ||
+                '_No learned voice yet. posterly learns each account’s voice automatically once it has enough published posts._',
+        ].filter(Boolean).join('\n\n');
     },
 };
 function formatStructuredValue(value) {

package/dist/tools/get-google-business-review-link.js

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 export const getGoogleBusinessReviewLinkTool = {
     name: 'get_google_business_review_link',
-    description: 'Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id.',
+    description: 'Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id. Returns reviewLink plus the Google Place ID (ChIJ...); that Place ID is output only and must NOT be passed back as location_id to other tools.',
     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 location/platform_user_id.'),
+        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 this tool returns. Prefer account_id.'),
     }),
     async execute(client, input) {
         const result = await client.getGoogleBusinessReviewLink(input);

package/dist/tools/get-learned-voice.d.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const getLearnedVoiceTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    }, "strip", z.ZodTypeAny, {
+        account_id: string | number;
+    }, {
+        account_id: string | number;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_id: string | number;
+    }): Promise<string>;
+};

package/dist/tools/get-learned-voice.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { mdLearnedVoice, mdTitle } from '../lib/format.js';
+export const getLearnedVoiceTool = {
+    name: 'get_learned_voice',
+    description: 'Get the voice posterly has learned from a connected account’s real published captions (the "learned captions" shown on the dashboard). Returns a narrative summary, voice traits, style guidelines, and observed posting habits. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has enough published posts to learn from. Read-only; this never overwrites the saved brand profile.',
+    inputSchema: z.object({
+        account_id: z
+            .union([z.string(), z.number()])
+            .describe('The social account ID to inspect (from list_accounts or list_brand_accounts).'),
+    }),
+    async execute(client, input) {
+        const { learned_voice } = await client.getAccountLearnedVoice(input.account_id);
+        const body = mdLearnedVoice(learned_voice);
+        if (!body) {
+            return [
+                mdTitle('No learned voice yet'),
+                'posterly has not learned a voice for this account yet. It learns automatically once the account has enough published posts (the captions are analyzed; the saved brand profile is never overwritten).',
+            ].join('\n\n');
+        }
+        return [mdTitle('Learned voice (from published captions)'), body].join('\n\n');
+    },
+};

package/dist/tools/get-post-analytics.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
 export const getPostAnalyticsTool = {
     name: 'get_post_analytics',
-    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
+    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
     inputSchema: z.object({
         account_id: z
             .number()

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

@@ -5,7 +5,7 @@ export const listGoogleBusinessMediaTool = {
     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 location/platform_user_id.'),
+        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.'),
     }),
     async execute(client, input) {
         const result = await client.listGoogleBusinessMedia(input);

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

@@ -5,7 +5,7 @@ export const listGoogleBusinessReviewsTool = {
     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 location/platform_user_id.'),
+        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.'),
     }),

package/dist/tools/reply-google-business-review.js

@@ -5,7 +5,7 @@ export const replyGoogleBusinessReviewTool = {
     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 location/platform_user_id.'),
+        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.'),
         review_name: z.string().min(1).describe('Full Google review resource name.'),
         comment: z.string().min(1).max(4096).describe('Exact owner reply text to post.'),
         confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),

package/dist/tools/suggest-google-business-review-reply.js

@@ -5,7 +5,7 @@ export const suggestGoogleBusinessReviewReplyTool = {
     inputSchema: z.object({
         workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
         account_id: z.number().int().positive().optional().describe('Optional Google Business account ID for brand voice context.'),
-        location_id: z.string().optional().describe('Google Business location/platform_user_id.'),
+        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.'),
         review_text: z.string().optional().describe('Review text. Leave empty for rating-only reviews.'),
         star_rating: z.number().min(1).max(5).describe('Review rating from 1 to 5.'),
         reviewer_name: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.23.0",
+  "version": "0.23.2",
   "description": "MCP server for posterly: schedule and publish social media posts across 11 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",

package/src/index.ts

@@ -14,6 +14,7 @@ import { listBrandsTool } from './tools/list-brands.js';
 import { getBrandTool } from './tools/get-brand.js';
 import { listBrandAccountsTool } from './tools/list-brand-accounts.js';
 import { getBrandProfileTool } from './tools/get-brand-profile.js';
+import { getLearnedVoiceTool } from './tools/get-learned-voice.js';
 import { createPostTool } from './tools/create-post.js';
 import { createPostsBatchTool } from './tools/create-posts-batch.js';
 import { findSlotTool } from './tools/find-slot.js';
@@ -397,6 +398,20 @@ server.tool(
   }
 );
 
+server.tool(
+  getLearnedVoiceTool.name,
+  getLearnedVoiceTool.description,
+  getLearnedVoiceTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await getLearnedVoiceTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   createPostTool.name,
   createPostTool.description,

package/src/lib/api-client.ts

@@ -45,6 +45,21 @@ export interface BrandProfile {
   created_at?: string | null;
   updated_at?: string | null;
   source: 'canonical' | 'legacy';
+  learned_voice?: LearnedVoice[];
+}
+
+export interface LearnedVoice {
+  social_account_id: number;
+  platform: string;
+  username: string | null;
+  narrative_summary: string | null;
+  summary: string | null;
+  traits: string[];
+  style_guidelines: string[];
+  observations: Record<string, unknown>;
+  sample_post_ids: number[];
+  post_count: number;
+  derived_at: string | null;
 }
 
 export interface Post {
@@ -623,6 +638,9 @@ export class PosterlyClient {
   constructor(apiKey?: string, baseUrl?: string) {
     this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
     this.baseUrl = resolvePosterlyBaseUrl(baseUrl);
+    if (this.apiKey) {
+      validatePosterlyBaseUrlForKeyUse(this.baseUrl);
+    }
   }
 
   hasApiKey(): boolean {
@@ -867,6 +885,10 @@ export class PosterlyClient {
     return this.request('GET', `/brands/${encodeURIComponent(id)}/profile`);
   }
 
+  async getAccountLearnedVoice(id: string | number): Promise<{ learned_voice: LearnedVoice | null }> {
+    return this.request('GET', `/accounts/${encodeURIComponent(String(id))}/learned-voice`);
+  }
+
   async listPosts(params?: {
     status?: string;
     platform?: string;
@@ -1364,6 +1386,101 @@ export function resolvePosterlyBaseUrl(baseUrl?: string): string {
   }
 }
 
+const TRUSTED_POSTERLY_HOSTS = new Set(['poster.ly', 'www.poster.ly']);
+
+type PosterlyBaseUrlInspection = {
+  valid: boolean;
+  secure: boolean;
+  protocol?: string;
+  host?: string;
+  trustedPosterlyHost: boolean;
+  localDevelopmentHost: boolean;
+  warnings: string[];
+  message: string;
+};
+
+function flagEnabled(name: string): boolean {
+  const value = (process.env[name] || '').trim().toLowerCase();
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
+function normalizeHostname(hostname: string): string {
+  return hostname.toLowerCase().replace(/^\[|\]$/g, '');
+}
+
+function isLocalHost(hostname: string): boolean {
+  const normalized = normalizeHostname(hostname);
+  return (
+    normalized === 'localhost' ||
+    normalized.endsWith('.localhost') ||
+    normalized === '127.0.0.1' ||
+    normalized === '::1'
+  );
+}
+
+export function inspectPosterlyBaseUrl(baseUrl: string): PosterlyBaseUrlInspection {
+  try {
+    const url = new URL(baseUrl);
+    const hostname = normalizeHostname(url.hostname);
+    const local = isLocalHost(hostname);
+    const trustedPosterlyHost = TRUSTED_POSTERLY_HOSTS.has(hostname);
+    const secure = url.protocol === 'https:' || (url.protocol === 'http:' && local);
+    const warnings: string[] = [];
+
+    if (!trustedPosterlyHost) {
+      warnings.push(local ? 'local_development_host' : 'custom_host');
+    }
+    if (!secure) {
+      warnings.push('insecure_non_local_url');
+    }
+
+    return {
+      valid: true,
+      secure,
+      protocol: url.protocol.replace(/:$/, ''),
+      host: url.host,
+      trustedPosterlyHost,
+      localDevelopmentHost: local,
+      warnings,
+      message: secure
+        ? 'Base URL is secure for API-key requests.'
+        : 'Non-local HTTP URLs are blocked for API-key requests.',
+    };
+  } catch {
+    return {
+      valid: false,
+      secure: false,
+      trustedPosterlyHost: false,
+      localDevelopmentHost: false,
+      warnings: ['invalid_url'],
+      message: 'Base URL must include a scheme and host, for example https://www.poster.ly.',
+    };
+  }
+}
+
+export function validatePosterlyBaseUrlForKeyUse(baseUrl: string): void {
+  const check = inspectPosterlyBaseUrl(baseUrl);
+  if (!check.valid) {
+    throw new Error(`${check.message} Received: ${baseUrl}`);
+  }
+
+  if (!check.secure && !flagEnabled('POSTERLY_ALLOW_INSECURE_URL')) {
+    throw new Error(
+      `Refusing to send an API key to ${baseUrl}. Use https, http://localhost for local development, or set POSTERLY_ALLOW_INSECURE_URL=true only for a trusted private development endpoint.`
+    );
+  }
+
+  if (
+    !check.trustedPosterlyHost &&
+    !check.localDevelopmentHost &&
+    !flagEnabled('POSTERLY_ALLOW_CUSTOM_BASE_URL')
+  ) {
+    throw new Error(
+      `Refusing to send an API key to custom host ${baseUrl}. Set POSTERLY_ALLOW_CUSTOM_BASE_URL=true only for a trusted Posterly deployment.`
+    );
+  }
+}
+
 function parseJson(text: string): any {
   try {
     return text ? JSON.parse(text) : {};

package/src/lib/format.ts

@@ -1,4 +1,4 @@
-import type { Account, Post } from './api-client.js';
+import type { Account, LearnedVoice, Post } from './api-client.js';
 
 type CellValue = string | number | boolean | null | undefined;
 
@@ -154,6 +154,51 @@ export function compactText(value: string | null | undefined, maxLength = 90): s
   return text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 1))}…` : text;
 }
 
+/**
+ * Render one account's learned voice (derived from its real published captions)
+ * as a Markdown block. Returns null when there is no learned voice to show.
+ */
+export function mdLearnedVoice(learned: LearnedVoice | null | undefined): string | null {
+  if (!learned) return null;
+
+  const obs = (learned.observations || {}) as Record<string, unknown>;
+  const num = (key: string): number | undefined => {
+    const value = obs[key];
+    return typeof value === 'number' ? value : undefined;
+  };
+  const topEmojis = Array.isArray(obs.top_emojis) ? (obs.top_emojis as string[]) : [];
+
+  const accountLabel = learned.username
+    ? `@${learned.username}${learned.platform ? ` (${learned.platform})` : ''}`
+    : `account ${learned.social_account_id}`;
+
+  const habits: string[] = [];
+  const avgLen = num('avg_caption_length');
+  if (avgLen != null) habits.push(`~${avgLen} chars/post`);
+  const emojiRate = num('emoji_rate');
+  if (emojiRate != null) {
+    habits.push(emojiRate >= 0.5 ? `~${emojiRate} emoji/post${topEmojis.length ? ` (${topEmojis.slice(0, 3).join(' ')})` : ''}` : 'rarely uses emoji');
+  }
+  const hashtagAvg = num('hashtag_avg');
+  if (hashtagAvg != null && hashtagAvg >= 0.5) habits.push(`~${Math.round(hashtagAvg)} hashtags/post`);
+  const questionRate = num('question_rate');
+  if (questionRate != null && questionRate >= 0.3) habits.push('often opens with a question');
+  const lineBreakRate = num('line_break_rate');
+  if (lineBreakRate != null && lineBreakRate >= 0.5) habits.push('uses line breaks');
+
+  const body = mdKeyValue([
+    ['Account', accountLabel],
+    ['Summary', compactText(learned.narrative_summary || learned.summary, 240)],
+    ['Traits', learned.traits?.length ? learned.traits.join(', ') : undefined],
+    ['Style guidelines', learned.style_guidelines?.length ? learned.style_guidelines.join(' • ') : undefined],
+    ['Observed habits', habits.length ? habits.join(', ') : undefined],
+    ['Learned from', `${learned.post_count} posts`],
+    ['Last updated', learned.derived_at ? formatDateTime(learned.derived_at) : undefined],
+  ]);
+
+  return body || null;
+}
+
 export function statusLabel(status: string | null | undefined): string {
   const value = String(status || 'unknown').toLowerCase();
   if (['created', 'success', 'succeeded', 'completed', 'published', 'active'].includes(value)) return `✅ ${status}`;

package/src/lib/version.ts

@@ -1 +1,8 @@
-export const POSTERLY_MCP_VERSION = '0.23.0';
+// Version of the npm stdio MCP package (posterly-mcp-server).
+//
+// MUST stay in lockstep with the hosted HTTP endpoint version in
+// lib/mcp/version.ts. The two MCP surfaces share one version namespace and
+// 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.23.1';

package/src/tools/add-google-business-media.ts

@@ -24,7 +24,7 @@ export const addGoogleBusinessMediaTool = {
   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 location/platform_user_id. Provide account_id or location_id.'),
+    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.'),
     source_url: z.string().url().describe('Public https URL of the photo or video (from upload_media / upload_media_from_url).'),
     category: z.enum(CATEGORIES).describe('Which gallery category to add the media to.'),
     media_format: z.enum(['PHOTO', 'VIDEO']).optional().describe('Defaults to PHOTO. Use VIDEO for videos (Google caps profile videos at 30s / 75MB).'),

package/src/tools/audit-google-business-profile.ts

@@ -8,7 +8,7 @@ export const auditGoogleBusinessProfileTool = {
   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 location/platform_user_id.'),
+    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.'),
   }),
 
   async execute(

package/src/tools/delete-google-business-media.ts

@@ -8,7 +8,7 @@ export const deleteGoogleBusinessMediaTool = {
   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 location/platform_user_id. Provide account_id or location_id.'),
+    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.'),
     media_name: z.string().min(1).describe('Full media resource name from list_google_business_media (accounts/.../locations/.../media/...).'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
   }),

package/src/tools/delete-google-business-review-reply.ts

@@ -8,7 +8,7 @@ export const deleteGoogleBusinessReviewReplyTool = {
   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 location/platform_user_id.'),
+    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.'),
     review_name: z.string().min(1).describe('Full Google review resource name.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
   }),

package/src/tools/get-account-analytics.ts

@@ -8,7 +8,7 @@ type MetricRow = [string, string];
 export const getAccountAnalyticsTool = {
   name: 'get_account_analytics',
   description:
-    'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
+    'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
   inputSchema: z.object({
     account_id: z
       .number()

package/src/tools/get-brand-profile.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
-import { code, compactText, formatDateTime, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
+import type { LearnedVoice } from '../lib/api-client.js';
+import { code, compactText, formatDateTime, mdLearnedVoice, mdKeyValue, mdSection, mdTitle } from '../lib/format.js';
 
 export const getBrandProfileTool = {
   name: 'get_brand_profile',
@@ -47,10 +48,20 @@ export const getBrandProfileTool = {
       ])),
     ].filter(Boolean).join('\n\n');
 
+    const learnedVoices = (Array.isArray(profile.learned_voice) ? profile.learned_voice : []) as LearnedVoice[];
+    const learnedBody = learnedVoices.length
+      ? mdSection(
+          'Learned voice (from published captions)',
+          learnedVoices.map((voice) => mdLearnedVoice(voice)).filter(Boolean).join('\n\n'),
+        )
+      : '';
+
     return [
       mdTitle(`Brand profile: ${profile.brand_name}`),
       profileBody || 'No extended brand profile fields have been saved yet.',
-    ].join('\n\n');
+      learnedBody ||
+        '_No learned voice yet. posterly learns each account’s voice automatically once it has enough published posts._',
+    ].filter(Boolean).join('\n\n');
   },
 };
 

package/src/tools/get-google-business-review-link.ts

@@ -4,11 +4,11 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const getGoogleBusinessReviewLinkTool = {
   name: 'get_google_business_review_link',
   description:
-    'Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id.',
+    'Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id. Returns reviewLink plus the Google Place ID (ChIJ...); that Place ID is output only and must NOT be passed back as location_id to other tools.',
   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 location/platform_user_id.'),
+    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 this tool returns. Prefer account_id.'),
   }),
 
   async execute(

package/src/tools/get-learned-voice.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { mdLearnedVoice, mdTitle } from '../lib/format.js';
+
+export const getLearnedVoiceTool = {
+  name: 'get_learned_voice',
+  description:
+    'Get the voice posterly has learned from a connected account’s real published captions (the "learned captions" shown on the dashboard). Returns a narrative summary, voice traits, style guidelines, and observed posting habits. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has enough published posts to learn from. Read-only; this never overwrites the saved brand profile.',
+  inputSchema: z.object({
+    account_id: z
+      .union([z.string(), z.number()])
+      .describe('The social account ID to inspect (from list_accounts or list_brand_accounts).'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { account_id: string | number },
+  ) {
+    const { learned_voice } = await client.getAccountLearnedVoice(input.account_id);
+
+    const body = mdLearnedVoice(learned_voice);
+    if (!body) {
+      return [
+        mdTitle('No learned voice yet'),
+        'posterly has not learned a voice for this account yet. It learns automatically once the account has enough published posts (the captions are analyzed; the saved brand profile is never overwritten).',
+      ].join('\n\n');
+    }
+
+    return [mdTitle('Learned voice (from published captions)'), body].join('\n\n');
+  },
+};

package/src/tools/get-post-analytics.ts

@@ -7,7 +7,7 @@ type AnalyticsPresentation = z.infer<typeof presentationSchema>;
 export const getPostAnalyticsTool = {
   name: 'get_post_analytics',
   description:
-    'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
+    'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
   inputSchema: z.object({
     account_id: z
       .number()

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

@@ -8,7 +8,7 @@ export const listGoogleBusinessMediaTool = {
   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 location/platform_user_id.'),
+    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.'),
   }),
 
   async execute(

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

@@ -8,7 +8,7 @@ export const listGoogleBusinessReviewsTool = {
   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 location/platform_user_id.'),
+    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.'),
   }),

package/src/tools/reply-google-business-review.ts

@@ -8,7 +8,7 @@ export const replyGoogleBusinessReviewTool = {
   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 location/platform_user_id.'),
+    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.'),
     review_name: z.string().min(1).describe('Full Google review resource name.'),
     comment: z.string().min(1).max(4096).describe('Exact owner reply text to post.'),
     confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),

package/src/tools/suggest-google-business-review-reply.ts

@@ -8,7 +8,7 @@ export const suggestGoogleBusinessReviewReplyTool = {
   inputSchema: z.object({
     workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
     account_id: z.number().int().positive().optional().describe('Optional Google Business account ID for brand voice context.'),
-    location_id: z.string().optional().describe('Google Business location/platform_user_id.'),
+    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.'),
     review_text: z.string().optional().describe('Review text. Leave empty for rating-only reviews.'),
     star_rating: z.number().min(1).max(5).describe('Review rating from 1 to 5.'),
     reviewer_name: z.string().optional(),