posterly-mcp-server 0.38.0 → 0.39.0

package/README.md

@@ -122,7 +122,7 @@ Add the same server definition to your Cursor MCP settings:
 
 ## Available tools
 
-`posterly-mcp-server@0.38.0` exposes 87 tools.
+`posterly-mcp-server@0.39.0` exposes 89 tools.
 
 Public setup tools work before `POSTERLY_API_KEY` exists:
 
@@ -176,6 +176,8 @@ Authenticated tools require `POSTERLY_API_KEY`:
 - `upload_media`
 - `upload_media_from_url`
 - `create_signed_upload`
+- `create_media_drop` (human drop page at https://www.poster.ly/drop/<token> for ChatGPT/Claude laptop files)
+- `list_media`
 - `find_available_slot`
 - `generate_captions`
 - `generate_image`

package/dist/index.js

@@ -74,6 +74,8 @@ import { getPlatformSchemaTool } from './tools/get-platform-schema.js';
 import { triggerPlatformHelperTool } from './tools/trigger-platform-helper.js';
 import { getXPostingQuotaTool } from './tools/get-x-posting-quota.js';
 import { createSignedUploadTool } from './tools/create-signed-upload.js';
+import { createMediaDropTool } from './tools/create-media-drop.js';
+import { listMediaTool } from './tools/list-media.js';
 import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
 import { connectAccountTool } from './tools/connect-account.js';
@@ -502,6 +504,24 @@ server.tool(createSignedUploadTool.name, createSignedUploadTool.description, cre
         return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
     }
 });
