posterly-mcp-server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { PosterlyClient } from './lib/api-client.js';
+import { listAccountsTool } from './tools/list-accounts.js';
+import { createPostTool } from './tools/create-post.js';
+import { findSlotTool } from './tools/find-slot.js';
+import { listPostsTool } from './tools/list-posts.js';
+import { uploadMediaTool } from './tools/upload-media.js';
+const server = new McpServer({
+    name: 'posterly',
+    version: '0.1.0',
+});
+let client;
+try {
+    client = new PosterlyClient();
+}
+catch (err) {
+    console.error(err.message);
+    process.exit(1);
+}
+// Register tools
+server.tool(listAccountsTool.name, listAccountsTool.description, listAccountsTool.inputSchema.shape, async () => {
+    try {
+        const text = await listAccountsTool.execute(client);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(createPostTool.name, createPostTool.description, createPostTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await createPostTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(findSlotTool.name, findSlotTool.description, findSlotTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await findSlotTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(listPostsTool.name, listPostsTool.description, listPostsTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await listPostsTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(uploadMediaTool.name, uploadMediaTool.description, uploadMediaTool.inputSchema.shape, async (input) => {
+    try {
+        const text = await uploadMediaTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/lib/api-client.d.ts

@@ -0,0 +1,66 @@
+export interface Account {
+    id: string;
+    platform: string;
+    username: string;
+    account_type?: string;
+    profile_picture_url?: string;
+}
+export interface Post {
+    id: number;
+    content: string;
+    scheduled_at: string;
+    social_account_id: string;
+    media_url?: string;
+    media_urls?: string[];
+    status: string;
+    post_type?: string;
+    platform_post_url?: string;
+    published_at?: string;
+}
+export interface Slot {
+    time: string;
+    local_time: string;
+}
+export declare class PosterlyClient {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey?: string, baseUrl?: string);
+    private request;
+    listAccounts(): Promise<Account[]>;
+    listPosts(params?: {
+        status?: string;
+        platform?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        posts: Post[];
+        total: number;
+    }>;
+    createPost(data: {
+        account_id?: string;
+        username?: string;
+        platform?: string;
+        caption: string;
+        scheduled_at?: string;
+        post_type?: string;
+        media_url?: string;
+        media_urls?: string[];
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        post: Post;
+    }>;
+    findAvailableSlots(params?: {
+        account_ids?: string[];
+        timezone?: string;
+        count?: number;
+    }): Promise<Slot[]>;
+    uploadMedia(input: {
+        filePath?: string;
+        base64Data?: string;
+        filename: string;
+        contentType?: string;
+    }): Promise<{
+        url: string;
+        path: string;
+    }>;
+}

package/dist/lib/api-client.js

@@ -0,0 +1,99 @@
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+export class PosterlyClient {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
+        this.baseUrl = (baseUrl || process.env.POSTERLY_URL || 'https://posterly.app').replace(/\/$/, '');
+        if (!this.apiKey) {
+            throw new Error('POSTERLY_API_KEY is required. Set it as an environment variable.');
+        }
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}/api/v1${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+        const init = { method, headers };
+        if (body instanceof FormData) {
+            init.body = body;
+        }
+        else if (body) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(body);
+        }
+        const res = await fetch(url, init);
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(err.error || `API error: ${res.status}`);
+        }
+        return res.json();
+    }
+    async listAccounts() {
+        const data = await this.request('GET', '/accounts');
+        return data.accounts;
+    }
+    async listPosts(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.status)
+            searchParams.set('status', params.status);
+        if (params?.platform)
+            searchParams.set('platform', params.platform);
+        if (params?.limit)
+            searchParams.set('limit', String(params.limit));
+        if (params?.offset)
+            searchParams.set('offset', String(params.offset));
+        const qs = searchParams.toString();
+        return this.request('GET', `/posts${qs ? `?${qs}` : ''}`);
+    }
+    async createPost(data) {
+        return this.request('POST', '/posts', data);
+    }
+    async findAvailableSlots(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.account_ids?.length)
+            searchParams.set('account_ids', params.account_ids.join(','));
+        if (params?.timezone)
+            searchParams.set('timezone', params.timezone);
+        if (params?.count)
+            searchParams.set('count', String(params.count));
+        const qs = searchParams.toString();
+        const data = await this.request('GET', `/slots/next${qs ? `?${qs}` : ''}`);
+        return data.slots;
+    }
+    async uploadMedia(input) {
+        let data;
+        if (input.filePath) {
+            const buffer = await readFile(resolve(input.filePath));
+            data = buffer.toString('base64');
+        }
+        else if (input.base64Data) {
+            data = input.base64Data;
+        }
+        else {
+            throw new Error('Provide filePath or base64Data');
+        }
+        const contentType = input.contentType ||
+            guessContentType(input.filename);
+        return this.request('POST', '/media/upload', {
+            filename: input.filename,
+            data,
+            content_type: contentType,
+        });
+    }
+}
+function guessContentType(filename) {
+    const ext = filename.split('.').pop()?.toLowerCase();
+    const map = {
+        jpg: 'image/jpeg',
+        jpeg: 'image/jpeg',
+        png: 'image/png',
+        gif: 'image/gif',
+        webp: 'image/webp',
+        mp4: 'video/mp4',
+        mov: 'video/quicktime',
+        webm: 'video/webm',
+    };
+    return map[ext || ''] || 'application/octet-stream';
+}

package/dist/tools/create-post.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const createPostTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_id: z.ZodOptional<z.ZodString>;
+        username: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        caption: z.ZodString;
+        scheduled_at: z.ZodOptional<z.ZodString>;
+        media_url: z.ZodOptional<z.ZodString>;
+        media_urls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        post_type: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        caption: string;
+        platform?: string | undefined;
+        account_id?: string | undefined;
+        username?: string | undefined;
+        scheduled_at?: string | undefined;
+        media_url?: string | undefined;
+        media_urls?: string[] | undefined;
+        post_type?: string | undefined;
+    }, {
+        caption: string;
+        platform?: string | undefined;
+        account_id?: string | undefined;
+        username?: string | undefined;
+        scheduled_at?: string | undefined;
+        media_url?: string | undefined;
+        media_urls?: string[] | undefined;
+        post_type?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_id?: string;
+        username?: string;
+        platform?: string;
+        caption: string;
+        scheduled_at?: string;
+        media_url?: string;
+        media_urls?: string[];
+        post_type?: string;
+    }): Promise<string>;
+};

package/dist/tools/create-post.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+export const createPostTool = {
+    name: 'create_post',
+    description: 'Schedule or immediately publish a social media post. Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately.',
+    inputSchema: z.object({
+        account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
+        username: z.string().optional().describe('Account username (alternative to account_id)'),
+        platform: z
+            .string()
+            .optional()
+            .describe('Platform name (required with username): instagram, twitter, linkedin, facebook, tiktok, threads, youtube, pinterest, google_business'),
+        caption: z.string().describe('The post caption/text content'),
+        scheduled_at: z
+            .string()
+            .optional()
+            .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
+        media_url: z.string().optional().describe('URL of media to attach (image or video)'),
+        media_urls: z
+            .array(z.string())
+            .optional()
+            .describe('Multiple media URLs for carousel posts'),
+        post_type: z
+            .string()
+            .optional()
+            .describe('Post type: text, image, video, carousel, reel, story'),
+    }),
+    async execute(client, input) {
+        const result = await client.createPost(input);
+        const p = result.post;
+        const when = p.scheduled_at
+            ? new Date(p.scheduled_at).toLocaleString()
+            : 'now';
+        return `Post created successfully!\n• ID: ${p.id}\n• Platform: ${p.platform || input.platform || 'unknown'}\n• Type: ${p.post_type}\n• Status: ${p.status}\n• Scheduled: ${when}`;
+    },
+};

package/dist/tools/find-slot.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const findSlotTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        account_ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        timezone: z.ZodOptional<z.ZodString>;
+        count: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        account_ids?: string[] | undefined;
+        timezone?: string | undefined;
+        count?: number | undefined;
+    }, {
+        account_ids?: string[] | undefined;
+        timezone?: string | undefined;
+        count?: number | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        account_ids?: string[];
+        timezone?: string;
+        count?: number;
+    }): Promise<string>;
+};

