posterly-mcp-server 0.44.0 → 0.45.0

package/src/tools/whoami.ts

@@ -1,39 +1,262 @@
 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, mdTable, mdTitle } from '../lib/format.js';
+import { validateArgs, type ToolContext } from '../lib/tool-runtime.js';
+
+const NPM_LATEST_URL = 'https://registry.npmjs.org/posterly-mcp-server/latest';
 
 export const whoamiTool = {
   name: 'whoami',
   description:
-    'Return the authenticated user, API key scopes, workspaces, and onboarding next step. ALWAYS call this at the start of a session. If onboarding.completed is false, walk the remaining onboarding steps IN THIS conversation (about you, connect, brand voice, first post). Do not send the user to /onboarding-v2 or the dashboard composer wizard.',
-  inputSchema: z.object({}),
-
-  async execute(client: PosterlyClient) {
-    const info = await client.whoami();
-
-    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'],
-        ['Onboarding', info.onboarding?.completed ? 'complete' : info.onboarding?.next_step_label || 'unknown'],
-      ]),
-      info.onboarding && !info.onboarding.completed
-        ? `**Onboarding next:** ${info.onboarding.next_step_label}. ${info.onboarding.instruction}`
-        : '',
-      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.',
-    ].filter(Boolean).join('\n\n');
+    'Who you are and how posterly is connected. view=identity (default): the authenticated user, API key scopes, workspaces, and onboarding next step. ALWAYS call this at the start of a session; if onboarding.completed is false, walk the remaining onboarding steps IN THIS conversation (about you, connect, brand voice, first post) and do not send the user to /onboarding-v2 or the dashboard composer wizard. view=status: MCP server version, latest npm version, endpoint and API key health, and update guidance; works before POSTERLY_API_KEY is configured.',
+  inputSchema: z.object({
+    view: z
+      .enum(['identity', 'status'])
+      .optional()
+      .describe('identity (default): user, scopes, workspaces, onboarding. status: MCP server and connection health.'),
+  }),
+  /** The old tools' exact input schemas, for alias calls (see alias-transport.ts). */
+  legacySchemas: {
+    get_mcp_status: z.object({}),
+  },
+
+  async execute(client: PosterlyClient, input: { view?: 'identity' | 'status' }, ctx: ToolContext) {
+    const { mode } = validateArgs(ctx, 'whoami', input);
+    if (mode === 'status') return mcpStatus(client);
+    return identity(client, ctx);
   },
 };
