posterly-mcp-server 0.43.8 → 0.45.0

package/src/tools/get-connect-session.ts

@@ -1,63 +0,0 @@
-import { z } from 'zod';
-import type { ConnectSession, PosterlyClient } from '../lib/api-client.js';
-import { DASHBOARD_CONNECT_URL, formatConnectedAccounts, formatLocalDateTime } from '../lib/format.js';
-
-export const getConnectSessionTool = {
-  name: 'get_connect_session',
-  description:
-    'Poll a posterly connect session. Use the returned status and next-step guidance to keep the user updated in plain language. Stop when status is connected, failed, cancelled, or expired.',
-  inputSchema: z.object({
-    session_id: z.string().describe('Connect session ID returned by create_connect_session.'),
-    debug: z
-      .boolean()
-      .optional()
-      .describe('When true, include the raw connect session JSON for debugging. Keep false for normal user-facing agent flows.'),
-  }),
-
-  async execute(
-    client: PosterlyClient,
-    input: { session_id: string; debug?: boolean },
-  ) {
-    const result = await client.getConnectSession(input.session_id);
-    return formatConnectSession(result.connect_session, Boolean(input.debug));
-  },
-};
-
-function formatConnectSession(session: ConnectSession, includeRaw: boolean): string {
-  const connected = session.connected_count ?? session.connected_accounts?.length ?? 0;
-  return [
-    `posterly connect session: ${session.id}`,
-    `Platform: ${session.platform}`,
-    `Status: ${session.status}`,
-    `Message: ${session.status_message}`,
-    `Connected accounts: ${connected}`,
-    `Accounts: ${formatConnectedAccounts(session.connected_accounts)}`,
-    session.error_message ? `Error: ${session.error_message}` : '',
-    `Expires: ${formatLocalDateTime(session.expires_at)}`,
-    `Dashboard connect page: ${DASHBOARD_CONNECT_URL}`,
-    '',
-    guidanceForStatus(session),
-    includeRaw ? `\nRaw connect session:\n${JSON.stringify(session, null, 2)}` : '',
-  ].filter(Boolean).join('\n');
-}
-
-function guidanceForStatus(session: ConnectSession): string {
-  switch (session.status) {
-    case 'created':
-    case 'opened':
-    case 'awaiting_provider':
-      return 'Next step for the AI agent: tell the user posterly is waiting for browser approval, then keep polling this session. Do not ask for social passwords or OAuth codes.';
-    case 'awaiting_credentials':
-      return 'Next step for the AI agent: tell the user posterly needs them to finish the browser credential step, then keep polling. Do not ask the user to paste credentials into chat.';
-    case 'connected':
-      return `Next step for the AI agent: tell the user ${formatConnectedAccounts(session.connected_accounts)} is connected, then ask what they want to schedule first or offer to create a test post.`;
-    case 'failed':
-      return 'Next step for the AI agent: tell the user the connection failed, share the error if present, and offer to create a fresh connect session.';
-    case 'cancelled':
-      return 'Next step for the AI agent: tell the user the connection was cancelled and offer to create a fresh connect session when they are ready.';
-    case 'expired':
-      return 'Next step for the AI agent: tell the user the connection link expired and create a fresh connect session if they still want to connect this account.';
-    default:
-      return 'Next step for the AI agent: explain the current connection status in plain language and keep polling unless the session is terminal.';
-  }
-}

package/src/tools/get-conversation.ts

