posterly-mcp-server 0.19.1 → 0.19.2

package/src/tools/list-brands.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdEmpty, mdTable, mdTitle } from '../lib/format.js';
 
 export const listBrandsTool = {
   name: 'list_brands',
@@ -17,20 +18,22 @@ export const listBrandsTool = {
 
     if (brands.length === 0) {
       return input.workspace_id
-        ? 'No brands found in this workspace.'
-        : 'No brands found. Create brands in the posterly dashboard first.';
+        ? mdEmpty('brands', 'This workspace does not have any brands or clients yet.')
+        : mdEmpty('brands', 'No brands or clients were found for this API key.', 'Create a brand in the Posterly dashboard, then run this again.');
     }
 
-    const lines = brands.map((brand) => {
-      const suffix = [
-        `ID: ${brand.id}`,
-        brand.workspace_id ? `ws: ${brand.workspace_id}` : null,
-        `accounts: ${brand.account_count}`,
-        brand.source,
-      ].filter(Boolean).join(', ');
-      return `• ${brand.name} (${suffix})`;
-    });
-
-    return `Brands (${brands.length}):\n${lines.join('\n')}`;
+    return [
+      mdTitle(`Brands (${brands.length})`),
+      mdTable(
+        ['Brand', 'Brand ID', 'Accounts', 'Source', 'Workspace'],
+        brands.map((brand) => [
+          brand.name,
+          code(brand.id),
+          brand.account_count,
+          brand.source,
+          brand.workspace_id ? code(brand.workspace_id) : 'default',
+        ]),
+      ),
+    ].join('\n\n');
   },
 };

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { compactText, formatDateTime, mdEmpty, mdTable, mdTitle, statusLabel } from '../lib/format.js';
 
 export const listGoogleBusinessReviewsTool = {
   name: 'list_google_business_reviews',
@@ -25,19 +26,22 @@ export const listGoogleBusinessReviewsTool = {
   ) {
     const result = await client.listGoogleBusinessReviews(input);
     if (result.reviews.length === 0) {
-      return 'No Google Business reviews found matching your filters.';
+      return mdEmpty('Google Business reviews', 'No reviews matched those filters.');
     }
 
-    const lines = [`Google Business reviews (${result.reviews.length} of ${result.total}):`];
-    for (const review of result.reviews.slice(0, 25)) {
-      const name = review.reviewer?.displayName || 'Anonymous';
-      const rating = review.starRating ? `${review.starRating} stars` : 'unrated';
-      const location = review.businessName || review.locationName || review.locationId || 'location';
-      const text = review.comment ? ` - ${review.comment.replace(/\s+/g, ' ').slice(0, 180)}` : '';
-      const replied = review.reviewReply ? ' replied' : ' unanswered';
-      lines.push(`- ${name} (${rating}, ${location},${replied})${text}`);
-    }
-
-    return lines.join('\n');
+    return [
+      mdTitle(`Google Business reviews (${result.reviews.length} of ${result.total})`),
+      mdTable(
+        ['Reviewer', 'Rating', 'Location', 'Reply', 'Updated', 'Comment'],
+        result.reviews.slice(0, 25).map((review) => [
+          review.reviewer?.displayName || 'Anonymous',
+          review.starRating ? `${review.starRating} stars` : 'unrated',
+          review.businessName || review.locationName || review.locationId || 'location',
+          statusLabel(review.reviewReply ? 'replied' : 'unanswered'),
+          formatDateTime(review.updateTime || review.createTime),
+          compactText(review.comment, 140) || '(rating only)',
+        ]),
+      ),
+    ].join('\n\n');
   },
 };

package/src/tools/list-oauth-clients.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdEmpty, mdTable, mdTitle, statusLabel } from '../lib/format.js';
 
 export const listOAuthClientsTool = {
   name: 'list_oauth_clients',
@@ -9,10 +10,18 @@ export const listOAuthClientsTool = {
 
   async execute(client: PosterlyClient) {
     const result = await client.listOAuthClients();
-    if (result.clients.length === 0) return 'No OAuth developer clients found.';
+    if (result.clients.length === 0) return mdEmpty('OAuth developer clients', 'No OAuth developer clients were found.');
     return [
-      `OAuth developer clients (${result.clients.length}):`,
-      ...result.clients.map((item) => `- ${item.client_name} (${item.client_id}) scopes=${item.default_scopes.join(', ')} active=${item.is_active}`),
-    ].join('\n');
+      mdTitle(`OAuth developer clients (${result.clients.length})`),
+      mdTable(
+        ['Client', 'Client ID', 'Scopes', 'State'],
+        result.clients.map((item) => [
+          item.client_name,
+          code(item.client_id),
+          item.default_scopes.join(', '),
+          statusLabel(item.is_active ? 'active' : 'inactive'),
+        ]),
+      ),
+    ].join('\n\n');
   },
 };

