postproxy-mcp 0.1.0

package/src/auth/credentials.ts

@@ -0,0 +1,43 @@
+/**
+ * Credentials management - reading API key from environment variables
+ */
+
+const DEFAULT_BASE_URL = "https://api.postproxy.dev/api";
+
+/**
+ * Get API key from environment variables
+ * @returns API key or null if not found
+ */
+export function getApiKey(): string | null {
+  const apiKey = process.env.POSTPROXY_API_KEY;
+  return apiKey || null;
+}
+
+/**
+ * Get base URL from environment variables or use default
+ * @returns Base URL for PostProxy API
+ */
+export function getBaseUrl(): string {
+  return process.env.POSTPROXY_BASE_URL || DEFAULT_BASE_URL;
+}
+
+/**
+ * Validate API key by making a test request (optional)
+ * This can be used to verify the key is valid before using it
+ */
+export async function validateApiKey(apiKey: string, baseUrl: string): Promise<boolean> {
+  try {
+    const response = await fetch(`${baseUrl}/profile_groups/`, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+      signal: AbortSignal.timeout(5000), // 5 second timeout for validation
+    });
+
+    return response.ok;
+  } catch (error) {
+    return false;
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Entry point for PostProxy MCP Server
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getApiKey, getBaseUrl } from "./auth/credentials.js";
+import { PostProxyClient } from "./api/client.js";
+import { createMCPServer } from "./server.js";
+import { log, logError } from "./utils/logger.js";
+import { createError, ErrorCodes } from "./utils/errors.js";
+
+async function main() {
+  // Check if setup command was called
+  if (process.argv[2] === "setup") {
+    const { setup } = await import("./setup.js");
+    await setup();
+    return;
+  }
+
+  try {
+    // Read environment variables
+    const apiKey = getApiKey();
+    const baseUrl = getBaseUrl();
+
+    if (!apiKey) {
+      logError(
+        createError(
+          ErrorCodes.AUTH_MISSING,
+          "POSTPROXY_API_KEY environment variable is not set"
+        ),
+        "startup"
+      );
+      process.exit(1);
+    }
+
+    // Create API client
+    const client = new PostProxyClient(apiKey, baseUrl);
+
+    // Create MCP server
+    const server = await createMCPServer(client);
+
+    // Setup stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+
+    log("PostProxy MCP Server started");
+  } catch (error) {
+    logError(error as Error, "startup");
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  logError(error as Error, "main");
+  process.exit(1);
+});

package/src/server.ts

