posterly-mcp-server 0.19.4 → 0.19.5

package/README.md

@@ -93,7 +93,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.19.0` exposes 49 tools:
+`posterly-mcp-server@0.19.5` exposes 49 tools:
 
 - `whoami`
 - `list_accounts`

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

@@ -165,8 +165,10 @@ export interface AccountAnalyticsSummary {
     total_likes?: number | null;
     platform_metrics?: Record<string, number | null | undefined>;
     display_metrics?: Array<{
+        key?: string;
         label: string;
         value: number | null | undefined;
+        unit?: string;
     }>;
 }
 export interface AccountAnalyticsSnapshot {

package/dist/tools/get-account-analytics.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+declare const presentationSchema: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
+type AnalyticsPresentation = z.infer<typeof presentationSchema>;
 export declare const getAccountAnalyticsTool: {
     name: string;
     description: string;
@@ -7,18 +9,23 @@ export declare const getAccountAnalyticsTool: {
         account_id: z.ZodNumber;
         from: z.ZodOptional<z.ZodString>;
         to: z.ZodOptional<z.ZodString>;
+        presentation: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
     }, "strip", z.ZodTypeAny, {
         account_id: number;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }, {
         account_id: number;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         account_id: number;
         from?: string;
         to?: string;
+        presentation?: AnalyticsPresentation;
     }): Promise<string>;
 };
+export {};

package/dist/tools/get-account-analytics.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
 export const getAccountAnalyticsTool = {
     name: 'get_account_analytics',
-    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels such as Google Business Profile Views, Search Views, Maps Views, Customer Actions, and Posts.',
+    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
     inputSchema: z.object({
         account_id: z
             .number()
@@ -14,74 +15,138 @@ export const getAccountAnalyticsTool = {
             .string()
             .optional()
             .describe('End date (ISO date). Defaults to today.'),
+        presentation: presentationSchema.describe('Output style: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
     }),
     async execute(client, input) {
         const result = await client.getAccountAnalytics(input);
-        const { account, range, summary, snapshots } = result;
-        const accountLabel = account.platform === 'google_business'
-            ? `${account.username} (Google Business, id ${account.id})`
-            : `@${account.username} (${account.platform}, id ${account.id})`;
-        const lines = [
-            `Analytics for ${accountLabel}`,
-            `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
-            '',
-            'Summary:',
-        ];
-        const nativeRows = getNativeMetricRows(account.platform, summary);
-        if (nativeRows.length > 0) {
-            for (const [label, value] of nativeRows) {
-                pushMetric(lines, label, value);
-            }
-        }
-        else if (account.platform === 'pinterest') {
-            pushGenericSummary(lines, summary);
-            pushMetric(lines, 'Outbound clicks', summary.total_website_clicks);
-        }
-        else if (account.platform === 'youtube') {
-            pushGenericSummary(lines, summary);
-            pushMetric(lines, 'Watch minutes', summary.total_watch_minutes);
-            pushMetric(lines, 'Likes', summary.total_likes);
-        }
-        else {
-            pushGenericSummary(lines, summary);
-        }
-        return lines.join('\n');
+        return formatAccountAnalytics(result, input.presentation || 'compact');
     },
 };