package/src/tools/list-platforms.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { PLANNED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+import { code, mdTable, mdTitle, statusLabel } from '../lib/format.js';
 
 export const listPlatformsTool = {
   name: 'list_platforms',
@@ -15,11 +16,20 @@ export const listPlatformsTool = {
 
   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')}`;
+    return [
+      mdTitle(`Posterly platforms (${result.platforms.length})`),
+      mdTable(
+        ['Platform', 'ID', 'Status', 'Post types', 'Helpers', 'Analytics'],
+        result.platforms.map((platform) => [
+          platform.label,
+          code(platform.id),
+          statusLabel(platform.status),
+          platform.post_types.join(', ') || 'n/a',
+          platform.helper_tools?.length || 0,
+          platform.analytics_supported,
+        ]),
+      ),
+    ].join('\n\n');
   },
 };

package/src/tools/list-posts.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+import { code, compactText, formatDateTime, mdEmpty, mdTable, mdTitle, statusLabel } from '../lib/format.js';
 
 export const listPostsTool = {
   name: 'list_posts',
@@ -47,16 +48,21 @@ export const listPostsTool = {
     });
 
     if (posts.length === 0) {
-      return 'No posts found matching your criteria.';
+      return mdEmpty('posts', 'No posts matched those filters.');
     }
 
-    const lines = posts.map((p) => {
-      const date = new Date(p.scheduled_at).toLocaleString();
-      const caption =
-        p.content.length > 60 ? p.content.slice(0, 60) + '…' : p.content;
-      return `• [${p.status}] #${p.id} — ${caption} (${date})`;
-    });
-
-    return `Posts (${posts.length} of ${total}):\n${lines.join('\n')}`;
+    return [
+      mdTitle(`Posts (${posts.length} of ${total})`),
+      mdTable(
+        ['Status', 'Post ID', 'Caption', 'Scheduled', 'Type'],
+        posts.map((post) => [
+          statusLabel(post.status),
+          code(post.id),
+          compactText(post.content, 80) || '(empty)',
+          formatDateTime(post.scheduled_at),
+          post.post_type || 'post',
+        ]),
+      ),
+    ].join('\n\n');
   },
 };

package/src/tools/list-webhooks.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, compactText, formatDateTime, mdEmpty, mdTable, mdTitle, statusLabel } from '../lib/format.js';
 
 export const listWebhooksTool = {
   name: 'list_webhooks',
@@ -12,19 +13,22 @@ export const listWebhooksTool = {
   async execute(client: PosterlyClient, input: { workspace_id?: string }) {
     const { webhooks } = await client.listWebhooks(input);
     if (webhooks.length === 0) {
-      return 'No webhooks found.';
+      return mdEmpty('webhooks', 'No webhook subscriptions were found.');
     }
 
-    const lines = [`Webhooks (${webhooks.length}):`];
-    for (const webhook of webhooks) {
-      const active = webhook.is_active ? 'active' : 'inactive';
-      const events = webhook.events?.length ? webhook.events.join(', ') : 'default events';
-      const last = webhook.last_delivery_at
-        ? ` last ${webhook.last_delivery_status || 'n/a'} at ${new Date(webhook.last_delivery_at).toLocaleString()}`
-        : '';
-      lines.push(`- ${webhook.id} [${active}] ${webhook.url} (${events})${last}`);
-    }
-    return lines.join('\n');
+    return [
+      mdTitle(`Webhooks (${webhooks.length})`),
+      mdTable(
+        ['Webhook ID', 'State', 'URL', 'Events', 'Last delivery', 'Last error'],
+        webhooks.map((webhook) => [
+          code(webhook.id),
+          statusLabel(webhook.is_active ? 'active' : 'inactive'),
+          webhook.url,
+          webhook.events?.length ? webhook.events.join(', ') : 'default events',
+          webhook.last_delivery_at ? `${webhook.last_delivery_status || 'n/a'} at ${formatDateTime(webhook.last_delivery_at)}` : 'n/a',
+          compactText(webhook.last_error, 80) || 'n/a',
+        ]),
+      ),
+    ].join('\n\n');
   },
 };
-

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdSuccess } from '../lib/format.js';
 
 export const replyGoogleBusinessReviewTool = {
   name: 'reply_google_business_review',
@@ -27,6 +28,8 @@ export const replyGoogleBusinessReviewTool = {
   ) {
     const { confirm: _confirm, ...payload } = input;
     const result = await client.replyGoogleBusinessReview(payload);
-    return result.message || 'Google Business review reply posted successfully.';
+    return mdSuccess('Google Business review reply posted', [
+      ['Message', result.message || 'Google Business review reply posted successfully.'],
+    ]);
   },
 };

