posterly-mcp-server 0.23.1 → 0.23.2

package/README.md

@@ -182,7 +182,13 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `test_webhook` (send a signed test delivery after explicit confirmation)
 - `get_x_posting_quota`
 
-Analytics tools currently support Instagram, LinkedIn, Google Business Profile, Pinterest, and YouTube.
+Analytics tools currently support Instagram, Facebook Pages, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads.
+
+## Media uploads
+
+This npm/stdio server can read local file paths. When `upload_media` receives a larger local file, it automatically requests a signed upload URL and uploads the raw bytes before returning the public media URL.
+
+The hosted HTTP MCP endpoint cannot do that for local files by itself because MCP tool calls are JSON-only. On hosted HTTP MCP, `upload_media` is for small base64 uploads up to 5MB decoded. For larger media there, use `upload_media_from_url` for public direct media URLs, or call `create_signed_upload` only from clients that can also `PUT` the raw file bytes to the returned `upload_url`.
 
 ## What the brand tools are for
 

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

@@ -967,3 +967,16 @@ export declare class PosterlyClient {
     }>;
 }
 export declare function resolvePosterlyBaseUrl(baseUrl?: string): string;
+type PosterlyBaseUrlInspection = {
+    valid: boolean;
+    secure: boolean;
+    protocol?: string;
+    host?: string;
+    trustedPosterlyHost: boolean;
+    localDevelopmentHost: boolean;
+    warnings: string[];
+    message: string;
+};
+export declare function inspectPosterlyBaseUrl(baseUrl: string): PosterlyBaseUrlInspection;
+export declare function validatePosterlyBaseUrlForKeyUse(baseUrl: string): void;
+export {};

package/dist/lib/api-client.js