-function getNativeMetricRows(platform, summary) {
-    // API-provided display_metrics is the contract for platform-native dashboards.
-    // Add future non-generic analytics platforms there so MCP output never guesses
-    // from internal storage field names.
-    const apiRows = (summary.display_metrics || [])
-        .filter((metric) => metric?.label)
-        .map((metric) => [metric.label, metric.value]);
-    if (apiRows.length > 0)
-        return apiRows;
+function formatAccountAnalytics(result, presentation) {
+    const { account, range, summary, snapshots } = result;
+    const rows = accountMetricRows(summary, account.platform);
+    const insights = analyticsInsights(summary, account.platform);
+    if (presentation === 'json') {
+        return JSON.stringify({
+            type: 'account_analytics',
+            account,
+            range,
+            snapshot_count: snapshots.length,
+            metrics: rows.map(([label, value]) => ({ label, value })),
+            insights,
+            summary,
+            snapshots,
+        }, null, 2);
+    }
+    if (presentation === 'table') {
+        return [
+            `**📊 Analytics for ${accountLabel(account.username)} (${account.id})**`,
+            `_${account.platform} · ${range.from} → ${range.to}_`,
+            '',
+            '**Account**',
+            markdownTable(['Field', 'Value'], [
+                ['Account ID', String(account.id)],
+                ['Daily snapshots', formatNumber(snapshots.length)],
+            ]),
+            '',
+            '**Metrics**',
+            markdownTable(['Metric', 'Value'], rows),
+            '',
+            '**Quick read**',
+            insights.map((insight) => `- ${insight}`).join('\n'),
+        ].join('\n');
+    }
+    return [
+        `**📊 Analytics for ${accountLabel(account.username)} (${account.id})**`,
+        `_${account.platform} · ${range.from} → ${range.to}_`,
+        '',
+        '**Account**',
+        `- **Account ID:** ${account.id}`,
+        `- **Daily snapshots:** ${formatNumber(snapshots.length)}`,
+        '',
+        '**Key metrics**',
+        rows.map(([label, value]) => `- **${label}:** ${value}`).join('\n'),
+        '',
+        '**Quick read**',
+        insights.map((insight) => `- ${insight}`).join('\n'),
+    ].join('\n');
+}
+function accountMetricRows(summary, platform) {
+    const nativeRows = nativeMetricRows(summary);
+    if (nativeRows.length > 0)
+        return nativeRows;
     if (platform === 'google_business') {
         const metrics = summary.platform_metrics || {};
         return [
-            ['Profile Views', metrics.profile_views ?? summary.total_views],
-            ['Search Views', metrics.search_views ?? summary.total_reach],
-            ['Maps Views', metrics.maps_views ?? summary.total_profile_views],
-            ['Customer Actions', metrics.customer_actions ?? summary.total_accounts_engaged],
-            ['Posts', metrics.posts ?? summary.current_media_count],
+            ['Profile Views', formatNumber(metrics.profile_views ?? summary.total_views)],
+            ['Search Views', formatNumber(metrics.search_views ?? summary.total_reach)],
+            ['Maps Views', formatNumber(metrics.maps_views ?? summary.total_profile_views)],
+            ['Customer Actions', formatNumber(metrics.customer_actions ?? summary.total_accounts_engaged)],
+            ['Posts', formatNumber(metrics.posts ?? summary.current_media_count)],
         ];
     }
-    return [];
+    const rows = genericMetricRows(summary);
+    if (platform === 'pinterest')
+        rows.push(['Outbound clicks', formatNumber(summary.total_website_clicks)]);
+    if (platform === 'youtube') {
+        rows.push(['Watch minutes', formatNumber(summary.total_watch_minutes)]);
+        rows.push(['Likes', formatNumber(summary.total_likes)]);
+    }
+    return rows;
+}
+function nativeMetricRows(summary) {
+    return (summary.display_metrics || [])
+        .filter((metric) => metric?.label)
+        .map((metric) => [metric.label, formatNumber(metric.value)]);
+}
+function genericMetricRows(summary) {
+    return [
+        ['Followers', `${formatNumber(summary.current_followers)} (${formatDelta(summary.followers_change)} in range)`],
+        ['Follows gained / lost', `+${formatNumber(summary.total_follows_gained)} / -${formatNumber(summary.total_follows_lost)}`],
+        ['Total reach', formatNumber(summary.total_reach)],
+        ['Total views', formatNumber(summary.total_views)],
+        ['Profile views', formatNumber(summary.total_profile_views)],
+        ['Accounts engaged', formatNumber(summary.total_accounts_engaged)],
+        ['Engagement rate by reach', formatPercent(summary.engagement_rate)],
+        ['Engagement rate by followers', formatPercent(summary.engagement_rate_by_followers)],
+    ];
+}
+function analyticsInsights(summary, platform) {
+    const insights = [];
+    if (platform === 'google_business' && (summary.display_metrics?.length || 0) > 0) {
+        insights.push('Google Business metrics are shown with dashboard-native labels.');
+    }
+    if ((summary.followers_change || 0) > 0)
+        insights.push(`Audience grew by ${formatDelta(summary.followers_change)} followers in this range.`);
+    if ((summary.followers_change || 0) < 0)
+        insights.push(`Audience dipped by ${formatDelta(summary.followers_change)} followers in this range.`);
+    if (summary.engagement_rate != null && platform !== 'google_business')
+        insights.push(`Engagement by reach is ${formatPercent(summary.engagement_rate)}.`);
+    if (platform === 'youtube' && summary.total_watch_minutes != null)
+        insights.push(`${formatNumber(summary.total_watch_minutes)} total watch minutes were recorded.`);
+    return insights.length ? insights : ['No standout movement detected in the returned period.'];
 }
 function formatDelta(n) {
     return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
 }
-function pushGenericSummary(lines, summary) {
-    lines.push(`• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`, `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`);
-    pushMetric(lines, 'Total reach', summary.total_reach);
-    pushMetric(lines, 'Total views', summary.total_views);
-    pushMetric(lines, 'Profile views', summary.total_profile_views);
-    pushMetric(lines, 'Total accounts engaged', summary.total_accounts_engaged);
-    lines.push(`• Engagement rate (by reach): ${summary.engagement_rate}%`, `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`);
+function formatNumber(value) {
+    return value == null ? 'n/a' : value.toLocaleString();
 }
-function pushMetric(lines, label, value) {
-    if (value != null) {
-        lines.push(`• ${label}: ${value.toLocaleString()}`);
-    }
+function formatPercent(value) {
+    return value == null ? 'n/a' : `${formatNumber(value)}%`;
+}
+function accountLabel(username) {
+    if (!username)
+        return 'account';
+    return username.startsWith('@') || /\s/.test(username) ? username : `@${username}`;
+}
+function markdownTable(headers, rows) {
+    return [
+        `| ${headers.map(escapeCell).join(' | ')} |`,
+        `| ${headers.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+    ].join('\n');
+}
+function escapeCell(value) {
+    return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
 }

package/dist/tools/get-post-analytics.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import type { PosterlyClient } from '../lib/api-client.js';
+declare const presentationSchema: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
+type AnalyticsPresentation = z.infer<typeof presentationSchema>;
 export declare const getPostAnalyticsTool: {
     name: string;
     description: string;
@@ -9,18 +11,21 @@ export declare const getPostAnalyticsTool: {
         to: z.ZodOptional<z.ZodString>;
         limit: z.ZodOptional<z.ZodNumber>;
         offset: z.ZodOptional<z.ZodNumber>;
+        presentation: z.ZodOptional<z.ZodEnum<["compact", "table", "json"]>>;
     }, "strip", z.ZodTypeAny, {
         account_id: number;
         limit?: number | undefined;
         offset?: number | undefined;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }, {
         account_id: number;
         limit?: number | undefined;
         offset?: number | undefined;
         from?: string | undefined;
         to?: string | undefined;
+        presentation?: "compact" | "table" | "json" | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         account_id: number;
@@ -28,5 +33,7 @@ export declare const getPostAnalyticsTool: {
         to?: string;
         limit?: number;
         offset?: number;
+        presentation?: AnalyticsPresentation;
     }): Promise<string>;
 };
+export {};

package/dist/tools/get-post-analytics.js

@@ -1,7 +1,8 @@
 import { z } from 'zod';
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
 export const getPostAnalyticsTool = {
     name: 'get_post_analytics',
-    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first.',
+    description: 'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
     inputSchema: z.object({
         account_id: z
             .number()
@@ -21,61 +22,139 @@ export const getPostAnalyticsTool = {
             .optional()
             .describe('Number of posts to return (default 50, max 200)'),
         offset: z.number().min(0).optional().describe('Pagination offset'),
+        presentation: presentationSchema.describe('Output style: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
     }),
     async execute(client, input) {
         const result = await client.getPostAnalytics(input);
-        const { account, range, posts, total } = result;
-        if (posts.length === 0) {
-            return `No analytics found for @${account.username} (${account.platform}) between ${range.from} and ${range.to}.`;
-        }
-        const lines = [
-            `Post analytics for @${account.username} (${account.platform})`,
-            `Range: ${range.from} → ${range.to}  •  Showing ${posts.length} of ${total}`,
-            '',
-        ];
-        for (const p of posts) {
-            const postedAt = p.posted_at
-                ? new Date(p.posted_at).toLocaleString()
-                : 'unknown date';
-            const caption = p.caption_snippet
-                ? p.caption_snippet.length > 60
-                    ? `${p.caption_snippet.slice(0, 60)}…`
-                    : p.caption_snippet
-                : '(no caption)';
-            const metrics = [
-                `${p.likes} likes`,
-                `${p.comments} comments`,
-                `${p.reach.toLocaleString()} reach`,
-            ];
-            if (p.impressions)
-                metrics.push(`${p.impressions.toLocaleString()} impressions`);
-            if (p.saved)
-                metrics.push(`${p.saved} saved`);
-            if (p.shares)
-                metrics.push(`${p.shares} shares`);
-            if (p.plays)
-                metrics.push(`${p.plays.toLocaleString()} plays`);
-            if (account.platform === 'youtube' && p.total_watch_time_ms) {
-                metrics.push(`${Math.round(p.total_watch_time_ms / 60000).toLocaleString()} watch minutes`);
-            }
-            if (account.platform === 'youtube' && p.avg_watch_time_ms) {
-                metrics.push(`${Math.round(p.avg_watch_time_ms / 1000)}s avg view`);
-            }
-            if (p.url_link_clicks) {
-                metrics.push(account.platform === 'pinterest'
-                    ? `${p.url_link_clicks.toLocaleString()} outbound clicks`
-                    : `${p.url_link_clicks.toLocaleString()} link clicks`);
-            }
-            if (p.user_profile_clicks) {
-                metrics.push(account.platform === 'pinterest'
-                    ? `${p.user_profile_clicks.toLocaleString()} pin clicks`
-                    : `${p.user_profile_clicks.toLocaleString()} profile clicks`);
-            }
-            lines.push(`• [${postedAt}] ${caption}`);
-            lines.push(`  ${metrics.join(' • ')}`);
-            if (p.permalink)
-                lines.push(`  ${p.permalink}`);
-        }
-        return lines.join('\n');
+        return formatPostAnalytics(result, input.presentation || 'compact');
     },
 };
+function formatPostAnalytics(result, presentation) {
+    const { account, range, posts, total } = result;
+    if (posts.length === 0) {
+        return `No analytics found for ${accountLabel(account.username)} (${account.platform}) between ${range.from} and ${range.to}.`;
+    }
+    const totals = posts.reduce((acc, post) => {
+        acc.likes += post.likes || 0;
+        acc.comments += post.comments || 0;
+        acc.reach += post.reach || 0;
+        acc.impressions += post.impressions || 0;
+        acc.shares += post.shares || 0;
+        acc.saves += post.saved || 0;
+        return acc;
+    }, { likes: 0, comments: 0, reach: 0, impressions: 0, shares: 0, saves: 0 });
+    if (presentation === 'json') {
+        return JSON.stringify({
+            type: 'post_analytics',
+            account,
+            range,
+            returned: {
+                count: posts.length,
+                total,
+            },
+            totals,
+            posts,
+        }, null, 2);
+    }
+    if (presentation === 'table') {
+        return [
+            `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+            `_${account.platform} · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+            '',
+            '**Returned totals**',
+            markdownTable(['Likes', 'Comments', 'Reach', 'Impressions', 'Shares', 'Saves'], [[
+                    formatNumber(totals.likes),
+                    formatNumber(totals.comments),
+                    formatNumber(totals.reach),
+                    formatNumber(totals.impressions),
+                    formatNumber(totals.shares),
+                    formatNumber(totals.saves),
+                ]]),
+            '',
+            '**Posts**',
+            markdownTable(['Posted', 'Post', 'Caption', 'Reach', 'Likes', 'Comments', 'Extras'], posts.map((post) => [
+                dateTime(post.posted_at),
+                post.id ? String(post.id) : post.platform_media_id,
+                compact(post.caption_snippet, 70) || '(no caption)',
+                formatNumber(post.reach),
+                formatNumber(post.likes),
+                formatNumber(post.comments),
+                postExtras(account.platform, post),
+            ])),
+        ].join('\n');
+    }
+    const lines = [
+        `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+        `_${account.platform} · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+        '',
+        '**Returned totals**',
+        `- **Likes:** ${formatNumber(totals.likes)}`,
+        `- **Comments:** ${formatNumber(totals.comments)}`,
+        `- **Reach:** ${formatNumber(totals.reach)}`,
+        `- **Impressions:** ${formatNumber(totals.impressions)}`,
+        `- **Shares:** ${formatNumber(totals.shares)}`,
+        `- **Saves:** ${formatNumber(totals.saves)}`,
+        '',
+        '**Posts**',
+    ];
+    posts.forEach((post, index) => {
+        lines.push(`${index + 1}. **${compact(post.caption_snippet, 70) || '(no caption)'}**`);
+        lines.push(`   Posted: ${dateTime(post.posted_at)}`);
+        lines.push(`   Post ID: ${post.id ? String(post.id) : post.platform_media_id}`);
+        lines.push(`   Reach: ${formatNumber(post.reach)}`);
+        lines.push(`   Likes: ${formatNumber(post.likes)}`);
+        lines.push(`   Comments: ${formatNumber(post.comments)}`);
+        lines.push(`   Extras: ${postExtras(account.platform, post)}`);
+    });
+    return lines.join('\n');
+}
+function postExtras(platform, post) {
+    const metrics = [];
+    if (post.impressions)
+        metrics.push(`${formatNumber(post.impressions)} impressions`);
+    if (post.saved)
+        metrics.push(`${formatNumber(post.saved)} saved`);
+    if (post.shares)
+        metrics.push(`${formatNumber(post.shares)} shares`);
+    if (post.plays)
+        metrics.push(`${formatNumber(post.plays)} plays`);
+    if (platform === 'youtube' && post.total_watch_time_ms)
+        metrics.push(`${formatNumber(Math.round(post.total_watch_time_ms / 60000))} watch minutes`);
+    if (platform === 'youtube' && post.avg_watch_time_ms)
+        metrics.push(`${formatNumber(Math.round(post.avg_watch_time_ms / 1000))}s avg view`);
+    if (post.url_link_clicks)
+        metrics.push(platform === 'pinterest' ? `${formatNumber(post.url_link_clicks)} outbound clicks` : `${formatNumber(post.url_link_clicks)} link clicks`);
+    if (post.user_profile_clicks)
+        metrics.push(platform === 'pinterest' ? `${formatNumber(post.user_profile_clicks)} pin clicks` : `${formatNumber(post.user_profile_clicks)} profile clicks`);
+    if (post.permalink)
+        metrics.push(post.permalink);
+    return metrics.join(' · ') || 'n/a';
+}
+function accountLabel(username) {
+    if (!username)
+        return 'account';
+    return username.startsWith('@') || /\s/.test(username) ? username : `@${username}`;
+}
+function dateTime(value) {
+    if (!value)
+        return 'n/a';
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? value : date.toLocaleString();
+}
+function compact(value, maxLength) {
+    const text = String(value || '').replace(/\s+/g, ' ').trim();
+    return text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 1))}…` : text;
+}
+function formatNumber(value) {
+    return value == null ? 'n/a' : value.toLocaleString();
+}
+function markdownTable(headers, rows) {
+    return [
+        `| ${headers.map(escapeCell).join(' | ')} |`,
+        `| ${headers.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+    ].join('\n');
+}
+function escapeCell(value) {
+    return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.19.4",
+  "version": "0.19.5",
   "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",

package/src/lib/api-client.ts

@@ -152,7 +152,7 @@ export interface AccountAnalyticsSummary {
   total_watch_minutes?: number | null;
   total_likes?: number | null;
   platform_metrics?: Record<string, number | null | undefined>;
-  display_metrics?: Array<{ label: string; value: number | null | undefined }>;
+  display_metrics?: Array<{ key?: string; label: string; value: number | null | undefined; unit?: string }>;
 }
 
 export interface AccountAnalyticsSnapshot {

package/src/tools/get-account-analytics.ts

@@ -1,10 +1,14 @@
 import { z } from 'zod';
-import type { AccountAnalyticsSummary, PosterlyClient } from '../lib/api-client.js';
+import type { AccountAnalyticsResponse, AccountAnalyticsSummary, PosterlyClient } from '../lib/api-client.js';
+
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
+type AnalyticsPresentation = z.infer<typeof presentationSchema>;
+type MetricRow = [string, string];
 
 export const getAccountAnalyticsTool = {
   name: 'get_account_analytics',
   description:
-    'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels such as Google Business Profile Views, Search Views, Maps Views, Customer Actions, and Posts.',
+    'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
   inputSchema: z.object({
     account_id: z
       .number()
@@ -17,92 +21,151 @@ export const getAccountAnalyticsTool = {
       .string()
       .optional()
       .describe('End date (ISO date). Defaults to today.'),
+    presentation: presentationSchema.describe('Output style: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
   }),
 
   async execute(
     client: PosterlyClient,
-    input: { account_id: number; from?: string; to?: string }
+    input: { account_id: number; from?: string; to?: string; presentation?: AnalyticsPresentation }
   ) {
     const result = await client.getAccountAnalytics(input);
-    const { account, range, summary, snapshots } = result;
+    return formatAccountAnalytics(result, input.presentation || 'compact');
+  },
+};
 
-    const accountLabel = account.platform === 'google_business'
-      ? `${account.username} (Google Business, id ${account.id})`
-      : `@${account.username} (${account.platform}, id ${account.id})`;
+function formatAccountAnalytics(result: AccountAnalyticsResponse, presentation: Exclude<AnalyticsPresentation, undefined>): string {
+  const { account, range, summary, snapshots } = result;
+  const rows = accountMetricRows(summary, account.platform);
+  const insights = analyticsInsights(summary, account.platform);
 
-    const lines: string[] = [
-      `Analytics for ${accountLabel}`,
-      `Range: ${range.from} → ${range.to} (${snapshots.length} daily snapshots)`,
-      '',
-      'Summary:',
-    ];
+  if (presentation === 'json') {
+    return JSON.stringify({
+      type: 'account_analytics',
+      account,
+      range,
+      snapshot_count: snapshots.length,
+      metrics: rows.map(([label, value]) => ({ label, value })),
+      insights,
+      summary,
+      snapshots,
+    }, null, 2);
+  }
 
-    const nativeRows = getNativeMetricRows(account.platform, summary);
-    if (nativeRows.length > 0) {
-      for (const [label, value] of nativeRows) {
-        pushMetric(lines, label, value);
-      }
-    } else if (account.platform === 'pinterest') {
-      pushGenericSummary(lines, summary);
-      pushMetric(lines, 'Outbound clicks', summary.total_website_clicks);
-    } else if (account.platform === 'youtube') {
-      pushGenericSummary(lines, summary);
-      pushMetric(lines, 'Watch minutes', summary.total_watch_minutes);
-      pushMetric(lines, 'Likes', summary.total_likes);
-    } else {
-      pushGenericSummary(lines, summary);
-    }
-
-    return lines.join('\n');
-  },
-};
+  if (presentation === 'table') {
+    return [
+      `**📊 Analytics for ${accountLabel(account.username)} (${account.id})**`,
+      `_${account.platform} · ${range.from} → ${range.to}_`,
+      '',
+      '**Account**',
+      markdownTable(['Field', 'Value'], [
+        ['Account ID', String(account.id)],
+        ['Daily snapshots', formatNumber(snapshots.length)],
+      ]),
+      '',
+      '**Metrics**',
+      markdownTable(['Metric', 'Value'], rows),
+      '',
+      '**Quick read**',
+      insights.map((insight) => `- ${insight}`).join('\n'),
+    ].join('\n');
+  }
 
-type MetricRow = [label: string, value: number | null | undefined];
+  return [
+    `**📊 Analytics for ${accountLabel(account.username)} (${account.id})**`,
+    `_${account.platform} · ${range.from} → ${range.to}_`,
+    '',
+    '**Account**',
+    `- **Account ID:** ${account.id}`,
+    `- **Daily snapshots:** ${formatNumber(snapshots.length)}`,
+    '',
+    '**Key metrics**',
+    rows.map(([label, value]) => `- **${label}:** ${value}`).join('\n'),
+    '',
+    '**Quick read**',
+    insights.map((insight) => `- ${insight}`).join('\n'),
+  ].join('\n');
+}
 
-function getNativeMetricRows(platform: string, summary: AccountAnalyticsSummary): MetricRow[] {
-  // API-provided display_metrics is the contract for platform-native dashboards.
-  // Add future non-generic analytics platforms there so MCP output never guesses
-  // from internal storage field names.
-  const apiRows = (summary.display_metrics || [])
-    .filter((metric) => metric?.label)
-    .map((metric) => [metric.label, metric.value] as MetricRow);
-  if (apiRows.length > 0) return apiRows;
+function accountMetricRows(summary: AccountAnalyticsSummary, platform: string): MetricRow[] {
+  const nativeRows = nativeMetricRows(summary);
+  if (nativeRows.length > 0) return nativeRows;
 
   if (platform === 'google_business') {
     const metrics = summary.platform_metrics || {};
     return [
-      ['Profile Views', metrics.profile_views ?? summary.total_views],
-      ['Search Views', metrics.search_views ?? summary.total_reach],
-      ['Maps Views', metrics.maps_views ?? summary.total_profile_views],
-      ['Customer Actions', metrics.customer_actions ?? summary.total_accounts_engaged],
-      ['Posts', metrics.posts ?? summary.current_media_count],
+      ['Profile Views', formatNumber(metrics.profile_views ?? summary.total_views)],
+      ['Search Views', formatNumber(metrics.search_views ?? summary.total_reach)],
+      ['Maps Views', formatNumber(metrics.maps_views ?? summary.total_profile_views)],
+      ['Customer Actions', formatNumber(metrics.customer_actions ?? summary.total_accounts_engaged)],
+      ['Posts', formatNumber(metrics.posts ?? summary.current_media_count)],
     ];
   }
 
-  return [];
+  const rows = genericMetricRows(summary);
+  if (platform === 'pinterest') rows.push(['Outbound clicks', formatNumber(summary.total_website_clicks)]);
+  if (platform === 'youtube') {
+    rows.push(['Watch minutes', formatNumber(summary.total_watch_minutes)]);
+    rows.push(['Likes', formatNumber(summary.total_likes)]);
+  }
+  return rows;
+}
+
+function nativeMetricRows(summary: AccountAnalyticsSummary): MetricRow[] {
+  return (summary.display_metrics || [])
+    .filter((metric) => metric?.label)
+    .map((metric) => [metric.label, formatNumber(metric.value)]);
+}
+
+function genericMetricRows(summary: AccountAnalyticsSummary): MetricRow[] {
+  return [
+    ['Followers', `${formatNumber(summary.current_followers)} (${formatDelta(summary.followers_change)} in range)`],
+    ['Follows gained / lost', `+${formatNumber(summary.total_follows_gained)} / -${formatNumber(summary.total_follows_lost)}`],
+    ['Total reach', formatNumber(summary.total_reach)],
+    ['Total views', formatNumber(summary.total_views)],
+    ['Profile views', formatNumber(summary.total_profile_views)],
+    ['Accounts engaged', formatNumber(summary.total_accounts_engaged)],
+    ['Engagement rate by reach', formatPercent(summary.engagement_rate)],
+    ['Engagement rate by followers', formatPercent(summary.engagement_rate_by_followers)],
+  ];
+}
+
+function analyticsInsights(summary: AccountAnalyticsSummary, platform: string): string[] {
+  const insights: string[] = [];
+  if (platform === 'google_business' && (summary.display_metrics?.length || 0) > 0) {
+    insights.push('Google Business metrics are shown with dashboard-native labels.');
+  }
+  if ((summary.followers_change || 0) > 0) insights.push(`Audience grew by ${formatDelta(summary.followers_change)} followers in this range.`);
+  if ((summary.followers_change || 0) < 0) insights.push(`Audience dipped by ${formatDelta(summary.followers_change)} followers in this range.`);
+  if (summary.engagement_rate != null && platform !== 'google_business') insights.push(`Engagement by reach is ${formatPercent(summary.engagement_rate)}.`);
+  if (platform === 'youtube' && summary.total_watch_minutes != null) insights.push(`${formatNumber(summary.total_watch_minutes)} total watch minutes were recorded.`);
+  return insights.length ? insights : ['No standout movement detected in the returned period.'];
 }
 
 function formatDelta(n: number): string {
   return n >= 0 ? `+${n.toLocaleString()}` : n.toLocaleString();
 }
 
-function pushGenericSummary(lines: string[], summary: AccountAnalyticsSummary) {
-  lines.push(
-    `• Followers: ${summary.current_followers.toLocaleString()} (${formatDelta(summary.followers_change)} in range)`,
-    `• Follows gained / lost: +${summary.total_follows_gained} / -${summary.total_follows_lost}`
-  );
-  pushMetric(lines, 'Total reach', summary.total_reach);
-  pushMetric(lines, 'Total views', summary.total_views);
-  pushMetric(lines, 'Profile views', summary.total_profile_views);
-  pushMetric(lines, 'Total accounts engaged', summary.total_accounts_engaged);
-  lines.push(
-    `• Engagement rate (by reach): ${summary.engagement_rate}%`,
-    `• Engagement rate (by followers): ${summary.engagement_rate_by_followers}%`
-  );
+function formatNumber(value: number | null | undefined): string {
+  return value == null ? 'n/a' : value.toLocaleString();
 }
 
-function pushMetric(lines: string[], label: string, value: number | null | undefined) {
-  if (value != null) {
-    lines.push(`• ${label}: ${value.toLocaleString()}`);
-  }
+function formatPercent(value: number | null | undefined): string {
+  return value == null ? 'n/a' : `${formatNumber(value)}%`;
+}
+
+function accountLabel(username: string): string {
+  if (!username) return 'account';
+  return username.startsWith('@') || /\s/.test(username) ? username : `@${username}`;
+}
+
+function markdownTable(headers: string[], rows: MetricRow[]): string {
+  return [
+    `| ${headers.map(escapeCell).join(' | ')} |`,
+    `| ${headers.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+  ].join('\n');
+}
+
+function escapeCell(value: string): string {
+  return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
 }

package/src/tools/get-post-analytics.ts

@@ -1,10 +1,13 @@
 import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
+import type { PostAnalyticsResponse, PostAnalyticsRow, PosterlyClient } from '../lib/api-client.js';
+
+const presentationSchema = z.enum(['compact', 'table', 'json']).optional();
+type AnalyticsPresentation = z.infer<typeof presentationSchema>;
 
 export const getPostAnalyticsTool = {
   name: 'get_post_analytics',
   description:
-    'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first.',
+    'Get per-post engagement metrics (likes, comments, reach, impressions, saves, shares, plays, clicks, watch time) for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, and YouTube. Returns the most recent posts first. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
   inputSchema: z.object({
     account_id: z
       .number()
@@ -24,6 +27,7 @@ export const getPostAnalyticsTool = {
       .optional()
       .describe('Number of posts to return (default 50, max 200)'),
     offset: z.number().min(0).optional().describe('Pagination offset'),
+    presentation: presentationSchema.describe('Output style: compact bullets, Markdown table, or raw JSON for client-side chart/card rendering.'),
   }),
 
   async execute(
@@ -34,65 +38,143 @@ export const getPostAnalyticsTool = {
       to?: string;
       limit?: number;
       offset?: number;
+      presentation?: AnalyticsPresentation;
     }
   ) {
     const result = await client.getPostAnalytics(input);
-    const { account, range, posts, total } = result;
+    return formatPostAnalytics(result, input.presentation || 'compact');
+  },
+};
 
-    if (posts.length === 0) {
-      return `No analytics found for @${account.username} (${account.platform}) between ${range.from} and ${range.to}.`;
-    }
+function formatPostAnalytics(result: PostAnalyticsResponse, presentation: Exclude<AnalyticsPresentation, undefined>): string {
+  const { account, range, posts, total } = result;
+
+  if (posts.length === 0) {
+    return `No analytics found for ${accountLabel(account.username)} (${account.platform}) between ${range.from} and ${range.to}.`;
+  }
 
-    const lines: string[] = [
-      `Post analytics for @${account.username} (${account.platform})`,
-      `Range: ${range.from} → ${range.to}  •  Showing ${posts.length} of ${total}`,
+  const totals = posts.reduce((acc, post) => {
+    acc.likes += post.likes || 0;
+    acc.comments += post.comments || 0;
+    acc.reach += post.reach || 0;
+    acc.impressions += post.impressions || 0;
+    acc.shares += post.shares || 0;
+    acc.saves += post.saved || 0;
+    return acc;
+  }, { likes: 0, comments: 0, reach: 0, impressions: 0, shares: 0, saves: 0 });
+
+  if (presentation === 'json') {
+    return JSON.stringify({
+      type: 'post_analytics',
+      account,
+      range,
+      returned: {
+        count: posts.length,
+        total,
+      },
+      totals,
+      posts,
+    }, null, 2);
+  }
+
+  if (presentation === 'table') {
+    return [
+      `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+      `_${account.platform} · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
       '',
-    ];
-
-    for (const p of posts) {
-      const postedAt = p.posted_at
-        ? new Date(p.posted_at).toLocaleString()
-        : 'unknown date';
-      const caption = p.caption_snippet
-        ? p.caption_snippet.length > 60
-          ? `${p.caption_snippet.slice(0, 60)}…`
-          : p.caption_snippet
-        : '(no caption)';
-      const metrics = [
-        `${p.likes} likes`,
-        `${p.comments} comments`,
-        `${p.reach.toLocaleString()} reach`,
-      ];
-      if (p.impressions) metrics.push(`${p.impressions.toLocaleString()} impressions`);
-      if (p.saved) metrics.push(`${p.saved} saved`);
-      if (p.shares) metrics.push(`${p.shares} shares`);
-      if (p.plays) metrics.push(`${p.plays.toLocaleString()} plays`);
-      if (account.platform === 'youtube' && p.total_watch_time_ms) {
-        metrics.push(`${Math.round(p.total_watch_time_ms / 60000).toLocaleString()} watch minutes`);
-      }
-      if (account.platform === 'youtube' && p.avg_watch_time_ms) {
-        metrics.push(`${Math.round(p.avg_watch_time_ms / 1000)}s avg view`);
-      }
-      if (p.url_link_clicks) {
-        metrics.push(
-          account.platform === 'pinterest'
-            ? `${p.url_link_clicks.toLocaleString()} outbound clicks`
-            : `${p.url_link_clicks.toLocaleString()} link clicks`
-        );
-      }
-      if (p.user_profile_clicks) {
-        metrics.push(
-          account.platform === 'pinterest'
-            ? `${p.user_profile_clicks.toLocaleString()} pin clicks`
-            : `${p.user_profile_clicks.toLocaleString()} profile clicks`
-        );
-      }
-
-      lines.push(`• [${postedAt}] ${caption}`);
-      lines.push(`  ${metrics.join(' • ')}`);
-      if (p.permalink) lines.push(`  ${p.permalink}`);
-    }
+      '**Returned totals**',
+      markdownTable(['Likes', 'Comments', 'Reach', 'Impressions', 'Shares', 'Saves'], [[
+        formatNumber(totals.likes),
+        formatNumber(totals.comments),
+        formatNumber(totals.reach),
+        formatNumber(totals.impressions),
+        formatNumber(totals.shares),
+        formatNumber(totals.saves),
+      ]]),
+      '',
+      '**Posts**',
+      markdownTable(['Posted', 'Post', 'Caption', 'Reach', 'Likes', 'Comments', 'Extras'], posts.map((post) => [
+        dateTime(post.posted_at),
+        post.id ? String(post.id) : post.platform_media_id,
+        compact(post.caption_snippet, 70) || '(no caption)',
+        formatNumber(post.reach),
+        formatNumber(post.likes),
+        formatNumber(post.comments),
+        postExtras(account.platform, post),
+      ])),
+    ].join('\n');
+  }
 
-    return lines.join('\n');
-  },
-};
+  const lines: string[] = [
+    `**📈 Post analytics for ${accountLabel(account.username)} (${account.id})**`,
+    `_${account.platform} · ${range.from} → ${range.to} · showing ${posts.length} of ${total}_`,
+    '',
+    '**Returned totals**',
+    `- **Likes:** ${formatNumber(totals.likes)}`,
+    `- **Comments:** ${formatNumber(totals.comments)}`,
+    `- **Reach:** ${formatNumber(totals.reach)}`,
+    `- **Impressions:** ${formatNumber(totals.impressions)}`,
+    `- **Shares:** ${formatNumber(totals.shares)}`,
+    `- **Saves:** ${formatNumber(totals.saves)}`,
+    '',
+    '**Posts**',
+  ];
+
+  posts.forEach((post, index) => {
+    lines.push(`${index + 1}. **${compact(post.caption_snippet, 70) || '(no caption)'}**`);
+    lines.push(`   Posted: ${dateTime(post.posted_at)}`);
+    lines.push(`   Post ID: ${post.id ? String(post.id) : post.platform_media_id}`);
+    lines.push(`   Reach: ${formatNumber(post.reach)}`);
+    lines.push(`   Likes: ${formatNumber(post.likes)}`);
+    lines.push(`   Comments: ${formatNumber(post.comments)}`);
+    lines.push(`   Extras: ${postExtras(account.platform, post)}`);
+  });
+
+  return lines.join('\n');
+}
+
+function postExtras(platform: string, post: PostAnalyticsRow): string {
+  const metrics: string[] = [];
+  if (post.impressions) metrics.push(`${formatNumber(post.impressions)} impressions`);
+  if (post.saved) metrics.push(`${formatNumber(post.saved)} saved`);
+  if (post.shares) metrics.push(`${formatNumber(post.shares)} shares`);
+  if (post.plays) metrics.push(`${formatNumber(post.plays)} plays`);
+  if (platform === 'youtube' && post.total_watch_time_ms) metrics.push(`${formatNumber(Math.round(post.total_watch_time_ms / 60000))} watch minutes`);
+  if (platform === 'youtube' && post.avg_watch_time_ms) metrics.push(`${formatNumber(Math.round(post.avg_watch_time_ms / 1000))}s avg view`);
+  if (post.url_link_clicks) metrics.push(platform === 'pinterest' ? `${formatNumber(post.url_link_clicks)} outbound clicks` : `${formatNumber(post.url_link_clicks)} link clicks`);
+  if (post.user_profile_clicks) metrics.push(platform === 'pinterest' ? `${formatNumber(post.user_profile_clicks)} pin clicks` : `${formatNumber(post.user_profile_clicks)} profile clicks`);
+  if (post.permalink) metrics.push(post.permalink);
+  return metrics.join(' · ') || 'n/a';
+}
+
+function accountLabel(username: string): string {
+  if (!username) return 'account';
+  return username.startsWith('@') || /\s/.test(username) ? username : `@${username}`;
+}
+
+function dateTime(value: string | null): string {
+  if (!value) return 'n/a';
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? value : date.toLocaleString();
+}
+
+function compact(value: string | null, maxLength: number): string {
+  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  return text.length > maxLength ? `${text.slice(0, Math.max(0, maxLength - 1))}…` : text;
+}
+
+function formatNumber(value: number | null | undefined): string {
+  return value == null ? 'n/a' : value.toLocaleString();
+}
+
+function markdownTable(headers: string[], rows: string[][]): string {
+  return [
+    `| ${headers.map(escapeCell).join(' | ')} |`,
+    `| ${headers.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => `| ${row.map(escapeCell).join(' | ')} |`),
+  ].join('\n');
+}
+
+function escapeCell(value: string): string {
+  return String(value).replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}