package/src/tools/run-video-function.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdJson, mdTitle } from '../lib/format.js';
 
 export const runVideoFunctionTool = {
   name: 'run_video_function',
@@ -24,9 +25,8 @@ export const runVideoFunctionTool = {
   ) {
     const result = await client.runVideoFunction(input);
     return [
-      `Video function ${input.functionName} completed`,
-      '',
-      JSON.stringify(result, null, 2),
-    ].join('\n');
+      mdTitle(`Video function ${code(input.functionName)} completed`),
+      mdJson('Result', result),
+    ].join('\n\n');
   },
 };

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdEmpty, mdQuote, mdSection, mdTitle } from '../lib/format.js';
 
 export const suggestGoogleBusinessReviewReplyTool = {
   name: 'suggest_google_business_review_reply',
@@ -34,11 +35,11 @@ export const suggestGoogleBusinessReviewReplyTool = {
     const result = await client.suggestGoogleBusinessReviewReply(input);
     const suggestions = Array.isArray(result.suggestions) ? result.suggestions : [];
     if (suggestions.length === 0) {
-      return 'No reply suggestions were generated.';
+      return mdEmpty('reply suggestions', 'No Google Business reply suggestions were generated.');
     }
     return [
-      `Suggested replies (${result.tone || 'professional'}, ${result.rating || input.star_rating} stars):`,
-      ...suggestions.map((text: string, index: number) => `${index + 1}. ${text}`),
-    ].join('\n');
+      mdTitle(`Suggested replies`, `${result.tone || 'professional'} tone · ${result.rating || input.star_rating} stars`),
+      ...suggestions.map((text: string, index: number) => mdSection(`Option ${index + 1}`, mdQuote(text))),
+    ].join('\n\n');
   },
 };

package/src/tools/test-webhook.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdJson, mdSuccess } from '../lib/format.js';
 
 export const testWebhookTool = {
   name: 'test_webhook',
@@ -13,6 +14,11 @@ export const testWebhookTool = {
   async execute(client: PosterlyClient, input: { webhook_id: string; confirm: true }) {
     const result = await client.testWebhook(input.webhook_id);
     const delivery = result.delivery || {};
-    return `Webhook test sent.\nDelivery: ${JSON.stringify(delivery, null, 2)}`;
+    return [
+      mdSuccess('Webhook test sent', [
+        ['Webhook ID', input.webhook_id],
+      ]),
+      mdJson('Delivery', delivery),
+    ].join('\n\n');
   },
 };

package/src/tools/trigger-platform-helper.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { PLATFORM_HELPER_NAMES, SUPPORTED_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
+import { code, mdJson, mdTitle } from '../lib/format.js';
 
 export const triggerPlatformHelperTool = {
   name: 'trigger_platform_helper',
@@ -29,6 +30,9 @@ export const triggerPlatformHelperTool = {
     },
   ) {
     const result = await client.triggerPlatformHelper(input);
-    return JSON.stringify(result, null, 2);
+    return [
+      mdTitle(`Platform helper ${code(input.helper)} completed`),
+      mdJson('Result', result),
+    ].join('\n\n');
   },
 };

package/src/tools/update-oauth-client.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdSuccess, statusLabel } from '../lib/format.js';
 
 const scopeSchema = z.enum(['accounts:read', 'accounts:write', 'posts:read', 'posts:write', 'media:write', 'analytics:read']);
 