@@ -1,44 +0,0 @@
-import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { formatLocalDateTime, truncateText } from '../lib/format.js';
-
-export const getConversationTool = {
-  name: 'get_conversation',
-  description:
-    'Get one social inbox DM conversation and its messages. Instagram and Facebook Page DMs only. Requires a Pro plan or higher plus posts:read.',
-  inputSchema: z.object({
-    conversation_id: z.string().min(1).describe('Conversation ID from list_conversations.'),
-    workspace_id: z.string().optional().describe('Optional. Omit to search every workspace you belong to; pass a workspace ID from whoami to limit to one.'),
-    limit: z.number().int().min(1).max(100).optional().describe('Maximum messages to return. Default 50, max 100.'),
-  }),
-
-  async execute(
-    client: PosterlyClient,
-    input: {
-      conversation_id: string;
-      workspace_id?: string;
-      limit?: number;
-    },
-  ) {
-    const result = await client.getConversation(input);
-    const conversation = result.conversation;
-    const username = typeof conversation.participant_username === 'string' ? `@${conversation.participant_username}` : 'unknown';
-    const lines = [
-      `Conversation ${String(conversation.id)}`,
-      `• Platform: ${typeof conversation.platform === 'string' ? conversation.platform : 'unknown'}`,
-      `• Participant: ${username}`,
-      `• Read: ${conversation.is_read === false ? 'no' : 'yes'}`,
-      `• Messages: ${result.messages.length}`,
-      '',
-    ];
-
-    for (const message of result.messages) {
-      const who = message.sender_is_business ? 'you' : (typeof message.sender_username === 'string' ? message.sender_username : 'them');
-      const when = formatLocalDateTime(typeof message.sent_at === 'string' ? message.sent_at : null);
-      const text = truncateText(typeof message.content === 'string' ? message.content : '', 240);
-      lines.push(`- [${when}] ${who}: ${text}`);
-    }
-
-    return lines.join('\n');
-  },
-};

package/src/tools/get-google-business-review-link.ts

@@ -1,30 +0,0 @@
-import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-
-export const getGoogleBusinessReviewLinkTool = {
-  name: 'get_google_business_review_link',
-  description:
-    'Get the direct public Google review link for a connected Google Business Profile location. Requires account_id or location_id. Returns reviewLink plus the Google Place ID (ChIJ...); that Place ID is output only and must NOT be passed back as location_id to other tools.',
-  inputSchema: z.object({
-    workspace_id: z.string().optional().describe('Filter to a workspace ID from whoami.'),
-    account_id: z.number().int().positive().optional().describe('Google Business account ID from list_accounts.'),
-    location_id: z.string().optional().describe('Google Business numeric location id (the location_id/platform_user_id from list_accounts, e.g. "197940849675145390"). NOT the ChIJ... Place ID this tool returns. Prefer account_id.'),
-  }),
-
-  async execute(
-    client: PosterlyClient,
-    input: {
-      workspace_id?: string;
-      account_id?: number;
-      location_id?: string;
-    },
-  ) {
-    const result = await client.getGoogleBusinessReviewLink(input);
-    return [
-      `Review link for ${result.businessName}:`,
-      result.reviewLink,
-      `Place ID: ${result.placeId}`,
-      `Account ID: ${result.account_id}`,
-    ].join('\n');
-  },
-};

package/src/tools/get-image-job.ts

@@ -1,36 +0,0 @@
-import { z } from 'zod';
-import type { PosterlyClient, ImageJob } from '../lib/api-client.js';
-
-export const getImageJobTool = {
-  name: 'get_image_job',
-  description:
-    'Get one AI image generation job by ID, or list recent image jobs when job_id is omitted. Use after generate_image to poll for completed urls.',
-  inputSchema: z.object({
-    job_id: z.string().optional(),
-    status: z.enum(['pending', 'processing', 'completed', 'failed']).optional(),
-    limit: z.number().int().min(1).max(50).default(10).optional(),
-  }),
-
-  async execute(client: PosterlyClient, input: { job_id?: string; status?: string; limit?: number }) {
-    const result = await client.getImageJob(input);
-    if (result.job) return formatJob(result.job, true);
-
-    const jobs = result.jobs || [];
-    return [
-      `Image jobs (${jobs.length})`,
-      jobs.map((job) => formatJob(job, false)).join('\n\n'),
-    ].filter(Boolean).join('\n');
-  },
-};
-
-function formatJob(job: ImageJob, includeRaw: boolean): string {
-  const lines = [
-    `${job.id}: ${job.status}`,
-    `Prompt: ${job.prompt}`,
-    `Model: ${job.model}; resolution: ${job.resolution}; thinking: ${job.thinking_level || 'n/a'}; cost: ${job.credit_cost}`,
-    job.urls?.length ? `URLs: ${job.urls.join(', ')}` : null,
-    job.error_message ? `Error: ${job.error_message}` : null,
-    includeRaw ? `\nRaw job:\n${JSON.stringify(job, null, 2)}` : null,
-  ];
-  return lines.filter(Boolean).join('\n');
-}