package/dist/tools/find-slot.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const findSlotTool = {
+    name: 'find_available_slot',
+    description: 'Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am–10pm). Returns up to 10 slots.',
+    inputSchema: z.object({
+        account_ids: z
+            .array(z.string())
+            .optional()
+            .describe('Filter slots for specific account IDs'),
+        timezone: z
+            .string()
+            .optional()
+            .describe('IANA timezone (e.g. America/New_York). Defaults to America/New_York.'),
+        count: z
+            .number()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe('Number of slots to return (default 5, max 10)'),
+    }),
+    async execute(client, input) {
+        const slots = await client.findAvailableSlots(input);
+        if (slots.length === 0) {
+            return 'No available slots found in the next 14 days.';
+        }
+        const lines = slots.map((s, i) => `${i + 1}. ${s.local_time} — ${new Date(s.time).toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' })}`);
+        return `Available posting slots:\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/list-accounts.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const listAccountsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    execute(client: PosterlyClient): Promise<string>;
+};

package/dist/tools/list-accounts.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export const listAccountsTool = {
+    name: 'list_accounts',
+    description: 'List all connected social media accounts. Shows platform, username, and account ID for each.',
+    inputSchema: z.object({}),
+    async execute(client) {
+        const accounts = await client.listAccounts();
+        if (accounts.length === 0) {
+            return 'No connected accounts found. Connect accounts in the posterly dashboard first.';
+        }
+        const lines = accounts.map((a) => `• ${a.platform} — @${a.username} (ID: ${a.id})`);
+        return `Connected accounts (${accounts.length}):\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/list-posts.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const listPostsTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        status: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        status?: string | undefined;
+        platform?: string | undefined;
+        limit?: number | undefined;
+    }, {
+        status?: string | undefined;
+        platform?: string | undefined;
+        limit?: number | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        status?: string;
+        platform?: string;
+        limit?: number;
+    }): Promise<string>;
+};