@@ -30,9 +31,15 @@ export const updateOAuthClientTool = {
       is_active?: boolean;
       confirm: true;
     },
-  ) {
+    ) {
     const { client_id, confirm: _confirm, ...payload } = input;
     const result = await client.updateOAuthClient(client_id, payload);
-    return `OAuth client updated: ${result.client.client_name} (${result.client.client_id}) active=${result.client.is_active}`;
+    return mdSuccess('OAuth client updated', [
+      ['Client', result.client.client_name],
+      ['Client ID', code(result.client.client_id)],
+      ['State', statusLabel(result.client.is_active ? 'active' : 'inactive')],
+      ['Redirect URIs', result.client.allowed_redirect_uris.join(', ')],
+      ['Default scopes', result.client.default_scopes.join(', ')],
+    ]);
   },
 };

package/src/tools/update-post-release-id.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdJson, mdTitle } from '../lib/format.js';
 
 export const updatePostReleaseIdTool = {
   name: 'update_post_release_id',
@@ -20,7 +21,9 @@ export const updatePostReleaseIdTool = {
       release_id: input.release_id,
       group_id: input.group_id,
     });
-    return JSON.stringify(result, null, 2);
+    return [
+      mdTitle(`✅ Release ID updated for post ${code(input.post_id)}`),
+      mdJson('Result', result),
+    ].join('\n\n');
   },
 };
-

package/src/tools/update-post-status.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdSuccess, statusLabel } from '../lib/format.js';
 
 export const updatePostStatusTool = {
   name: 'update_post_status',
@@ -26,6 +27,11 @@ export const updatePostStatusTool = {
       scheduled_at: input.scheduled_at,
     });
     const transition = result.transition || {};
-    return `Post #${input.post_id} status changed from ${transition.old_status || 'unknown'} to ${transition.new_status || input.status}.`;
+    return mdSuccess('Post status updated', [
+      ['Post ID', code(input.post_id)],
+      ['From', statusLabel(transition.old_status || 'unknown')],
+      ['To', statusLabel(transition.new_status || input.status)],
+      ['Scheduled', input.scheduled_at || undefined],
+    ]);
   },
 };

package/src/tools/update-post.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, formatDateTime, mdKeyValue, mdQuote, mdSection, mdTitle, statusLabel } from '../lib/format.js';
 
 const instagramSettingsSchema = z.object({
   __type: z.enum(['instagram', 'instagram-standalone']).optional(),
@@ -108,10 +109,14 @@ export const updatePostTool = {
     const result = await client.updatePost(post_id, payload);
     const p = result.post as Record<string, any>;
 
-    const when = p.scheduled_at
-      ? new Date(p.scheduled_at).toLocaleString()
-      : 'N/A';
-
-    return `Post #${p.id} updated successfully!\n• Status: ${p.status}\n• Caption: ${p.content || '(empty)'}\n• Scheduled: ${when}`;
+    return [
+      mdTitle(`✅ Post ${code(p.id)} updated`),
+      mdKeyValue([
+        ['Status', statusLabel(p.status)],
+        ['Scheduled', formatDateTime(p.scheduled_at)],
+        ['Type', p.post_type || 'unknown'],
+      ]),
+      mdSection('Caption', p.content ? mdQuote(p.content) : '_(empty)_'),
+    ].join('\n\n');
   },
 };

package/src/tools/update-webhook.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
 import { webhookEventSchema } from './webhook-events.js';
+import { code, mdSuccess, statusLabel } from '../lib/format.js';
 
 export const updateWebhookTool = {
   name: 'update_webhook',
@@ -31,7 +32,11 @@ export const updateWebhookTool = {
     const { webhook_id, confirm: _confirm, ...payload } = input;
     const result = await client.updateWebhook(webhook_id, payload);
     const active = result.webhook.is_active ? 'active' : 'inactive';
-    return `Webhook updated: ${result.webhook.id}\nURL: ${result.webhook.url}\nState: ${active}\nEvents: ${result.webhook.events.join(', ')}`;
+    return mdSuccess('Webhook updated', [
+      ['Webhook ID', code(result.webhook.id)],
+      ['URL', result.webhook.url],
+      ['State', statusLabel(active)],
+      ['Events', result.webhook.events.join(', ')],
+    ]);
   },
 };
-

package/src/tools/upload-media-from-url.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { formatBytes, mdSuccess } from '../lib/format.js';
 
 export const uploadMediaFromUrlTool = {
   name: 'upload_media_from_url',
@@ -20,14 +21,11 @@ export const uploadMediaFromUrlTool = {
       filename: input.filename,
       contentType: input.content_type,
     });
-    return [
-      'Remote media uploaded successfully.',
-      `• URL: ${result.url}`,
-      `• Source URL: ${result.source_url}`,
-      `• Content type: ${result.content_type}`,
-      `• Size: ${result.size} bytes`,
-      '',
-      'Use this URL as media_url when creating a post.',
-    ].join('\n');
+    return mdSuccess('Remote media uploaded', [
+      ['URL', result.url],
+      ['Source URL', result.source_url],
+      ['Content type', result.content_type],
+      ['Size', formatBytes(result.size)],
+    ], 'Use this URL as `media_url` when creating a post.');
   },
 };