@@ -6,6 +6,9 @@ export class PosterlyClient {
     constructor(apiKey, baseUrl) {
         this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
         this.baseUrl = resolvePosterlyBaseUrl(baseUrl);
+        if (this.apiKey) {
+            validatePosterlyBaseUrlForKeyUse(this.baseUrl);
+        }
     }
     hasApiKey() {
         return Boolean(this.apiKey);
@@ -485,6 +488,73 @@ export function resolvePosterlyBaseUrl(baseUrl) {
         return configured.replace(/\/api\/v1\/?$/, '').replace(/\/$/, '');
     }
 }
+const TRUSTED_POSTERLY_HOSTS = new Set(['poster.ly', 'www.poster.ly']);
+function flagEnabled(name) {
+    const value = (process.env[name] || '').trim().toLowerCase();
+    return value === 'true' || value === '1' || value === 'yes';
+}
+function normalizeHostname(hostname) {
+    return hostname.toLowerCase().replace(/^\[|\]$/g, '');
+}
+function isLocalHost(hostname) {
+    const normalized = normalizeHostname(hostname);
+    return (normalized === 'localhost' ||
+        normalized.endsWith('.localhost') ||
+        normalized === '127.0.0.1' ||
+        normalized === '::1');
+}
+export function inspectPosterlyBaseUrl(baseUrl) {
+    try {
+        const url = new URL(baseUrl);
+        const hostname = normalizeHostname(url.hostname);
+        const local = isLocalHost(hostname);
+        const trustedPosterlyHost = TRUSTED_POSTERLY_HOSTS.has(hostname);
+        const secure = url.protocol === 'https:' || (url.protocol === 'http:' && local);
+        const warnings = [];
+        if (!trustedPosterlyHost) {
+            warnings.push(local ? 'local_development_host' : 'custom_host');
+        }
+        if (!secure) {
+            warnings.push('insecure_non_local_url');
+        }
+        return {
+            valid: true,
+            secure,
+            protocol: url.protocol.replace(/:$/, ''),
+            host: url.host,
+            trustedPosterlyHost,
+            localDevelopmentHost: local,
+            warnings,
+            message: secure
+                ? 'Base URL is secure for API-key requests.'
+                : 'Non-local HTTP URLs are blocked for API-key requests.',
+        };
+    }
+    catch {
+        return {
+            valid: false,
+            secure: false,
+            trustedPosterlyHost: false,
+            localDevelopmentHost: false,
+            warnings: ['invalid_url'],
+            message: 'Base URL must include a scheme and host, for example https://www.poster.ly.',
+        };
+    }
+}
+export function validatePosterlyBaseUrlForKeyUse(baseUrl) {
+    const check = inspectPosterlyBaseUrl(baseUrl);
+    if (!check.valid) {
+        throw new Error(`${check.message} Received: ${baseUrl}`);
+    }
+    if (!check.secure && !flagEnabled('POSTERLY_ALLOW_INSECURE_URL')) {
+        throw new Error(`Refusing to send an API key to ${baseUrl}. Use https, http://localhost for local development, or set POSTERLY_ALLOW_INSECURE_URL=true only for a trusted private development endpoint.`);
+    }
+    if (!check.trustedPosterlyHost &&
+        !check.localDevelopmentHost &&
+        !flagEnabled('POSTERLY_ALLOW_CUSTOM_BASE_URL')) {
+        throw new Error(`Refusing to send an API key to custom host ${baseUrl}. Set POSTERLY_ALLOW_CUSTOM_BASE_URL=true only for a trusted Posterly deployment.`);
+    }
+}
 function parseJson(text) {
     try {
         return text ? JSON.parse(text) : {};

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

@@ -2,7 +2,7 @@ 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 and supports presentation: compact, table, or json.',
+    description: 'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
     inputSchema: z.object({
         account_id: z
             .number()

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

@@ -2,7 +2,7 @@ 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. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
+    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, YouTube, and Threads. 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()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.23.1",
+  "version": "0.23.2",
   "description": "MCP server for posterly: schedule and publish social media posts across 11 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",

package/src/lib/api-client.ts

@@ -638,6 +638,9 @@ export class PosterlyClient {
   constructor(apiKey?: string, baseUrl?: string) {
     this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
     this.baseUrl = resolvePosterlyBaseUrl(baseUrl);
+    if (this.apiKey) {
+      validatePosterlyBaseUrlForKeyUse(this.baseUrl);
+    }
   }
 
   hasApiKey(): boolean {
@@ -1383,6 +1386,101 @@ export function resolvePosterlyBaseUrl(baseUrl?: string): string {
   }
 }
 
+const TRUSTED_POSTERLY_HOSTS = new Set(['poster.ly', 'www.poster.ly']);
+
+type PosterlyBaseUrlInspection = {
+  valid: boolean;
+  secure: boolean;
+  protocol?: string;
+  host?: string;
+  trustedPosterlyHost: boolean;
+  localDevelopmentHost: boolean;
+  warnings: string[];
+  message: string;
+};
+
+function flagEnabled(name: string): boolean {
+  const value = (process.env[name] || '').trim().toLowerCase();
+  return value === 'true' || value === '1' || value === 'yes';
+}
+
+function normalizeHostname(hostname: string): string {
+  return hostname.toLowerCase().replace(/^\[|\]$/g, '');
+}
+
+function isLocalHost(hostname: string): boolean {
+  const normalized = normalizeHostname(hostname);
+  return (
+    normalized === 'localhost' ||
+    normalized.endsWith('.localhost') ||
+    normalized === '127.0.0.1' ||
+    normalized === '::1'
+  );
+}
+
+export function inspectPosterlyBaseUrl(baseUrl: string): PosterlyBaseUrlInspection {
+  try {
+    const url = new URL(baseUrl);
+    const hostname = normalizeHostname(url.hostname);
+    const local = isLocalHost(hostname);
+    const trustedPosterlyHost = TRUSTED_POSTERLY_HOSTS.has(hostname);
+    const secure = url.protocol === 'https:' || (url.protocol === 'http:' && local);
+    const warnings: string[] = [];
+
+    if (!trustedPosterlyHost) {
+      warnings.push(local ? 'local_development_host' : 'custom_host');
+    }
+    if (!secure) {
+      warnings.push('insecure_non_local_url');
+    }
+
+    return {
+      valid: true,
+      secure,
+      protocol: url.protocol.replace(/:$/, ''),
+      host: url.host,
+      trustedPosterlyHost,
+      localDevelopmentHost: local,
+      warnings,
+      message: secure
+        ? 'Base URL is secure for API-key requests.'
+        : 'Non-local HTTP URLs are blocked for API-key requests.',
+    };
+  } catch {
+    return {
+      valid: false,
+      secure: false,
+      trustedPosterlyHost: false,
+      localDevelopmentHost: false,
+      warnings: ['invalid_url'],
+      message: 'Base URL must include a scheme and host, for example https://www.poster.ly.',
+    };
+  }
+}
+
+export function validatePosterlyBaseUrlForKeyUse(baseUrl: string): void {
+  const check = inspectPosterlyBaseUrl(baseUrl);
+  if (!check.valid) {
+    throw new Error(`${check.message} Received: ${baseUrl}`);
+  }
+
+  if (!check.secure && !flagEnabled('POSTERLY_ALLOW_INSECURE_URL')) {
+    throw new Error(
+      `Refusing to send an API key to ${baseUrl}. Use https, http://localhost for local development, or set POSTERLY_ALLOW_INSECURE_URL=true only for a trusted private development endpoint.`
+    );
+  }
+
+  if (
+    !check.trustedPosterlyHost &&
+    !check.localDevelopmentHost &&
+    !flagEnabled('POSTERLY_ALLOW_CUSTOM_BASE_URL')
+  ) {
+    throw new Error(
+      `Refusing to send an API key to custom host ${baseUrl}. Set POSTERLY_ALLOW_CUSTOM_BASE_URL=true only for a trusted Posterly deployment.`
+    );
+  }
+}
+
 function parseJson(text: string): any {
   try {
     return text ? JSON.parse(text) : {};

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

@@ -8,7 +8,7 @@ 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 and supports presentation: compact, table, or json.',
+    'Get daily analytics snapshots and a period summary for a connected social account. Supports Instagram, Facebook, LinkedIn, Google Business Profile, Pinterest, YouTube, and Threads. Uses API-provided display_metrics for platform-native dashboard labels and supports presentation: compact, table, or json.',
   inputSchema: z.object({
     account_id: z
       .number()

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

@@ -7,7 +7,7 @@ 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. presentation controls output: compact for Telegram/mobile, table for Markdown clients, json for custom chart/card renderers.',
+    '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, YouTube, and Threads. 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()