+server.tool(createMediaDropTool.name, createMediaDropTool.description, createMediaDropTool.inputSchema.shape, getToolAnnotations(createMediaDropTool.name), async (input) => {
+    try {
+        const text = await createMediaDropTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
+server.tool(listMediaTool.name, listMediaTool.description, listMediaTool.inputSchema.shape, getToolAnnotations(listMediaTool.name), async (input) => {
+    try {
+        const text = await listMediaTool.execute(client, input);
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+});
 server.tool(getVideoOptionsTool.name, getVideoOptionsTool.description, getVideoOptionsTool.inputSchema.shape, getToolAnnotations(getVideoOptionsTool.name), async () => {
     try {
         const text = await getVideoOptionsTool.execute(client);

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

@@ -1262,6 +1262,33 @@ export declare class PosterlyClient {
         public_url: string;
         headers?: Record<string, string>;
     }>;
+    createMediaDrop(input?: {
+        filename?: string;
+        maxFiles?: number;
+    }): Promise<{
+        session_id: string;
+        drop_url: string;
+        expires_at: string;
+        max_bytes: number;
+        max_files: number;
+        instructions: string;
+    }>;
+    listMedia(params?: {
+        limit?: number;
+        dropSessionId?: string;
+    }): Promise<{
+        media: Array<{
+            id: string;
+            public_url: string;
+            filename: string;
+            path: string;
+            mime: string | null;
+            bytes: number | null;
+            created_at: string;
+            drop_session_id: string | null;
+        }>;
+        total: number;
+    }>;
     uploadMedia(input: {
         filePath?: string;
         base64Data?: string;

package/dist/lib/api-client.js

@@ -506,6 +506,21 @@ export class PosterlyClient {
             size,
         });
     }
+    async createMediaDrop(input) {
+        return this.request('POST', '/media/drop-sessions', {
+            filename: input?.filename,
+            max_files: input?.maxFiles,
+        });
+    }
+    async listMedia(params) {
+        const searchParams = new URLSearchParams();
+        if (params?.limit)
+            searchParams.set('limit', String(params.limit));
+        if (params?.dropSessionId)
+            searchParams.set('drop_session_id', params.dropSessionId);
+        const qs = searchParams.toString();
+        return this.request('GET', `/media${qs ? `?${qs}` : ''}`);
+    }
     async uploadMedia(input) {
         this.requireApiKey();
         let fileBuffer;

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const POSTERLY_MCP_VERSION = "0.38.0";
+export declare const POSTERLY_MCP_VERSION = "0.39.0";

package/dist/lib/version.js

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.38.0';
+export const POSTERLY_MCP_VERSION = '0.39.0';

package/dist/tools/create-media-drop.d.ts

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

package/dist/tools/create-media-drop.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export const createMediaDropTool = {
+    name: 'create_media_drop',
+    description: 'Create a human drop page so ChatGPT or Claude users can upload a laptop file without dashboard login. Returns drop_url (https://www.poster.ly/drop/<token>). Send that URL to the user, wait, then call list_media. This is not the chat paperclip and not create_signed_upload.',
+    inputSchema: z.object({
+        filename: z.string().optional().describe('Optional filename hint for the user, e.g. launch-video.mp4'),
+        max_files: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe('How many files the drop can accept. Default 10, max 10.'),
+    }),
+    async execute(client, input) {
+        const drop = await client.createMediaDrop({
+            filename: input.filename,
+            maxFiles: input.max_files,
+        });
+        return [
+            'Media drop created. Send this URL to the user. They open it with no posterly login and drop the file.',
+            `• Drop URL: ${drop.drop_url}`,
+            `• Session ID: ${drop.session_id}`,
+            `• Expires: ${drop.expires_at}`,
+            `• Max bytes: ${drop.max_bytes}`,
+            `• Max files: ${drop.max_files}`,
+            drop.instructions,
+            'After they finish, call list_media with this drop_session_id, then validate_post / create_post using public_url.',
+            'Chat attachments never reach MCP. HEIC and PDF are rejected.',
+        ].join('\n');
+    },
+};

package/dist/tools/create-signed-upload.d.ts

@@ -8,12 +8,12 @@ export declare const createSignedUploadTool: {
         content_type: z.ZodString;
         size: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
-        content_type: string;
         filename: string;
+        content_type: string;
         size: number;
     }, {
-        content_type: string;
         filename: string;
+        content_type: string;
         size: number;
     }>;
     execute(client: PosterlyClient, input: {

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

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

package/dist/tools/list-media.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+export const listMediaTool = {
+    name: 'list_media',
+    description: 'List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files the human uploaded on /drop/<token>. Use public_url with validate_post / create_post.',
+    inputSchema: z.object({
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe('Number of assets to return (default 10, max 50)'),
+        drop_session_id: z
+            .string()
+            .optional()
+            .describe('Filter to files uploaded through one create_media_drop session'),
+    }),
+    async execute(client, input) {
+        const result = await client.listMedia({
+            limit: input.limit,
+            dropSessionId: input.drop_session_id,
+        });
+        if (result.media.length === 0) {
+            return 'No media found. If you just sent a drop URL, wait for the user to finish uploading, then call list_media again.';
+        }
+        const lines = result.media.map((item) => {
+            const size = typeof item.bytes === 'number' ? `${item.bytes} bytes` : 'unknown size';
+            const drop = item.drop_session_id ? ` drop=${item.drop_session_id}` : '';
+            return `• ${item.filename} (${item.mime || 'unknown'}, ${size})${drop}\n  public_url: ${item.public_url}`;
+        });
+        return [
+            `Media (${result.media.length} of ${result.total}):`,
+            ...lines,
+            '',
+            'Pass public_url to validate_post / create_post. Do not invent URLs.',
+        ].join('\n');
+    },
+};

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

@@ -9,12 +9,12 @@ export declare const uploadMediaFromUrlTool: {
         content_type: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         url: string;
-        content_type?: string | undefined;
         filename?: string | undefined;
+        content_type?: string | undefined;
     }, {
         url: string;
-        content_type?: string | undefined;
         filename?: string | undefined;
+        content_type?: string | undefined;
     }>;
     execute(client: PosterlyClient, input: {
         url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posterly-mcp-server",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "mcpName": "io.github.awpthorp/posterly",
   "description": "MCP server for posterly: schedule and publish social media posts across 18 platforms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, Cline, and more)",
   "license": "MIT",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.awpthorp/posterly",
   "title": "posterly",
   "description": "Validate, schedule, publish, and analyze social content across 18 platforms with posterly.",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "websiteUrl": "https://www.poster.ly/mcp",
   "repository": {
     "url": "https://github.com/awpthorp/posterly",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "posterly-mcp-server",
-      "version": "0.38.0",
+      "version": "0.39.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -75,6 +75,8 @@ import { getPlatformSchemaTool } from './tools/get-platform-schema.js';
 import { triggerPlatformHelperTool } from './tools/trigger-platform-helper.js';
 import { getXPostingQuotaTool } from './tools/get-x-posting-quota.js';
 import { createSignedUploadTool } from './tools/create-signed-upload.js';
+import { createMediaDropTool } from './tools/create-media-drop.js';
+import { listMediaTool } from './tools/list-media.js';
 import { uploadMediaFromUrlTool } from './tools/upload-media-from-url.js';
 import { getConnectLinkTool } from './tools/get-connect-link.js';
 import { connectAccountTool } from './tools/connect-account.js';
@@ -776,6 +778,36 @@ server.tool(
   }
 );
 
+server.tool(
+  createMediaDropTool.name,
+  createMediaDropTool.description,
+  createMediaDropTool.inputSchema.shape,
+  getToolAnnotations(createMediaDropTool.name),
+  async (input) => {
+    try {
+      const text = await createMediaDropTool.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(
+  listMediaTool.name,
+  listMediaTool.description,
+  listMediaTool.inputSchema.shape,
+  getToolAnnotations(listMediaTool.name),
+  async (input) => {
+    try {
+      const text = await listMediaTool.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(
   getVideoOptionsTool.name,
   getVideoOptionsTool.description,

package/src/lib/api-client.ts

@@ -1702,6 +1702,46 @@ export class PosterlyClient {
     });
   }
 
+  async createMediaDrop(input?: {
+    filename?: string;
+    maxFiles?: number;
+  }): Promise<{
+    session_id: string;
+    drop_url: string;
+    expires_at: string;
+    max_bytes: number;
+    max_files: number;
+    instructions: string;
+  }> {
+    return this.request('POST', '/media/drop-sessions', {
+      filename: input?.filename,
+      max_files: input?.maxFiles,
+    });
+  }
+
+  async listMedia(params?: {
+    limit?: number;
+    dropSessionId?: string;
+  }): Promise<{
+    media: Array<{
+      id: string;
+      public_url: string;
+      filename: string;
+      path: string;
+      mime: string | null;
+      bytes: number | null;
+      created_at: string;
+      drop_session_id: string | null;
+    }>;
+    total: number;
+  }> {
+    const searchParams = new URLSearchParams();
+    if (params?.limit) searchParams.set('limit', String(params.limit));
+    if (params?.dropSessionId) searchParams.set('drop_session_id', params.dropSessionId);
+    const qs = searchParams.toString();
+    return this.request('GET', `/media${qs ? `?${qs}` : ''}`);
+  }
+
   async uploadMedia(input: {
     filePath?: string;
     base64Data?: string;

package/src/lib/version.ts

@@ -5,4 +5,4 @@
 // tool set (minus the intentional pre-auth signup tools that only this stdio
 // package exposes). `npm run check:mcp-parity` enforces both the version match
 // and the tool-list match, and runs in the pre-commit hook.
-export const POSTERLY_MCP_VERSION = '0.38.0';
+export const POSTERLY_MCP_VERSION = '0.39.0';

package/src/tools/create-media-drop.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const createMediaDropTool = {
+  name: 'create_media_drop',
+  description:
+    'Create a human drop page so ChatGPT or Claude users can upload a laptop file without dashboard login. Returns drop_url (https://www.poster.ly/drop/<token>). Send that URL to the user, wait, then call list_media. This is not the chat paperclip and not create_signed_upload.',
+  inputSchema: z.object({
+    filename: z.string().optional().describe('Optional filename hint for the user, e.g. launch-video.mp4'),
+    max_files: z
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe('How many files the drop can accept. Default 10, max 10.'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { filename?: string; max_files?: number },
+  ) {
+    const drop = await client.createMediaDrop({
+      filename: input.filename,
+      maxFiles: input.max_files,
+    });
+    return [
+      'Media drop created. Send this URL to the user. They open it with no posterly login and drop the file.',
+      `• Drop URL: ${drop.drop_url}`,
+      `• Session ID: ${drop.session_id}`,
+      `• Expires: ${drop.expires_at}`,
+      `• Max bytes: ${drop.max_bytes}`,
+      `• Max files: ${drop.max_files}`,
+      drop.instructions,
+      'After they finish, call list_media with this drop_session_id, then validate_post / create_post using public_url.',
+      'Chat attachments never reach MCP. HEIC and PDF are rejected.',
+    ].join('\n');
+  },
+};

package/src/tools/list-media.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { PosterlyClient } from '../lib/api-client.js';
+
+export const listMediaTool = {
+  name: 'list_media',
+  description:
+    'List the newest media assets for the authenticated user. After create_media_drop, pass drop_session_id to see files the human uploaded on /drop/<token>. Use public_url with validate_post / create_post.',
+  inputSchema: z.object({
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe('Number of assets to return (default 10, max 50)'),
+    drop_session_id: z
+      .string()
+      .optional()
+      .describe('Filter to files uploaded through one create_media_drop session'),
+  }),
+
+  async execute(
+    client: PosterlyClient,
+    input: { limit?: number; drop_session_id?: string },
+  ) {
+    const result = await client.listMedia({
+      limit: input.limit,
+      dropSessionId: input.drop_session_id,
+    });
+
+    if (result.media.length === 0) {
+      return 'No media found. If you just sent a drop URL, wait for the user to finish uploading, then call list_media again.';
+    }
+
+    const lines = result.media.map((item) => {
+      const size = typeof item.bytes === 'number' ? `${item.bytes} bytes` : 'unknown size';
+      const drop = item.drop_session_id ? ` drop=${item.drop_session_id}` : '';
+      return `• ${item.filename} (${item.mime || 'unknown'}, ${size})${drop}\n  public_url: ${item.public_url}`;
+    });
+
+    return [
+      `Media (${result.media.length} of ${result.total}):`,
+      ...lines,
+      '',
+      'Pass public_url to validate_post / create_post. Do not invent URLs.',
+    ].join('\n');
+  },
+};

package/tool-annotations.json

@@ -45,6 +45,8 @@
     "upload_media",
     "upload_media_from_url",
     "create_signed_upload",
+    "create_media_drop",
+    "list_media",
     "get_video_options",
     "run_video_function",
     "generate_video",
@@ -113,6 +115,7 @@
     "validate_post",
     "find_available_slot",
     "list_posts",
+    "list_media",
     "get_video_options",
     "get_video_job",
     "get_post",
@@ -196,6 +199,7 @@
     "create_posts_batch",
     "upload_media_from_url",
     "create_signed_upload",
+    "create_media_drop",
     "run_video_function",
     "generate_video",
     "get_video_job",