posterly-mcp-server 0.43.8 → 0.45.0

package/src/tools/list-platforms.ts

@@ -1,25 +1,149 @@
 import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { PLANNED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+import type { ConnectOption, PosterlyClient } from '../lib/api-client.js';
+import { ALL_PLATFORM_INPUTS, CONNECT_INPUTS, PLANNED_PLATFORM_IDS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type ListPlatformsInput = {
+  view?: 'platforms' | 'schema' | 'connect_link';
+  include_planned?: boolean;
+  account_id?: string;
+  platform?: string;
+  target?: string;
+  workspace_id?: string;
+  debug?: boolean;
+};
 
 export const listPlatformsTool = {
   name: 'list_platforms',
   description:
-    'List posterly platform integrations, posting capabilities, content/media limits, settings schemas, helper tools, and analytics support. Use include_planned to show future integration possibilities from the Postiz parity audit.',
+    'Platforms, settings schemas, and connection links. view=platforms (default): posterly platform integrations, posting capabilities, content/media limits, settings schemas, helper tools, and analytics support (include_planned shows future integration possibilities). view=schema: the settings schema for one connected account_id (preferred: returns connection-specific capabilities, needed before Instagram native tags/collaborators) or one platform; account_id wins if both are given. view=connect_link: dashboard handoff links and readiness for every target, or one target (instagram, meta, linkedin_page, twitter, telegram, reddit, wordpress, ...); use connection_url in a logged-in browser (direct OAuth URLs are intentionally not exposed); credential platforms show the credential_fields that connect_account needs.',
   inputSchema: z.object({
+    view: z
+      .enum(['platforms', 'schema', 'connect_link'])
+      .optional()
+      .describe('platforms (default), schema, or connect_link.'),
+    account_id: z
+      .string()
+      .optional()
+      .describe('view=schema: connected account ID from list_accounts. Preferred because it returns account context.'),
+    platform: z
+      .enum(ALL_PLATFORM_INPUTS)
+      .optional()
+      .describe(`view=schema: platform ID such as ${SUPPORTED_PLATFORM_IDS.join(', ')}. Set include_planned to inspect planned providers.`),
+    target: z
+      .enum(CONNECT_INPUTS)
+      .optional()
+      .describe('view=connect_link: connection target such as instagram, meta, linkedin_page, twitter, x, google_business, telegram, reddit, or wordpress. Omit to list live connection targets.'),
+    workspace_id: z
+      .string()
+      .optional()
+      .describe('view=connect_link: filter connected account counts to a workspace.'),
     include_planned: z
       .boolean()
       .optional()
       .describe(`Include planned integrations such as ${PLANNED_PLATFORM_IDS.join(', ')}.`),
+    debug: z
+      .boolean()
+      .optional()
+      .describe('view=connect_link: when true, include the raw connect option JSON for debugging. Keep false for normal user-facing agent flows.'),
   }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    get_platform_schema: z.object({
+      account_id: z.string().optional(),
+      platform: z.enum(ALL_PLATFORM_INPUTS).optional(),
+      include_planned: z.boolean().optional(),
+    }),
+    get_connect_link: z.object({
+      platform: z.enum(CONNECT_INPUTS).optional(),
+      workspace_id: z.string().optional(),
+      include_planned: z.boolean().optional(),
+      debug: z.boolean().optional(),
+    }),
+  },
 
-  async execute(client: PosterlyClient, input: { include_planned?: boolean }) {
-    const result = await client.listPlatforms(input);
-    const lines = result.platforms.map((platform) => {
-      const helperCount = platform.helper_tools?.length || 0;
-      return `• ${platform.label} (${platform.id}): ${platform.status}; post types: ${platform.post_types.join(', ') || 'n/a'}; helpers: ${helperCount}; analytics: ${platform.analytics_supported ? 'yes' : 'no'}`;
-    });
-
-    return `posterly platforms (${result.platforms.length}):\n${lines.join('\n')}`;
+  async execute(client: PosterlyClient, input: ListPlatformsInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'list_platforms', input);
+    if (mode === 'schema') return platformSchema(client, args as ListPlatformsInput);
+    if (mode === 'connect_link') return connectLink(client, args as ListPlatformsInput);
+    return platforms(client, args as ListPlatformsInput);
   },
 };
+
+async function platforms(client: PosterlyClient, input: ListPlatformsInput): Promise<string> {
+  const result = await client.listPlatforms({ include_planned: input.include_planned });
+  const lines = result.platforms.map((platform) => {
+    const helperCount = platform.helper_tools?.length || 0;
+    return `• ${platform.label} (${platform.id}): ${platform.status}; post types: ${platform.post_types.join(', ') || 'n/a'}; helpers: ${helperCount}; analytics: ${platform.analytics_supported ? 'yes' : 'no'}`;
+  });
+
+  return `posterly platforms (${result.platforms.length}):\n${lines.join('\n')}`;
+}
+
+async function platformSchema(client: PosterlyClient, input: ListPlatformsInput): Promise<string> {
+  const result = await client.getPlatformSchema({ account_id: input.account_id, platform: input.platform, include_planned: input.include_planned });
+  const schema = result.schema || result.platform || result.platforms?.[0];
+  if (!schema) return JSON.stringify(result, null, 2);
+
+  const fields = schema.settings_schema?.fields || [];
+  const helpers = schema.helper_tools || [];
+  const accountLine = result.account
+    ? `Account: ${(result.account.username as string) || result.account.id} (${result.account.platform})\n`
+    : '';
+  const instagramTaggingLine = result.account?.instagram_tagging
+    ? `Instagram tagging capabilities: ${JSON.stringify(result.account.instagram_tagging)}`
+    : '';
+
+  return [
+    `${schema.label} (${schema.id}) schema`,
+    accountLine.trim(),
+    instagramTaggingLine,
+    `Status: ${schema.status}`,
+    `Post types: ${schema.post_types.join(', ') || 'n/a'}`,
+    `Content limit: ${schema.content_limit ?? 'n/a'}`,
+    `Media: ${JSON.stringify(schema.media)}`,
+    `Analytics: ${schema.analytics_supported ? 'yes' : 'no'}`,
+    fields.length
+      ? `Settings:\n${fields.map((field: any) => `• ${field.key}${field.required ? ' (required)' : ''}: ${field.description}`).join('\n')}`
+      : 'Settings: none',
+    helpers.length
+      ? `Helpers:\n${helpers.map((helper: any) => `• ${helper.name}: ${helper.description}`).join('\n')}`
+      : 'Helpers: none',
+    `Example settings: ${JSON.stringify(schema.settings_schema?.example || {})}`,
+  ].filter(Boolean).join('\n');
+}
+
+async function connectLink(client: PosterlyClient, input: ListPlatformsInput): Promise<string> {
+  const { debug } = input;
+  const result = await client.getConnectLink({
+    platform: input.target,
+    workspace_id: input.workspace_id,
+    include_planned: input.include_planned,
+  });
+  if (result.connect) {
+    return formatConnectOption(result.connect, Boolean(debug));
+  }
+
+  const options = result.connect_options || [];
+  const lines = options.map((option) => formatConnectOption(option, false));
+  return `posterly connection options (${options.length}):\n${lines.join('\n\n')}`;
+}
+
+function formatConnectOption(option: ConnectOption, includeRaw: boolean): string {
+  const missing = option.missing_env?.length
+    ? `missing env: ${option.missing_env.map((group) => group.join(' or ')).join(', ')}`
+    : 'configured';
+  const accounts = option.connected_count ?? option.connected_accounts?.length ?? 0;
+  const fields = option.credential_fields?.length
+    ? `; credential fields: ${option.credential_fields.map((field: any) => field.key).join(', ')}`
+    : '';
+  const scopes = option.scopes?.length ? `; scopes: ${option.scopes.join(', ')}` : '';
+  const raw = includeRaw ? `\n\nRaw connect option:\n${JSON.stringify(option, null, 2)}` : '';
+
+  return [
+    `${option.label} (${option.platform})`,
+    `Status: ${option.status}; method: ${option.method}; ${missing}; connected accounts: ${accounts}`,
+    `Connection URL: ${option.connection_url || 'not available'}${fields}${scopes}`,
+    raw,
+  ].join('\n');
+}

package/src/tools/list-workspace-members.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import type { PosterlyClient, WorkspaceMembersResponse } from '../lib/api-client.js';
+import { code, mdKeyValue, mdSection, mdTable, mdTitle } from '../lib/format.js';
+
+export function formatBrandIds(value: string[] | null | undefined): string {
+  if (!Array.isArray(value)) return 'hidden';
+  return value.length === 0 ? 'every brand' : value.map((id) => code(id)).join(', ');
+}
+
+function formatWorkspaceMembers(result: WorkspaceMembersResponse): string {
+  const members = result.members || [];
+  const invites = result.invites || [];
+  return [
+    mdTitle(`Team (${members.length} members, ${invites.length} pending invites)`, `Workspace ${result.workspace_id}`),
+    mdSection('Members', members.length > 0
+      ? mdTable(
+          ['Name', 'Member ID', 'Email', 'Role', 'Status', 'Brands'],
+          members.map((member) => [
+            member.name || member.email || member.id,
+            code(member.id),
+            member.email,
+            member.role,
+            member.status,
+            formatBrandIds(member.brand_ids),
+          ]),
+        )
+      : 'No members found.'),
+    mdSection('Pending invites', invites.length > 0
+      ? mdTable(
+          ['Email', 'Invite ID', 'Role', 'Brands', 'Expires'],
+          invites.map((invite) => [
+            invite.email,
+            code(invite.id),
+            invite.role,
+            formatBrandIds(invite.brand_ids),
+            invite.expires_at,
+          ]),
+        )
+      : ''),
+    mdSection('Seats', mdKeyValue([
+      ['Active members', result.usage?.active_members],
+      ['Pending invites', result.usage?.pending_invites],
+      ['Seats in use', result.usage?.seats_used],
+    ])),
+  ].filter(Boolean).join('\n\n');
+}
+
+export const listWorkspaceMembersTool = {
+  name: 'list_workspace_members',
+  description:
+    'List the people in a workspace: members (with role, status and brand access) and pending invites, plus seats in use. Needs an API key with the Manage team permission. Any workspace member can list; brand-limited teammates only see brand ids they can access.',
+  inputSchema: z.object({
+    workspace_id: z.string().describe('Workspace ID (from whoami).'),
+  }),
+
+  async execute(client: PosterlyClient, input: { workspace_id: string }) {
+    const workspaceId = input.workspace_id?.trim();
+    if (!workspaceId) throw new Error('workspace_id is required. Get it from whoami.');
+    return formatWorkspaceMembers(await client.listWorkspaceMembers(workspaceId));
+  },
+};

package/src/tools/manage-comment.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdQuote, mdSection } from '../lib/format.js';
+import { previewThenConfirm, readFailedNote, readForPreview, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type ManageCommentInput = {
+  action: 'reply' | 'update' | 'delete';
+  comment_id: string;
+  content?: string;
+  type?: 'public' | 'private';
+  is_hidden?: boolean;
+  is_read?: boolean;
+  workspace_id?: string;
+  confirm?: boolean;
+  preview_id?: string;
+};
+
+export const manageCommentTool = {
+  name: 'manage_comment',
+  description:
+    'Act on an inbox comment (Pro plan or higher plus posts:write). action=reply (comment_id, content): reply to an Instagram, Facebook Page, Threads, or LinkedIn Page comment; type private is Instagram only, the others take public replies only. action=update (comment_id, is_hidden and/or is_read): hide or unhide it on the platform, or mark it read or unread; reversible, no confirm needed. action=delete (comment_id): delete an Instagram or Facebook Page comment, irreversible and admin only; Threads replies cannot be deleted, hide them instead. reply and delete use preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id.',
+  inputSchema: z.object({
+    action: z.enum(['reply', 'update', 'delete']).describe('reply, update, or delete.'),
+    comment_id: z.string().min(1).describe('Comment ID from list_comments.'),
+    content: z.string().min(1).optional().describe('reply: reply text to post.'),
+    type: z.enum(['public', 'private']).optional().describe('reply: public (default) or private. Private is Instagram only.'),
+    is_hidden: z.boolean().optional().describe('update: hide or unhide the comment on Instagram, Facebook, or Threads.'),
+    is_read: z.boolean().optional().describe('update: mark the comment read or unread in posterly.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
+    confirm: z.boolean().optional().describe('reply and delete: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('reply and delete: the preview_id from the preview call. Required with confirm: true.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    reply_to_comment: z.object({
+      comment_id: z.string().min(1),
+      content: z.string().min(1),
+      type: z.enum(['public', 'private']).optional(),
+      workspace_id: z.string().optional(),
+      confirm: z.literal(true),
+    }),
+    update_comment: z.object({
+      comment_id: z.string().min(1),
+      is_hidden: z.boolean().optional(),
+      is_read: z.boolean().optional(),
+      workspace_id: z.string().optional(),
+    }),
+    delete_comment: z.object({
+      comment_id: z.string().min(1),
+      workspace_id: z.string().optional(),
+      confirm: z.literal(true),
+    }),
+  },
+
+  async execute(client: PosterlyClient, input: ManageCommentInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'manage_comment', input);
+    if (mode === 'update') return updateComment(client, args as ManageCommentInput);
+    if (mode === 'delete') {
+      return previewThenConfirm({
+        tool: 'manage_comment',
+        action: 'delete',
+        args,
+        nonce: false,
+        legacyRefusal: 'Refusing to delete comment without confirm=true after explicit user confirmation.',
+        ctx,
+        describe: async () => [
+          await describeComment(client, args as ManageCommentInput),
+          'Deletes this comment from the posterly inbox and, on Instagram or Facebook, from the network. This cannot be undone. Threads replies cannot be deleted; hide them with action=update instead.',
+        ].join('\n\n'),
+        run: () => deleteComment(client, args as ManageCommentInput & { confirm: true }),
+      });
+    }
+    return previewThenConfirm({
+      tool: 'manage_comment',
+      action: 'reply',
+      args,
+      nonce: true,
+      legacyRefusal: 'Refusing to reply to a comment without confirm=true after explicit user confirmation.',
+      ctx,
+      describe: async () => [
+        await describeComment(client, args as ManageCommentInput),
+        mdSection(`Reply to post (${args.type === 'private' ? 'private' : 'public'})`, mdQuote(String(args.content ?? ''))),
+        'This posts on the social network as your account.',
+      ].join('\n\n'),
+      run: () => replyToComment(client, args as ManageCommentInput & { content: string }),
+    });
+  },
+};
+
+async function describeComment(client: PosterlyClient, input: ManageCommentInput): Promise<string> {
+  const read = await readForPreview(() => client.getComment({ comment_id: input.comment_id, workspace_id: input.workspace_id }));
+  if (!read.ok) {
+    return [readFailedNote(read.error), mdKeyValue([['Comment ID', code(input.comment_id)], ['Workspace', input.workspace_id ? code(input.workspace_id) : undefined]])].join('\n\n');
+  }
+  const comment = read.data.comment;
+  return mdSection('Comment', mdKeyValue([
+    ['Comment ID', code(String(comment.id))],
+    ['Platform', typeof comment.platform === 'string' ? comment.platform : 'unknown'],
+    ['Author', typeof comment.author_username === 'string' ? `@${comment.author_username}` : 'unknown'],
+    ['Content', typeof comment.content === 'string' ? comment.content : '(empty)'],
+  ]));
+}
+
+async function replyToComment(client: PosterlyClient, input: ManageCommentInput & { content: string }): Promise<string> {
+  const result = await client.replyToComment({
+    comment_id: input.comment_id,
+    content: input.content,
+    type: input.type,
+    workspace_id: input.workspace_id,
+  });
+  return `Comment reply sent (${result.reply_type}, reply_id ${result.reply_id}).`;
+}
+
+async function updateComment(client: PosterlyClient, input: ManageCommentInput): Promise<string> {
+  const result = await client.updateComment({
+    comment_id: input.comment_id,
+    is_hidden: input.is_hidden,
+    is_read: input.is_read,
+    workspace_id: input.workspace_id,
+  });
+  const comment = result.comment;
+  const parts = [`Comment ${String(comment.id)} updated.`];
+  if (typeof comment.is_hidden === 'boolean') parts.push(`Hidden: ${comment.is_hidden ? 'yes' : 'no'}.`);
+  if (typeof comment.is_read === 'boolean') parts.push(`Read: ${comment.is_read ? 'yes' : 'no'}.`);
+  return parts.join(' ');
+}
+
+async function deleteComment(client: PosterlyClient, input: ManageCommentInput & { confirm: true }): Promise<string> {
+  if (input.confirm !== true) {
+    throw new Error('Refusing to delete comment without confirm=true after explicit user confirmation.');
+  }
+  await client.deleteComment(input.comment_id, input.workspace_id);
+  // Output kept byte-identical to the old delete_comment tool (its alias
+  // must match); the old name in the next-step line still works until the
+  // alias sunset.
+  return [
+    `Comment ${input.comment_id} deleted successfully.`,
+    'It has been deleted from the posterly inbox. On Instagram or Facebook it is also removed on the network when the platform call succeeds.',
+    '',
+    'Next step for the AI agent: tell the user the comment is gone. Threads replies cannot be deleted; hide them with update_comment instead.',
+  ].join('\n');
+}

package/src/tools/manage-conversation.ts

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdQuote, mdSection } from '../lib/format.js';
+import { omitKeys, previewThenConfirm, readFailedNote, readForPreview, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+type ManageConversationInput = {
+  action: 'send' | 'sync';
+  conversation_id?: string;
+  content?: string;
+  account_id?: number;
+  sync_type?: 'all' | 'dm' | 'comments';
+  workspace_id?: string;
+  confirm?: boolean;
+  preview_id?: string;
+};
+
+export const manageConversationTool = {
+  name: 'manage_conversation',
+  description:
+    'Act on the social inbox (Pro plan or higher plus posts:write). action=send (conversation_id, content): send a DM reply in an Instagram or Facebook Page conversation, honoring the 24-hour messaging window (Threads has no DMs); preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id. action=sync (account_id): pull the latest Instagram, Facebook Page, Threads, or LinkedIn inbox data for one account; 30-second cooldown (60 seconds for LinkedIn); Threads and LinkedIn sync comments only.',
+  inputSchema: z.object({
+    action: z.enum(['send', 'sync']).describe('send or sync.'),
+    conversation_id: z.string().min(1).optional().describe('send: conversation ID from list_conversations.'),
+    content: z.string().min(1).optional().describe('send: message text to send.'),
+    account_id: z.number().int().positive().optional().describe('sync: social account ID from list_accounts.'),
+    sync_type: z.enum(['all', 'dm', 'comments']).optional().describe('sync: what to sync. Defaults to all. Threads and LinkedIn are comments-only.'),
+    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
+    confirm: z.boolean().optional().describe('send: leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('send: the preview_id from the preview call. Required with confirm: true.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    send_message: z.object({
+      conversation_id: z.string().min(1),
+      content: z.string().min(1),
+      workspace_id: z.string().optional(),
+      confirm: z.literal(true),
+    }),
+    sync_inbox: z.object({
+      account_id: z.number().int().positive(),
+      sync_type: z.enum(['all', 'dm', 'comments']).optional(),
+      workspace_id: z.string().optional(),
+    }),
+  },
+
+  async execute(client: PosterlyClient, input: ManageConversationInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'manage_conversation', input);
+    if (mode === 'sync') return syncInbox(client, args as ManageConversationInput & { account_id: number });
+    return previewThenConfirm({
+      tool: 'manage_conversation',
+      action: 'send',
+      args,
+      nonce: true,
+      legacyRefusal: 'Refusing to send an inbox message without confirm=true after explicit user confirmation.',
+      ctx,
+      describe: async () => {
+        const read = await readForPreview(() => client.getConversation({ conversation_id: args.conversation_id, workspace_id: args.workspace_id, limit: 3 }));
+        const header = read.ok
+          ? mdSection('Conversation', mdKeyValue([
+              ['Conversation ID', code(String(read.data.conversation.id))],
+              ['Platform', typeof read.data.conversation.platform === 'string' ? read.data.conversation.platform : 'unknown'],
+              ['Participant', typeof read.data.conversation.participant_username === 'string' ? `@${read.data.conversation.participant_username}` : 'unknown'],
+            ]))
+          : [readFailedNote(read.error), mdKeyValue([['Conversation ID', code(args.conversation_id)]])].join('\n\n');
+        return [
+          header,
+          mdSection('Message to send', mdQuote(String(args.content ?? ''))),
+          'This sends a DM as your account. Instagram and Facebook only allow replies within 24 hours of the person\'s last message.',
+        ].join('\n\n');
+      },
+      run: async () => {
+        const result = await client.sendMessage({
+          conversation_id: args.conversation_id,
+          content: args.content,
+          workspace_id: args.workspace_id,
+        });
+        return `Message sent (message_id ${result.message_id}).`;
+      },
+    });
+  },
+};
+
+async function syncInbox(client: PosterlyClient, input: ManageConversationInput & { account_id: number }): Promise<string> {
+  const result = await client.syncInbox(omitKeys(input, ['action', 'confirm', 'preview_id']) as { account_id: number; sync_type?: 'all' | 'dm' | 'comments'; workspace_id?: string });
+  const parts = ['Inbox sync completed.'];
+  const keys = Object.keys(result.results || {});
+  if (keys.length > 0) parts.push(`Synced: ${keys.join(', ')}.`);
+  return parts.join(' ');
+}

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

@@ -0,0 +1,147 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdSection } from '../lib/format.js';
+import { omitKeys, previewThenConfirm, readFailedNote, readForPreview, validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+const CATEGORIES = [
+  'COVER',
+  'PROFILE',
+  'LOGO',
+  'EXTERIOR',
+  'INTERIOR',
+  'PRODUCT',
+  'AT_WORK',
+  'FOOD_AND_DRINK',
+  'MENU',
+  'COMMON_AREA',
+  'ROOMS',
+  'TEAMS',
+  'ADDITIONAL',
+] as const;
+
+const LOCATION_ID_DESCRIPTION = 'Google Business numeric location id (the location_id/platform_user_id from list_accounts, e.g. "197940849675145390"). NOT the ChIJ... Place ID from list_google_business_reviews view=review_link. Prefer account_id.';
+const LEGACY_LOCATION = {
+  workspace_id: z.string().optional(),
+  account_id: z.number().int().positive().optional(),
+  location_id: z.string().optional(),
+};
+
+type ManageMediaInput = {
+  action: 'add' | 'delete';
+  workspace_id?: string;
+  account_id?: number;
+  location_id?: string;
+  source_url?: string;
+  category?: (typeof CATEGORIES)[number];
+  media_format?: 'PHOTO' | 'VIDEO';
+  media_name?: string;
+  confirm?: boolean;
+  preview_id?: string;
+};
+
+function payloadOf(input: ManageMediaInput): Record<string, any> {
+  return omitKeys(input, ['action', 'confirm', 'preview_id']);
+}
+
+function locationRows(input: ManageMediaInput): Array<[string, string | undefined]> {
+  return [
+    ['Account ID', input.account_id !== undefined ? code(input.account_id) : undefined],
+    ['Location ID', input.location_id ? code(input.location_id) : undefined],
+    ['Workspace', input.workspace_id ? code(input.workspace_id) : undefined],
+  ];
+}
+
+export const manageGoogleBusinessMediaTool = {
+  name: 'manage_google_business_media',
+  description:
+    'Change a Google Business Profile gallery (the photos and videos shown on Maps and Search). action=add (source_url, category): add a photo or video from a public https URL (upload it with upload_media first); COVER and PROFILE are single-slot and replace the existing one. action=delete (media_name from list_google_business_media): permanently remove an item from the public profile. Both use preview then confirm: call without confirm to get a preview and preview_id, show it, then call again with confirm=true and that preview_id.',
+  inputSchema: z.object({
+    action: z.enum(['add', 'delete']).describe('add or delete.'),
+    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(LOCATION_ID_DESCRIPTION),
+    source_url: z.string().url().optional().describe('add: public https URL of the photo or video (from upload_media).'),
+    category: z.enum(CATEGORIES).optional().describe('add: which gallery category to add the media to.'),
+    media_format: z.enum(['PHOTO', 'VIDEO']).optional().describe('add: defaults to PHOTO. Use VIDEO for videos (Google caps profile videos at 30s / 75MB).'),
+    media_name: z.string().min(1).optional().describe('delete: full media resource name from list_google_business_media (accounts/.../locations/.../media/...).'),
+    confirm: z.boolean().optional().describe('Leave out to get a preview; true only with the preview_id after the user approved it.'),
+    preview_id: z.string().optional().describe('The preview_id from the preview call. Required with confirm: true.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    add_google_business_media: z.object({
+      ...LEGACY_LOCATION,
+      source_url: z.string().url(),
+      category: z.enum(CATEGORIES),
+      media_format: z.enum(['PHOTO', 'VIDEO']).optional(),
+      confirm: z.literal(true),
+    }),
+    delete_google_business_media: z.object({
+      ...LEGACY_LOCATION,
+      media_name: z.string().min(1),
+      confirm: z.literal(true),
+    }),
+  },
+
+  async execute(client: PosterlyClient, input: ManageMediaInput, ctx: ToolContext) {
+    const { mode, args } = validateArgs(ctx, 'manage_google_business_media', input);
+    const call = args as ManageMediaInput;
+    if (mode === 'delete') {
+      return previewThenConfirm({
+        tool: 'manage_google_business_media',
+        action: 'delete',
+        args,
+        nonce: false,
+        legacyRefusal: 'Refusing to delete Google Business media without confirm=true after explicit user confirmation.',
+        ctx,
+        describe: async () => {
+          const read = await readForPreview(() => client.listGoogleBusinessMedia({
+            workspace_id: call.workspace_id,
+            account_id: call.account_id,
+            location_id: call.location_id,
+          }));
+          const item = read.ok ? (read.data.media || []).find((media) => media?.name === call.media_name) : null;
+          const details = item
+            ? mdSection('Media', mdKeyValue([
+                ['Resource name', code(String(item.name))],
+                ['Type', item.mediaFormat === 'VIDEO' ? 'video' : 'photo'],
+                ['Category', item.category || 'uncategorised'],
+                ...locationRows(call),
+              ]))
+            : [
+                read.ok ? '_This item was not found in the current gallery listing, so the preview shows the request as given._' : readFailedNote(read.error),
+                mdKeyValue([['Resource name', code(String(call.media_name))], ...locationRows(call)]),
+              ].join('\n\n');
+          return [details, 'This permanently removes the item from the public Google Business profile.'].join('\n\n');
+        },
+        run: async () => {
+          const result = await client.deleteGoogleBusinessMedia(payloadOf(call) as { media_name: string });
+          return result.message || 'Media removed from the Google Business profile.';
+        },
+      });
+    }
+    return previewThenConfirm({
+      tool: 'manage_google_business_media',
+      action: 'add',
+      args,
+      nonce: true,
+      legacyRefusal: 'Refusing to add Google Business media without confirm=true after explicit user confirmation.',
+      ctx,
+      describe: async () => [
+        mdSection('Media to add', mdKeyValue([
+          ['Source URL', call.source_url],
+          ['Category', call.category],
+          ['Format', call.media_format || 'PHOTO'],
+          ...locationRows(call),
+        ])),
+        call.category === 'COVER' || call.category === 'PROFILE'
+          ? `This adds the item publicly to the Google Business profile and replaces the current ${String(call.category).toLowerCase()} image.`
+          : 'This adds the item publicly to the Google Business profile gallery on Maps and Search.',
+      ].join('\n\n'),
+      run: async () => {
+        const result = await client.addGoogleBusinessMedia(payloadOf(call) as { source_url: string; category: string });
+        return result.message || 'Media added to the Google Business profile.';
+      },
+    });
+  },
+};