@@ -0,0 +1,235 @@
+/**
+ * MCP Server setup and tool registration
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import type { PostProxyClient } from "./api/client.js";
+import { handleAuthStatus } from "./tools/auth.js";
+import { handleProfilesList } from "./tools/profiles.js";
+import {
+  handlePostPublish,
+  handlePostStatus,
+  handlePostDelete,
+  handlePostPublishDraft,
+} from "./tools/post.js";
+import { handleHistoryList } from "./tools/history.js";
+import { createError, ErrorCodes } from "./utils/errors.js";
+import { logToolCall } from "./utils/logger.js";
+
+/**
+ * Tool definitions for the PostProxy MCP server.
+ * Exported for potential reuse in other contexts (e.g., Cloudflare Workers).
+ */
+export const TOOL_DEFINITIONS = [
+  {
+    name: "auth.status",
+    description: "Check authentication status, API configuration, and workspace information",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "profiles.list",
+    description: "List all available social media profiles (targets) for posting",
+    inputSchema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "post.publish",
+    description: "Publish a post to specified social media targets. Supports text content, media attachments, scheduling, drafts, and platform-specific customization via the 'platforms' parameter.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: {
+          type: "string",
+          description: "Post content text (caption/description)",
+        },
+        targets: {
+          type: "array",
+          items: { type: "string" },
+          description: "Array of target profile IDs to publish to",
+        },
+        schedule: {
+          type: "string",
+          description: "Optional ISO 8601 scheduled time (e.g., '2024-12-31T23:59:59Z')",
+        },
+        media: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional array of media URLs or local file paths (images or videos). File paths can be absolute (/path/to/file.jpg), relative (./image.png), or use ~ for home directory (~/Pictures/photo.jpg)",
+        },
+        idempotency_key: {
+          type: "string",
+          description: "Optional idempotency key for request deduplication",
+        },
+        require_confirmation: {
+          type: "boolean",
+          description: "If true, return summary without publishing (dry run)",
+        },
+        draft: {
+          type: "boolean",
+          description: "If true, creates a draft post that won't publish automatically",
+        },
+        platforms: {
+          type: "object",
+          description: "Platform-specific parameters. Keys are platform names, values are parameter objects. Use this to add collaborators, set video titles, privacy settings, etc.",
+          properties: {
+            instagram: {
+              type: "object",
+              description: "Instagram: format (post|reel|story), collaborators (array of usernames), first_comment (string), cover_url (string), audio_name (string), trial_strategy (MANUAL|SS_PERFORMANCE), thumb_offset (string in ms)",
+              additionalProperties: true,
+            },
+            youtube: {
+              type: "object",
+              description: "YouTube: title (string), privacy_status (public|unlisted|private), cover_url (thumbnail URL)",
+              additionalProperties: true,
+            },
+            tiktok: {
+              type: "object",
+              description: "TikTok: privacy_status (PUBLIC_TO_EVERYONE|MUTUAL_FOLLOW_FRIENDS|FOLLOWER_OF_CREATOR|SELF_ONLY), photo_cover_index (integer), auto_add_music (bool), made_with_ai (bool), disable_comment (bool), disable_duet (bool), disable_stitch (bool), brand_content_toggle (bool), brand_organic_toggle (bool)",
+              additionalProperties: true,
+            },
+            facebook: {
+              type: "object",
+              description: "Facebook: format (post|story), first_comment (string), page_id (string)",
+              additionalProperties: true,
+            },
+            linkedin: {
+              type: "object",
+              description: "LinkedIn: organization_id (string for company pages)",
+              additionalProperties: true,
+            },
+            twitter: {
+              type: "object",
+              description: "Twitter/X: No platform-specific parameters available",
+              additionalProperties: true,
+            },
+            threads: {
+              type: "object",
+              description: "Threads: No platform-specific parameters available",
+              additionalProperties: true,
+            },
+          },
+          additionalProperties: true,
+        },
+      },
+      required: ["content", "targets"],
+    },
+  },
+  {
+    name: "post.status",
+    description: "Get status of a published post by job ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: {
+          type: "string",
+          description: "Job ID from post.publish response",
+        },
+      },
+      required: ["job_id"],
+    },
+  },
+  {
+    name: "post.publish_draft",
+    description: "Publish a draft post. Only posts with draft status can be published using this endpoint",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: {
+          type: "string",
+          description: "Job ID of the draft post to publish",
+        },
+      },
+      required: ["job_id"],
+    },
+  },
+  {
+    name: "post.delete",
+    description: "Delete a post by job ID",
+    inputSchema: {
+      type: "object",
+      properties: {
+        job_id: {
+          type: "string",
+          description: "Job ID to delete",
+        },
+      },
+      required: ["job_id"],
+    },
+  },
+  {
+    name: "history.list",
+    description: "List recent post jobs",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Maximum number of jobs to return (default: 10)",
+        },
+      },
+    },
+  },
+] as const;
+
+export async function createMCPServer(client: PostProxyClient): Promise<Server> {
+  const server = new Server(
+    {
+      name: "postproxy-mcp",
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [...TOOL_DEFINITIONS],
+    };
+  });
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+
+    logToolCall(name, args);
+
+    try {
+      switch (name) {
+        case "auth.status":
+          return await handleAuthStatus(client);
+        case "profiles.list":
+          return await handleProfilesList(client);
+        case "post.publish":
+          return await handlePostPublish(client, args as any);
+        case "post.status":
+          return await handlePostStatus(client, args as any);
+        case "post.publish_draft":
+          return await handlePostPublishDraft(client, args as any);
+        case "post.delete":
+          return await handlePostDelete(client, args as any);
+        case "history.list":
+          return await handleHistoryList(client, args as any);
+        default:
+          throw createError(ErrorCodes.API_ERROR, `Unknown tool: ${name}`);
+      }
+    } catch (error: any) {
+      if (error.code && error.message) {
+        // Already an MCPError
+        throw error;
+      }
+      throw createError(ErrorCodes.API_ERROR, error.message || "Tool execution failed");
+    }
+  });
+
+  return server;
+}

