posterly-mcp-server 0.23.0 → 0.23.1

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)

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;

package/dist/lib/api-client.js

@@ -179,6 +179,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)

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-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/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.1",
   "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 {
@@ -867,6 +882,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;

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-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/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(),