postproxy-mcp 0.1.0

package/src/tools/post.ts

@@ -0,0 +1,338 @@
+/**
+ * Post tools: post.publish, post.status, post.delete
+ */
+
+import type { PostProxyClient } from "../api/client.js";
+import { PostPublishSchema } from "../utils/validation.js";
+import { generateIdempotencyKey } from "../utils/idempotency.js";
+import { createError, ErrorCodes } from "../utils/errors.js";
+import { logError } from "../utils/logger.js";
+import { handleProfilesList } from "./profiles.js";
+
+export async function handlePostPublish(
+  client: PostProxyClient,
+  args: {
+    content: string;
+    targets: string[];
+    schedule?: string;
+    media?: string[];
+    idempotency_key?: string;
+    require_confirmation?: boolean;
+    draft?: boolean;
+    platforms?: Record<string, Record<string, any>>;
+  }
+) {
+  // Validate input
+  try {
+    PostPublishSchema.parse(args);
+  } catch (error: any) {
+    throw createError(ErrorCodes.VALIDATION_ERROR, `Invalid input: ${error.message}`);
+  }
+
+  // If require_confirmation, return summary without publishing
+  if (args.require_confirmation) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              summary: {
+                targets: args.targets,
+                content_preview: args.content.substring(0, 100) + (args.content.length > 100 ? "..." : ""),
+                media_count: args.media?.length || 0,
+                schedule_time: args.schedule,
+                draft: args.draft || false,
+                platforms: args.platforms || {},
+              },
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+
+  // Get profiles to convert target IDs to platform names
+  const profilesResult = await handleProfilesList(client);
+  const profilesData = JSON.parse(profilesResult.content[0]?.text || "{}");
+  const targetsMap = new Map<string, any>();
+  for (const target of profilesData.targets || []) {
+    targetsMap.set(target.id, target);
+  }
+
+  // Convert target IDs to platform names (API expects platform names, not IDs)
+  const platformNames: string[] = [];
+  for (const targetId of args.targets) {
+    const target = targetsMap.get(targetId);
+    if (!target) {
+      throw createError(ErrorCodes.TARGET_NOT_FOUND, `Target ${targetId} not found`);
+    }
+    platformNames.push(target.platform); // platform name (e.g., "twitter")
+  }
+
+  // Validate that platforms keys match platform names if platforms are provided
+  if (args.platforms) {
+    const platformKeys = Object.keys(args.platforms);
+    const invalidPlatforms = platformKeys.filter(
+      (key) => !platformNames.includes(key)
+    );
+    if (invalidPlatforms.length > 0) {
+      throw createError(
+        ErrorCodes.VALIDATION_ERROR,
+        `Platform parameters specified for platforms not in targets: ${invalidPlatforms.join(", ")}. Available platforms: ${platformNames.join(", ")}`
+      );
+    }
+  }
+
+  // Generate idempotency key if not provided
+  const idempotencyKey = args.idempotency_key || generateIdempotencyKey(
+    args.content,
+    args.targets,
+    args.schedule
+  );
+
+  // Validate draft parameter is correctly passed
+  // Ensure draft is explicitly set (true, false, or undefined) and will be handled correctly
+  const draftValue = args.draft !== undefined ? args.draft : undefined;
+
+  // Create post
+  try {
+    const response = await client.createPost({
+      content: args.content,
+      profiles: platformNames, // API expects platform names, not profile IDs
+      schedule: args.schedule,
+      media: args.media,
+      idempotency_key: idempotencyKey,
+      draft: draftValue, // Explicitly pass draft value (true, false, or undefined)
+      platforms: args.platforms, // Platform-specific parameters
+    });
+
+    // Check if draft was requested but API ignored it
+    // Use strict boolean comparison to ensure we catch all cases
+    const wasDraftRequested = args.draft === true;
+    const isDraftInResponse = Boolean(response.draft) === true;
+    const wasProcessedImmediately = response.status === "processed" && wasDraftRequested;
+
+    // Draft is ignored if: it was requested AND (it's not in response OR post was processed immediately)
+    const draftIgnored = wasDraftRequested && (!isDraftInResponse || wasProcessedImmediately);
+
+    // Build response object
+    const responseData: any = {
+      job_id: response.id,
+      status: response.status,
+      draft: response.draft,
+      scheduled_at: response.scheduled_at,
+      created_at: response.created_at,
+    };
+
+    // Always include warning field if draft was ignored
+    if (draftIgnored) {
+      responseData.warning = "Warning: Draft was requested but API returned draft: false. The post may have been processed immediately. This can happen if the API does not support drafts with media or other parameters.";
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(responseData, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    logError(error as Error, "post.publish");
+    throw createError(
+      ErrorCodes.PUBLISH_FAILED,
+      `Failed to publish post: ${(error as Error).message}`
+    );
+  }
+}
+
+export async function handlePostStatus(
+  client: PostProxyClient,
+  args: { job_id: string }
+) {
+  if (!args.job_id) {
+    throw createError(ErrorCodes.VALIDATION_ERROR, "job_id is required");
+  }
+
+  try {
+    const postDetails = await client.getPost(args.job_id);
+
+    // Parse platforms into per-platform format
+    const platforms: Array<{
+      platform: string;
+      status: "pending" | "processing" | "published" | "failed" | "deleted";
+      url?: string;
+      post_id?: string;
+      error?: string | null;
+      attempted_at: string | null;
+      insights?: any;
+    }> = [];
+
+    if (postDetails.platforms) {
+      for (const platform of postDetails.platforms) {
+        platforms.push({
+          platform: platform.platform,
+          status: platform.status,
+          url: platform.url,
+          post_id: platform.post_id,
+          error: platform.error || null,
+          attempted_at: platform.attempted_at,
+          insights: platform.insights,
+        });
+      }
+    }
+
+    // Determine overall status from post status and platform statuses
+    let overallStatus: "pending" | "processing" | "complete" | "failed" | "draft" = "pending";
+    
+    // Handle draft status first
+    if (postDetails.status === "draft" || postDetails.draft === true) {
+      overallStatus = "draft";
+    } else if (postDetails.status === "scheduled") {
+      overallStatus = "pending";
+    } else if (postDetails.status === "processing") {
+      overallStatus = "processing";
+    } else if (postDetails.status === "processed") {
+      if (platforms.length === 0) {
+        overallStatus = "pending";
+      } else {
+        const allPublished = platforms.every((p) => p.status === "published");
+        const allFailed = platforms.every((p) => p.status === "failed");
+        const anyPending = platforms.some((p) => p.status === "pending" || p.status === "processing");
+
+        if (anyPending) {
+          // Only if there are pending/processing platforms - this is truly processing
+          overallStatus = "processing";
+        } else if (allPublished) {
+          overallStatus = "complete";
+        } else if (allFailed) {
+          overallStatus = "failed";
+        } else {
+          // Mixed statuses (some published, some failed) - processing is complete
+          // Use "complete" since processing is finished, details are in platforms
+          overallStatus = "complete";
+        }
+      }
+    } else if (postDetails.status === "pending") {
+      overallStatus = "pending";
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              job_id: args.job_id,
+              overall_status: overallStatus,
+              draft: postDetails.draft || false,
+              status: postDetails.status,
+              platforms,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error) {
+    logError(error as Error, "post.status");
+    throw createError(
+      ErrorCodes.API_ERROR,
+      `Failed to get post status: ${(error as Error).message}`
+    );
+  }
+}
+
+export async function handlePostPublishDraft(
+  client: PostProxyClient,
+  args: { job_id: string }
+) {
+  if (!args.job_id) {
+    throw createError(ErrorCodes.VALIDATION_ERROR, "job_id is required");
+  }
+
+  try {
+    // First check if the post exists and is a draft
+    const postDetails = await client.getPost(args.job_id);
+    
+    if (!postDetails.draft && postDetails.status !== "draft") {
+      throw createError(
+        ErrorCodes.VALIDATION_ERROR,
+        `Post ${args.job_id} is not a draft and cannot be published using this endpoint`
+      );
+    }
+
+    // Publish the draft post
+    const publishedPost = await client.publishPost(args.job_id);
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              job_id: publishedPost.id,
+              status: publishedPost.status,
+              draft: publishedPost.draft,
+              scheduled_at: publishedPost.scheduled_at,
+              created_at: publishedPost.created_at,
+              message: "Draft post published successfully",
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error) {
+    logError(error as Error, "post.publish_draft");
+    
+    // Re-throw validation errors as-is
+    if (error instanceof Error && "code" in error && error.code === ErrorCodes.VALIDATION_ERROR) {
+      throw error;
+    }
+    
+    throw createError(
+      ErrorCodes.API_ERROR,
+      `Failed to publish draft post: ${(error as Error).message}`
+    );
+  }
+}
+
+export async function handlePostDelete(
+  client: PostProxyClient,
+  args: { job_id: string }
+) {
+  if (!args.job_id) {
+    throw createError(ErrorCodes.VALIDATION_ERROR, "job_id is required");
+  }
+
+  try {
+    await client.deletePost(args.job_id);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              job_id: args.job_id,
+              deleted: true,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error) {
+    logError(error as Error, "post.delete");
+    throw createError(
+      ErrorCodes.API_ERROR,
+      `Failed to delete post: ${(error as Error).message}`
+    );
+  }
+}

package/src/tools/profiles.ts

@@ -0,0 +1,69 @@
+/**
+ * Profiles tools: profiles.list
+ */
+
+import type { PostProxyClient } from "../api/client.js";
+import { getApiKey } from "../auth/credentials.js";
+import { createError, ErrorCodes } from "../utils/errors.js";
+import { logError, logToolCall } from "../utils/logger.js";
+
+export async function handleProfilesList(client: PostProxyClient) {
+  logToolCall("profiles.list", {});
+
+  // Check API key
+  const apiKey = getApiKey();
+  if (!apiKey) {
+    throw createError(ErrorCodes.AUTH_MISSING, "API key is not configured");
+  }
+
+  try {
+    // Get all profile groups
+    const profileGroups = await client.getProfileGroups();
+
+    // Get profiles for each group
+    const allTargets: Array<{
+      id: string;
+      name: string;
+      platform: string;
+      profile_group_id: string;
+    }> = [];
+
+    for (const group of profileGroups) {
+      try {
+        const profiles = await client.getProfiles(group.id);
+        for (const profile of profiles) {
+          allTargets.push({
+            id: profile.id, // Already a string
+            name: profile.name,
+            platform: profile.platform,
+            profile_group_id: profile.profile_group_id, // Already a string
+          });
+        }
+      } catch (error) {
+        logError(error as Error, `profiles.list (group ${group.id})`);
+        // Continue with other groups even if one fails
+      }
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              targets: allTargets,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error) {
+    logError(error as Error, "profiles.list");
+    throw createError(
+      ErrorCodes.API_ERROR,
+      `Failed to retrieve profiles: ${(error as Error).message}`
+    );
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,161 @@
+/**
+ * TypeScript types for PostProxy API responses and requests
+ */
+
+export interface ProfileGroup {
+  id: string;
+  name: string;
+  profiles_count: number;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface Profile {
+  id: string;
+  name: string;
+  platform: string;
+  profile_group_id: string;
+  expires_at: string | null;
+  post_count: number;
+  username?: string;
+  avatar_url?: string;
+}
+
+export interface CreatePostParams {
+  content: string;
+  profile_group_id?: number; // Not used by API, kept for compatibility
+  profiles: string[]; // Platform names (e.g., ["twitter"]), not profile IDs
+  schedule?: string;
+  media?: string[];
+  idempotency_key?: string;
+  draft?: boolean; // If true, creates a draft post that won't publish automatically
+  platforms?: PlatformParams; // Platform-specific parameters
+}
+
+export interface CreatePostResponse {
+  id: string;
+  body?: string; // API returns "body" field
+  content?: string; // Some responses use "content"
+  status: "draft" | "pending" | "processing" | "processed" | "scheduled";
+  draft: boolean;
+  scheduled_at: string | null;
+  created_at: string;
+  platforms: PlatformOutcome[];
+}
+
+export interface PlatformOutcome {
+  platform: string;
+  status: "pending" | "processing" | "published" | "failed" | "deleted";
+  params: Record<string, any>;
+  attempted_at: string | null;
+  insights?: {
+    impressions?: number;
+    on?: string;
+    [key: string]: any;
+  };
+  url?: string;
+  post_id?: string;
+  error?: string | null; // Error message from platform (replaces error_reason)
+}
+
+export interface PostDetails {
+  id: string;
+  body?: string; // API returns "body" field
+  content?: string; // Some responses use "content"
+  status: "draft" | "pending" | "processing" | "processed" | "scheduled";
+  draft: boolean;
+  scheduled_at: string | null;
+  created_at: string;
+  updated_at?: string;
+  platforms: PlatformOutcome[];
+}
+
+export interface Post {
+  id: string;
+  body?: string; // API returns "body" field
+  content?: string; // Some responses use "content"
+  status: "draft" | "pending" | "processing" | "processed" | "scheduled";
+  draft: boolean;
+  scheduled_at: string | null;
+  created_at: string;
+  updated_at?: string;
+  platforms: PlatformOutcome[];
+}
+
+/**
+ * Platform-specific parameters for Instagram
+ */
+export interface InstagramParams {
+  format?: "post" | "reel" | "story";
+  collaborators?: string[]; // Array of usernames (up to 10 for posts, 3 for reels)
+  first_comment?: string;
+  cover_url?: string; // For reels
+  audio_name?: string; // For reels
+  trial_strategy?: "MANUAL" | "SS_PERFORMANCE"; // For reels
+  thumb_offset?: string; // Thumbnail offset in milliseconds for reels
+}
+
+/**
+ * Platform-specific parameters for YouTube
+ */
+export interface YouTubeParams {
+  title?: string; // Video title
+  privacy_status?: "public" | "unlisted" | "private"; // Video visibility
+  cover_url?: string; // Custom thumbnail URL
+}
+
+/**
+ * Platform-specific parameters for TikTok
+ */
+export interface TikTokParams {
+  privacy_status?: "PUBLIC_TO_EVERYONE" | "MUTUAL_FOLLOW_FRIENDS" | "FOLLOWER_OF_CREATOR" | "SELF_ONLY";
+  photo_cover_index?: number; // Index (0-based) of photo to use as cover
+  auto_add_music?: boolean; // Enable automatic music
+  made_with_ai?: boolean; // Mark content as AI-generated
+  disable_comment?: boolean; // Disable comments on the post
+  disable_duet?: boolean; // Disable duets
+  disable_stitch?: boolean; // Disable stitches
+  brand_content_toggle?: boolean; // Mark video as paid partnership promoting a third-party business
+  brand_organic_toggle?: boolean; // Mark video as paid partnership promoting your own brand
+}
+
+/**
+ * Platform-specific parameters for Facebook
+ */
+export interface FacebookParams {
+  format?: "post" | "story";
+  first_comment?: string; // Comment to add after posting
+  page_id?: string; // Page ID when you have multiple pages
+}
+
+/**
+ * Platform-specific parameters for LinkedIn
+ */
+export interface LinkedInParams {
+  organization_id?: string; // Post on behalf of an organization/company page
+}
+
+/**
+ * Platform-specific parameters for Twitter/X
+ * Note: Twitter/X does not have platform-specific parameters
+ */
+export type TwitterParams = Record<string, never>;
+
+/**
+ * Platform-specific parameters for Threads
+ * Note: Threads does not have platform-specific parameters
+ */
+export type ThreadsParams = Record<string, never>;
+
+/**
+ * Union type for all platform-specific parameters
+ */
+export interface PlatformParams {
+  instagram?: InstagramParams;
+  youtube?: YouTubeParams;
+  tiktok?: TikTokParams;
+  facebook?: FacebookParams;
+  linkedin?: LinkedInParams;
+  twitter?: TwitterParams;
+  threads?: ThreadsParams;
+}

package/src/utils/errors.ts

@@ -0,0 +1,38 @@
+/**
+ * Error handling utilities for MCP server
+ */
+
+export class MCPError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public details?: any
+  ) {
+    super(message);
+    this.name = "MCPError";
+    Object.setPrototypeOf(this, MCPError.prototype);
+  }
+}
+
+export const ErrorCodes = {
+  AUTH_MISSING: "AUTH_MISSING",
+  AUTH_INVALID: "AUTH_INVALID",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  TARGET_NOT_FOUND: "TARGET_NOT_FOUND",
+  PUBLISH_FAILED: "PUBLISH_FAILED",
+  PLATFORM_ERROR: "PLATFORM_ERROR",
+  API_ERROR: "API_ERROR",
+} as const;
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+
+export function formatError(error: Error, code: ErrorCode, details?: any): MCPError {
+  if (error instanceof MCPError) {
+    return error;
+  }
+  return new MCPError(code, error.message || "An error occurred", details);
+}
+
+export function createError(code: ErrorCode, message: string, details?: any): MCPError {
+  return new MCPError(code, message, details);
+}

package/src/utils/idempotency.ts

@@ -0,0 +1,31 @@
+/**
+ * Idempotency key generation utilities
+ */
+
+import { createHash } from "crypto";
+
+/**
+ * Generate an idempotency key from normalized post data
+ */
+export function generateIdempotencyKey(
+  content: string,
+  targets: string[],
+  schedule?: string
+): string {
+  // Normalize input data
+  const normalizedContent = content.trim();
+  const normalizedTargets = [...targets].sort();
+  const normalizedSchedule = schedule || "";
+
+  // Create a JSON string from normalized data
+  const data = JSON.stringify({
+    content: normalizedContent,
+    targets: normalizedTargets,
+    schedule: normalizedSchedule,
+  });
+
+  // Generate SHA256 hash
+  const hash = createHash("sha256").update(data).digest("hex");
+
+  return hash;
+}