posterly-mcp-server 0.26.0 → 0.27.0

package/dist/tools/validate-post.js

@@ -0,0 +1,28 @@
+import { buildCreatePostPayload, createPostPayloadInputSchema, } from './create-post.js';
+export const validatePostInputSchema = createPostPayloadInputSchema;
+export const validatePostTool = {
+    name: 'validate_post',
+    description: 'Validate and normalize one post without creating it. This does not create records, copy remote media, consume post-item/storage quota, reserve X quota, emit webhooks, or enqueue publication. Third-party media may return remote_media_not_materialized because live create performs storage copy and final byte validation. Use this before showing the final preview and asking for confirmation to call create_post.',
+    inputSchema: validatePostInputSchema,
+    async execute(client, input) {
+        const payload = buildCreatePostPayload(input);
+        const result = await client.validatePost(payload);
+        const lines = [
+            'Post validation passed.',
+            `• Platform: ${result.normalized.platform}`,
+            `• Account ID: ${result.normalized.account_id}`,
+            `• Type: ${result.normalized.post_type}`,
+            `• Scheduled: ${result.normalized.scheduled_at}`,
+            `• Workspace: ${result.normalized.workspace_id || 'personal/default'}`,
+            `• Would create: ${result.would_create.status}`,
+        ];
+        if (result.warnings.length > 0) {
+            lines.push('• Warnings:');
+            for (const warning of result.warnings) {
+                lines.push(`  - ${warning.code}: ${warning.message}`);
+            }
+        }
+        lines.push('Show the final preview and obtain explicit confirmation before calling create_post.');
+        return lines.join('\n');
+    },
+};

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.26.0",
-  "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)",
+  "version": "0.27.0",
+  "mcpName": "io.github.awpthorp/posterly",
+  "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",
   "homepage": "https://www.poster.ly/mcp",
   "repository": {

package/server.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.awpthorp/posterly",
+  "title": "posterly",
+  "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
+  "version": "0.27.0",
+  "websiteUrl": "https://www.poster.ly/mcp",
+  "repository": {
+    "url": "https://github.com/awpthorp/posterly",
+    "source": "github",
+    "subfolder": "mcp-server"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "posterly-mcp-server",
+      "version": "0.27.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "POSTERLY_API_KEY",
+          "description": "posterly API key. Optional for public signup tools; required for authenticated tools.",
+          "format": "string",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://www.poster.ly/api/mcp"
+    }
+  ]
+}

package/src/index.ts

@@ -20,6 +20,8 @@ import { getPostInsightsTool } from './tools/get-post-insights.js';
 import { listPostSuggestionsTool } from './tools/list-post-suggestions.js';
 import { dismissSuggestionTool } from './tools/dismiss-suggestion.js';
 import { createPostTool } from './tools/create-post.js';
+import { validatePostTool } from './tools/validate-post.js';
+import { submitAgentFeedbackTool } from './tools/submit-agent-feedback.js';
 import { createPostsBatchTool } from './tools/create-posts-batch.js';
 import { findSlotTool } from './tools/find-slot.js';
 import { listPostsTool } from './tools/list-posts.js';
@@ -548,6 +550,34 @@ server.tool(
   }
 );
 
