schedpilot-mcp 1.0.0

package/.env.example

@@ -0,0 +1,6 @@
+# SchedPilot API token
+# Option A — Personal API key (created at app.schedpilot.com/api-access)
+SCHEDPILOT_TOKEN=smm_your_api_key_here
+
+# Option B — OAuth access token (obtained via OAuth 2.0 Authorization Code flow)
+# SCHEDPILOT_TOKEN=sp_tok_your_oauth_token_here

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "schedpilot-mcp",
+  "version": "1.0.0",
+  "description": "Model Context Protocol server for SchedPilot — schedule and manage social media posts via AI agents",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "schedpilot-mcp": "./server.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "axios": "^1.6.0",
+    "form-data": "^4.0.0",
+    "zod": "^3.22.0"
+  }
+}

package/server.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * SchedPilot MCP Server
+ *
+ * Exposes SchedPilot as a Model Context Protocol (MCP) tool server so that
+ * AI agents (Claude, OpenClaw, Hermes, Cursor, etc.) can schedule and manage
+ * social media posts on the user's behalf.
+ *
+ * Authentication
+ * ──────────────
+ * Set SCHEDPILOT_TOKEN in the environment before starting:
+ *   - Personal API key:  smm_xxxxxxxx   (created at app.schedpilot.com/api-access)
+ *   - OAuth token:       sp_tok_xxxxxx  (obtained via OAuth 2.0 flow)
+ *
+ * Claude Desktop setup (~/.claude_desktop_config.json)
+ * ────────────────────────────────────────────────────
+ * {
+ *   "mcpServers": {
+ *     "schedpilot": {
+ *       "command": "node",
+ *       "args": ["/absolute/path/to/schedpilot-node-server-side/mcp/server.js"],
+ *       "env": { "SCHEDPILOT_TOKEN": "smm_your_key_here" }
+ *     }
+ *   }
+ * }
+ */
+
+import { McpServer }         from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z }                 from 'zod';
+import axios                 from 'axios';
+import FormData              from 'form-data';
+import { URL }               from 'url';
+import path                  from 'path';
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const API_BASE = 'https://api.schedpilot.com/developers/v1';
+
+const TOKEN = process.env.SCHEDPILOT_TOKEN;
+if (!TOKEN) {
+  process.stderr.write(
+    '[SchedPilot MCP] ERROR: SCHEDPILOT_TOKEN environment variable is not set.\n' +
+    'Set it to a personal API key (smm_...) or OAuth token (sp_tok_...).\n'
+  );
+  process.exit(1);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/** Standard JSON headers for all requests */
+function jsonHeaders() {
+  return {
+    Authorization:  `Bearer ${TOKEN}`,
+    'Content-Type': 'application/json',
+    Accept:         'application/json',
+  };
+}
+
+/** Wrap any value as a successful MCP text result */
+function ok(data) {
+  const text = typeof data === 'string' ? data : JSON.stringify(data, null, 2);
+  return { content: [{ type: 'text', text }] };
+}
+
+/** Wrap an error string as a failed MCP result */
+function fail(message) {
+  return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+}
+
+/** Call the API, return { ok, status, data } */
+async function apiGet(path, params = {}) {
+  const qs = new URLSearchParams(
+    Object.fromEntries(Object.entries(params).filter(([, v]) => v !== undefined))
+  ).toString();
+  const url = `${API_BASE}${path}${qs ? '?' + qs : ''}`;
+  const res = await axios.get(url, { headers: jsonHeaders(), validateStatus: () => true });
+  return { ok: res.status >= 200 && res.status < 300, status: res.status, data: res.data };
+}
+
+async function apiPost(path, body) {
+  const res = await axios.post(`${API_BASE}${path}`, body, {
+    headers: jsonHeaders(),
+    validateStatus: () => true,
+  });
+  return { ok: res.status >= 200 && res.status < 300, status: res.status, data: res.data };
+}
+
+async function apiDelete(path) {
+  const res = await axios.delete(`${API_BASE}${path}`, {
+    headers: jsonHeaders(),
+    validateStatus: () => true,
+  });
+  return { ok: res.status >= 200 && res.status < 300, status: res.status, data: res.data };
+}
+
+
+// ── MCP Server ────────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name:    'schedpilot',
+  version: '1.0.0',
+});
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool 1 — get_accounts
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool(
+  'get_accounts',
+
+  'Get all social media accounts connected to the SchedPilot account. ' +
+  'Returns each account\'s id, type (e.g. twitter, linkedin, instagram), display name, and username. ' +
+  'Always call this first to discover valid account IDs before creating posts.',
+
+  {}, // no inputs
+
+  async () => {
+    try {
+      const r = await apiGet('/accounts');
+      if (!r.ok) return fail(`${r.status} — ${JSON.stringify(r.data)}`);
+      return ok(r.data);
+    } catch (err) {
+      return fail(err.message);
+    }
+  }
+);
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool 2 — list_posts
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool(
+  'list_posts',
+
+  'List social media posts with optional filters. ' +
+  'Returns post IDs, content, scheduled dates, platforms, and publish status.',
+
+  {
+    status: z.enum(['scheduled', 'posted', 'failed', 'draft', 'pending_approval', 'all'])
+      .default('all')
+      .describe('Filter by post status. Use "all" to see everything.'),
+    start_date: z.string().optional()
+      .describe('Only return posts on or after this date (YYYY-MM-DD).'),
+    end_date: z.string().optional()
+      .describe('Only return posts on or before this date (YYYY-MM-DD).'),
+    page: z.number().int().min(1).default(1)
+      .describe('Page number for pagination (starts at 1).'),
+    per_page: z.number().int().min(1).max(100).default(20)
+      .describe('Number of results per page (max 100).'),
+  },
+
+  async ({ status, start_date, end_date, page, per_page }) => {
+    try {
+      const r = await apiGet('/posts', { status, start_date, end_date, page, per_page });
+      if (!r.ok) return fail(`${r.status} — ${JSON.stringify(r.data)}`);
+      return ok(r.data);
+    } catch (err) {
+      return fail(err.message);
+    }
+  }
+);
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool 3 — create_post
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool(
+  'create_post',
+
+  'Schedule a new social media post to one or more connected accounts. ' +
+  'Use get_accounts first to find valid account IDs and types. ' +
+  'Use upload_media first if you want to attach images or videos. ' +
+  'Returns the created post_id and scheduled details.',
+
+  {
+    content: z.string().min(1)
+      .describe('The text content of the post. For Twitter/X, keep it under 280 characters.'),
+
+    scheduled_date: z.string()
+      .describe('When to publish the post. Format: "YYYY-MM-DD HH:MM:SS" or ISO 8601. Example: "2024-06-15 14:30:00"'),
+
+    timezone: z.string().default('UTC')
+      .describe('Timezone for scheduled_date. Examples: "UTC", "America/New_York", "Europe/London". Defaults to UTC.'),
+
+    accounts: z.array(z.object({
+      id:   z.number().int().describe('Account ID as returned by get_accounts.'),
+      type: z.string().describe('Account type exactly as returned by get_accounts (e.g. "twitter", "linkedin", "instagram", "linkedin_page").'),
+    })).min(1)
+      .describe('At least one account to post to. Get IDs from get_accounts.'),
+
+    image_ids: z.array(z.string()).optional()
+      .describe('Image media IDs to attach. Format: ["image-42", "image-43"]. Get IDs from upload_media.'),
+
+    video_ids: z.array(z.string()).optional()
+      .describe('Video media IDs to attach. Format: ["video-7"]. Get IDs from upload_media. Cannot combine with images.'),
+  },
+
+  async ({ content, scheduled_date, timezone, accounts, image_ids, video_ids }) => {
+    try {
+      const body = { content, scheduled_date, timezone, accounts };
+      if (image_ids?.length) body.image_ids = image_ids;
+      if (video_ids?.length) body.video_ids = video_ids;
+
+      const r = await apiPost('/post', body);
+      if (!r.ok) return fail(`${r.status} — ${JSON.stringify(r.data)}`);
+      return ok(r.data);
+    } catch (err) {
+      return fail(err.message);
+    }
+  }
+);
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool 4 — delete_post
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool(
+  'delete_post',
+
+  'Cancel and permanently delete a scheduled post. ' +
+  'This will fail with a 409 error if the post has already been published on any platform — published posts cannot be deleted. ' +
+  'Get post IDs from list_posts or create_post.',
+
+  {
+    post_id: z.number().int().min(1)
+      .describe('The numeric ID of the post to delete.'),
+  },
+
+  async ({ post_id }) => {
+    try {
+      const r = await apiDelete(`/posts/${post_id}`);
+      if (!r.ok) return fail(`${r.status} — ${JSON.stringify(r.data)}`);
+      return ok(r.data);
+    } catch (err) {
+      return fail(err.message);
+    }
+  }
+);
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool 5 — upload_media
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool(
+  'upload_media',
+
+  'Upload an image or video to SchedPilot from a public URL. ' +
+  'Returns a media_id string (e.g. "image-42" or "video-7") that you pass to create_post. ' +
+  'Supported images: JPG, PNG, GIF, WebP. Supported video: MP4, MOV, AVI, MKV. Max size: 5 GB.',
+
+  {
+    url: z.string().url()
+      .describe('A publicly accessible URL to the image or video file to upload.'),
+    filename: z.string().optional()
+      .describe('Optional filename hint (e.g. "banner.jpg"). Inferred from the URL if omitted.'),
+  },
+
+  async ({ url, filename }) => {
+    try {
+      // 1. Download the file from the provided URL
+      const download = await axios.get(url, {
+        responseType: 'arraybuffer',
+        timeout:      30_000,
+        validateStatus: () => true,
+      });
+
+      if (download.status !== 200) {
+        return fail(`Could not download file — remote server responded with HTTP ${download.status}`);
+      }
+
+      const buffer      = Buffer.from(download.data);
+      const contentType = download.headers['content-type'] || 'application/octet-stream';
+
+      // Derive a sensible filename from the URL when not supplied
+      let inferredName = filename;
+      if (!inferredName) {
+        try {
+          inferredName = path.basename(new URL(url).pathname) || 'upload.bin';
+        } catch {
+          inferredName = 'upload.bin';
+        }
+      }
+
+      // 2. Upload as multipart/form-data using the 'file' field the API expects
+      const form = new FormData();
+      form.append('file', buffer, { filename: inferredName, contentType });
+
+      const res = await axios.post(`${API_BASE}/media/upload`, form, {
+        headers: {
+          Authorization: `Bearer ${TOKEN}`,
+          ...form.getHeaders(),
+        },
+        validateStatus: () => true,
+        maxContentLength: Infinity,
+        maxBodyLength:    Infinity,
+      });
+
+      if (!( res.status >= 200 && res.status < 300)) {
+        return fail(`Upload failed (${res.status}): ${JSON.stringify(res.data)}`);
+      }
+
+      // Response: { media_id: "image-42", type: "image", mime_type: "image/jpeg" }
+      return ok(res.data);
+    } catch (err) {
+      return fail(err.message);
+    }
+  }
+);
+
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tool 6 — get_analytics
+// ─────────────────────────────────────────────────────────────────────────────
+server.tool(
+  'get_analytics',
+
+  'Get performance analytics for a specific published post. ' +
+  'Returns impressions, reach, clicks, likes, comments, shares, and engagement rate ' +
+  'broken down by platform (LinkedIn, Twitter/X, etc.) plus aggregated totals. ' +
+  'Only works for posts with posted_status = "posted".',
+
+  {
+    post_id: z.number().int().min(1)
+      .describe('The numeric ID of the post to retrieve analytics for.'),
+  },
+
+  async ({ post_id }) => {
+    try {
+      const r = await apiGet(`/analytics/${post_id}`);
+      if (!r.ok) return fail(`${r.status} — ${JSON.stringify(r.data)}`);
+      return ok(r.data);
+    } catch (err) {
+      return fail(err.message);
+    }
+  }
+);
+
+
+// ── Connect & run ─────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);