package/src/tools/get-learned-voice.ts

@@ -1,31 +0,0 @@
-import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { mdLearnedVoice, mdTitle } from '../lib/format.js';
-
-export const getLearnedVoiceTool = {
-  name: 'get_learned_voice',
-  description:
-    'Get the voice posterly has learned from a connected account’s real published captions (the "learned captions" shown on the dashboard). Returns a narrative summary, voice traits, style guidelines, and observed posting habits. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has enough published posts to learn from. Read-only; this never overwrites the saved brand profile.',
-  inputSchema: z.object({
-    account_id: z
-      .union([z.string(), z.number()])
-      .describe('The social account ID to inspect (from list_accounts or list_brand_accounts).'),
-  }),
-
-  async execute(
-    client: PosterlyClient,
-    input: { account_id: string | number },
-  ) {
-    const { learned_voice } = await client.getAccountLearnedVoice(input.account_id);
-
-    const body = mdLearnedVoice(learned_voice);
-    if (!body) {
-      return [
-        mdTitle('No learned voice yet'),
-        'posterly has not learned a voice for this account yet. It learns automatically once the account has enough published posts (the captions are analyzed; the saved brand profile is never overwritten).',
-      ].join('\n\n');
-    }
-
-    return [mdTitle('Learned voice (from published captions)'), body].join('\n\n');
-  },
-};

package/src/tools/get-mcp-status.ts