package/src/tools/upload-media.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { mdError, mdSuccess } from '../lib/format.js';
 
 export const uploadMediaTool = {
   name: 'upload_media',
@@ -35,7 +36,7 @@ export const uploadMediaTool = {
     }
   ) {
     if (!input.file_path && !input.base64_data) {
-      return 'Error: Provide either file_path or base64_data.';
+      return mdError('Provide either `file_path` or `base64_data`.');
     }
 
     const result = await client.uploadMedia({
@@ -45,6 +46,9 @@ export const uploadMediaTool = {
       contentType: input.content_type,
     });
 
-    return `Media uploaded successfully!\n• URL: ${result.url}\n\nUse this URL as media_url when creating a post.`;
+    return mdSuccess('Media uploaded', [
+      ['URL', result.url],
+      ['Storage path', result.path],
+    ], 'Use this URL as `media_url` when creating a post.');
   },
 };

package/src/tools/whoami.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+import { code, mdKeyValue, mdTable, mdTitle } from '../lib/format.js';
 
 export const whoamiTool = {
   name: 'whoami',
@@ -10,28 +11,25 @@ export const whoamiTool = {
   async execute(client: PosterlyClient) {
     const info = await client.whoami();
 
-    const lines: string[] = [];
-    lines.push(`User: ${info.user.email || info.user.id}`);
-    lines.push(`API scopes: ${info.api_key.scopes.join(', ') || 'none'}`);
-    lines.push('');
-    lines.push(
-      `Default workspace: ${info.default_workspace.name} (${info.default_workspace.id})` +
-        (info.default_workspace.timezone ? ` — tz: ${info.default_workspace.timezone}` : '')
-    );
-    lines.push('');
-    lines.push(`All workspaces (${info.workspaces.length}):`);
-    for (const ws of info.workspaces) {
-      const marker = ws.id === info.default_workspace.id ? ' [default]' : '';
-      const personal = ws.is_personal ? ' [personal]' : '';
-      const tz = ws.timezone ? ` — tz: ${ws.timezone}` : '';
-      lines.push(`• ${ws.name} — ${ws.id} (role: ${ws.role || 'member'})${personal}${marker}${tz}`);
-    }
-
-    lines.push('');
-    lines.push(
-      'Tip: pass workspace_id to create_post / list_posts / list_accounts / find_available_slot to scope actions to a specific workspace. Omit it to use the default.'
-    );
-
-    return lines.join('\n');
+    return [
+      mdTitle('Posterly identity'),
+      mdKeyValue([
+        ['User', info.user.email || code(info.user.id)],
+        ['API scopes', info.api_key.scopes.join(', ') || 'none'],
+        ['Default workspace', `${info.default_workspace.name} (${code(info.default_workspace.id)})`],
+        ['Default timezone', info.default_workspace.timezone || 'n/a'],
+      ]),
+      mdTable(
+        ['Workspace', 'Workspace ID', 'Role', 'Timezone', 'Default'],
+        info.workspaces.map((workspace) => [
+          `${workspace.name}${workspace.is_personal ? ' (personal)' : ''}`,
+          code(workspace.id),
+          workspace.role || 'member',
+          workspace.timezone || 'n/a',
+          workspace.id === info.default_workspace.id,
+        ]),
+      ),
+      '**Tip:** Pass `workspace_id` to `create_post`, `list_posts`, `list_accounts`, and `find_available_slot` when you want the assistant to stay inside one workspace.',
+    ].join('\n\n');
   },
 };