postproxy-mcp 0.1.0

package/dist/utils/validation.js

@@ -0,0 +1,145 @@
+/**
+ * Validation schemas using Zod
+ */
+import { z } from "zod";
+/**
+ * Schema for ISO 8601 date strings
+ */
+export const ISO8601DateSchema = z.string().refine((date) => {
+    const d = new Date(date);
+    return !isNaN(d.getTime()) && date.includes("T");
+}, {
+    message: "Must be a valid ISO 8601 date string (e.g., 2024-01-01T12:00:00Z)",
+});
+/**
+ * Schema for URL strings
+ */
+export const URLSchema = z.string().url({
+    message: "Must be a valid URL",
+});
+/**
+ * Check if a string looks like a file path
+ */
+export function isFilePath(value) {
+    // Absolute paths, relative paths, or home directory paths
+    return (value.startsWith("/") ||
+        value.startsWith("./") ||
+        value.startsWith("../") ||
+        value.startsWith("~/") ||
+        // Windows absolute paths
+        /^[A-Za-z]:[\\/]/.test(value));
+}
+/**
+ * Schema for media items (URLs or file paths)
+ */
+export const MediaItemSchema = z.string().refine((value) => {
+    // Allow file paths
+    if (isFilePath(value)) {
+        return true;
+    }
+    // Or valid URLs
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, {
+    message: "Must be a valid URL or file path",
+});
+/**
+ * Platform-specific validation schemas
+ */
+// Instagram parameters validation
+export const InstagramParamsSchema = z.object({
+    format: z.enum(["post", "reel", "story"], {
+        errorMap: () => ({ message: "Instagram format must be 'post', 'reel', or 'story'" }),
+    }).optional(),
+    collaborators: z.array(z.string()).max(10, {
+        message: "Instagram allows up to 10 collaborators for posts, 3 for reels",
+    }).optional(),
+    first_comment: z.string().optional(),
+    cover_url: URLSchema.optional(),
+    audio_name: z.string().optional(),
+    trial_strategy: z.enum(["MANUAL", "SS_PERFORMANCE"], {
+        errorMap: () => ({ message: "Instagram trial_strategy must be 'MANUAL' or 'SS_PERFORMANCE'" }),
+    }).optional(),
+    thumb_offset: z.string().optional(),
+}).strict();
+// YouTube parameters validation
+export const YouTubeParamsSchema = z.object({
+    title: z.string().optional(),
+    privacy_status: z.enum(["public", "unlisted", "private"], {
+        errorMap: () => ({ message: "YouTube privacy_status must be 'public', 'unlisted', or 'private'" }),
+    }).optional(),
+    cover_url: URLSchema.optional(),
+}).strict();
+// TikTok parameters validation
+export const TikTokParamsSchema = z.object({
+    privacy_status: z.enum([
+        "PUBLIC_TO_EVERYONE",
+        "MUTUAL_FOLLOW_FRIENDS",
+        "FOLLOWER_OF_CREATOR",
+        "SELF_ONLY"
+    ], {
+        errorMap: () => ({ message: "TikTok privacy_status must be one of: PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY" }),
+    }).optional(),
+    photo_cover_index: z.number().int().nonnegative({
+        message: "TikTok photo_cover_index must be a non-negative integer",
+    }).optional(),
+    auto_add_music: z.boolean().optional(),
+    made_with_ai: z.boolean().optional(),
+    disable_comment: z.boolean().optional(),
+    disable_duet: z.boolean().optional(),
+    disable_stitch: z.boolean().optional(),
+    brand_content_toggle: z.boolean().optional(),
+    brand_organic_toggle: z.boolean().optional(),
+}).strict();
+// Facebook parameters validation
+export const FacebookParamsSchema = z.object({
+    format: z.enum(["post", "story"], {
+        errorMap: () => ({ message: "Facebook format must be 'post' or 'story'" }),
+    }).optional(),
+    first_comment: z.string().optional(),
+    page_id: z.string().optional(),
+}).strict();
+// LinkedIn parameters validation
+export const LinkedInParamsSchema = z.object({
+    organization_id: z.string().optional(),
+}).strict();
+// Twitter/X and Threads don't have platform-specific parameters
+export const TwitterParamsSchema = z.object({}).strict();
+export const ThreadsParamsSchema = z.object({}).strict();
+// Combined platform parameters schema
+export const PlatformParamsSchema = z.object({
+    instagram: InstagramParamsSchema.optional(),
+    youtube: YouTubeParamsSchema.optional(),
+    tiktok: TikTokParamsSchema.optional(),
+    facebook: FacebookParamsSchema.optional(),
+    linkedin: LinkedInParamsSchema.optional(),
+    twitter: TwitterParamsSchema.optional(),
+    threads: ThreadsParamsSchema.optional(),
+}).strict().optional();
+/**
+ * Schema for post.publish parameters
+ */
+export const PostPublishSchema = z.object({
+    content: z.string().min(1, "Content cannot be empty"),
+    targets: z.array(z.string()).min(1, "At least one target is required"),
+    schedule: ISO8601DateSchema.optional(),
+    media: z.array(MediaItemSchema).optional(),
+    idempotency_key: z.string().optional(),
+    require_confirmation: z.boolean().optional(),
+    draft: z.boolean().optional(),
+    platforms: PlatformParamsSchema,
+});
+/**
+ * Validate that a schedule date is in the future
+ */
+export function validateScheduleInFuture(schedule) {
+    const scheduleDate = new Date(schedule);
+    const now = new Date();
+    return scheduleDate > now;
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "postproxy-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for PostProxy API integration with Claude Code",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "postproxy-mcp": "./dist/index.js",
+    "postproxy-mcp-setup": "./dist/setup-cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "dev:worker": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "postproxy",
+    "claude",
+    "social-media"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "workers-mcp": "0.1.0-3",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250124.0",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.3",
+    "wrangler": "^4.61.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/api/client.ts

@@ -0,0 +1,497 @@
+/**
+ * PostProxy API HTTP client
+ */
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { homedir } from "node:os";
+import type {
+  ProfileGroup,
+  Profile,
+  CreatePostParams,
+  CreatePostResponse,
+  PostDetails,
+  Post,
+} from "../types/index.js";
+import { createError, ErrorCodes, formatError, type ErrorCode } from "../utils/errors.js";
+import { log, logError } from "../utils/logger.js";
+import { isFilePath } from "../utils/validation.js";
+
+export class PostProxyClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(apiKey: string, baseUrl: string) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, ""); // Remove trailing slash
+  }
+
+  /**
+   * Extract array from API response
+   * API returns either:
+   * - Direct array: [...]
+   * - Object with data field: {"data": [...]}
+   * - Paginated response: {"total": N, "data": [...]}
+   */
+  private extractArray<T>(response: any): T[] {
+    if (Array.isArray(response)) {
+      return response;
+    }
+    if (response && typeof response === "object" && Array.isArray(response.data)) {
+      return response.data;
+    }
+    // Return empty array if response is not in expected format
+    return [];
+  }
+
+  /**
+   * Expand ~ to home directory in file paths
+   */
+  private expandPath(filePath: string): string {
+    if (filePath.startsWith("~/")) {
+      return filePath.replace("~", homedir());
+    }
+    return filePath;
+  }
+
+  /**
+   * Get MIME type based on file extension
+   */
+  private getMimeType(filePath: string): string {
+    const ext = filePath.toLowerCase().split(".").pop();
+    const mimeTypes: Record<string, string> = {
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      png: "image/png",
+      gif: "image/gif",
+      webp: "image/webp",
+      mp4: "video/mp4",
+      mov: "video/quicktime",
+      avi: "video/x-msvideo",
+      webm: "video/webm",
+    };
+    return mimeTypes[ext || ""] || "application/octet-stream";
+  }
+
+  /**
+   * Check if any media items are file paths (vs URLs)
+   */
+  private hasFilePaths(media: string[]): boolean {
+    return media.some((item) => isFilePath(item));
+  }
+
+  /**
+   * Create post using multipart/form-data (for file uploads)
+   * Uses form field names with brackets: post[body], profiles[], media[]
+   */
+  private async createPostWithFiles(
+    params: CreatePostParams,
+    extraHeaders: Record<string, string>
+  ): Promise<CreatePostResponse> {
+    const url = `${this.baseUrl}/posts`;
+    const formData = new FormData();
+
+    // Add post body
+    formData.append("post[body]", params.content);
+
+    // Add scheduled_at if provided
+    if (params.schedule) {
+      formData.append("post[scheduled_at]", params.schedule);
+    }
+
+    // Add draft if provided
+    if (params.draft !== undefined) {
+      formData.append("post[draft]", String(params.draft));
+    }
+
+    // Add profiles (platform names)
+    for (const profile of params.profiles) {
+      formData.append("profiles[]", profile);
+    }
+
+    // Add media files and URLs
+    if (params.media && params.media.length > 0) {
+      for (const mediaItem of params.media) {
+        if (isFilePath(mediaItem)) {
+          // It's a file path - read and upload the file
+          const expandedPath = this.expandPath(mediaItem);
+          try {
+            const fileContent = readFileSync(expandedPath);
+            const fileName = basename(expandedPath);
+            const mimeType = this.getMimeType(expandedPath);
+            const blob = new Blob([fileContent], { type: mimeType });
+            formData.append("media[]", blob, fileName);
+            if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+              log(`Adding file to upload: ${fileName} (${mimeType}, ${fileContent.length} bytes)`);
+            }
+          } catch (error) {
+            throw createError(
+              ErrorCodes.VALIDATION_ERROR,
+              `Failed to read file: ${mediaItem} - ${(error as Error).message}`
+            );
+          }
+        } else {
+          // It's a URL - pass it as-is
+          formData.append("media[]", mediaItem);
+        }
+      }
+    }
+
+    // Add platform-specific parameters as JSON
+    if (params.platforms && Object.keys(params.platforms).length > 0) {
+      formData.append("platforms", JSON.stringify(params.platforms));
+    }
+
+    // Build headers (no Content-Type - fetch will set it with boundary for multipart)
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...extraHeaders,
+    };
+
+    if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+      log(`Creating post with file upload (multipart/form-data)`);
+      log(`Profiles: ${params.profiles.join(", ")}`);
+      log(`Media count: ${params.media?.length || 0}`);
+    }
+
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: formData,
+        signal: AbortSignal.timeout(60000), // 60 second timeout for file uploads
+      });
+
+      const requestId = response.headers.get("x-request-id");
+
+      if (!response.ok) {
+        let errorMessage = `API request failed with status ${response.status}`;
+        let errorDetails: any = { status: response.status, requestId };
+
+        try {
+          const errorBody = await response.json();
+          if (Array.isArray(errorBody.errors)) {
+            errorMessage = errorBody.errors.join("; ");
+            errorDetails = { ...errorDetails, errors: errorBody.errors };
+          } else if (errorBody.message) {
+            errorMessage = errorBody.message;
+            errorDetails = { ...errorDetails, ...errorBody };
+          } else if (errorBody.error) {
+            errorMessage = typeof errorBody.error === "string"
+              ? errorBody.error
+              : errorBody.message || errorMessage;
+            errorDetails = { ...errorDetails, ...errorBody };
+          }
+        } catch {
+          errorMessage = response.statusText || errorMessage;
+        }
+
+        let errorCode: ErrorCode = ErrorCodes.API_ERROR;
+        if (response.status === 401) {
+          errorCode = ErrorCodes.AUTH_INVALID;
+        } else if (response.status === 404) {
+          errorCode = ErrorCodes.TARGET_NOT_FOUND;
+        } else if (response.status >= 400 && response.status < 500) {
+          errorCode = ErrorCodes.VALIDATION_ERROR;
+        }
+
+        logError(createError(errorCode, errorMessage, errorDetails), `API POST /posts (multipart)`);
+        throw createError(errorCode, errorMessage, errorDetails);
+      }
+
+      const jsonResponse = await response.json();
+      if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+        log(`Response POST /posts (multipart)`, JSON.stringify(jsonResponse, null, 2));
+      }
+      return jsonResponse as CreatePostResponse;
+    } catch (error) {
+      if (error instanceof Error && error.name === "TimeoutError") {
+        throw createError(
+          ErrorCodes.API_ERROR,
+          "Request timeout - API did not respond within 60 seconds"
+        );
+      }
+      if (error instanceof Error && "code" in error) {
+        throw error;
+      }
+      logError(error as Error, `API POST /posts (multipart)`);
+      throw formatError(error as Error, ErrorCodes.API_ERROR, { method: "POST", path: "/posts" });
+    }
+  }
+
+  /**
+   * Make an HTTP request to the PostProxy API
+   */
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: any,
+    extraHeaders?: Record<string, string>
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+    };
+
+    // Merge extra headers if provided
+    if (extraHeaders) {
+      Object.assign(headers, extraHeaders);
+    }
+
+    const options: RequestInit = {
+      method,
+      headers,
+      signal: AbortSignal.timeout(30000), // 30 second timeout
+    };
+
+    if (body && (method === "POST" || method === "PUT" || method === "PATCH")) {
+      options.body = JSON.stringify(body);
+      // Log request payload in debug mode
+      if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+        log(`Request ${method} ${path}`, JSON.stringify(body, null, 2));
+      }
+    }
+
+    try {
+      const response = await fetch(url, options);
+      const requestId = response.headers.get("x-request-id");
+
+      if (!response.ok) {
+        let errorMessage = `API request failed with status ${response.status}`;
+        let errorDetails: any = { status: response.status, requestId };
+
+        try {
+          const errorBody = await response.json();
+          
+          // Handle different error response formats
+          if (Array.isArray(errorBody.errors)) {
+            // 422 validation errors: {"errors": ["...", "..."]}
+            errorMessage = errorBody.errors.join("; ");
+            errorDetails = { ...errorDetails, errors: errorBody.errors };
+          } else if (errorBody.message) {
+            // 400 errors: {"status":400,"error":"Bad Request","message":"..."}
+            errorMessage = errorBody.message;
+            errorDetails = { ...errorDetails, ...errorBody };
+          } else if (errorBody.error) {
+            // Some errors use "error" field
+            errorMessage = typeof errorBody.error === "string" 
+              ? errorBody.error 
+              : errorBody.message || errorMessage;
+            errorDetails = { ...errorDetails, ...errorBody };
+          } else {
+            // Fallback: use any available message field
+            errorMessage = errorBody.message || errorBody.error || errorMessage;
+            errorDetails = { ...errorDetails, ...errorBody };
+          }
+        } catch {
+          // If response is not JSON, use status text
+          errorMessage = response.statusText || errorMessage;
+        }
+
+        // Map HTTP status codes to error codes
+        let errorCode: ErrorCode = ErrorCodes.API_ERROR;
+        if (response.status === 401) {
+          errorCode = ErrorCodes.AUTH_INVALID;
+        } else if (response.status === 404) {
+          errorCode = ErrorCodes.TARGET_NOT_FOUND;
+        } else if (response.status >= 400 && response.status < 500) {
+          errorCode = ErrorCodes.VALIDATION_ERROR;
+        }
+
+        logError(createError(errorCode, errorMessage, errorDetails), `API ${method} ${path}`);
+        throw createError(errorCode, errorMessage, errorDetails);
+      }
+
+      // Handle empty responses
+      const contentType = response.headers.get("content-type");
+      if (contentType && contentType.includes("application/json")) {
+        const jsonResponse = await response.json();
+        // Log response in debug mode
+        if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+          log(`Response ${method} ${path}`, JSON.stringify(jsonResponse, null, 2));
+        }
+        return jsonResponse;
+      }
+
+      return {} as T;
+    } catch (error) {
+      if (error instanceof Error && error.name === "TimeoutError") {
+        throw createError(
+          ErrorCodes.API_ERROR,
+          "Request timeout - API did not respond within 30 seconds"
+        );
+      }
+
+      if (error instanceof Error && "code" in error && error.code === "AUTH_INVALID") {
+        throw error;
+      }
+
+      logError(error as Error, `API ${method} ${path}`);
+      throw formatError(error as Error, ErrorCodes.API_ERROR, { method, path });
+    }
+  }
+
+  /**
+   * Get all profile groups
+   */
+  async getProfileGroups(): Promise<ProfileGroup[]> {
+    const response = await this.request<any>("GET", "/profile_groups/");
+    return this.extractArray<ProfileGroup>(response);
+  }
+
+  /**
+   * Get profiles, optionally filtered by group ID
+   */
+  async getProfiles(groupId?: string | number): Promise<Profile[]> {
+    const path = groupId
+      ? `/profiles?group_id=${groupId}`
+      : "/profiles";
+    const response = await this.request<any>("GET", path);
+    return this.extractArray<Profile>(response);
+  }
+
+  /**
+   * Create a new post
+   * API expects: { post: { body, scheduled_at, draft }, profiles: [...], media: [...], platforms: {...} }
+   * Note: draft parameter must be inside the post object, not at the top level
+   * If media contains file paths, uses multipart/form-data for file upload
+   */
+  async createPost(params: CreatePostParams): Promise<CreatePostResponse> {
+    // Check if we need to use multipart/form-data for file uploads
+    if (params.media && params.media.length > 0 && this.hasFilePaths(params.media)) {
+      const extraHeaders: Record<string, string> = {};
+      if (params.idempotency_key) {
+        extraHeaders["Idempotency-Key"] = params.idempotency_key;
+      }
+      return this.createPostWithFiles(params, extraHeaders);
+    }
+
+    // Transform to API format (JSON request for URLs only)
+    const apiPayload: any = {
+      post: {
+        body: params.content,
+      },
+      profiles: params.profiles, // Array of platform names (e.g., ["twitter"])
+      media: params.media || [], // Always include media field, even if empty
+    };
+
+    if (params.schedule) {
+      apiPayload.post.scheduled_at = params.schedule;
+    }
+
+    // Draft parameter must be inside the post object, not at the top level
+    if (params.draft !== undefined) {
+      apiPayload.post.draft = params.draft;
+    }
+
+    // Platform-specific parameters
+    // Only include platforms if it's a non-empty object with at least one platform
+    // Supports all platform parameter types: strings, numbers, booleans, arrays (e.g., collaborators)
+    // Empty platform objects (e.g., {"linkedin": {}}) are also supported
+    if (
+      params.platforms &&
+      typeof params.platforms === "object" &&
+      !Array.isArray(params.platforms) &&
+      Object.keys(params.platforms).length > 0
+    ) {
+      // Validate structure: each key should be a platform name (string), value should be an object
+      // Note: We only validate the top-level structure. Detailed validation happens in validation.ts
+      // Platform parameter objects can contain: strings, numbers, booleans, arrays (e.g., collaborators), or be empty {}
+      const isValidPlatforms = Object.entries(params.platforms).every(
+        ([key, value]) =>
+          typeof key === "string" &&
+          typeof value === "object" &&
+          value !== null &&
+          !Array.isArray(value)
+      );
+
+      if (isValidPlatforms) {
+        apiPayload.platforms = params.platforms;
+      } else {
+        log("WARNING: Invalid platforms structure, skipping platform parameters");
+      }
+    }
+
+    // Log payload in debug mode to troubleshoot draft issues
+    if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+      log("Creating post with payload:", JSON.stringify(apiPayload, null, 2));
+      log(`Draft parameter: requested=${params.draft}, sending=${apiPayload.draft}`);
+      if (params.media && params.media.length > 0) {
+        log(`Post includes ${params.media.length} media file(s)`);
+      }
+      if (params.platforms) {
+        log(`Platform parameters received: ${JSON.stringify(params.platforms, null, 2)}`);
+        log(`Platform parameter keys: ${Object.keys(params.platforms).join(", ")}`);
+        if (apiPayload.platforms) {
+          log(`Platform parameters sent to API: ${JSON.stringify(apiPayload.platforms, null, 2)}`);
+        } else {
+          log("WARNING: Platform parameters were provided but not included in API payload (invalid structure or empty)");
+        }
+      } else {
+        log("No platform parameters provided");
+      }
+    }
+
+    // Add idempotency key as header if provided
+    const extraHeaders: Record<string, string> = {};
+    if (params.idempotency_key) {
+      extraHeaders["Idempotency-Key"] = params.idempotency_key;
+    }
+
+    const response = await this.request<CreatePostResponse>("POST", "/posts", apiPayload, extraHeaders);
+
+    // Log response in debug mode, especially draft status
+    if (process.env.POSTPROXY_MCP_DEBUG === "1") {
+      log(`Post created: id=${response.id}, status=${response.status}, draft=${response.draft}`);
+      if (params.draft === true && response.draft === false) {
+        log("WARNING: Draft was requested but API returned draft=false. API may have ignored the draft parameter.");
+      }
+    }
+
+    return response;
+  }
+
+  /**
+   * Get post details by ID
+   */
+  async getPost(postId: string): Promise<PostDetails> {
+    return this.request<PostDetails>("GET", `/posts/${postId}`);
+  }
+
+  /**
+   * List posts with optional pagination
+   */
+  async listPosts(limit?: number, page?: number, perPage?: number): Promise<Post[]> {
+    const params = new URLSearchParams();
+    // Map limit to per_page (API expects per_page, not limit)
+    if (limit !== undefined) {
+      params.append("per_page", String(limit));
+    }
+    if (page !== undefined) {
+      params.append("page", String(page));
+    }
+    if (perPage !== undefined) {
+      params.append("per_page", String(perPage));
+    }
+    const queryString = params.toString();
+    const path = queryString ? `/posts?${queryString}` : "/posts";
+    const response = await this.request<any>("GET", path);
+    return this.extractArray<Post>(response);
+  }
+
+  /**
+   * Delete a post by ID
+   */
+  async deletePost(postId: string): Promise<void> {
+    await this.request<void>("DELETE", `/posts/${postId}`);
+  }
+
+  /**
+   * Publish a draft post
+   * Only posts with status "draft" can be published using this endpoint
+   */
+  async publishPost(postId: string): Promise<PostDetails> {
+    return this.request<PostDetails>("POST", `/posts/${postId}/publish`);
+  }
+}