@@ -1,212 +0,0 @@
-import { z } from 'zod';
-import { POSTERLY_MCP_VERSION } from '../lib/version.js';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { resolvePosterlyBaseUrl } from '../lib/api-client.js';
-import { code, mdKeyValue, mdTitle } from '../lib/format.js';
-
-const NPM_LATEST_URL = 'https://registry.npmjs.org/posterly-mcp-server/latest';
-
-export const getMcpStatusTool = {
-  name: 'get_mcp_status',
-  description:
-    'Report the posterly MCP server version, latest npm version, MCP endpoint health, API key health, and update guidance. Safe to call before POSTERLY_API_KEY is configured.',
-  inputSchema: z.object({}),
-
-  async execute(client: PosterlyClient) {
-    const apiOrigin = client.getBaseUrl();
-    const [latest, apiProbe, authProbe] = await Promise.all([
-      fetchLatestNpmVersion(),
-      probeHostedMcp(apiOrigin),
-      client.hasApiKey() ? client.probeWhoami() : Promise.resolve(null),
-    ]);
-    const updateStatus = describeUpdateStatus(POSTERLY_MCP_VERSION, latest.version, latest.error);
-    const versionMatch = apiProbe.version ? yesNo(apiProbe.version === POSTERLY_MCP_VERSION) : 'unknown';
-    const rows: Array<[string, string | number | boolean]> = [
-      ['Connection type', 'local app process (stdio)'],
-      ['Current server version', POSTERLY_MCP_VERSION],
-      ['Latest npm version', latest.version || 'unknown'],
-      ['Update status', updateStatus],
-      ['posterly API origin', code(apiOrigin)],
-      ['MCP endpoint health', formatApiProbe(apiProbe)],
-      ['Hosted MCP version', apiProbe.version || 'unknown'],
-      ['Version match', versionMatch],
-      ['API key configured', client.hasApiKey()],
-      ['API auth check', formatAuthProbe(authProbe)],
-    ];
-
-    if (authProbe?.ok && authProbe.whoami) {
-      rows.push(
-        ['User', authProbe.whoami.user.email || code(authProbe.whoami.user.id)],
-        ['Default workspace', `${authProbe.whoami.default_workspace.name} (${code(authProbe.whoami.default_workspace.id)})`],
-        ['API scopes', authProbe.whoami.api_key.scopes.join(', ') || 'none'],
-      );
-    }
-
-    return [
-      mdTitle('posterly MCP status'),
-      mdKeyValue(rows),
-      latest.error ? `**Latest check:** ${latest.error}` : '',
-      apiProbe.error ? `**MCP endpoint check:** ${apiProbe.error}` : '',
-      authProbe && !authProbe.ok ? `**API auth check:** ${authProbe.error || 'API key validation failed'}` : '',
-      nextStep({ hasApiKey: client.hasApiKey(), updateStatus, apiProbe, authProbe }),
-    ].filter(Boolean).join('\n\n');
-  },
-};
-
-type HostedMcpProbe = {
-  ok: boolean;
-  status?: number;
-  version?: string;
-  error?: string;
-  durationMs: number;
-};
-
-type AuthProbe = Awaited<ReturnType<PosterlyClient['probeWhoami']>> | null;
-
-async function probeHostedMcp(apiOrigin: string): Promise<HostedMcpProbe> {
-  const startedAt = Date.now();
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 2500);
-
-  try {
-    const res = await fetch(`${resolvePosterlyBaseUrl(apiOrigin)}/api/mcp`, {
-      headers: { Accept: 'application/json' },
-      signal: controller.signal,
-    });
-    const text = await res.text();
-    const data = parseJson(text);
-    if (!res.ok) {
-      return {
-        ok: false,
-        status: res.status,
-        error: formatError(data, text, res.statusText),
-        durationMs: Date.now() - startedAt,
-      };
-    }
-    const version = typeof data?.serverInfo?.version === 'string' ? data.serverInfo.version : undefined;
-    return {
-      ok: Boolean(version),
-      status: res.status,
-      version,
-      error: version ? undefined : 'Hosted MCP response did not include serverInfo.version',
-      durationMs: Date.now() - startedAt,
-    };
-  } catch (err: any) {
-    return {
-      ok: false,
-      error: err?.name === 'AbortError' ? 'timed out after 2500ms' : err?.message || String(err),
-      durationMs: Date.now() - startedAt,
-    };
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function fetchLatestNpmVersion(): Promise<{ version?: string; error?: string }> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 2500);
-
-  try {
-    const res = await fetch(NPM_LATEST_URL, {
-      headers: { Accept: 'application/json' },
-      signal: controller.signal,
-    });
-    if (!res.ok) {
-      return { error: `npm registry returned HTTP ${res.status}` };
-    }
-    const data = await res.json() as { version?: unknown };
-    return typeof data.version === 'string'
-      ? { version: data.version }
-      : { error: 'npm registry response did not include a version' };
-  } catch (err: any) {
-    const reason = err?.name === 'AbortError' ? 'timed out' : err?.message || String(err);
-    return { error: `could not check npm latest: ${reason}` };
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-function describeUpdateStatus(current: string, latest?: string, error?: string): string {
-  if (!latest) return error ? 'unknown' : 'unknown';
-
-  const comparison = compareSemver(current, latest);
-  if (comparison < 0) {
-    return `update available: restart the MCP client or run ${code('npx -y posterly-mcp-server@latest')}`;
-  }
-  if (comparison > 0) {
-    return 'running newer than npm latest; npm may not have been published yet';
-  }
-  return 'current';
-}
-
-function formatApiProbe(probe: HostedMcpProbe): string {
-  if (probe.ok) return `ok (HTTP ${probe.status}, ${probe.durationMs}ms)`;
-  const status = probe.status ? `HTTP ${probe.status}` : 'network';
-  return `failed (${status}, ${probe.durationMs}ms)`;
-}
-
-function formatAuthProbe(probe: AuthProbe): string {
-  if (!probe) return 'skipped (POSTERLY_API_KEY not configured)';
-  if (probe.ok) return `valid (HTTP ${probe.status}, ${probe.durationMs}ms)`;
-  const status = probe.status ? `HTTP ${probe.status}` : 'network';
-  return `failed (${status}, ${probe.durationMs}ms)`;
-}
-
-function nextStep(input: {
-  hasApiKey: boolean;
-  updateStatus: string;
-  apiProbe: HostedMcpProbe;
-  authProbe: AuthProbe;
-}): string {
-  const { hasApiKey, updateStatus, apiProbe, authProbe } = input;
-  if (updateStatus.startsWith('update available')) {
-    return '**Next step:** Restart your MCP client so it pulls `posterly-mcp-server@latest`, then call `get_mcp_status` again.';
-  }
-  if (!apiProbe.ok) {
-    return '**Next step:** Check `POSTERLY_URL` / `POSTERLY_API_BASE_URL`, DNS, and network access to the hosted MCP endpoint, then call `get_mcp_status` again.';
-  }
-  if (!hasApiKey) {
-    return '**Next step:** Add `POSTERLY_API_KEY` after activating API and MCP access, then call `whoami`.';
-  }
-  if (authProbe && !authProbe.ok) {
-    return '**Next step:** Create or reinstall a valid posterly API key, then restart the MCP client and call `get_mcp_status` again.';
-  }
-  return '**Next step:** Call `whoami` to confirm the user, workspace, and scopes before scheduling posts.';
-}
-
-function yesNo(value: boolean): string {
-  return value ? 'yes' : 'no';
-}
-
-function parseJson(text: string): any {
-  try {
-    return text ? JSON.parse(text) : {};
-  } catch {
-    return null;
-  }
-}
-
-function formatError(data: any, fallback: string, statusText: string): string {
-  if (data && typeof data === 'object') {
-    return data.error || data.message || data.code || statusText || 'API request failed';
-  }
-  return fallback || statusText || 'API request failed';
-}
-
-function compareSemver(a: string, b: string): number {
-  const left = parts(a);
-  const right = parts(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (left[i] !== right[i]) return left[i] > right[i] ? 1 : -1;
-  }
-  return 0;
-}
-
-function parts(value: string): [number, number, number] {
-  const nums = value.split(/[.-]/).slice(0, 3).map((part) => Number.parseInt(part, 10));
-  return [
-    Number.isFinite(nums[0]) ? nums[0] : 0,
-    Number.isFinite(nums[1]) ? nums[1] : 0,
-    Number.isFinite(nums[2]) ? nums[2] : 0,
-  ];
-}

package/src/tools/get-performance-profile.ts

@@ -1,47 +0,0 @@
-import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { mdTitle, mdSection, mdKeyValue, mdBullets, mdQuote, mdEmpty, formatPercent, formatDateTime } from '../lib/format.js';
-
-export const getPerformanceProfileTool = {
-  name: 'get_performance_profile',
-  description:
-    "Get the performance profile posterly has derived for a connected account from the last 90 days of per-post analytics. Returns coaching stats (format, timing, caption-length patterns), an engagement-rate trend, and a narrative summary. Keyed by social account ID (from list_accounts or list_brand_accounts). Returns nothing until the account has a derived profile; Google Business Profile and other platforms without per-post analytics never get one. Read-only; requires a Pro plan or higher.",
-  inputSchema: z.object({
-    account_id: z
-      .union([z.string(), z.number()])
-      .describe('The social account ID to inspect (from list_accounts or list_brand_accounts).'),
-  }),
-
-  async execute(client: PosterlyClient, input: { account_id: string | number }) {
-    const { performance_profile, reason } = await client.getAccountPerformanceProfile(input.account_id);
-
-    if (!performance_profile) {
-      const detail = reason === 'platform_not_measurable'
-        ? 'This platform does not produce per-post analytics, so posterly cannot build a performance profile for it.'
-        : reason === 'feature_not_available'
-          ? 'Performance profiles require a Pro plan or higher.'
-          : 'posterly has not built a performance profile for this account yet. It needs about 90 days of tracked posts to learn from.';
-      return mdEmpty('performance profile yet', detail);
-    }
-
-    const label = performance_profile.username
-      ? `@${performance_profile.username}${performance_profile.platform ? ` (${performance_profile.platform})` : ''}`
-      : `account ${performance_profile.social_account_id}`;
-
-    const rate = performance_profile.engagement_rate_avg != null
-      ? formatPercent(performance_profile.engagement_rate_avg * 100)
-      : 'n/a';
-
-    return [
-      mdTitle('Account performance profile', `${label} · last ${performance_profile.window_days ?? 90} days`),
-      performance_profile.narrative_summary ? mdSection('Summary', mdQuote(performance_profile.narrative_summary)) : '',
-      performance_profile.bullets.length ? mdSection('What is working', mdBullets(performance_profile.bullets)) : '',
-      mdSection('Stats', mdKeyValue([
-        ['Posts sampled', performance_profile.sample_size],
-        ['Avg engagement rate', rate],
-        ['Engagement trend', performance_profile.engagement_rate_trend],
-        ['Derived at', formatDateTime(performance_profile.derived_at)],
-      ])),
-    ].filter(Boolean).join('\n\n');
-  },
-};

package/src/tools/get-platform-schema.ts

@@ -1,56 +0,0 @@
-import { z } from 'zod';
-import type { PosterlyClient } from '../lib/api-client.js';
-import { ALL_PLATFORM_INPUTS, SUPPORTED_PLATFORM_IDS } from '../generated/platform-manifest.js';
-
-export const getPlatformSchemaTool = {
-  name: 'get_platform_schema',
-  description:
-    'Get the platform schema for a specific connected account or platform. For Instagram, pass account_id before native tags/collaborators so connection-specific capabilities are returned.',
-  inputSchema: z.object({
-    account_id: z
-      .string()
-      .optional()
-      .describe('Connected account ID from list_accounts. Preferred because it returns account context.'),
-    platform: z
-      .enum(ALL_PLATFORM_INPUTS)
-      .optional()
-      .describe(`Platform ID such as ${SUPPORTED_PLATFORM_IDS.join(', ')}. Set include_planned to inspect planned providers.`),
-    include_planned: z.boolean().optional(),
-  }),
-
-  async execute(
-    client: PosterlyClient,
-    input: { account_id?: string; platform?: string; include_planned?: boolean },
-  ) {
-    const result = await client.getPlatformSchema(input);
-    const schema = result.schema || result.platform || result.platforms?.[0];
-    if (!schema) return JSON.stringify(result, null, 2);
-
-    const fields = schema.settings_schema?.fields || [];
-    const helpers = schema.helper_tools || [];
-    const accountLine = result.account
-      ? `Account: ${(result.account.username as string) || result.account.id} (${result.account.platform})\n`
-      : '';
-    const instagramTaggingLine = result.account?.instagram_tagging
-      ? `Instagram tagging capabilities: ${JSON.stringify(result.account.instagram_tagging)}`
-      : '';
-
-    return [
-      `${schema.label} (${schema.id}) schema`,
-      accountLine.trim(),
-      instagramTaggingLine,
-      `Status: ${schema.status}`,
-      `Post types: ${schema.post_types.join(', ') || 'n/a'}`,
-      `Content limit: ${schema.content_limit ?? 'n/a'}`,
-      `Media: ${JSON.stringify(schema.media)}`,
-      `Analytics: ${schema.analytics_supported ? 'yes' : 'no'}`,
-      fields.length
-        ? `Settings:\n${fields.map((field: any) => `• ${field.key}${field.required ? ' (required)' : ''}: ${field.description}`).join('\n')}`
-        : 'Settings: none',
-      helpers.length
-        ? `Helpers:\n${helpers.map((helper: any) => `• ${helper.name}: ${helper.description}`).join('\n')}`
-        : 'Helpers: none',
-      `Example settings: ${JSON.stringify(schema.settings_schema?.example || {})}`,
-    ].filter(Boolean).join('\n');
-  },
-};