+
+async function identity(client: PosterlyClient, ctx: ToolContext): Promise<string> {
+  const info = await client.whoami();
+
+  const text = [
+    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'],
+      ['Onboarding', info.onboarding?.completed ? 'complete' : info.onboarding?.next_step_label || 'unknown'],
+    ]),
+    info.onboarding && !info.onboarding.completed
+      ? `**Onboarding next:** ${info.onboarding.next_step_label}. ${info.onboarding.instruction}`
+      : '',
+    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.',
+  ].filter(Boolean).join('\n\n');
+
+  // Only when tool sets are filtered, so the default answer is unchanged.
+  const toolsets = ctx.toolsets;
+  if (!toolsets || toolsets.all) return text;
+  return `${text}\n\n**Tool sets:** ${toolsets.enabled.join(', ')} are listed in this connection. Every tool can still be called by name. To list every set, unset POSTERLY_TOOLSETS (or set it to all) and restart the MCP client.`;
+}
+
+async function mcpStatus(client: PosterlyClient): Promise<string> {
+  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 `whoami` with `view: "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 `whoami` with `view: "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 `whoami` with `view: "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/tool-annotations.json

@@ -3,237 +3,164 @@
     "get_agent_signup_info",
     "start_signup",
     "get_signup_session",
-    "get_mcp_status",
     "whoami",
+    "create_api_key",
+    "delete_api_key",
+    "list_workspace_members",
+    "manage_workspace_member",
     "list_accounts",
     "disconnect_account",
-    "get_connect_link",
     "connect_account",
     "create_connect_session",
-    "get_connect_session",
-    "create_api_key",
-    "delete_api_key",
-    "get_credits",
-    "get_subscription",
-    "cancel_subscription",
-    "pause_subscription",
-    "resume_subscription",
-    "downgrade_subscription",
     "list_oauth_clients",
-    "create_oauth_client",
-    "update_oauth_client",
-    "delete_oauth_client",
+    "manage_oauth_client",
     "list_platforms",
-    "get_platform_schema",
     "trigger_platform_helper",
     "list_brands",
-    "get_brand",
-    "list_brand_accounts",
-    "get_brand_profile",
-    "get_learned_voice",
-    "get_performance_profile",
-    "get_post_insights",
     "list_post_suggestions",
     "dismiss_suggestion",
+    "list_posts",
+    "get_post",
+    "ask_support",
+    "find_available_slot",
     "submit_agent_feedback",
     "submit_product_feedback",
     "validate_post",
     "create_post",
     "create_posts_batch",
-    "find_available_slot",
-    "list_posts",
+    "update_post",
+    "delete_post",
+    "get_x_posting_quota",
     "upload_media",
-    "upload_media_from_url",
     "create_signed_upload",
     "create_media_drop",
     "list_media",
     "get_video_options",
     "run_video_function",
     "generate_video",
-    "get_video_job",
-    "get_image_job",
+    "list_jobs",
     "generate_captions",
     "generate_image",
-    "get_post",
-    "get_post_missing",
-    "ask_support",
-    "update_post",
-    "update_post_status",
-    "update_post_release_id",
-    "delete_post",
-    "delete_comment",
-    "delete_post_group",
-    "get_account_analytics",
-    "get_post_analytics",
+    "list_analytics",
     "list_google_business_reviews",
-    "get_google_business_review_link",
     "audit_google_business_profile",
-    "suggest_google_business_review_reply",
-    "reply_google_business_review",
-    "delete_google_business_review_reply",
+    "manage_google_business_review",
     "list_google_business_media",
-    "add_google_business_media",
-    "delete_google_business_media",
+    "manage_google_business_media",
+    "list_conversations",
+    "manage_conversation",
+    "list_comments",
+    "manage_comment",
     "list_activity",
-    "get_updates",
     "list_webhooks",
     "create_webhook",
-    "update_webhook",
-    "delete_webhook",
-    "test_webhook",
-    "get_x_posting_quota",
-    "list_conversations",
-    "get_conversation",
-    "send_message",
-    "list_comments",
-    "get_comment",
-    "reply_to_comment",
-    "update_comment",
-    "sync_inbox",
-    "list_workspace_members",
-    "manage_workspace_member"
+    "manage_webhook",
+    "get_credits",
+    "get_subscription",
+    "cancel_subscription",
+    "pause_subscription",
+    "resume_subscription",
+    "downgrade_subscription",
+    "get_updates"
   ],
   "readOnlyTools": [
     "get_agent_signup_info",
     "get_signup_session",
-    "get_mcp_status",
     "whoami",
+    "list_workspace_members",
     "list_accounts",
-    "get_connect_link",
-    "get_connect_session",
-    "get_credits",
-    "get_subscription",
     "list_oauth_clients",
     "list_platforms",
-    "get_platform_schema",
     "trigger_platform_helper",
     "list_brands",
-    "get_brand",
-    "list_brand_accounts",
-    "get_brand_profile",
-    "get_learned_voice",
-    "get_performance_profile",
-    "get_post_insights",
     "list_post_suggestions",
-    "validate_post",
-    "find_available_slot",
     "list_posts",
+    "get_post",
+    "find_available_slot",
+    "validate_post",
+    "get_x_posting_quota",
     "list_media",
     "get_video_options",
-    "get_video_job",
-    "get_image_job",
-    "get_post",
-    "get_post_missing",
-    "get_account_analytics",
-    "get_post_analytics",
+    "run_video_function",
+    "list_jobs",
+    "list_analytics",
     "list_google_business_reviews",
-    "get_google_business_review_link",
     "audit_google_business_profile",
     "list_google_business_media",
-    "list_activity",
-    "get_updates",
-    "list_webhooks",
-    "get_x_posting_quota",
     "list_conversations",
-    "get_conversation",
     "list_comments",
-    "get_comment",
-    "list_workspace_members"
+    "list_activity",
+    "list_webhooks",
+    "get_credits",
+    "get_subscription",
+    "get_updates"
   ],
   "destructiveTools": [
-    "disconnect_account",
     "delete_api_key",
-    "cancel_subscription",
-    "pause_subscription",
-    "downgrade_subscription",
-    "update_oauth_client",
-    "delete_oauth_client",
+    "manage_workspace_member",
+    "disconnect_account",
+    "manage_oauth_client",
     "dismiss_suggestion",
     "update_post",
-    "update_post_status",
     "delete_post",
-    "delete_comment",
-    "delete_post_group",
-    "reply_google_business_review",
-    "delete_google_business_review_reply",
-    "delete_google_business_media",
-    "update_webhook",
-    "delete_webhook",
-    "manage_workspace_member"
+    "manage_google_business_review",
+    "manage_google_business_media",
+    "manage_comment",
+    "manage_webhook",
+    "cancel_subscription",
+    "pause_subscription",
+    "downgrade_subscription"
   ],
   "idempotentMutationTools": [
-    "connect_account",
-    "disconnect_account",
     "delete_api_key",
-    "cancel_subscription",
-    "pause_subscription",
-    "resume_subscription",
-    "downgrade_subscription",
-    "update_oauth_client",
-    "delete_oauth_client",
+    "disconnect_account",
+    "connect_account",
     "dismiss_suggestion",
     "update_post",
-    "update_post_status",
-    "update_post_release_id",
     "delete_post",
-    "delete_comment",
-    "delete_post_group",
-    "reply_google_business_review",
-    "delete_google_business_review_reply",
-    "delete_google_business_media",
-    "update_webhook",
-    "delete_webhook",
-    "update_comment"
+    "cancel_subscription",
+    "pause_subscription",
+    "resume_subscription",
+    "downgrade_subscription"
   ],
   "openWorldTools": [
     "start_signup",
     "get_signup_session",
-    "get_mcp_status",
+    "whoami",
+    "manage_workspace_member",
+    "list_accounts",
     "disconnect_account",
     "connect_account",
     "create_connect_session",
-    "get_connect_session",
-    "get_credits",
-    "get_subscription",
-    "cancel_subscription",
-    "pause_subscription",
-    "resume_subscription",
-    "downgrade_subscription",
     "trigger_platform_helper",
+    "ask_support",
     "validate_post",
     "create_post",
     "create_posts_batch",
-    "upload_media_from_url",
+    "get_x_posting_quota",
+    "upload_media",
     "create_signed_upload",
     "create_media_drop",
     "run_video_function",
     "generate_video",
-    "get_video_job",
-    "get_image_job",
+    "list_jobs",
     "generate_captions",
     "generate_image",
-    "ask_support",
-    "get_account_analytics",
-    "get_post_analytics",
+    "list_analytics",
     "list_google_business_reviews",
-    "get_google_business_review_link",
     "audit_google_business_profile",
-    "suggest_google_business_review_reply",
-    "reply_google_business_review",
-    "delete_google_business_review_reply",
+    "manage_google_business_review",
     "list_google_business_media",
-    "add_google_business_media",
-    "delete_google_business_media",
+    "manage_google_business_media",
+    "manage_conversation",
+    "manage_comment",
     "create_webhook",
-    "update_webhook",
-    "delete_webhook",
-    "test_webhook",
-    "get_x_posting_quota",
-    "send_message",
-    "reply_to_comment",
-    "update_comment",
-    "delete_comment",
-    "sync_inbox",
-    "manage_workspace_member"
+    "manage_webhook",
+    "get_credits",
+    "get_subscription",
+    "cancel_subscription",
+    "pause_subscription",
+    "resume_subscription",
+    "downgrade_subscription"
   ]
 }