posterly-mcp-server 0.3.0 → 0.4.0

package/dist/index.js

@@ -11,9 +11,10 @@ import { getPostTool } from './tools/get-post.js';
 import { updatePostTool } from './tools/update-post.js';
 import { deletePostTool } from './tools/delete-post.js';
 import { whoamiTool } from './tools/whoami.js';
+import { generateImageTool } from './tools/generate-image.js';
 const server = new McpServer({
     name: 'posterly',
-    version: '0.3.0',
+    version: '0.4.0',
 });
 let client;
 try {
@@ -78,6 +79,15 @@ server.tool(uploadMediaTool.name, uploadMediaTool.description, uploadMediaTool.i
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(generateImageTool.name, generateImageTool.description, generateImageTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await generateImageTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(getPostTool.name, getPostTool.description, getPostTool.inputSchema.shape, async (input) => {
     try {
         const text = await getPostTool.execute(client, input);

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

@@ -99,6 +99,31 @@ export declare class PosterlyClient {
         deleted: boolean;
         id: number;
     }>;
+    generateImage(data: {
+        prompt: string;
+        aspect_ratio?: string;
+        style?: string;
+        variations?: number;
+        model?: 'flash' | 'pro';
+        resolution?: '512' | '1K' | '2K' | '4K';
+    }): Promise<{
+        urls: string[];
+        images: Array<{
+            url: string;
+            filename: string;
+            path: string;
+        }>;
+        model: string;
+        credits_used: number;
+        warnings?: string[];
+        usage: {
+            used: number | null;
+            limit: number | null;
+            period: string | null;
+            tier: string | null;
+            billed_from: 'plan_quota' | 'credits';
+        };
+    }>;
     findAvailableSlots(params?: {
         account_ids?: string[];
         timezone?: string;

package/dist/lib/api-client.js

@@ -68,6 +68,9 @@ export class PosterlyClient {
     async deletePost(id) {
         return this.request('DELETE', `/posts/${id}`);
     }
+    async generateImage(data) {
+        return this.request('POST', '/ai/generate-image', data);
+    }
     async findAvailableSlots(params) {
         const searchParams = new URLSearchParams();
         if (params?.account_ids?.length)

package/dist/tools/create-post.js

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 export const createPostTool = {
     name: 'create_post',
-    description: 'Schedule or immediately publish a social media post. Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. IMPORTANT: posts belong to a workspace. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace. Call `whoami` first in any new session to confirm which workspace posts will land in, and pass workspace_id explicitly if the user has more than one workspace.',
+    description: 'Schedule or immediately publish a social media post. This is a DESTRUCTIVE WRITE that creates content on the user\'s real social accounts — once scheduled_at passes, it will be posted publicly and cannot be un-posted.\n\n' +
+        'REQUIRED BEFORE CALLING:\n' +
+        '1. Call `whoami` at the start of any new session to confirm which workspace and user you are acting for.\n' +
+        '2. Show the user a preview containing ALL of: account(s) and platform(s), final caption text, scheduled time (in the user\'s timezone), media attached (if any), and workspace name.\n' +
+        '3. Get explicit confirmation from the user (e.g. "post it", "yes schedule that", "looks good") BEFORE calling this tool. Do NOT infer consent from earlier instructions like "post about X every Monday" — confirm each individual post or the entire batch.\n' +
+        '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole before calling create_post repeatedly.\n\n' +
+        'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.',
     inputSchema: z.object({
         account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
         username: z.string().optional().describe('Account username (alternative to account_id)'),

package/dist/tools/delete-post.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 export const deletePostTool = {
     name: 'delete_post',
-    description: 'Delete a scheduled or draft post. Cannot delete published or currently publishing posts.',
+    description: 'Delete a scheduled or draft post. DESTRUCTIVE and IRREVERSIBLE — the post and its caption cannot be recovered. Cannot delete published or currently publishing posts.\n\n' +
+        'REQUIRED BEFORE CALLING: Fetch the post with `get_post` first and show the user what will be deleted (caption, account, scheduled time). Get explicit confirmation ("yes delete it", "remove it") before calling. Never delete multiple posts in a single batch without listing each one and confirming the full list.',
     inputSchema: z.object({
         post_id: z.number().describe('The post ID to delete'),
     }),

package/dist/tools/generate-image.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const generateImageTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        prompt: z.ZodString;
+        aspect_ratio: z.ZodOptional<z.ZodEnum<["1:1", "9:16", "4:5", "3:4", "2:3", "1:4", "1:8", "21:9", "16:9", "4:3", "3:2", "4:1", "8:1", "5:4"]>>;
+        style: z.ZodOptional<z.ZodEnum<["photographic", "illustration", "minimal", "vibrant", "professional", "youtube_thumbnail", "reel_cover", "review_background"]>>;
+        variations: z.ZodOptional<z.ZodNumber>;
+        model: z.ZodOptional<z.ZodEnum<["flash", "pro"]>>;
+        resolution: z.ZodOptional<z.ZodEnum<["512", "1K", "2K", "4K"]>>;
+    }, "strip", z.ZodTypeAny, {
+        prompt: string;
+        aspect_ratio?: "1:1" | "9:16" | "4:5" | "3:4" | "2:3" | "1:4" | "1:8" | "21:9" | "16:9" | "4:3" | "3:2" | "4:1" | "8:1" | "5:4" | undefined;
+        style?: "photographic" | "illustration" | "minimal" | "vibrant" | "professional" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
+        variations?: number | undefined;
+        model?: "flash" | "pro" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+    }, {
+        prompt: string;
+        aspect_ratio?: "1:1" | "9:16" | "4:5" | "3:4" | "2:3" | "1:4" | "1:8" | "21:9" | "16:9" | "4:3" | "3:2" | "4:1" | "8:1" | "5:4" | undefined;
+        style?: "photographic" | "illustration" | "minimal" | "vibrant" | "professional" | "youtube_thumbnail" | "reel_cover" | "review_background" | undefined;
+        variations?: number | undefined;
+        model?: "flash" | "pro" | undefined;
+        resolution?: "512" | "1K" | "2K" | "4K" | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        prompt: string;
+        aspect_ratio?: string;
+        style?: string;
+        variations?: number;
+        model?: "flash" | "pro";
+        resolution?: "512" | "1K" | "2K" | "4K";
+    }): Promise<string>;
+};

package/dist/tools/generate-image.js

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+export const generateImageTool = {
+    name: 'generate_image',
+    description: 'Generate an AI image via Posterly\'s Nano Banana (Gemini) integration. The image is saved to the user\'s media storage and the returned URL can be passed to `create_post` as `media_url`.\n\n' +
+        'COSTS CREDITS. Every call consumes part of the user\'s monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively — always describe the image you\'re about to generate (subject, style, aspect ratio) to the user and get confirmation before calling.\n\n' +
+        'If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim — do not retry.\n\n' +
+        'Common aspect ratios by platform:\n' +
+        '  • Instagram feed / LinkedIn: 1:1 (square) or 4:5 (portrait)\n' +
+        '  • Instagram Story/Reel, TikTok, YouTube Shorts: 9:16\n' +
+        '  • YouTube thumbnail, Twitter cards, landscape feed: 16:9\n' +
+        '  • Pinterest: 2:3',
+    inputSchema: z.object({
+        prompt: z
+            .string()
+            .min(5)
+            .max(4000)
+            .describe('Detailed image description. 5–4000 characters. Describe subject, scene, lighting, mood, and style.'),
+        aspect_ratio: z
+            .enum([
+            '1:1', '9:16', '4:5', '3:4', '2:3', '1:4', '1:8',
+            '21:9', '16:9', '4:3', '3:2', '4:1', '8:1', '5:4',
+        ])
+            .optional()
+            .describe('Aspect ratio. Default 1:1. Pick based on target platform (see tool description).'),
+        style: z
+            .enum([
+            'photographic', 'illustration', 'minimal', 'vibrant', 'professional',
+            'youtube_thumbnail', 'reel_cover', 'review_background',
+        ])
+            .optional()
+            .describe('Preset style. Default photographic. Use youtube_thumbnail / reel_cover for platform-optimized covers; review_background for testimonial backgrounds.'),
+        variations: z
+            .number()
+            .int()
+            .min(1)
+            .max(4)
+            .optional()
+            .describe('How many variations to generate. Default 1. Each variation costs credits separately — prefer 1 unless the user explicitly wants options.'),
+        model: z
+            .enum(['flash', 'pro'])
+            .optional()
+            .describe('flash (default, 1 credit per 1K image) is fast and cost-effective. pro (2 credits per 1K) is higher quality for hero imagery. Start with flash unless quality is critical.'),
+        resolution: z
+            .enum(['512', '1K', '2K', '4K'])
+            .optional()
+            .describe('Output resolution. Default 1K. Higher resolutions cost more credits. 512 is flash-only.'),
+    }),
+    async execute(client, input) {
+        const result = await client.generateImage(input);
+        const lines = [];
+        lines.push(`Generated ${result.images.length} image${result.images.length === 1 ? '' : 's'} via ${result.model}.`);
+        lines.push('');
+        result.images.forEach((img, i) => {
+            lines.push(`${i + 1}. ${img.url}`);
+        });
+        lines.push('');
+        lines.push(`Billed from: ${result.usage.billed_from}${result.credits_used > 0 ? ` (${result.credits_used} credits)` : ''}`);
+        if (result.usage.limit != null) {
+            lines.push(`Plan usage: ${result.usage.used ?? 0}/${result.usage.limit} this ${result.usage.period || 'period'}${result.usage.tier ? ` (${result.usage.tier})` : ''}`);
+        }
+        if (result.warnings?.length) {
+            lines.push('');
+            lines.push('Warnings:');
+            result.warnings.forEach((w) => lines.push(`• ${w}`));
+        }
+        lines.push('');
+        lines.push('Pass any of these URLs to create_post as media_url (or media_urls for a carousel).');
+        return lines.join('\n');
+    },
+};

package/dist/tools/update-post.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 export const updatePostTool = {
     name: 'update_post',
-    description: 'Update a scheduled or draft post. Can change caption, scheduled time, media, or post type. Cannot edit published or currently publishing posts.',
+    description: 'Update a scheduled or draft post. DESTRUCTIVE WRITE — overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts.\n\n' +
+        'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media) and the PROPOSED changes, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction — each edit needs its own confirmation.',
     inputSchema: z.object({
         post_id: z.number().describe('The post ID to update'),
         caption: z.string().optional().describe('New caption/text content'),

package/dist/tools/upload-media.js

@@ -1,7 +1,9 @@
 import { z } from 'zod';
 export const uploadMediaTool = {
     name: 'upload_media',
-    description: 'Upload an image or video file to posterly. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Images up to 10MB, videos up to 50MB. IMPORTANT: If the user shares an image in the chat, use base64_data (not file_path) since chat-uploaded images are not on the local filesystem. Only use file_path when the user provides an actual local filesystem path.',
+    description: 'Upload an image or video file to posterly storage. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Images up to 10MB, videos up to 50MB.\n\n' +
+        'This writes to the user\'s media storage (counts against quota) but does NOT publish the file anywhere. Uploading is safe — it\'s the subsequent `create_post` call that publishes content, and that tool has its own confirmation requirements.\n\n' +
+        'IMPORTANT: If the user shares an image in the chat, use base64_data (not file_path) since chat-uploaded images are not on the local filesystem. Only use file_path when the user provides an actual local filesystem path — never guess paths.',
     inputSchema: z.object({
         file_path: z
             .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -12,10 +12,11 @@ import { getPostTool } from './tools/get-post.js';
 import { updatePostTool } from './tools/update-post.js';
 import { deletePostTool } from './tools/delete-post.js';
 import { whoamiTool } from './tools/whoami.js';
+import { generateImageTool } from './tools/generate-image.js';
 
 const server = new McpServer({
   name: 'posterly',
-  version: '0.3.0',
+  version: '0.4.0',
 });
 
 let client: PosterlyClient;
@@ -112,6 +113,20 @@ server.tool(
   }
 );
 
+server.tool(
+  generateImageTool.name,
+  generateImageTool.description,
+  generateImageTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await generateImageTool.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(
   getPostTool.name,
   getPostTool.description,

package/src/lib/api-client.ts

@@ -157,6 +157,30 @@ export class PosterlyClient {
     return this.request('DELETE', `/posts/${id}`);
   }
 
+  async generateImage(data: {
+    prompt: string;
+    aspect_ratio?: string;
+    style?: string;
+    variations?: number;
+    model?: 'flash' | 'pro';
+    resolution?: '512' | '1K' | '2K' | '4K';
+  }): Promise<{
+    urls: string[];
+    images: Array<{ url: string; filename: string; path: string }>;
+    model: string;
+    credits_used: number;
+    warnings?: string[];
+    usage: {
+      used: number | null;
+      limit: number | null;
+      period: string | null;
+      tier: string | null;
+      billed_from: 'plan_quota' | 'credits';
+    };
+  }> {
+    return this.request('POST', '/ai/generate-image', data);
+  }
+
   async findAvailableSlots(params?: {
     account_ids?: string[];
     timezone?: string;

package/src/tools/create-post.ts

@@ -4,7 +4,13 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const createPostTool = {
   name: 'create_post',
   description:
-    'Schedule or immediately publish a social media post. Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. IMPORTANT: posts belong to a workspace. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace. Call `whoami` first in any new session to confirm which workspace posts will land in, and pass workspace_id explicitly if the user has more than one workspace.',
+    'Schedule or immediately publish a social media post. This is a DESTRUCTIVE WRITE that creates content on the user\'s real social accounts — once scheduled_at passes, it will be posted publicly and cannot be un-posted.\n\n' +
+    'REQUIRED BEFORE CALLING:\n' +
+    '1. Call `whoami` at the start of any new session to confirm which workspace and user you are acting for.\n' +
+    '2. Show the user a preview containing ALL of: account(s) and platform(s), final caption text, scheduled time (in the user\'s timezone), media attached (if any), and workspace name.\n' +
+    '3. Get explicit confirmation from the user (e.g. "post it", "yes schedule that", "looks good") BEFORE calling this tool. Do NOT infer consent from earlier instructions like "post about X every Monday" — confirm each individual post or the entire batch.\n' +
+    '4. If scheduling multiple posts in one turn, list every post first and confirm the batch as a whole before calling create_post repeatedly.\n\n' +
+    'Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately. If workspace_id is omitted, the server resolves one from the social account, falling back to the caller\'s default (personal) workspace — pass workspace_id explicitly if the user has more than one workspace.',
   inputSchema: z.object({
     account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
     username: z.string().optional().describe('Account username (alternative to account_id)'),

package/src/tools/delete-post.ts

@@ -4,7 +4,8 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const deletePostTool = {
   name: 'delete_post',
   description:
-    'Delete a scheduled or draft post. Cannot delete published or currently publishing posts.',
+    'Delete a scheduled or draft post. DESTRUCTIVE and IRREVERSIBLE — the post and its caption cannot be recovered. Cannot delete published or currently publishing posts.\n\n' +
+    'REQUIRED BEFORE CALLING: Fetch the post with `get_post` first and show the user what will be deleted (caption, account, scheduled time). Get explicit confirmation ("yes delete it", "remove it") before calling. Never delete multiple posts in a single batch without listing each one and confirming the full list.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to delete'),
   }),

package/src/tools/generate-image.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const generateImageTool = {
+  name: 'generate_image',
+  description:
+    'Generate an AI image via Posterly\'s Nano Banana (Gemini) integration. The image is saved to the user\'s media storage and the returned URL can be passed to `create_post` as `media_url`.\n\n' +
+    'COSTS CREDITS. Every call consumes part of the user\'s monthly AI image quota (or purchased credits once the quota is exhausted). Do NOT call speculatively — always describe the image you\'re about to generate (subject, style, aspect ratio) to the user and get confirmation before calling.\n\n' +
+    'If the user is over their plan limit and has no credits, this tool returns a 402 with upgrade info. Surface that message verbatim — do not retry.\n\n' +
+    'Common aspect ratios by platform:\n' +
+    '  • Instagram feed / LinkedIn: 1:1 (square) or 4:5 (portrait)\n' +
+    '  • Instagram Story/Reel, TikTok, YouTube Shorts: 9:16\n' +
+    '  • YouTube thumbnail, Twitter cards, landscape feed: 16:9\n' +
+    '  • Pinterest: 2:3',
+  inputSchema: z.object({
+    prompt: z
+      .string()
+      .min(5)
+      .max(4000)
+      .describe('Detailed image description. 5–4000 characters. Describe subject, scene, lighting, mood, and style.'),
+    aspect_ratio: z
+      .enum([
+        '1:1', '9:16', '4:5', '3:4', '2:3', '1:4', '1:8',
+        '21:9', '16:9', '4:3', '3:2', '4:1', '8:1', '5:4',
+      ])
+      .optional()
+      .describe('Aspect ratio. Default 1:1. Pick based on target platform (see tool description).'),
+    style: z
+      .enum([
+        'photographic', 'illustration', 'minimal', 'vibrant', 'professional',
+        'youtube_thumbnail', 'reel_cover', 'review_background',
+      ])
+      .optional()
+      .describe('Preset style. Default photographic. Use youtube_thumbnail / reel_cover for platform-optimized covers; review_background for testimonial backgrounds.'),
+    variations: z
+      .number()
+      .int()
+      .min(1)
+      .max(4)
+      .optional()
+      .describe('How many variations to generate. Default 1. Each variation costs credits separately — prefer 1 unless the user explicitly wants options.'),
+    model: z
+      .enum(['flash', 'pro'])
+      .optional()
+      .describe('flash (default, 1 credit per 1K image) is fast and cost-effective. pro (2 credits per 1K) is higher quality for hero imagery. Start with flash unless quality is critical.'),
+    resolution: z
+      .enum(['512', '1K', '2K', '4K'])
+      .optional()
+      .describe('Output resolution. Default 1K. Higher resolutions cost more credits. 512 is flash-only.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      prompt: string;
+      aspect_ratio?: string;
+      style?: string;
+      variations?: number;
+      model?: 'flash' | 'pro';
+      resolution?: '512' | '1K' | '2K' | '4K';
+    }
+  ) {
+    const result = await client.generateImage(input);
+
+    const lines: string[] = [];
+    lines.push(`Generated ${result.images.length} image${result.images.length === 1 ? '' : 's'} via ${result.model}.`);
+    lines.push('');
+    result.images.forEach((img, i) => {
+      lines.push(`${i + 1}. ${img.url}`);
+    });
+    lines.push('');
+    lines.push(`Billed from: ${result.usage.billed_from}${result.credits_used > 0 ? ` (${result.credits_used} credits)` : ''}`);
+    if (result.usage.limit != null) {
+      lines.push(`Plan usage: ${result.usage.used ?? 0}/${result.usage.limit} this ${result.usage.period || 'period'}${result.usage.tier ? ` (${result.usage.tier})` : ''}`);
+    }
+    if (result.warnings?.length) {
+      lines.push('');
+      lines.push('Warnings:');
+      result.warnings.forEach((w) => lines.push(`• ${w}`));
+    }
+    lines.push('');
+    lines.push('Pass any of these URLs to create_post as media_url (or media_urls for a carousel).');
+
+    return lines.join('\n');
+  },
+};

package/src/tools/update-post.ts

@@ -4,7 +4,8 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const updatePostTool = {
   name: 'update_post',
   description:
-    'Update a scheduled or draft post. Can change caption, scheduled time, media, or post type. Cannot edit published or currently publishing posts.',
+    'Update a scheduled or draft post. DESTRUCTIVE WRITE — overwrites the existing post\'s caption/media/schedule. Cannot edit published or currently publishing posts.\n\n' +
+    'REQUIRED BEFORE CALLING: Show the user a side-by-side of the CURRENT post (caption, scheduled time, media) and the PROPOSED changes, and get explicit confirmation ("yes update it", "apply those changes") before calling. Do not auto-edit posts based on a general instruction — each edit needs its own confirmation.',
   inputSchema: z.object({
     post_id: z.number().describe('The post ID to update'),
     caption: z.string().optional().describe('New caption/text content'),

package/src/tools/upload-media.ts

@@ -4,7 +4,9 @@ import type { PosterlyClient } from '../lib/api-client.js';
 export const uploadMediaTool = {
   name: 'upload_media',
   description:
-    'Upload an image or video file to posterly. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Images up to 10MB, videos up to 50MB. IMPORTANT: If the user shares an image in the chat, use base64_data (not file_path) since chat-uploaded images are not on the local filesystem. Only use file_path when the user provides an actual local filesystem path.',
+    'Upload an image or video file to posterly storage. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Images up to 10MB, videos up to 50MB.\n\n' +
+    'This writes to the user\'s media storage (counts against quota) but does NOT publish the file anywhere. Uploading is safe — it\'s the subsequent `create_post` call that publishes content, and that tool has its own confirmation requirements.\n\n' +
+    'IMPORTANT: If the user shares an image in the chat, use base64_data (not file_path) since chat-uploaded images are not on the local filesystem. Only use file_path when the user provides an actual local filesystem path — never guess paths.',
   inputSchema: z.object({
     file_path: z
       .string()