posterly-mcp-server 0.22.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.20.8` exposes 59 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`
@@ -167,6 +168,12 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `suggest_google_business_review_reply`
 - `reply_google_business_review` (post/update a public GBP review reply after explicit confirmation)
 - `delete_google_business_review_reply` (delete a GBP review reply after explicit confirmation)
+- `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';
@@ -41,6 +42,9 @@ import { auditGoogleBusinessProfileTool } from './tools/audit-google-business-pr
 import { suggestGoogleBusinessReviewReplyTool } from './tools/suggest-google-business-review-reply.js';
 import { replyGoogleBusinessReviewTool } from './tools/reply-google-business-review.js';
 import { deleteGoogleBusinessReviewReplyTool } from './tools/delete-google-business-review-reply.js';
+import { listGoogleBusinessMediaTool } from './tools/list-google-business-media.js';
+import { addGoogleBusinessMediaTool } from './tools/add-google-business-media.js';
+import { deleteGoogleBusinessMediaTool } from './tools/delete-google-business-media.js';
 import { listActivityTool } from './tools/list-activity.js';
 import { listWebhooksTool } from './tools/list-webhooks.js';
 import { createWebhookTool } from './tools/create-webhook.js';
@@ -275,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);
@@ -536,6 +549,33 @@ server.tool(deleteGoogleBusinessReviewReplyTool.name, deleteGoogleBusinessReview
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(listGoogleBusinessMediaTool.name, listGoogleBusinessMediaTool.description, listGoogleBusinessMediaTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await listGoogleBusinessMediaTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(addGoogleBusinessMediaTool.name, addGoogleBusinessMediaTool.description, addGoogleBusinessMediaTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await addGoogleBusinessMediaTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(deleteGoogleBusinessMediaTool.name, deleteGoogleBusinessMediaTool.description, deleteGoogleBusinessMediaTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await deleteGoogleBusinessMediaTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(listActivityTool.name, listActivityTool.description, listActivityTool.inputSchema.shape, async (input) => {
     try {
         const text = await listActivityTool.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;
@@ -372,6 +386,28 @@ export interface GoogleBusinessReviewsResponse {
     total: number;
     locations: Array<Record<string, unknown>>;
 }
+export interface GoogleBusinessMediaItem {
+    name: string;
+    mediaFormat: 'PHOTO' | 'VIDEO' | 'MEDIA_FORMAT_UNSPECIFIED';
+    category: string | null;
+    googleUrl: string | null;
+    thumbnailUrl: string | null;
+    createTime: string | null;
+    widthPixels: number | null;
+    heightPixels: number | null;
+    attribution: {
+        profileName?: string;
+        profilePhotoUrl?: string;
+        profileUrl?: string;
+    } | null;
+    account_id?: number;
+    location_id?: string | null;
+}
+export interface GoogleBusinessMediaResponse {
+    media: GoogleBusinessMediaItem[];
+    total: number;
+    locations: Array<Record<string, unknown>>;
+}
 export interface GoogleBusinessReviewLinkResponse {
     reviewLink: string;
     placeId: string;
@@ -658,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;
@@ -820,6 +859,25 @@ export declare class PosterlyClient {
         location_id?: string;
         review_name: string;
     }): Promise<Record<string, any>>;
+    listGoogleBusinessMedia(params?: {
+        workspace_id?: string;
+        account_id?: number;
+        location_id?: string;
+    }): Promise<GoogleBusinessMediaResponse>;
+    addGoogleBusinessMedia(data: {
+        workspace_id?: string;
+        account_id?: number;
+        location_id?: string;
+        source_url: string;
+        category: string;
+        media_format?: 'PHOTO' | 'VIDEO';
+    }): Promise<Record<string, any>>;
+    deleteGoogleBusinessMedia(data: {
+        workspace_id?: string;
+        account_id?: number;
+        location_id?: string;
+        media_name: string;
+    }): Promise<Record<string, any>>;
     listActivity(params?: {
         workspace_id?: string;
         post_id?: number;

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)
@@ -333,6 +336,23 @@ export class PosterlyClient {
     async deleteGoogleBusinessReviewReply(data) {
         return this.request('DELETE', '/google-business/reviews/reply', data);
     }
+    async listGoogleBusinessMedia(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.workspace_id)
+            searchParams.set('workspace_id', params.workspace_id);
+        if (params?.account_id)
+            searchParams.set('account_id', String(params.account_id));
+        if (params?.location_id)
+            searchParams.set('location_id', params.location_id);
+        const qs = searchParams.toString();
+        return this.request('GET', `/google-business/media${qs ? `?${qs}` : ''}`);
+    }
+    async addGoogleBusinessMedia(data) {
+        return this.request('POST', '/google-business/media', data);
+    }
+    async deleteGoogleBusinessMedia(data) {
+        return this.request('DELETE', '/google-business/media', data);
+    }
     async listActivity(params) {
         const searchParams = new URLSearchParams();
         if (params?.workspace_id)

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.20.8";
+export declare const POSTERLY_MCP_VERSION = "0.23.1";

package/dist/lib/version.js

@@ -1 +1,8 @@
-export const POSTERLY_MCP_VERSION = '0.20.8';
+// 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.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+declare const CATEGORIES: readonly ["COVER", "PROFILE", "LOGO", "EXTERIOR", "INTERIOR", "PRODUCT", "AT_WORK", "FOOD_AND_DRINK", "MENU", "COMMON_AREA", "ROOMS", "TEAMS", "ADDITIONAL"];
+export declare const addGoogleBusinessMediaTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        workspace_id: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodNumber>;
+        location_id: z.ZodOptional<z.ZodString>;
+        source_url: z.ZodString;
+        category: z.ZodEnum<["COVER", "PROFILE", "LOGO", "EXTERIOR", "INTERIOR", "PRODUCT", "AT_WORK", "FOOD_AND_DRINK", "MENU", "COMMON_AREA", "ROOMS", "TEAMS", "ADDITIONAL"]>;
+        media_format: z.ZodOptional<z.ZodEnum<["PHOTO", "VIDEO"]>>;
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        confirm: true;
+        source_url: string;
+        category: "COVER" | "PROFILE" | "LOGO" | "EXTERIOR" | "INTERIOR" | "PRODUCT" | "AT_WORK" | "FOOD_AND_DRINK" | "MENU" | "COMMON_AREA" | "ROOMS" | "TEAMS" | "ADDITIONAL";
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        location_id?: string | undefined;
+        media_format?: "PHOTO" | "VIDEO" | undefined;
+    }, {
+        confirm: true;
+        source_url: string;
+        category: "COVER" | "PROFILE" | "LOGO" | "EXTERIOR" | "INTERIOR" | "PRODUCT" | "AT_WORK" | "FOOD_AND_DRINK" | "MENU" | "COMMON_AREA" | "ROOMS" | "TEAMS" | "ADDITIONAL";
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        location_id?: string | undefined;
+        media_format?: "PHOTO" | "VIDEO" | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        workspace_id?: string;
+        account_id?: number;
+        location_id?: string;
+        source_url: string;
+        category: (typeof CATEGORIES)[number];
+        media_format?: "PHOTO" | "VIDEO";
+        confirm: true;
+    }): Promise<any>;
+};
+export {};

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

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+const CATEGORIES = [
+    'COVER',
+    'PROFILE',
+    'LOGO',
+    'EXTERIOR',
+    'INTERIOR',
+    'PRODUCT',
+    'AT_WORK',
+    'FOOD_AND_DRINK',
+    'MENU',
+    'COMMON_AREA',
+    'ROOMS',
+    'TEAMS',
+    'ADDITIONAL',
+];
+export const addGoogleBusinessMediaTool = {
+    name: 'add_google_business_media',
+    description: 'Add a photo or video to a Google Business Profile gallery (the media shown on Maps and Search). Provide a public https source_url first by uploading via upload_media_from_url or upload_media. COVER and PROFILE are single-slot and replace the existing one. WRITE: show the location, category, and media URL to the user, then pass confirm=true only after explicit confirmation.',
+    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.'),
+        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).'),
+        confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+    }),
+    async execute(client, input) {
+        const { confirm: _confirm, ...payload } = input;
+        const result = await client.addGoogleBusinessMedia(payload);
+        return result.message || 'Media added to the Google Business profile.';
+    },
+};

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.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const deleteGoogleBusinessMediaTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        workspace_id: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodNumber>;
+        location_id: z.ZodOptional<z.ZodString>;
+        media_name: z.ZodString;
+        confirm: z.ZodLiteral<true>;
+    }, "strip", z.ZodTypeAny, {
+        confirm: true;
+        media_name: string;
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        location_id?: string | undefined;
+    }, {
+        confirm: true;
+        media_name: string;
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        location_id?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        workspace_id?: string;
+        account_id?: number;
+        location_id?: string;
+        media_name: string;
+        confirm: true;
+    }): Promise<any>;
+};

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

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export const deleteGoogleBusinessMediaTool = {
+    name: 'delete_google_business_media',
+    description: 'Remove a photo or video from a Google Business Profile gallery. Get media_name from list_google_business_media. This permanently deletes the item from the public profile. WRITE: show the exact media item and location to the user, then pass confirm=true only after explicit confirmation.',
+    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.'),
+        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.'),
+    }),
+    async execute(client, input) {
+        const { confirm: _confirm, ...payload } = input;
+        const result = await client.deleteGoogleBusinessMedia(payload);
+        return result.message || 'Media removed from the Google Business profile.';
+    },
+};

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.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const listGoogleBusinessMediaTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        workspace_id: z.ZodOptional<z.ZodString>;
+        account_id: z.ZodOptional<z.ZodNumber>;
+        location_id: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        location_id?: string | undefined;
+    }, {
+        workspace_id?: string | undefined;
+        account_id?: number | undefined;
+        location_id?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        workspace_id?: string;
+        account_id?: number;
+        location_id?: string;
+    }): Promise<string>;
+};

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

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+export const listGoogleBusinessMediaTool = {
+    name: 'list_google_business_media',
+    description: 'List the photos and videos on a Google Business Profile gallery (the media shown on Maps and Search) for one location/account or every accessible GBP location. This is separate from media attached to a post. Returns each item\'s resource name, category, format, and URLs.',
+    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.'),
+    }),
+    async execute(client, input) {
+        const result = await client.listGoogleBusinessMedia(input);
+        if (result.media.length === 0) {
+            return 'No photos or videos found on the Google Business profile for your filters.';
+        }
+        const lines = [`Google Business profile media (${result.media.length}):`];
+        for (const item of result.media.slice(0, 50)) {
+            const kind = item.mediaFormat === 'VIDEO' ? 'video' : 'photo';
+            const category = item.category || 'uncategorised';
+            const attribution = item.attribution?.profileName ? ` by ${item.attribution.profileName}` : '';
+            lines.push(`- [${kind}] ${category}${attribution} :: ${item.name}`);
+        }
+        lines.push('', 'Use the resource name (after ::) as media_name to delete an item.');
+        return lines.join('\n');
+    },
+};

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.22.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';
@@ -42,6 +43,9 @@ import { auditGoogleBusinessProfileTool } from './tools/audit-google-business-pr
 import { suggestGoogleBusinessReviewReplyTool } from './tools/suggest-google-business-review-reply.js';
 import { replyGoogleBusinessReviewTool } from './tools/reply-google-business-review.js';
 import { deleteGoogleBusinessReviewReplyTool } from './tools/delete-google-business-review-reply.js';
+import { listGoogleBusinessMediaTool } from './tools/list-google-business-media.js';
+import { addGoogleBusinessMediaTool } from './tools/add-google-business-media.js';
+import { deleteGoogleBusinessMediaTool } from './tools/delete-google-business-media.js';
 import { listActivityTool } from './tools/list-activity.js';
 import { listWebhooksTool } from './tools/list-webhooks.js';
 import { createWebhookTool } from './tools/create-webhook.js';
@@ -394,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,
@@ -800,6 +818,48 @@ server.tool(
   }
 );
 
+server.tool(
+  listGoogleBusinessMediaTool.name,
+  listGoogleBusinessMediaTool.description,
+  listGoogleBusinessMediaTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await listGoogleBusinessMediaTool.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(
+  addGoogleBusinessMediaTool.name,
+  addGoogleBusinessMediaTool.description,
+  addGoogleBusinessMediaTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await addGoogleBusinessMediaTool.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(
+  deleteGoogleBusinessMediaTool.name,
+  deleteGoogleBusinessMediaTool.description,
+  deleteGoogleBusinessMediaTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await deleteGoogleBusinessMediaTool.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(
   listActivityTool.name,
   listActivityTool.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 {
@@ -369,6 +384,26 @@ export interface GoogleBusinessReviewsResponse {
   locations: Array<Record<string, unknown>>;
 }
 
+export interface GoogleBusinessMediaItem {
+  name: string;
+  mediaFormat: 'PHOTO' | 'VIDEO' | 'MEDIA_FORMAT_UNSPECIFIED';
+  category: string | null;
+  googleUrl: string | null;
+  thumbnailUrl: string | null;
+  createTime: string | null;
+  widthPixels: number | null;
+  heightPixels: number | null;
+  attribution: { profileName?: string; profilePhotoUrl?: string; profileUrl?: string } | null;
+  account_id?: number;
+  location_id?: string | null;
+}
+
+export interface GoogleBusinessMediaResponse {
+  media: GoogleBusinessMediaItem[];
+  total: number;
+  locations: Array<Record<string, unknown>>;
+}
+
 export interface GoogleBusinessReviewLinkResponse {
   reviewLink: string;
   placeId: string;
@@ -847,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;
@@ -1117,6 +1156,39 @@ export class PosterlyClient {
     return this.request('DELETE', '/google-business/reviews/reply', data);
   }
 
+  async listGoogleBusinessMedia(params?: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+  }): Promise<GoogleBusinessMediaResponse> {
+    const searchParams = new URLSearchParams();
+    if (params?.workspace_id) searchParams.set('workspace_id', params.workspace_id);
+    if (params?.account_id) searchParams.set('account_id', String(params.account_id));
+    if (params?.location_id) searchParams.set('location_id', params.location_id);
+    const qs = searchParams.toString();
+    return this.request('GET', `/google-business/media${qs ? `?${qs}` : ''}`);
+  }
+
+  async addGoogleBusinessMedia(data: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+    source_url: string;
+    category: string;
+    media_format?: 'PHOTO' | 'VIDEO';
+  }): Promise<Record<string, any>> {
+    return this.request('POST', '/google-business/media', data);
+  }
+
+  async deleteGoogleBusinessMedia(data: {
+    workspace_id?: string;
+    account_id?: number;
+    location_id?: string;
+    media_name: string;
+  }): Promise<Record<string, any>> {
+    return this.request('DELETE', '/google-business/media', data);
+  }
+
   async listActivity(params?: {
     workspace_id?: string;
     post_id?: number;

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.20.8';
+// 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

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+const CATEGORIES = [
+  'COVER',
+  'PROFILE',
+  'LOGO',
+  'EXTERIOR',
+  'INTERIOR',
+  'PRODUCT',
+  'AT_WORK',
+  'FOOD_AND_DRINK',
+  'MENU',
+  'COMMON_AREA',
+  'ROOMS',
+  'TEAMS',
+  'ADDITIONAL',
+] as const;
+
+export const addGoogleBusinessMediaTool = {
+  name: 'add_google_business_media',
+  description:
+    'Add a photo or video to a Google Business Profile gallery (the media shown on Maps and Search). Provide a public https source_url first by uploading via upload_media_from_url or upload_media. COVER and PROFILE are single-slot and replace the existing one. WRITE: show the location, category, and media URL to the user, then pass confirm=true only after explicit confirmation.',
+  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.'),
+    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).'),
+    confirm: z.literal(true).describe('Must be true after explicit user confirmation.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      location_id?: string;
+      source_url: string;
+      category: (typeof CATEGORIES)[number];
+      media_format?: 'PHOTO' | 'VIDEO';
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    const result = await client.addGoogleBusinessMedia(payload);
+    return result.message || 'Media added to the Google Business profile.';
+  },
+};

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

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const deleteGoogleBusinessMediaTool = {
+  name: 'delete_google_business_media',
+  description:
+    'Remove a photo or video from a Google Business Profile gallery. Get media_name from list_google_business_media. This permanently deletes the item from the public profile. WRITE: show the exact media item and location to the user, then pass confirm=true only after explicit confirmation.',
+  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.'),
+    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.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      workspace_id?: string;
+      account_id?: number;
+      location_id?: string;
+      media_name: string;
+      confirm: true;
+    },
+  ) {
+    const { confirm: _confirm, ...payload } = input;
+    const result = await client.deleteGoogleBusinessMedia(payload);
+    return result.message || 'Media removed from the Google Business profile.';
+  },
+};

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

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listGoogleBusinessMediaTool = {
+  name: 'list_google_business_media',
+  description:
+    'List the photos and videos on a Google Business Profile gallery (the media shown on Maps and Search) for one location/account or every accessible GBP location. This is separate from media attached to a post. Returns each item\'s resource name, category, format, and URLs.',
+  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.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { workspace_id?: string; account_id?: number; location_id?: string },
+  ) {
+    const result = await client.listGoogleBusinessMedia(input);
+    if (result.media.length === 0) {
+      return 'No photos or videos found on the Google Business profile for your filters.';
+    }
+
+    const lines = [`Google Business profile media (${result.media.length}):`];
+    for (const item of result.media.slice(0, 50)) {
+      const kind = item.mediaFormat === 'VIDEO' ? 'video' : 'photo';
+      const category = item.category || 'uncategorised';
+      const attribution = item.attribution?.profileName ? ` by ${item.attribution.profileName}` : '';
+      lines.push(`- [${kind}] ${category}${attribution} :: ${item.name}`);
+    }
+    lines.push('', 'Use the resource name (after ::) as media_name to delete an item.');
+    return lines.join('\n');
+  },
+};

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