package/dist/tools/list-posts.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export const listPostsTool = {
+    name: 'list_posts',
+    description: 'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft) or platform.',
+    inputSchema: z.object({
+        status: z
+            .string()
+            .optional()
+            .describe('Filter by status: draft, scheduled, published, failed'),
+        platform: z
+            .string()
+            .optional()
+            .describe('Filter by platform: instagram, twitter, linkedin, etc.'),
+        limit: z
+            .number()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Number of posts to return (default 10, max 50)'),
+    }),
+    async execute(client, input) {
+        const { posts, total } = await client.listPosts({
+            ...input,
+            limit: input.limit || 10,
+        });
+        if (posts.length === 0) {
+            return 'No posts found matching your criteria.';
+        }
+        const lines = posts.map((p) => {
+            const date = new Date(p.scheduled_at).toLocaleString();
+            const caption = p.content.length > 60 ? p.content.slice(0, 60) + '…' : p.content;
+            return `• [${p.status}] #${p.id} — ${caption} (${date})`;
+        });
+        return `Posts (${posts.length} of ${total}):\n${lines.join('\n')}`;
+    },
+};

package/dist/tools/upload-media.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+export declare const uploadMediaTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        file_path: z.ZodOptional<z.ZodString>;
+        base64_data: z.ZodOptional<z.ZodString>;
+        filename: z.ZodString;
+        content_type: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        filename: string;
+        file_path?: string | undefined;
+        base64_data?: string | undefined;
+        content_type?: string | undefined;
+    }, {
+        filename: string;
+        file_path?: string | undefined;
+        base64_data?: string | undefined;
+        content_type?: string | undefined;
+    }>;
+    execute(client: PosterlyClient, input: {
+        file_path?: string;
+        base64_data?: string;
+        filename: string;
+        content_type?: string;
+    }): Promise<string>;
+};