+server.tool(
+  submitAgentFeedbackTool.name,
+  submitAgentFeedbackTool.description,
+  submitAgentFeedbackTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await submitAgentFeedbackTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  validatePostTool.name,
+  validatePostTool.description,
+  validatePostTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await validatePostTool.execute(client, input as any);
+      return { content: [{ type: 'text' as const, text }] };
+    } catch (err: any) {
+      return { content: [{ type: 'text' as const, text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 server.tool(
   createPostTool.name,
   createPostTool.description,

package/src/lib/api-client.ts

@@ -188,6 +188,41 @@ export type CreatePostResponse = {
   workspace: { id: string; name: string; is_personal: boolean; resolved_from: 'explicit' | 'account' | 'personal' };
 };
 
+export type ValidatePostResponse = {
+  dry_run: true;
+  valid: true;
+  normalized: {
+    account_id: number;
+    platform: string;
+    post_type: string;
+    scheduled_at: string;
+    workspace_id: string | null;
+  };
+  warnings: Array<{ code: string; message: string }>;
+  would_create: { status: string };
+};
+
+export type AgentFeedbackPayload = {
+  source: 'mcp' | 'cli' | 'rest' | 'skill';
+  tool: string;
+  outcome: 'success' | 'error' | 'abandoned';
+  error_code?: string;
+  client?: string;
+  comment?: string;
+  context?: {
+    request_id?: string;
+    http_status?: number;
+    latency_ms?: number;
+    attempt?: number;
+  };
+};
+
+export type AgentFeedbackResponse = {
+  accepted: true;
+  feedback_id: string;
+  request_id: string;
+};
+
 export type BatchCreatePostsResponse = {
   posts: Array<CreatePostResponse & { index: number; replayed: boolean }>;
   errors: Array<{ index: number; status: number; error: string; validation_errors?: unknown }>;
@@ -1105,6 +1140,14 @@ export class PosterlyClient {
     return this.request('POST', '/posts', data);
   }
 
+  async validatePost(data: CreatePostPayload): Promise<ValidatePostResponse> {
+    return this.request('POST', '/posts', { ...data, dry_run: true });
+  }
+
+  async submitAgentFeedback(data: AgentFeedbackPayload): Promise<AgentFeedbackResponse> {
+    return this.request('POST', '/agent-feedback', data);
+  }
+
   async createPostsBatch(data: { posts: CreatePostPayload[] }): Promise<BatchCreatePostsResponse> {
     return this.request('POST', '/posts/batch', data);
   }

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.26.0';
+export const POSTERLY_MCP_VERSION = '0.27.0';

package/src/tools/create-post.ts

@@ -15,7 +15,7 @@ export const instagramSettingsSchema = z.object({
     .array(z.union([z.string(), z.object({ username: z.string().optional(), label: z.string().optional(), handle: z.string().optional() })]))
     .optional(),
   first_comment: z.string().optional(),
-  media_alt_texts: z.record(z.string()).optional(),
+  media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
   reel_thumb_offset: z.number().nonnegative().optional(),
 });
@@ -24,7 +24,7 @@ export const platformSettingsSchema = z.object({
   __type: z.string().optional(),
   post_type: z.string().optional(),
   content_type: z.string().optional(),
-  media_alt_texts: z.record(z.string()).optional(),
+  media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
   reel_thumb_offset: z.number().nonnegative().optional(),
   // X
@@ -40,13 +40,13 @@ export const platformSettingsSchema = z.object({
   reply_control: z.enum(['everyone', 'accounts_you_follow', 'mentioned_only', 'followers_only', 'parent_post_author_only']).optional(),
   topic_tag: z.string().optional(), // Threads single discovery topic tag
   share_to_instagram: z.boolean().optional(), // Threads: also share the published post to the linked Instagram account as a Story
-  text_attachment: z.record(z.unknown()).optional(),
+  text_attachment: z.record(z.string(), z.unknown()).optional(),
   // Facebook
   text_format_preset_id: z.string().optional(),
   // LinkedIn
   document_title: z.string().optional(),
   document_filename: z.string().optional(),
-  mentions: z.array(z.record(z.unknown())).optional(),
+  mentions: z.array(z.record(z.string(), z.unknown())).optional(),
   thumbnail_url: z.string().optional(),
   thumbnail_method: z.string().optional(),
   // TikTok
@@ -73,9 +73,9 @@ export const platformSettingsSchema = z.object({
   video_cover_url: z.string().optional(),
   cover_image_method: z.enum(['upload', 'frame', 'api']).optional(),
   // Google Business
-  event: z.record(z.unknown()).optional(),
-  offer: z.record(z.unknown()).optional(),
-  cta: z.record(z.unknown()).optional(),
+  event: z.record(z.string(), z.unknown()).optional(),
+  offer: z.record(z.string(), z.unknown()).optional(),
+  cta: z.record(z.string(), z.unknown()).optional(),
   // YouTube
   notify_subscribers: z.boolean().optional(),
   add_shorts_hashtag: z.boolean().optional(),

package/src/tools/submit-agent-feedback.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+const tokenSchema = z.string().regex(/^[a-z0-9][a-z0-9_.:-]{0,63}$/);
+const printableSchema = (maxLength: number) =>
+  z.string().trim().min(1).max(maxLength).refine(
+      (value) => !/[\u0000-\u001f\u007f]/.test(value),
+      'Control characters are not allowed',
+    );
+
+export const submitAgentFeedbackInputSchema = z.object({
+  source: z.enum(['mcp', 'cli', 'rest', 'skill']),
+  tool: tokenSchema,
+  outcome: z.enum(['success', 'error', 'abandoned']),
+  error_code: tokenSchema.optional(),
+  client: printableSchema(80).optional(),
+  comment: printableSchema(1000)
+    .refine(
+      (value) => !/(?:pst_(?:live|test)_|sk-[a-z0-9_-]{12,})/i.test(value),
+      'Comments must not contain secrets',
+    )
+    .optional(),
+  context: z.object({
+    request_id: z.string().regex(/^[a-zA-Z0-9_.:-]{8,80}$/).optional(),
+    http_status: z.number().int().min(100).max(599).optional(),
+    latency_ms: z.number().int().min(0).max(300000).optional(),
+    attempt: z.number().int().min(1).max(20).optional(),
+  }).strict().optional(),
+}).strict();
+
+export type SubmitAgentFeedbackInput = z.infer<typeof submitAgentFeedbackInputSchema>;
+
+export const submitAgentFeedbackTool = {
+  name: 'submit_agent_feedback',
+  description:
+    'Submit bounded private operational telemetry after a concrete posterly workflow outcome. This does not alter product content but writes a private feedback event. Never include API keys, prompts, captions, media URLs, personal data, or fabricated outcomes.',
+  inputSchema: submitAgentFeedbackInputSchema,
+
+  async execute(client: PosterlyClient, input: SubmitAgentFeedbackInput) {
+    const result = await client.submitAgentFeedback(input);
+    return [
+      'Agent feedback accepted.',
+      `• Feedback ID: ${result.feedback_id}`,
+      `• Request ID: ${result.request_id}`,
+    ].join('\n');
+  },
+};

package/src/tools/trigger-platform-helper.ts

@@ -16,7 +16,7 @@ export const triggerPlatformHelperTool = {
       .enum(SUPPORTED_PLATFORM_INPUTS)
       .optional()
       .describe(`Platform hint when no account_id is supplied. Supported: ${SUPPORTED_PLATFORM_IDS.join(', ')}.`),
-    params: z.record(z.unknown()).optional(),
+    params: z.record(z.string(), z.unknown()).optional(),
   }),
 
   async execute(

package/src/tools/update-post.ts

@@ -14,7 +14,7 @@ const instagramSettingsSchema = z.object({
     .array(z.union([z.string(), z.object({ username: z.string().optional(), label: z.string().optional(), handle: z.string().optional() })]))
     .optional(),
   first_comment: z.string().optional(),
-  media_alt_texts: z.record(z.string()).optional(),
+  media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
   reel_thumb_offset: z.number().nonnegative().optional(),
 });
@@ -23,7 +23,7 @@ const platformSettingsSchema = z.object({
   __type: z.string().optional(),
   post_type: z.string().optional(),
   content_type: z.string().optional(),
-  media_alt_texts: z.record(z.string()).optional(),
+  media_alt_texts: z.record(z.string(), z.string()).optional(),
   reel_cover_url: z.string().optional(),
   reel_thumb_offset: z.number().nonnegative().optional(),
   reply_settings: z.enum(['everyone', 'following', 'mentionedUsers', 'subscribers', 'verified']).optional(),
@@ -31,11 +31,11 @@ const platformSettingsSchema = z.object({
   reply_control: z.enum(['everyone', 'accounts_you_follow', 'mentioned_only', 'followers_only', 'parent_post_author_only']).optional(),
   topic_tag: z.string().optional(),
   share_to_instagram: z.boolean().optional(), // Threads: also share the published post to the linked Instagram account as a Story
-  text_attachment: z.record(z.unknown()).optional(),
+  text_attachment: z.record(z.string(), z.unknown()).optional(),
   text_format_preset_id: z.string().optional(),
   document_title: z.string().optional(),
   document_filename: z.string().optional(),
-  mentions: z.array(z.record(z.unknown())).optional(),
+  mentions: z.array(z.record(z.string(), z.unknown())).optional(),
   thumbnail_url: z.string().optional(),
   thumbnail_method: z.string().optional(),
   privacy_level: z.string().optional(),
@@ -57,9 +57,9 @@ const platformSettingsSchema = z.object({
   cover_image_url: z.string().optional(),
   video_cover_url: z.string().optional(),
   cover_image_method: z.enum(['upload', 'frame', 'api']).optional(),
-  event: z.record(z.unknown()).optional(),
-  offer: z.record(z.unknown()).optional(),
-  cta: z.record(z.unknown()).optional(),
+  event: z.record(z.string(), z.unknown()).optional(),
+  offer: z.record(z.string(), z.unknown()).optional(),
+  cta: z.record(z.string(), z.unknown()).optional(),
   notify_subscribers: z.boolean().optional(),
   add_shorts_hashtag: z.boolean().optional(),
   buttons: z.array(z.object({ text: z.string(), url: z.string() })).optional(),

package/src/tools/validate-post.ts

@@ -0,0 +1,41 @@
+import type { PosterlyClient } from '../lib/api-client.js';
+import {
+  buildCreatePostPayload,
+  createPostPayloadInputSchema,
+} from './create-post.js';
+
+export const validatePostInputSchema = createPostPayloadInputSchema;
+
+export type ValidatePostInput = Parameters<typeof buildCreatePostPayload>[0];
+
+export const validatePostTool = {
+  name: 'validate_post',
+  description:
+    'Validate and normalize one post without creating it. This does not create records, copy remote media, consume post-item/storage quota, reserve X quota, emit webhooks, or enqueue publication. Third-party media may return remote_media_not_materialized because live create performs storage copy and final byte validation. Use this before showing the final preview and asking for confirmation to call create_post.',
+  inputSchema: validatePostInputSchema,
+
+  async execute(client: PosterlyClient, input: ValidatePostInput) {
+    const payload = buildCreatePostPayload(input);
+    const result = await client.validatePost(payload);
+
+    const lines = [
+      'Post validation passed.',
+      `• Platform: ${result.normalized.platform}`,
+      `• Account ID: ${result.normalized.account_id}`,
+      `• Type: ${result.normalized.post_type}`,
+      `• Scheduled: ${result.normalized.scheduled_at}`,
+      `• Workspace: ${result.normalized.workspace_id || 'personal/default'}`,
+      `• Would create: ${result.would_create.status}`,
+    ];
+
+    if (result.warnings.length > 0) {
+      lines.push('• Warnings:');
+      for (const warning of result.warnings) {
+        lines.push(`  - ${warning.code}: ${warning.message}`);
+      }
+    }
+
+    lines.push('Show the final preview and obtain explicit confirmation before calling create_post.');
+    return lines.join('\n');
+  },
+};