package/src/setup-cli.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for setup script
+ */
+
+import { setup } from "./setup.js";
+
+setup().catch((error) => {
+  console.error(`\n❌ Fatal error: ${error}`);
+  process.exit(1);
+});

package/src/setup.ts

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * Interactive setup script for PostProxy MCP Server
+ * Makes it easy for non-technical users to configure Claude Code integration
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+import * as readline from "readline";
+
+interface ClaudeConfig {
+  mcpServers?: {
+    [key: string]: {
+      command: string;
+      env?: {
+        POSTPROXY_API_KEY?: string;
+        POSTPROXY_BASE_URL?: string;
+      };
+    };
+  };
+}
+
+function getConfigPath(): string {
+  const platform = process.platform;
+  
+  if (platform === "win32") {
+    return join(process.env.APPDATA || "", "Claude", "claude_desktop_config.json");
+  } else {
+    return join(homedir(), ".config", "claude", "claude_desktop_config.json");
+  }
+}
+
+function readConfig(): ClaudeConfig {
+  const configPath = getConfigPath();
+  
+  if (!existsSync(configPath)) {
+    return {};
+  }
+  
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+  } catch (error) {
+    console.error(`⚠️  Error reading config file: ${error}`);
+    return {};
+  }
+}
+
+function writeConfig(config: ClaudeConfig): void {
+  const configPath = getConfigPath();
+  const configDir = dirname(configPath);
+  
+  // Create directory if it doesn't exist
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  
+  try {
+    writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+    console.log(`✅ Configuration saved to: ${configPath}`);
+  } catch (error) {
+    console.error(`❌ Error writing config file: ${error}`);
+    process.exit(1);
+  }
+}
+
+function question(rl: readline.Interface, query: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(query, resolve);
+  });
+}
+
+function questionWithDefault(rl: readline.Interface, query: string, defaultValue: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(`${query} [${defaultValue}]: `, (answer) => {
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+async function main() {
+  console.log("\n🚀 PostProxy MCP Server Setup");
+  console.log("=" .repeat(50));
+  console.log("This script will help you configure Claude Code to use PostProxy MCP Server.\n");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    // Get API key
+    console.log("📝 Step 1: PostProxy API Configuration");
+    console.log("-" .repeat(50));
+    
+    const apiKey = await question(
+      rl,
+      "Enter your PostProxy API key: "
+    );
+
+    if (!apiKey || apiKey.trim().length === 0) {
+      console.error("❌ API key is required!");
+      process.exit(1);
+    }
+
+    const baseUrl = await questionWithDefault(
+      rl,
+      "Enter PostProxy API base URL",
+      "https://api.postproxy.dev/api"
+    );
+
+    // Determine command path
+    console.log("\n📦 Step 2: Installation Path");
+    console.log("-" .repeat(50));
+    
+    console.log("\nHow did you install PostProxy MCP Server?");
+    console.log("1. Installed globally via npm (npm install -g postproxy-mcp)");
+    console.log("2. Using local development build");
+    console.log("3. Custom path");
+    
+    const installType = await question(rl, "\nSelect option (1-3): ");
+
+    let command: string;
+    
+    if (installType === "1") {
+      command = "postproxy-mcp";
+    } else if (installType === "2") {
+      // Try to detect current location
+      const currentDir = process.cwd();
+      const possiblePath = join(currentDir, "dist", "index.js");
+      
+      if (existsSync(possiblePath)) {
+        command = possiblePath;
+        console.log(`✅ Detected local build at: ${command}`);
+      } else {
+        const customPath = await question(
+          rl,
+          "Enter path to dist/index.js: "
+        );
+        command = customPath;
+      }
+    } else {
+      command = await question(rl, "Enter full path to postproxy-mcp command: ");
+    }
+
+    // Read existing config
+    const config = readConfig();
+    
+    // Update config
+    if (!config.mcpServers) {
+      config.mcpServers = {};
+    }
+
+    config.mcpServers.postproxy = {
+      command: command,
+      env: {
+        POSTPROXY_API_KEY: apiKey.trim(),
+        POSTPROXY_BASE_URL: baseUrl.trim(),
+      },
+    };
+
+    // Write config
+    console.log("\n💾 Step 3: Saving Configuration");
+    console.log("-" .repeat(50));
+    
+    writeConfig(config);
+
+    // Final instructions
+    console.log("\n✨ Setup Complete!");
+    console.log("=" .repeat(50));
+    console.log("\n📋 Next steps:");
+    console.log("1. Restart your Claude Code session");
+    console.log("2. Test the connection by asking Claude: 'Check my PostProxy authentication status'");
+    console.log("3. If configured correctly, Claude will automatically use PostProxy tools");
+    console.log("\n💡 Tip: You can run this setup again anytime with: postproxy-mcp setup");
+    console.log("");
+
+  } catch (error) {
+    console.error(`\n❌ Setup failed: ${error}`);
+    process.exit(1);
+  } finally {
+    rl.close();
+  }
+}
+
+export { main as setup };

package/src/tools/auth.ts

@@ -0,0 +1,45 @@
+/**
+ * Authentication tools: auth.status
+ */
+
+import type { PostProxyClient } from "../api/client.js";
+import { getApiKey, getBaseUrl } from "../auth/credentials.js";
+import { createError, ErrorCodes } from "../utils/errors.js";
+import { logError, logToolCall } from "../utils/logger.js";
+
+export async function handleAuthStatus(client: PostProxyClient) {
+  logToolCall("auth.status", {});
+
+  const apiKey = getApiKey();
+  const baseUrl = getBaseUrl();
+
+  const result: {
+    authenticated: boolean;
+    base_url: string;
+    profile_groups_count?: number;
+  } = {
+    authenticated: apiKey !== null,
+    base_url: baseUrl,
+  };
+
+  // If authenticated, try to get profile groups count
+  if (apiKey !== null) {
+    try {
+      const profileGroups = await client.getProfileGroups();
+      result.profile_groups_count = profileGroups.length;
+    } catch (error) {
+      // If we can't get profile groups, just return without the count
+      // Don't fail the whole request
+      logError(error as Error, "auth.status");
+    }
+  }
+
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}

package/src/tools/history.ts

@@ -0,0 +1,89 @@
+/**
+ * History tools: history.list
+ */
+
+import type { PostProxyClient } from "../api/client.js";
+import { createError, ErrorCodes } from "../utils/errors.js";
+import { logError } from "../utils/logger.js";
+
+export async function handleHistoryList(
+  client: PostProxyClient,
+  args: { limit?: number }
+) {
+  const limit = args.limit || 10;
+
+  try {
+    const posts = await client.listPosts(limit);
+
+    const jobs = posts.map((post) => {
+      // Get content from either "body" or "content" field (API uses "body")
+      const content = post.body || post.content || "";
+      
+      // Determine overall status from post status
+      let overallStatus = "unknown";
+      
+      // Handle draft status first
+      if (post.status === "draft" || post.draft === true) {
+        overallStatus = "draft";
+      } else if (post.status === "scheduled") {
+        overallStatus = "pending";
+      } else if (post.status === "processing") {
+        overallStatus = "processing";
+      } else if (post.status === "processed") {
+        // Check platform statuses to determine overall status
+        if (post.platforms && post.platforms.length > 0) {
+          const allPublished = post.platforms.every((p) => p.status === "published");
+          const allFailed = post.platforms.every((p) => p.status === "failed");
+          const anyPending = post.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 {
+          overallStatus = "pending";
+        }
+      } else if (post.status === "pending") {
+        overallStatus = "pending";
+      }
+
+      return {
+        job_id: post.id,
+        content_preview: content.substring(0, 100) + (content.length > 100 ? "..." : ""),
+        created_at: post.created_at,
+        overall_status: overallStatus,
+        draft: post.draft || false,
+        platforms_count: post.platforms?.length || 0,
+      };
+    });
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              jobs,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  } catch (error) {
+    logError(error as Error, "history.list");
+    throw createError(
+      ErrorCodes.API_ERROR,
+      `Failed to list history: ${(error as Error).message}`
+    );
+  }
+}