package/dist/tools/upload-media.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+export const uploadMediaTool = {
+    name: 'upload_media',
+    description: 'Upload an image or video file to posterly. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Max 5MB.',
+    inputSchema: z.object({
+        file_path: z
+            .string()
+            .optional()
+            .describe('Absolute path to a local file to upload'),
+        base64_data: z
+            .string()
+            .optional()
+            .describe('Base64-encoded file data (alternative to file_path)'),
+        filename: z
+            .string()
+            .describe('Filename with extension (e.g. photo.jpg, video.mp4)'),
+        content_type: z
+            .string()
+            .optional()
+            .describe('MIME type (auto-detected from filename if omitted)'),
+    }),
+    async execute(client, input) {
+        if (!input.file_path && !input.base64_data) {
+            return 'Error: Provide either file_path or base64_data.';
+        }
+        const result = await client.uploadMedia({
+            filePath: input.file_path,
+            base64Data: input.base64_data,
+            filename: input.filename,
+            contentType: input.content_type,
+        });
+        return `Media uploaded successfully!\n• URL: ${result.url}\n\nUse this URL as media_url when creating a post.`;
+    },
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "posterly-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for posterly — schedule social media posts from Claude Desktop",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "posterly-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { PosterlyClient } from './lib/api-client.js';
+import { listAccountsTool } from './tools/list-accounts.js';
+import { createPostTool } from './tools/create-post.js';
+import { findSlotTool } from './tools/find-slot.js';
+import { listPostsTool } from './tools/list-posts.js';
+import { uploadMediaTool } from './tools/upload-media.js';
+
+const server = new McpServer({
+  name: 'posterly',
+  version: '0.1.0',
+});
+
+let client: PosterlyClient;
+
+try {
+  client = new PosterlyClient();
+} catch (err: any) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+// Register tools
+server.tool(
+  listAccountsTool.name,
+  listAccountsTool.description,
+  listAccountsTool.inputSchema.shape,
+  async () => {
+    try {
+      const text = await listAccountsTool.execute(client);
+      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,
+  createPostTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await createPostTool.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(
+  findSlotTool.name,
+  findSlotTool.description,
+  findSlotTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await findSlotTool.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(
+  listPostsTool.name,
+  listPostsTool.description,
+  listPostsTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await listPostsTool.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(
+  uploadMediaTool.name,
+  uploadMediaTool.description,
+  uploadMediaTool.inputSchema.shape,
+  async (input) => {
+    try {
+      const text = await uploadMediaTool.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 };
+    }
+  }
+);
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/src/lib/api-client.ts

@@ -0,0 +1,164 @@
+import { readFile } from 'fs/promises';
+import { resolve } from 'path';
+
+export interface Account {
+  id: string;
+  platform: string;
+  username: string;
+  account_type?: string;
+  profile_picture_url?: string;
+}
+
+export interface Post {
+  id: number;
+  content: string;
+  scheduled_at: string;
+  social_account_id: string;
+  media_url?: string;
+  media_urls?: string[];
+  status: string;
+  post_type?: string;
+  platform_post_url?: string;
+  published_at?: string;
+}
+
+export interface Slot {
+  time: string;
+  local_time: string;
+}
+
+export class PosterlyClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(apiKey?: string, baseUrl?: string) {
+    this.apiKey = apiKey || process.env.POSTERLY_API_KEY || '';
+    this.baseUrl = (baseUrl || process.env.POSTERLY_URL || 'https://posterly.app').replace(/\/$/, '');
+
+    if (!this.apiKey) {
+      throw new Error('POSTERLY_API_KEY is required. Set it as an environment variable.');
+    }
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${this.baseUrl}/api/v1${path}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${this.apiKey}`,
+    };
+
+    const init: RequestInit = { method, headers };
+
+    if (body instanceof FormData) {
+      init.body = body;
+    } else if (body) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(body);
+    }
+
+    const res = await fetch(url, init);
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({ error: res.statusText }));
+      throw new Error(err.error || `API error: ${res.status}`);
+    }
+
+    return res.json() as Promise<T>;
+  }
+
+  async listAccounts(): Promise<Account[]> {
+    const data = await this.request<{ accounts: Account[] }>('GET', '/accounts');
+    return data.accounts;
+  }
+
+  async listPosts(params?: {
+    status?: string;
+    platform?: string;
+    limit?: number;
+    offset?: number;
+  }): Promise<{ posts: Post[]; total: number }> {
+    const searchParams = new URLSearchParams();
+    if (params?.status) searchParams.set('status', params.status);
+    if (params?.platform) searchParams.set('platform', params.platform);
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.offset) searchParams.set('offset', String(params.offset));
+
+    const qs = searchParams.toString();
+    return this.request('GET', `/posts${qs ? `?${qs}` : ''}`);
+  }
+
+  async createPost(data: {
+    account_id?: string;
+    username?: string;
+    platform?: string;
+    caption: string;
+    scheduled_at?: string;
+    post_type?: string;
+    media_url?: string;
+    media_urls?: string[];
+    metadata?: Record<string, unknown>;
+  }): Promise<{ post: Post }> {
+    return this.request('POST', '/posts', data);
+  }
+
+  async findAvailableSlots(params?: {
+    account_ids?: string[];
+    timezone?: string;
+    count?: number;
+  }): Promise<Slot[]> {
+    const searchParams = new URLSearchParams();
+    if (params?.account_ids?.length) searchParams.set('account_ids', params.account_ids.join(','));
+    if (params?.timezone) searchParams.set('timezone', params.timezone);
+    if (params?.count) searchParams.set('count', String(params.count));
+
+    const qs = searchParams.toString();
+    const data = await this.request<{ slots: Slot[] }>('GET', `/slots/next${qs ? `?${qs}` : ''}`);
+    return data.slots;
+  }
+
+  async uploadMedia(input: {
+    filePath?: string;
+    base64Data?: string;
+    filename: string;
+    contentType?: string;
+  }): Promise<{ url: string; path: string }> {
+    let data: string;
+
+    if (input.filePath) {
+      const buffer = await readFile(resolve(input.filePath));
+      data = buffer.toString('base64');
+    } else if (input.base64Data) {
+      data = input.base64Data;
+    } else {
+      throw new Error('Provide filePath or base64Data');
+    }
+
+    const contentType =
+      input.contentType ||
+      guessContentType(input.filename);
+
+    return this.request('POST', '/media/upload', {
+      filename: input.filename,
+      data,
+      content_type: contentType,
+    });
+  }
+}
+
+function guessContentType(filename: string): string {
+  const ext = filename.split('.').pop()?.toLowerCase();
+  const map: Record<string, string> = {
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+  };
+  return map[ext || ''] || 'application/octet-stream';
+}

package/src/tools/create-post.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const createPostTool = {
+  name: 'create_post',
+  description:
+    'Schedule or immediately publish a social media post. Provide either account_id OR username+platform to identify the account. If scheduled_at is omitted, the post publishes immediately.',
+  inputSchema: z.object({
+    account_id: z.string().optional().describe('Social account ID (from list_accounts)'),
+    username: z.string().optional().describe('Account username (alternative to account_id)'),
+    platform: z
+      .string()
+      .optional()
+      .describe('Platform name (required with username): instagram, twitter, linkedin, facebook, tiktok, threads, youtube, pinterest, google_business'),
+    caption: z.string().describe('The post caption/text content'),
+    scheduled_at: z
+      .string()
+      .optional()
+      .describe('ISO 8601 datetime for scheduling (e.g. 2026-03-05T09:00:00Z). Omit for immediate publish.'),
+    media_url: z.string().optional().describe('URL of media to attach (image or video)'),
+    media_urls: z
+      .array(z.string())
+      .optional()
+      .describe('Multiple media URLs for carousel posts'),
+    post_type: z
+      .string()
+      .optional()
+      .describe('Post type: text, image, video, carousel, reel, story'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      account_id?: string;
+      username?: string;
+      platform?: string;
+      caption: string;
+      scheduled_at?: string;
+      media_url?: string;
+      media_urls?: string[];
+      post_type?: string;
+    }
+  ) {
+    const result = await client.createPost(input);
+    const p = result.post as Record<string, any>;
+
+    const when = p.scheduled_at
+      ? new Date(p.scheduled_at).toLocaleString()
+      : 'now';
+
+    return `Post created successfully!\n• ID: ${p.id}\n• Platform: ${p.platform || input.platform || 'unknown'}\n• Type: ${p.post_type}\n• Status: ${p.status}\n• Scheduled: ${when}`;
+  },
+};

package/src/tools/find-slot.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const findSlotTool = {
+  name: 'find_available_slot',
+  description:
+    'Find available time slots for posting. Respects a 1-hour gap between posts and preferred hours (8am–10pm). Returns up to 10 slots.',
+  inputSchema: z.object({
+    account_ids: z
+      .array(z.string())
+      .optional()
+      .describe('Filter slots for specific account IDs'),
+    timezone: z
+      .string()
+      .optional()
+      .describe('IANA timezone (e.g. America/New_York). Defaults to America/New_York.'),
+    count: z
+      .number()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe('Number of slots to return (default 5, max 10)'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      account_ids?: string[];
+      timezone?: string;
+      count?: number;
+    }
+  ) {
+    const slots = await client.findAvailableSlots(input);
+
+    if (slots.length === 0) {
+      return 'No available slots found in the next 14 days.';
+    }
+
+    const lines = slots.map(
+      (s, i) => `${i + 1}. ${s.local_time} — ${new Date(s.time).toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' })}`
+    );
+    return `Available posting slots:\n${lines.join('\n')}`;
+  },
+};

package/src/tools/list-accounts.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listAccountsTool = {
+  name: 'list_accounts',
+  description: 'List all connected social media accounts. Shows platform, username, and account ID for each.',
+  inputSchema: z.object({}),
+
+  async execute(client: PosterlyClient) {
+    const accounts = await client.listAccounts();
+
+    if (accounts.length === 0) {
+      return 'No connected accounts found. Connect accounts in the posterly dashboard first.';
+    }
+
+    const lines = accounts.map(
+      (a) => `• ${a.platform} — @${a.username} (ID: ${a.id})`
+    );
+    return `Connected accounts (${accounts.length}):\n${lines.join('\n')}`;
+  },
+};

package/src/tools/list-posts.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listPostsTool = {
+  name: 'list_posts',
+  description:
+    'List upcoming or recent posts. Filter by status (scheduled, published, failed, draft) or platform.',
+  inputSchema: z.object({
+    status: z
+      .string()
+      .optional()
+      .describe('Filter by status: draft, scheduled, published, failed'),
+    platform: z
+      .string()
+      .optional()
+      .describe('Filter by platform: instagram, twitter, linkedin, etc.'),
+    limit: z
+      .number()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe('Number of posts to return (default 10, max 50)'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { status?: string; platform?: string; limit?: number }
+  ) {
+    const { posts, total } = await client.listPosts({
+      ...input,
+      limit: input.limit || 10,
+    });
+
+    if (posts.length === 0) {
+      return 'No posts found matching your criteria.';
+    }
+
+    const lines = posts.map((p) => {
+      const date = new Date(p.scheduled_at).toLocaleString();
+      const caption =
+        p.content.length > 60 ? p.content.slice(0, 60) + '…' : p.content;
+      return `• [${p.status}] #${p.id} — ${caption} (${date})`;
+    });
+
+    return `Posts (${posts.length} of ${total}):\n${lines.join('\n')}`;
+  },
+};

package/src/tools/upload-media.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const uploadMediaTool = {
+  name: 'upload_media',
+  description:
+    'Upload an image or video file to posterly. Returns a URL that can be used with create_post. Supports JPEG, PNG, GIF, WebP, MP4, MOV, WebM. Max 5MB.',
+  inputSchema: z.object({
+    file_path: z
+      .string()
+      .optional()
+      .describe('Absolute path to a local file to upload'),
+    base64_data: z
+      .string()
+      .optional()
+      .describe('Base64-encoded file data (alternative to file_path)'),
+    filename: z
+      .string()
+      .describe('Filename with extension (e.g. photo.jpg, video.mp4)'),
+    content_type: z
+      .string()
+      .optional()
+      .describe('MIME type (auto-detected from filename if omitted)'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: {
+      file_path?: string;
+      base64_data?: string;
+      filename: string;
+      content_type?: string;
+    }
+  ) {
+    if (!input.file_path && !input.base64_data) {
+      return 'Error: Provide either file_path or base64_data.';
+    }
+
+    const result = await client.uploadMedia({
+      filePath: input.file_path,
+      base64Data: input.base64_data,
+      filename: input.filename,
+      contentType: input.content_type,
+    });
+
+    return `Media uploaded successfully!\n• URL: ${result.url}\n\nUse this URL as media_url when creating a post.`;
+  },
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}