posterly-mcp-server 0.19.10 → 0.20.0

package/README.md

@@ -14,7 +14,7 @@ This package gives Claude Desktop, Cursor, Windsurf, Cline, and other local MCP
 - generate images
 - read account and post analytics
 
-Posterly also exposes the same authenticated toolset over HTTP at [poster.ly/mcp](https://www.poster.ly/mcp), but this npm package is the local `stdio` transport.
+Posterly also exposes the same authenticated toolset over HTTP at [poster.ly/mcp](https://www.poster.ly/mcp), but this npm package is the local `stdio` connection for desktop AI clients.
 
 ## Requirements
 
@@ -108,11 +108,11 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.19.10` exposes 56 tools.
+`posterly-mcp-server@0.20.0` exposes 56 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
-- `get_mcp_status` (show the installed server version, latest npm version, API origin, API key presence, and update guidance)
+- `get_mcp_status` (show the installed server version, latest npm version, MCP endpoint health, API auth health, and update guidance)
 - `get_agent_signup_info`
 - `start_signup` (start paid signup and return a Posterly checkout handoff URL)
 - `get_signup_session` (poll checkout, payment, password, and agent-access status)

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

@@ -500,6 +500,14 @@ export declare class PosterlyClient {
     private apiKey;
     constructor(apiKey?: string, baseUrl?: string);
     hasApiKey(): boolean;
+    getBaseUrl(): string;
+    probeWhoami(timeoutMs?: number): Promise<{
+        ok: boolean;
+        status?: number;
+        error?: string;
+        durationMs: number;
+        whoami?: Whoami;
+    }>;
     private requireApiKey;
     private request;
     private publicRequest;

package/dist/lib/api-client.js

@@ -10,6 +10,59 @@ export class PosterlyClient {
     hasApiKey() {
         return Boolean(this.apiKey);
     }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    async probeWhoami(timeoutMs = 2500) {
+        const startedAt = Date.now();
+        if (!this.apiKey) {
+            return {
+                ok: false,
+                error: 'POSTERLY_API_KEY is not configured',
+                durationMs: 0,
+            };
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const res = await fetch(`${this.baseUrl}/api/v1/whoami`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    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: formatProbeError(data, text, res.statusText),
+                    durationMs: Date.now() - startedAt,
+                };
+            }
+            return {
+                ok: true,
+                status: res.status,
+                durationMs: Date.now() - startedAt,
+                whoami: data,
+            };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: err?.name === 'AbortError'
+                    ? `timed out after ${timeoutMs}ms`
+                    : err?.message || String(err),
+                durationMs: Date.now() - startedAt,
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
     requireApiKey() {
         if (!this.apiKey) {
             throw new Error('Posterly access is not installed yet. Use start_signup to begin paid setup, or set POSTERLY_API_KEY after signup.');
@@ -403,6 +456,20 @@ export function resolvePosterlyBaseUrl(baseUrl) {
         return configured.replace(/\/api\/v1\/?$/, '').replace(/\/$/, '');
     }
 }
+function parseJson(text) {
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch {
+        return null;
+    }
+}
+function formatProbeError(data, fallback, statusText) {
+    if (data && typeof data === 'object') {
+        return data.error || data.message || data.code || statusText || 'API request failed';
+    }
+    return fallback || statusText || 'API request failed';
+}
 function guessContentType(filename) {
     const ext = filename.split('.').pop()?.toLowerCase();
     const map = {

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.19.10";
+export declare const POSTERLY_MCP_VERSION = "0.20.0";

package/dist/lib/version.js

@@ -1 +1 @@
-export const POSTERLY_MCP_VERSION = '0.19.10';
+export const POSTERLY_MCP_VERSION = '0.20.0';

package/dist/tools/get-agent-signup-info.js

@@ -13,7 +13,7 @@ export const getAgentSignupInfoTool = {
             authState,
             '',
             'Pre-auth tools:',
-            '- get_mcp_status: checks the installed server version, latest npm version, API origin, and whether POSTERLY_API_KEY is configured.',
+            '- get_mcp_status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
             '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
             '- get_signup_session: polls checkout, payment, password, and agent-access status.',
             '',

package/dist/tools/get-mcp-status.js

@@ -5,26 +5,81 @@ 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, API endpoint, API key presence, and update guidance. Safe to call before POSTERLY_API_KEY is configured.',
+    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) {
-        const latest = await fetchLatestNpmVersion();
+        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 = [
+            ['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([
-                ['Transport', 'stdio'],
-                ['Current server version', POSTERLY_MCP_VERSION],
-                ['Latest npm version', latest.version || 'unknown'],
-                ['Update status', updateStatus],
-                ['Posterly API origin', code(resolvePosterlyBaseUrl())],
-                ['API key configured', client.hasApiKey()],
-            ]),
+            mdKeyValue(rows),
             latest.error ? `**Latest check:** ${latest.error}` : '',
-            nextStep(client.hasApiKey(), updateStatus),
+            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');
     },
 };
+async function probeHostedMcp(apiOrigin) {
+    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) {
+        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() {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 2500);
@@ -61,15 +116,53 @@ function describeUpdateStatus(current, latest, error) {
     }
     return 'current';
 }
-function nextStep(hasApiKey, updateStatus) {
+function formatApiProbe(probe) {
+    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) {
+    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) {
+    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) {
+    return value ? 'yes' : 'no';
+}
+function parseJson(text) {
+    try {
+        return text ? JSON.parse(text) : {};
+    }
+    catch {
+        return null;
+    }
+}
+function formatError(data, fallback, statusText) {
+    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, b) {
     const left = parts(a);
     const right = parts(b);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.19.10",
+  "version": "0.20.0",
   "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

@@ -517,6 +517,67 @@ export class PosterlyClient {
     return Boolean(this.apiKey);
   }
 
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  async probeWhoami(timeoutMs = 2500): Promise<{
+    ok: boolean;
+    status?: number;
+    error?: string;
+    durationMs: number;
+    whoami?: Whoami;
+  }> {
+    const startedAt = Date.now();
+    if (!this.apiKey) {
+      return {
+        ok: false,
+        error: 'POSTERLY_API_KEY is not configured',
+        durationMs: 0,
+      };
+    }
+
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const res = await fetch(`${this.baseUrl}/api/v1/whoami`, {
+        method: 'GET',
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          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: formatProbeError(data, text, res.statusText),
+          durationMs: Date.now() - startedAt,
+        };
+      }
+      return {
+        ok: true,
+        status: res.status,
+        durationMs: Date.now() - startedAt,
+        whoami: data as Whoami,
+      };
+    } catch (err: any) {
+      return {
+        ok: false,
+        error: err?.name === 'AbortError'
+          ? `timed out after ${timeoutMs}ms`
+          : err?.message || String(err),
+        durationMs: Date.now() - startedAt,
+      };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
   private requireApiKey(): void {
     if (!this.apiKey) {
       throw new Error(
@@ -1146,6 +1207,21 @@ export function resolvePosterlyBaseUrl(baseUrl?: string): string {
   }
 }
 
+function parseJson(text: string): any {
+  try {
+    return text ? JSON.parse(text) : {};
+  } catch {
+    return null;
+  }
+}
+
+function formatProbeError(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 guessContentType(filename: string): string {
   const ext = filename.split('.').pop()?.toLowerCase();
   const map: Record<string, string> = {

package/src/lib/version.ts

@@ -1 +1 @@
-export const POSTERLY_MCP_VERSION = '0.19.10';
+export const POSTERLY_MCP_VERSION = '0.20.0';

package/src/tools/get-agent-signup-info.ts

@@ -18,7 +18,7 @@ export const getAgentSignupInfoTool = {
       authState,
       '',
       'Pre-auth tools:',
-      '- get_mcp_status: checks the installed server version, latest npm version, API origin, and whether POSTERLY_API_KEY is configured.',
+      '- get_mcp_status: checks the installed server version, latest npm version, MCP endpoint health, API auth health, and whether POSTERLY_API_KEY is configured.',
       '- start_signup: starts paid signup and returns a Posterly checkout handoff URL plus a signup poll URL.',
       '- get_signup_session: polls checkout, payment, password, and agent-access status.',
       '',

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

@@ -9,29 +9,99 @@ 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, API endpoint, API key presence, and update guidance. Safe to call before POSTERLY_API_KEY is configured.',
+    '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 latest = await fetchLatestNpmVersion();
+    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([
-        ['Transport', 'stdio'],
-        ['Current server version', POSTERLY_MCP_VERSION],
-        ['Latest npm version', latest.version || 'unknown'],
-        ['Update status', updateStatus],
-        ['Posterly API origin', code(resolvePosterlyBaseUrl())],
-        ['API key configured', client.hasApiKey()],
-      ]),
+      mdKeyValue(rows),
       latest.error ? `**Latest check:** ${latest.error}` : '',
-      nextStep(client.hasApiKey(), updateStatus),
+      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);
@@ -69,16 +139,60 @@ function describeUpdateStatus(current: string, latest?: string, error?: string):
   return 'current';
 }
 
-function nextStep(hasApiKey: boolean, updateStatus: string): string {
+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);