@codingmantra/mcp-server 0.3.0 → 0.5.0

package/README.md

@@ -2,8 +2,21 @@
 
 The official **Model Context Protocol (MCP)** server connecting AI assistants (Claude Desktop, Cursor, Cline, and Antigravity) to CodingMantra's generative AI media engines.
 
-## What's New in v0.3.0
-- **Social media workflows:** 15 tools for connected accounts, caption creation, drafts, gallery images, immediate publishing, scheduling, status, cancellation, and analytics. Uses the same CodingMantra API key.
+## What's New in v0.5.0
+
+- Instagram supports single-image posts and ordered carousels of 2–10 images; Facebook supports up to 10 images in a multi-photo post.
+- New `list_social_library` retrieves reusable complete posts with ordered slides, captions and usage filters. `list_social_media` retains generated-gallery access.
+- Optional `mediaLayout` provides common square or portrait canvases using fit or crop, including reusable uploaded media IDs.
+- Existing single-image publishing and scheduling inputs remain supported.
+- Polling exposes processing details and delivery review flags. Never create a replacement post automatically when final delivery is uncertain.
+
+## Previous v0.4.0 changes
+
+- Social publishing and scheduling use the versioned developer API, supporting stable platform-prefixed account IDs, multiple targets, and caller-supplied idempotency keys.
+- New `upload_social_image` and `get_social_image` tools support URL, base64, data URI, local files, and reusable media IDs.
+- Per-account polling includes provider post IDs; cancellation retains delivery history. HTTP error codes and Retry-After are exposed in structured MCP errors.
+- **Migration:** publication and scheduling inputs changed from the v0.3 platform/accountId or platforms/content shape to the contract below. Existing drafts, caption generation, analytics, and editing tools remain available.
+- **Social media workflows:** 19 tools for connected accounts, caption creation, drafts, gallery images, immediate publishing, scheduling, status, cancellation, and analytics. Uses the same CodingMantra API key.
 
 - **Current API coverage:** Story Teller, HeyGen Talking Avatar IV, and Jewellery Rate Poster tools.
 - **Video contract alignment:** Required prompt/model/duration/resolution/aspect ratio, character descriptions, seed, guidance, and local reference-image resolution.
@@ -11,7 +24,7 @@ The official **Model Context Protocol (MCP)** server connecting AI assistants (C
 
 - 🖼️ **Native MCP Image Output**: Generated images (including QR codes, logos, try-on shots, and product photos) return standard MCP `ImageContent` so they render directly in your AI assistant's chat window.
 - 📁 **Local File Path Resolution**: Pass local paths (e.g. `./shoe.png` or `/Users/.../portrait.jpg`) directly in tool arguments—the server automatically reads and encodes them as base64 data URIs.
-- ⚡ **Expanded Tool Suite (43 Tools)**: Expanded image generation support including Passport Photos, Baby Milestones, YouTube Thumbnails, Blog Images, Nano Banana, Professional Photography, Sketch-to-Real, Human Builder, Apparel/Product/Jewelry Try-On, Festival Posts, Upscaling, and Discovery.
+- ⚡ **Expanded Tool Suite (47 Tools)**: Expanded image generation support including Passport Photos, Baby Milestones, YouTube Thumbnails, Blog Images, Nano Banana, Professional Photography, Sketch-to-Real, Human Builder, Apparel/Product/Jewelry Try-On, Festival Posts, Upscaling, and Discovery.
 - 🎯 **Advanced Model & Resolution Parameters**: Direct support for `model`, `modelId`, `promptId`, custom reference images, and server-side credit synchronization.
 - 🛡️ **Graceful Error Handling & 120s Timeout**: Informative error diagnostics when API keys are missing or requests time out, with clean stdio protocol execution.
 
@@ -19,7 +32,7 @@ The official **Model Context Protocol (MCP)** server connecting AI assistants (C
 
 ## Features & Tool Suite
 
-The server exposes **43 specialized generative and utility tools** over standard I/O (`stdio`):
+The server exposes **47 specialized generative, utility and social tools** over standard I/O (`stdio`):
 
 ### 1. Synchronous Image Generation (Immediate Inline Image Output)
 - **`generate_product_photo`** — Generates studio-grade commercial product photos with custom background scenes, ambient occlusion contact shadows, camera optics, resolutions (1K, 2K, 4K), aspect ratios, and dynamic logo/text overlays.
@@ -71,13 +84,16 @@ All generations automatically deduct credits from your CodingMantra wallet and p
 - **`save_social_draft`** — Create or fully replace a draft; uploads local images. Does not schedule or publish.
 - **`delete_social_draft`** — Remove a saved draft.
 - **`list_social_media`** — Paginate your generated image gallery.
+- **`upload_social_image`** — Upload and normalize an image; returns reusable owner-scoped media ID and URL.
+- **`get_social_image`** — Read uploaded media metadata.
+- **`schedule_social_draft`** — Atomically queue an approved saved draft; reuse draftId safely.
 - **`schedule_social_post`** — Queue final content for automatic future delivery to selected accounts.
 - **`list_social_posts`** — Filter the posting calendar by status, platform, and date range.
-- **`get_social_post`** — Inspect status, errors, retries, and published job IDs.
+- **`get_social_post`** — Inspect overall/per-account status, errors, retries, job IDs, and provider post IDs.
 - **`update_social_post`** — Edit or reschedule a queued post; retry a failed post with a new future time.
-- **`cancel_social_post`** — Stop a queued post before publication starts.
+- **`cancel_social_post`** — Cancel remaining deliveries; retain history and successful account results.
 - **`delete_social_post`** — Delete an eligible schedule record; does not delete a live platform post.
-- **`publish_social_post`** — Post immediately to one connected account.
+- **`publish_social_post`** — Queue immediate delivery to one or multiple connected accounts; poll to confirm publication.
 - **`get_social_analytics`** — Recorded reach, engagement, totals, top posts, and posting activity.
 
 #### Working with Claude, Codex, Antigravity, and other assistants
@@ -88,24 +104,34 @@ Try: “Create three Facebook posts for my bakery’s launch. Use a warm voice a
 
 Start with `get_social_workflow` and `list_social_accounts`. Use exact returned account IDs. Supply `brandBrief` to isolate a particular brand; otherwise caption generation uses saved brand context. Provide audience, verified facts, tone, offer, and CTA. Combine caption generation with existing image tools, or write captions directly in your assistant without AI credit charges.
 
-Instagram supports **exactly one image**, with at most **2,200 characters including hashtags**. Facebook supports text and up to 10 images, with 63,206 characters including hashtags. Video/reel publishing and other networks are not implemented. Generated images may use local file paths; the server resolves them and the backend persists them when drafts or schedules are saved.
+Instagram supports **1–10 images (one image or a carousel)**, with at most **2,200 characters including hashtags**. Facebook supports text and up to 10 images, with 63,206 characters including hashtags. Video/reel publishing and other networks are not implemented. Generated images may use local file paths; the server resolves them and the backend persists them when drafts or schedules are saved.
+
+Publishing and scheduling accept `accountIds` as one string or up to 20 distinct IDs from `list_social_accounts`, such as `facebook:123456` and `instagram:17890000000000000`. Account names are labels; use `platformAccountId` without its prefix only in existing draft/edit/analytics inputs. Those tools retain their legacy schemas.
 
-Scheduling requires `platforms`, `content.caption` (may be empty if there is an image), and a future `scheduledFor` ISO timestamp with an explicit UTC offset. Do not guess an ambiguous timezone. Use `draftId` when queuing a saved draft: the backend atomically consumes it and repeated requests return the same schedule. Immediate publishing has no idempotency guarantee; inspect publication state before retrying a timeout. Successful schedules publish on the backend cron worker even when the assistant is offline.
+Each intended post requires a caller-chosen `idempotencyKey` (8–128 letters, digits, dot, underscore, colon, or hyphen). Preserve the exact key and body on a retry. A new key intentionally creates a new post. Conflicting reuse returns 409; removing the original history returns 410. Both publication and scheduling are **asynchronous**: queue acceptance does not prove a live post. Poll `get_social_post` for each account's status, job ID and `providerPostId`. Provider acceptance followed by response loss can still be ambiguous; inspect provider history before rescheduling.
+
+Call `schedule_social_post` with a future ISO timestamp containing an explicit UTC offset. Resolve an ambiguous timezone first. `publish_social_post` uses the same shape without `scheduledFor`. Drafts remain separate; copy approved caption/images into the request. Standalone scheduling does not consume a saved draft or accept `draftId`/`socialContentId`. Use `schedule_social_draft` for the existing atomic draft-consumption workflow: provide draftId, complete platforms/content and scheduledFor using the draft’s raw platform account IDs. Reusing draftId returns the original schedule. This tool retains the v0.3 scheduling shape for approved saved drafts.
 
 ```json
 {
-  "draftId": "returned_draft_id",
-  "platforms": [{ "platform": "facebook", "accountId": "returned_page_id", "accountName": "My Bakery" }],
-  "content": {
-    "caption": "Our opening day is almost here. Join us for fresh bread!",
-    "hashtags": ["bakery", "freshbread"],
-    "mediaUrls": ["https://example.com/my-generated-image.png"]
-  },
-  "scheduledFor": "2026-10-10T09:00:00+05:30"
+  "accountIds": ["facebook:123456", "instagram:17890000000000000"],
+  "caption": "Meet our new collection.",
+  "hashtags": ["NewCollection"],
+  "images": [{"url": "https://example.com/product.jpg"}],
+  "idempotencyKey": "brand-launch-2027-001",
+  "scheduledFor": "2027-01-15T10:00:00+05:30"
 }
 ```
 
-Deployment order: deploy the updated web API, verify the cron worker, then release/use MCP v0.3.0. The backend must support bearer API keys; older browser-session-only endpoints return 401. For REST examples and the route map, see the repository’s `docs/social-mcp-api.md`.
+Each `images` item accepts a URL/base64/data-URI/local-path string or `{url}`, `{base64, mimeType?}`, `{path}`, or `{mediaId}`. `upload_social_image` takes `{ "image": <input> }`, excluding an existing media ID; it returns a `data` envelope with media ID, URL, JPEG MIME type, dimensions, bytes, and creation time. For example, upload `{ "image": { "path": "/path/to/product.png" } }`, then use `{ "mediaId": "returned-uuid" }` in a post. `get_social_image` accepts `{ "id": "returned-uuid" }`. Uploads do not publish or run AI generation.
+
+Source images must be static JPEG/PNG/WebP and no more than 10 MB/40 million pixels. JSON bodies are bounded to 20 MB. HTTPS URLs must be public port 443, return directly, and contain no credentials. Redirects/private destinations are rejected. The backend normalizes images to JPEG; Instagram requires a 4:5–1.91:1 aspect ratio. Dedicated API assets remain independent of gallery deletion. Use media IDs for large or repeated images.
+
+Versioned social responses retain the REST `{data: ...}` envelope in MCP text and structuredContent. List posts accepts `limit` 1–100 (default 20), `offset` 0–10,000, status/platform and ISO date filters. `cancel_social_post` cancels remaining deliveries and retains history; it does not remove remote posts. Updating or deleting history uses the existing owner-scoped hub API and remains blocked for active/published posts. Editing a keyed post does not free its original key; create an intentional new post with a new key.
+
+Limits are shared across keys per user: 300 reads and 60 writes per minute. API failures provide structured `error.code`, `error.status`, and optional `error.retryAfter` alongside text. Wait for Retry-After on 429 or request-in-progress conflicts; no automatic retry is performed by the MCP server.
+
+Deployment order: deploy the updated web API and Firestore rules, verify the cron worker, then release/use MCP v0.5.0. The package version here is prepared locally; updating source does not publish npm. See [social API documentation](https://codingmantra.com/api-docs/social-media), [OpenAPI contract](https://codingmantra.com/openapi/social-media.json), and repository `docs/social-mcp-api.md`.
 
 
 ## Video parameters
@@ -232,3 +258,16 @@ CODINGMANTRA_API_KEY=your_key node build/index.js
 ## License
 
 Private & Proprietary — Part of the CodingMantra Web Portal © 2026. All rights reserved.
+
+MCP transport note: the server accepts messages up to 24 MB so base64 images within the 20 MB API JSON limit fit with the MCP envelope. Individual clients may impose smaller message limits; use local paths, direct HTTPS URLs, and reusable media IDs in that case. Larger messages exceed the transport bound and can close the connection.
+
+
+### Ordered carousels and the Content Library
+
+Instagram accepts one image or 2–10 ordered carousel slides. Facebook accepts up to 10 images as a multi-photo feed post; its presentation is controlled by Facebook and may differ from an Instagram slider. Existing single-image requests and `mediaUrl` content remain supported. The first image is the cover. A carousel counts as one published Instagram post; publishing quota is per Instagram account in a rolling 24-hour window, read from Meta's `content_publishing_limit` response rather than assumed globally.
+
+`POST /api/v1/social/posts` and MCP `publish_social_post` / `schedule_social_post` accept ordered `images` and optional `mediaLayout`: `original`, `square-fit`, `square-crop`, `portrait-fit`, or `portrait-crop`. Fit preserves the complete image with white padding; crop fills a common canvas. Uploaded media IDs also support canvas conversion. Use the same idempotency key and unchanged body on retry. Post responses include `postType`, `imageCount`, `coverImage`, `processingMessage`, `deliveryNeedsReview`, and per-account publication `permalink`. A queued response confirms acceptance; poll `get_social_post` until delivery completes. When `deliveryNeedsReview` is true, inspect the account before intentionally creating another post; do not automatically retry with a new key.
+
+`GET /api/v1/social/library` (API-key authentication) and MCP `list_social_library` return `{ data: { items, total, hasMore } }`. Each item includes `mediaUrl` (cover), ordered `mediaUrls`, `type` (`image`, `carousel`, or `video`), caption, hashtags, usage, and statuses. Filters: `groupBy=post|media` (default `post`), `status=unused|scheduled|published`, `type`, `platform`, raw `accountId` (requires platform), `search`, `offset`, and `limit` (1–100, default 24). `list_social_media` continues to read the generated-image gallery. This library is read-only; reuse creates a new post.
+
+The Hub Content Library defaults to Posts, displays slide counts, opens every slide in a navigable preview, and reuses all images in order. Individual media retains the existing deduplicated asset view. The session-authenticated `/api/social/library` defaults to `groupBy=media` for compatibility; the Hub explicitly requests `post`. Saved content POST/PATCH supports `mediaUrls` (1–10), maintains scalar `mediaUrl` as the cover, and stores multi-image records as `carousel`.

package/build/api-client.js

@@ -1,6 +1,18 @@
 import dotenv from 'dotenv';
 dotenv.config({ quiet: true });
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 minutes for heavy generation tasks
+export class CodingMantraApiError extends Error {
+    status;
+    code;
+    retryAfter;
+    constructor(message, status, code, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+        this.name = 'CodingMantraApiError';
+    }
+}
 export function getApiKey() {
     return process.env.CODINGMANTRA_API_KEY;
 }
@@ -40,15 +52,20 @@ export async function apiClient(endpoint, options = {}) {
         });
     }
     catch (fetchError) {
-        if (fetchError?.name === 'TimeoutError' || fetchError?.name === 'AbortError') {
-            throw new Error(`CodingMantra API request timed out after ${DEFAULT_TIMEOUT_MS / 1000}s for ${endpoint}`);
+        if (fetchError instanceof Error && (fetchError.name === 'TimeoutError' || fetchError.name === 'AbortError')) {
+            const retryAdvice = endpoint === '/v1/social/posts' && options.method === 'POST'
+                ? ' Retry the exact body with the same idempotencyKey; do not create a new key.' : '';
+            throw new Error(`CodingMantra API request timed out for ${endpoint}.${retryAdvice}`);
         }
-        throw new Error(`Failed to connect to CodingMantra API at ${url}: ${fetchError?.message || fetchError}`);
+        throw new Error(`Failed to connect to CodingMantra API at ${url}: ${fetchError instanceof Error ? fetchError.message : String(fetchError)}`);
     }
     if (!response.ok) {
         let errorMsg = `API request failed (${response.status} ${response.statusText})`;
+        let code;
+        const text = await response.text();
         try {
-            const errorData = await response.json();
+            const errorData = JSON.parse(text);
+            code = typeof errorData?.error?.code === 'string' ? errorData.error.code : undefined;
             if (typeof errorData?.error === 'string') {
                 errorMsg += `: ${errorData.error}`;
             }
@@ -63,9 +80,9 @@ export async function apiClient(endpoint, options = {}) {
             }
         }
         catch {
-            errorMsg += `: ${await response.text()}`;
+            errorMsg += `: ${text.slice(0, 1000)}`;
         }
-        throw new Error(errorMsg);
+        throw new CodingMantraApiError(errorMsg, response.status, code, response.headers.get('retry-after') || undefined);
     }
     return response.json();
 }

package/build/image-utils.js

@@ -41,7 +41,7 @@ function getMimeTypeFromExt(filePath) {
  * reads it and converts to a base64 data URI.
  * If already a URL or data URI, returns as is.
  */
-export function resolveImageInput(input) {
+export function resolveImageInput(input, maxBytes) {
     if (!input || typeof input !== 'string')
         return '';
     const trimmed = input.trim();
@@ -53,12 +53,16 @@ export function resolveImageInput(input) {
     try {
         const resolvedPath = path.isAbsolute(trimmed) ? trimmed : path.resolve(process.cwd(), trimmed);
         if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isFile()) {
+            if (maxBytes && fs.statSync(resolvedPath).size > maxBytes)
+                throw new RangeError('Source image exceeds the allowed size (10 MB for social API uploads).');
             const buffer = fs.readFileSync(resolvedPath);
             const mimeType = getMimeTypeFromExt(resolvedPath);
             return `data:${mimeType};base64,${buffer.toString('base64')}`;
         }
     }
-    catch {
+    catch (error) {
+        if (error instanceof RangeError)
+            throw error;
         // If any filesystem read error, fall through
     }
     return trimmed;

package/build/index.js

@@ -3,13 +3,13 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
-import { apiClient } from './api-client.js';
+import { apiClient, CodingMantraApiError } from './api-client.js';
 import { formatImageToolResult, resolveImageInput, resolveImagesArray } from './image-utils.js';
 const server = new Server({
     name: "codingmantra-mcp",
-    version: "0.3.0",
+    version: "0.5.0",
 }, {
-    instructions: "For social media, start with get_social_workflow and list_social_accounts. Create captions and images, save drafts for review, then schedule or publish according to the user’s request. Use exact connected account IDs and explicit timezone offsets. Only Facebook Pages and Instagram image posts are supported. Keep social provider tokens on the backend.",
+    instructions: "For social media, start with get_social_workflow and list_social_accounts. Create captions and images, save drafts for review, then schedule or publish according to the user’s request. Use platform-prefixed account IDs, a stable caller-chosen idempotencyKey for each intended post, and explicit timezone offsets. Publication is asynchronous; poll get_social_post and never claim a queued post is live. Only Facebook Pages and Instagram image posts are supported. Keep social provider tokens on the backend.",
     capabilities: {
         tools: {},
     },
@@ -647,11 +647,11 @@ const EDIT_NANO_BANANA_TOOL = {
             },
             model: {
                 type: "string",
-                description: "Model tier ('flash', 'pro', 'standard'). Default is 'flash' (google/gemini-3.1-flash-image)."
+                description: "Model tier ('flash', 'pro', 'standard', 'gemini-nano-banana-2.1', 'hy-image-v3.5-preview'). Default is 'flash' (google/gemini-3.1-flash-image)."
             },
             modelId: {
                 type: "string",
-                description: "The image model ID."
+                description: "The image model ID (e.g. 'tencent/hy-image-v3.5-preview', 'google/gemini-nano-banana-2.1', 'google/gemini-3.1-flash-image')."
             },
             resolution: {
                 type: "string",
@@ -948,15 +948,16 @@ const CHECK_JOB_STATUS_TOOL = {
 const SOCIAL_ACCOUNT_SCHEMA = {
     type: 'object', properties: {
         platform: { type: 'string', enum: ['facebook', 'instagram'], description: 'Connected social platform.' },
-        accountId: { type: 'string', minLength: 1, description: 'Exact account ID returned by list_social_accounts.' },
+        accountId: { type: 'string', minLength: 1, description: 'Raw platformAccountId returned by list_social_accounts, without the facebook: or instagram: prefix; used only for draft/edit operations.' },
         accountName: { type: 'string', minLength: 1, description: 'Account display name returned by list_social_accounts.' },
     }, required: ['platform', 'accountId', 'accountName'],
 };
 const SOCIAL_CONTENT_PROPERTIES = {
     caption: { type: 'string', maxLength: 63206, description: 'Post text. Instagram caption plus hashtags must fit 2200 characters.' },
+    mediaLayout: { type: 'string', enum: ['original', 'square-fit', 'square-crop', 'portrait-fit', 'portrait-crop'], description: 'Apply the same canvas to all slides; fit preserves the full image with white padding, crop fills the canvas.' },
     brandBrief: { type: 'string', maxLength: 4000, description: 'Brand name, audience, voice, offer, facts, and call to action for this post.' },
     hashtags: { type: 'array', maxItems: 30, items: { type: 'string', description: 'Hashtag with or without a leading #.' }, description: 'Relevant hashtags; duplicates already in the caption are omitted during publication.' },
-    mediaUrls: { type: 'array', maxItems: 10, items: { type: 'string', description: 'HTTPS image URL, PNG/JPEG/WebP data URI, or local image path.' }, description: 'Images only. Instagram currently requires exactly one image; Facebook accepts up to 10.' },
+    mediaUrls: { type: 'array', maxItems: 10, items: { type: 'string', description: 'HTTPS image URL, PNG/JPEG/WebP data URI, or local image path.' }, description: 'Images only. Instagram supports one image or a carousel of 2–10 images; Facebook accepts up to 10.' },
 };
 const SOCIAL_SCHEDULE_PROPERTIES = {
     draftId: { type: 'string', description: 'Optional saved draft ID. Scheduling consumes it atomically; repeating this request returns the same scheduled post.' },
@@ -965,32 +966,57 @@ const SOCIAL_SCHEDULE_PROPERTIES = {
     content: { type: 'object', properties: SOCIAL_CONTENT_PROPERTIES, required: ['caption'], description: 'Final post caption, hashtags, brand brief, and images.' },
     scheduledFor: { type: 'string', format: 'date-time', description: 'Future ISO 8601 timestamp with explicit UTC offset, e.g. 2026-10-10T09:00:00+05:30. Resolve the user’s timezone before scheduling.' },
 };
-const SOCIAL_ID = { type: 'string', minLength: 1, pattern: '^[A-Za-z0-9_-]+$', description: 'Exact draft or scheduled post ID returned by a social tool.' };
+const SOCIAL_API_IMAGE = {
+    description: 'HTTPS URL, raw base64, data URI, local image path, or explicit image object. Static JPEG/PNG/WebP; 10 MB decoded limit. Uploaded media IDs belong to your API-key owner.',
+    oneOf: [
+        { type: 'string', minLength: 1, description: 'Public HTTPS URL, raw base64, data URI, or local image file path.' },
+        { type: 'object', additionalProperties: false, properties: { url: { type: 'string', minLength: 1, description: 'Direct public HTTPS image URL on port 443; no redirects.' } }, required: ['url'] },
+        { type: 'object', additionalProperties: false, properties: { base64: { type: 'string', minLength: 1, description: 'Raw base64 or image data URI.' }, mimeType: { type: 'string', enum: ['image/jpeg', 'image/png', 'image/webp'], description: 'Optional declared type; must match actual bytes.' } }, required: ['base64'] },
+        { type: 'object', additionalProperties: false, properties: { path: { type: 'string', minLength: 1, description: 'Local JPEG/PNG/WebP image file to upload.' } }, required: ['path'] },
+        { type: 'object', additionalProperties: false, properties: { mediaId: { type: 'string', format: 'uuid', description: 'Reusable UUID returned by upload_social_image.' } }, required: ['mediaId'] },
+    ],
+};
+const SOCIAL_POST_PROPERTIES = {
+    accountIds: { description: 'One or up to 20 distinct IDs from list_social_accounts: facebook:<Meta Page ID> or instagram:<Meta account ID>.', oneOf: [
+            { type: 'string', pattern: '^(facebook|instagram):[0-9]+$', description: 'One platform-prefixed connected account ID.' },
+            { type: 'array', minItems: 1, maxItems: 20, uniqueItems: true, items: { type: 'string', pattern: '^(facebook|instagram):[0-9]+$', description: 'Platform-prefixed connected account ID.' } },
+        ] },
+    mediaLayout: SOCIAL_CONTENT_PROPERTIES.mediaLayout,
+    caption: SOCIAL_CONTENT_PROPERTIES.caption,
+    hashtags: SOCIAL_CONTENT_PROPERTIES.hashtags,
+    images: { type: 'array', maxItems: 10, items: SOCIAL_API_IMAGE, description: 'Image inputs; Instagram requires 1–10 images (single image or carousel). Use reusable mediaId for large images.' },
+    idempotencyKey: { type: 'string', minLength: 8, maxLength: 128, pattern: '^[A-Za-z0-9._:-]+$', description: 'Caller-chosen key for this intended post. Preserve the exact key and body on retries; a new key means a new post. Never invent a new key after a timeout.' },
+};
+const SOCIAL_ID = { type: 'string', minLength: 1, pattern: '^[A-Za-z0-9_-]+$', description: 'Exact draft, media UUID or post ID returned by a social tool.' };
 const socialRead = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 const socialWrite = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
 const socialDelete = { ...socialWrite, destructiveHint: true, idempotentHint: true };
 const SOCIAL_TOOLS = [
     { name: 'get_social_workflow', description: 'Read the social workflow, capabilities, timezone guidance, and platform restrictions before planning content or posting. Read-only; no API call.', annotations: { ...socialRead, openWorldHint: false }, inputSchema: { type: 'object', properties: {} } },
-    { name: 'list_social_accounts', description: 'List connected Facebook Pages and Instagram accounts with IDs, names, permissions, and reconnect status. Read-only; OAuth tokens are never returned. Connect accounts in the web hub first.', annotations: socialRead, inputSchema: { type: 'object', properties: {} } },
+    { name: 'list_social_accounts', description: 'Read connected Facebook Pages and Instagram accounts with stable platform-prefixed IDs, raw platformAccountId, names, capabilities and reconnect status. No provider tokens. Connect in the web hub first.', annotations: socialRead, inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
     { name: 'generate_social_caption', description: 'Synchronously create or refine a caption and hashtags from a brief or images. Uses wallet credits and saved brand context unless brandBrief is supplied. Does not publish. Include verified facts, audience, tone, and CTA in the brief; review the result.', annotations: socialWrite, inputSchema: { type: 'object', properties: { ...SOCIAL_CONTENT_PROPERTIES, platform: { type: 'string', enum: ['facebook', 'instagram'], description: 'Target platform; defaults to Instagram.' } } } },
     { name: 'list_social_drafts', description: 'Read saved drafts, including captions, images, account selections, and proposed dates. Returns 20 per page; use offset for pagination.', annotations: socialRead, inputSchema: { type: 'object', properties: { offset: { type: 'integer', minimum: 0, description: 'Number of drafts to skip.' } } } },
     { name: 'save_social_draft', description: 'Save a new draft or replace an existing draft by id. Does not queue or publish. Send the complete draft when editing; omitted fields use API defaults. Local images are uploaded and persisted.', annotations: socialWrite, inputSchema: { type: 'object', properties: { ...SOCIAL_CONTENT_PROPERTIES, id: SOCIAL_ID, platforms: { type: 'array', items: SOCIAL_ACCOUNT_SCHEMA, description: 'Optional target accounts; drafts may have no accounts yet.' }, scheduledFor: { type: ['string', 'null'], format: 'date-time', description: 'Optional proposed date with explicit offset; saving does not schedule.' }, socialContentId: { type: 'string', description: 'Optional media library content ID.' } } } },
     { name: 'delete_social_draft', description: 'Delete one saved draft belonging to the API-key owner. Does not delete a scheduled or published post.', annotations: socialDelete, inputSchema: { type: 'object', properties: { id: SOCIAL_ID }, required: ['id'] } },
+    { name: 'list_social_library', description: 'Read reusable saved content and scheduled/published posts with ordered slides. Defaults to grouped posts; groupBy media returns individual assets. Read-only.', annotations: socialRead, inputSchema: { type: 'object', properties: { groupBy: { type: 'string', enum: ['post', 'media'] }, status: { type: 'string', enum: ['unused', 'scheduled', 'published'] }, type: { type: 'string', enum: ['image', 'carousel', 'video'] }, platform: { type: 'string', enum: ['facebook', 'instagram'] }, accountId: { type: 'string', description: 'Raw platform account ID; requires platform.' }, search: { type: 'string', maxLength: 200 }, offset: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 100 } } } },
     { name: 'list_social_media', description: 'Read generated images from your gallery for use in posts. Returns public media URLs; use existing image generation tools to create new visuals.', annotations: socialRead, inputSchema: { type: 'object', properties: { page: { type: 'integer', minimum: 1, description: 'Gallery page (default 1).' }, limit: { type: 'integer', minimum: 1, maximum: 50, description: 'Images per page (default 24).' } } } },
-    { name: 'schedule_social_post', description: 'Queue a final post for automatic future publication to connected accounts. Returns a scheduled post ID. ISO timestamps require a UTC offset; the server scheduler publishes even when this assistant is offline. Use draftId to avoid duplicate draft scheduling.', annotations: socialWrite, inputSchema: { type: 'object', properties: SOCIAL_SCHEDULE_PROPERTIES, required: ['platforms', 'content', 'scheduledFor'] } },
+    { name: 'upload_social_image', description: 'Synchronously upload and normalize an image from HTTPS URL, base64, data URI, or local file. Returns an owner-scoped reusable media ID and JPEG URL; does not publish or generate AI content. Source max 10 MB/40 million pixels; request max 20 MB.', annotations: socialWrite, inputSchema: { type: 'object', additionalProperties: false, properties: { image: { ...SOCIAL_API_IMAGE, oneOf: SOCIAL_API_IMAGE.oneOf.slice(0, 4) } }, required: ['image'] } },
+    { name: 'get_social_image', description: 'Read prepared image metadata by reusable media UUID. Read-only and scoped to your API-key owner.', annotations: socialRead, inputSchema: { type: 'object', additionalProperties: false, properties: { id: { type: 'string', format: 'uuid', description: 'Media UUID returned by upload_social_image.' } }, required: ['id'] } },
+    { name: 'schedule_social_draft', description: 'Asynchronously queue an approved saved hub draft using the existing atomic draft-consumption workflow. Requires draftId and complete final platforms/content/scheduledFor. Reusing draftId returns the original schedule; do not use for new standalone posts. Use raw platformAccountId in platforms.', annotations: { ...socialWrite, idempotentHint: true }, inputSchema: { type: 'object', additionalProperties: false, properties: SOCIAL_SCHEDULE_PROPERTIES, required: ['draftId', 'platforms', 'content', 'scheduledFor'] } },
+    { name: 'schedule_social_post', description: 'Asynchronously queue future delivery to one or multiple owned accounts. Requires a future ISO timestamp with an explicit offset and an idempotencyKey. Acceptance is not publication; poll get_social_post for per-account results. Does not consume a saved draft.', annotations: { ...socialWrite, idempotentHint: true }, inputSchema: { type: 'object', additionalProperties: false, properties: { ...SOCIAL_POST_PROPERTIES, scheduledFor: SOCIAL_SCHEDULE_PROPERTIES.scheduledFor }, required: ['accountIds', 'idempotencyKey', 'scheduledFor'] } },
     { name: 'list_social_posts', description: 'Read scheduled, published, failed, or cancelled posts. Filter by platform, status, or date range; use limit/offset for pagination. Dates must include a UTC offset.', annotations: socialRead, inputSchema: { type: 'object', properties: {
                 status: { type: 'string', enum: ['scheduled', 'published', 'failed', 'cancelled'], description: 'Post status filter.' },
                 platform: { type: 'string', enum: ['facebook', 'instagram'], description: 'Platform filter.' },
                 fromDate: { type: 'string', format: 'date-time', description: 'Inclusive start timestamp with offset.' },
                 toDate: { type: 'string', format: 'date-time', description: 'Inclusive end timestamp with offset.' },
-                limit: { type: 'integer', minimum: 1, maximum: 500, description: 'Page size, default 50.' },
-                offset: { type: 'integer', minimum: 0, description: 'Number of posts to skip.' },
+                limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Page size, default 20.' },
+                offset: { type: 'integer', minimum: 0, maximum: 10000, description: 'Number of posts to skip.' },
             } } },
-    { name: 'get_social_post', description: 'Read one scheduled post, including status, error, retries, and published job IDs. Check this before retrying a failed or ambiguous publication.', annotations: socialRead, inputSchema: { type: 'object', properties: { id: SOCIAL_ID }, required: ['id'] } },
+    { name: 'get_social_post', description: 'Read one scheduled post, including overall and per-account delivery status, retries, errors, job IDs and providerPostId receipts. Check this before retrying a failed or ambiguous publication.', annotations: socialRead, inputSchema: { type: 'object', properties: { id: SOCIAL_ID }, required: ['id'] } },
     { name: 'update_social_post', description: 'Edit a pending schedule, content, or target accounts. Provide a new future scheduledFor to reschedule or retry a failed post. The API rejects changes to posts that are publishing or already published.', annotations: { ...socialWrite, idempotentHint: true }, inputSchema: { type: 'object', properties: { id: SOCIAL_ID, content: { type: 'object', properties: SOCIAL_CONTENT_PROPERTIES, description: 'Fields to change; omitted fields retain their existing values.' }, platforms: SOCIAL_SCHEDULE_PROPERTIES.platforms, scheduledFor: SOCIAL_SCHEDULE_PROPERTIES.scheduledFor }, required: ['id'] } },
-    { name: 'cancel_social_post', description: 'Cancel a queued post so it will not publish. The API rejects cancellation while publishing or after publication. Does not remove an already published platform post.', annotations: socialDelete, inputSchema: { type: 'object', properties: { id: SOCIAL_ID }, required: ['id'] } },
+    { name: 'cancel_social_post', description: 'Cancel outstanding deliveries and retain the record. Successful targets remain published; pending targets are cancelled. The API rejects cancellation while publishing or after publication. Does not remove an already published platform post.', annotations: socialDelete, inputSchema: { type: 'object', properties: { id: SOCIAL_ID }, required: ['id'] } },
     { name: 'delete_social_post', description: 'Remove a schedule record. The API prevents deletion during publishing or after publication. Does not delete a live Facebook or Instagram post.', annotations: socialDelete, inputSchema: { type: 'object', properties: { id: SOCIAL_ID }, required: ['id'] } },
-    { name: 'publish_social_post', description: 'Publish immediately to one connected Facebook Page or Instagram account when the user requests posting now. Returns the platform publication result. Images only; Instagram requires exactly one image. Avoid blind retries after timeouts because a post may already be live.', annotations: { ...socialWrite, destructiveHint: true }, inputSchema: { type: 'object', properties: { ...SOCIAL_CONTENT_PROPERTIES, platform: { type: 'string', enum: ['facebook', 'instagram'], description: 'Platform to publish to.' }, accountId: { type: 'string', minLength: 1, description: 'Exact connected account ID from list_social_accounts.' }, socialContentId: { type: 'string', description: 'Optional media library content ID for publication tracking.' }, link: { type: 'string', description: 'Optional HTTPS link for a Facebook post.' } }, required: ['platform', 'accountId', 'caption'] } },
+    { name: 'publish_social_post', description: 'Asynchronously queue immediate delivery to one or multiple owned Facebook/Instagram accounts. Requires idempotencyKey; identical retries return the original post. HTTP acceptance does not mean live publication. Poll get_social_post; remote response loss may still be ambiguous.', annotations: { ...socialWrite, destructiveHint: true, idempotentHint: true }, inputSchema: { type: 'object', additionalProperties: false, properties: SOCIAL_POST_PROPERTIES, required: ['accountIds', 'idempotencyKey'] } },
     { name: 'get_social_analytics', description: 'Read recorded publishing totals, reach, engagement, top posts, and posting activity. Metrics reflect stored provider data and may be incomplete; these are not guaranteed optimal posting times.', annotations: socialRead, inputSchema: { type: 'object', properties: { range: { type: 'string', enum: ['7d', '30d', '90d'], description: 'Reporting range, default 30d.' }, platform: { type: 'string', enum: ['facebook', 'instagram'], description: 'Optional platform filter.' }, accountId: { type: 'string', description: 'Optional connected account filter.' } } } },
 ];
 const socialSchemaValidator = new AjvJsonSchemaValidator();
@@ -1021,6 +1047,17 @@ function socialImage(value) {
     catch { /* invalid source */ }
     throw new Error('Use an HTTPS image URL or a local PNG, JPEG, or WebP file.');
 }
+function socialApiImage(value) {
+    if (typeof value === 'string')
+        return resolveImageInput(value, 10 * 1024 * 1024);
+    if (value && typeof value === 'object' && 'path' in value) {
+        const image = socialImage(resolveImageInput(String(value.path), 10 * 1024 * 1024));
+        if (!image.startsWith('data:'))
+            throw new Error('The local image path must point to an existing JPEG, PNG or WebP file.');
+        return image;
+    }
+    return value;
+}
 function socialQuery(args, allowed) {
     const query = new URLSearchParams();
     for (const key of allowed)
@@ -1054,25 +1091,32 @@ async function executeSocialTool(name, rawArgs) {
         }
         args.content = content;
     }
+    if (Array.isArray(args.images))
+        args.images = args.images.map(socialApiImage);
     let result;
     if (name === 'get_social_workflow') {
         result = {
             supportedPlatforms: ['facebook', 'instagram'],
             connectUrl: 'https://codingmantra.com/tools/digital-marketing/social-media-hub',
-            steps: ['list_social_accounts', 'generate_social_caption or write a caption with your assistant', 'generate an image with existing MCP tools or list_social_media', 'save_social_draft for review', 'schedule_social_post or publish_social_post as requested', 'list_social_posts / get_social_post / get_social_analytics'],
-            limits: { instagram: { images: 1, captionIncludingHashtags: 2200 }, facebook: { maxImages: 10, captionIncludingHashtags: 63206 }, videoPublishing: false },
+            steps: ['list_social_accounts', 'generate_social_caption or write a caption with your assistant', 'generate an image, list_social_media, or upload_social_image for a reusable mediaId', 'save_social_draft for review', 'schedule_social_post or publish_social_post as requested; schedule_social_draft for an approved saved draft', 'list_social_posts / get_social_post / get_social_analytics'],
+            limits: { instagram: { minImages: 1, maxImages: 10, carousel: true, captionIncludingHashtags: 2200 }, facebook: { minImages: 0, maxImages: 10, multiPhoto: true, captionIncludingHashtags: 63206 }, videoPublishing: false },
             timezone: 'Ask for the user’s intended timezone when ambiguous; convert to an ISO 8601 timestamp with an explicit UTC offset. Dates are returned as ISO 8601 UTC timestamps.',
             contentGuidance: 'Use a clear hook, useful verified facts, the intended audience and brand voice, and one CTA. Supply brandBrief to generate_social_caption for per-brand context. Never invent prices, claims, discounts, or business details. Caption generation uses credits; drafts and schedules do not run AI.',
-            scheduling: 'The deployed backend requires its cron scheduler to run. The assistant does not need to remain online. Saved drafts are consumed atomically; reuse draftId to make repeated scheduling requests safe.',
-            retries: 'Inspect failed post errors and publishedJobIds before rescheduling. Immediate publication has no idempotency guarantee; do not automatically retry ambiguous timeouts.',
+            accountIds: 'Use accounts[].id for publishing/scheduling (facebook:123 or instagram:456); draft/edit/analytics tools use the raw platformAccountId plus platform.',
+            apiDocsUrl: 'https://codingmantra.com/api-docs/social-media',
+            openApiUrl: 'https://codingmantra.com/openapi/social-media.json',
+            rateLimits: { readsPerMinute: 300, writesPerMinute: 60, scope: 'per user, shared across API keys; respect Retry-After on 429' },
+            scheduling: 'The deployed backend requires its cron scheduler to run. Both immediate and future delivery are asynchronous. Poll get_social_post for per-account receipts. Saving a draft does not publish. schedule_social_post copies standalone content; schedule_social_draft atomically consumes an approved saved draft and reuses draftId for safe retries.',
+            retries: 'Preserve idempotencyKey and the exact request body for retries. Same-key retries return the original record; conflicting content returns 409, removed history returns 410. Do not generate a new key after a timeout. Provider acceptance followed by response loss can still be ambiguous; inspect the hub and provider history before rescheduling.',
         };
     }
     else {
         let endpoint = '';
         let method = 'GET';
         let body;
+        const headers = {};
         if (name === 'list_social_accounts')
-            endpoint = '/social/meta/connection';
+            endpoint = '/v1/social/accounts';
         if (name === 'generate_social_caption') {
             endpoint = '/social/caption';
             method = 'POST';
@@ -1089,55 +1133,53 @@ async function executeSocialTool(name, rawArgs) {
             endpoint = `/social/drafts?id=${socialId(args)}`;
             method = 'DELETE';
         }
+        if (name === 'list_social_library')
+            endpoint = '/v1/social/library' + socialQuery(args, ['groupBy', 'status', 'type', 'platform', 'accountId', 'search', 'offset', 'limit']);
         if (name === 'list_social_media')
             endpoint = '/social/gallery' + socialQuery({ ...args, type: 'image' }, ['type', 'page', 'limit']);
-        if (name === 'schedule_social_post') {
+        if (name === 'schedule_social_draft') {
             endpoint = '/social/schedule';
             method = 'POST';
             body = args;
         }
+        if (name === 'upload_social_image') {
+            endpoint = '/v1/social/media';
+            method = 'POST';
+            body = socialApiImage(args.image);
+        }
+        if (name === 'get_social_image')
+            endpoint = `/v1/social/media/${socialId(args)}`;
+        if (name === 'schedule_social_post' || name === 'publish_social_post') {
+            endpoint = '/v1/social/posts';
+            method = 'POST';
+            const { idempotencyKey, ...post } = args;
+            headers['Idempotency-Key'] = String(idempotencyKey);
+            body = post;
+        }
         if (name === 'list_social_posts')
-            endpoint = '/social/schedule' + socialQuery(args, ['status', 'platform', 'fromDate', 'toDate', 'limit', 'offset']);
-        if (['get_social_post', 'update_social_post', 'cancel_social_post', 'delete_social_post'].includes(name)) {
+            endpoint = '/v1/social/posts' + socialQuery(args, ['status', 'platform', 'fromDate', 'toDate', 'limit', 'offset']);
+        if (['update_social_post', 'delete_social_post'].includes(name)) {
             endpoint = `/social/schedule/${socialId(args)}`;
             if (name === 'update_social_post') {
                 method = 'PATCH';
                 const { id: _id, ...updates } = args;
                 body = updates;
             }
-            if (name === 'cancel_social_post') {
-                method = 'PATCH';
-                body = { status: 'cancelled' };
-            }
             if (name === 'delete_social_post')
                 method = 'DELETE';
         }
-        if (name === 'publish_social_post') {
-            endpoint = '/social/meta/publish';
-            method = 'POST';
-            const caption = typeof args.caption === 'string' ? args.caption.trim() : '';
-            if (args.hashtags !== undefined && (!Array.isArray(args.hashtags) || args.hashtags.some(tag => typeof tag !== 'string' || !/^#?[\p{L}\p{N}_]+$/u.test(tag))))
-                throw new Error('Use valid hashtags containing letters, numbers, or underscores.');
-            const existing = new Set((caption.match(/#[\p{L}\p{N}_]+/gu) || []).map(tag => tag.toLowerCase()));
-            const tags = (args.hashtags || []).map(tag => `#${tag.replace(/^#/, '')}`).filter(tag => {
-                if (existing.has(tag.toLowerCase()))
-                    return false;
-                existing.add(tag.toLowerCase());
-                return true;
-            });
-            const text = [caption, tags.join(' ')].filter(Boolean).join('\n\n');
-            const images = args.mediaUrls || [];
-            if (!['facebook', 'instagram'].includes(String(args.platform)))
-                throw new Error('Choose Facebook or Instagram.');
-            if (args.platform === 'instagram' && images.length !== 1)
-                throw new Error('Instagram requires exactly one image.');
-            body = args.platform === 'instagram'
-                ? { platform: 'instagram', instagramId: args.accountId, caption: text, imageDataUrl: images[0]?.startsWith('data:') ? images[0] : undefined, imageUrl: images[0]?.startsWith('https:') ? images[0] : undefined, socialContentId: args.socialContentId }
-                : { platform: 'facebook', pageId: args.accountId, message: text, imageUrls: images.length ? images : undefined, link: args.link, socialContentId: args.socialContentId };
+        if (name === 'get_social_post' || name === 'cancel_social_post') {
+            endpoint = `/v1/social/posts/${socialId(args)}`;
+            if (name === 'cancel_social_post')
+                method = 'DELETE';
         }
         if (name === 'get_social_analytics')
             endpoint = '/social/analytics' + socialQuery(args, ['range', 'platform', 'accountId']);
-        result = await apiClient(endpoint, { method, ...(body ? { body: JSON.stringify(body) } : {}) });
+        const requestBody = body !== undefined ? JSON.stringify(body) : undefined;
+        if (endpoint.startsWith('/v1/social/') && requestBody && Buffer.byteLength(requestBody, 'utf8') > 20 * 1024 * 1024) {
+            throw new Error('Social API JSON requests must be 20 MB or smaller. Upload images separately and reuse media IDs.');
+        }
+        result = await apiClient(endpoint, { method, headers, signal: AbortSignal.timeout(300_000), ...(requestBody !== undefined ? { body: requestBody } : {}) });
     }
     result = normalizeSocialDates(result);
     return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result, ...(result.success === false ? { isError: true } : {}) };
@@ -1539,17 +1581,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
     }
     catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
         return {
-            content: [{ type: "text", text: `❌ **Error:** ${error.message || error}` }],
+            ...(error instanceof CodingMantraApiError ? { structuredContent: { error: { code: error.code, message, status: error.status, retryAfter: error.retryAfter } } } : {}),
+            content: [{ type: "text", text: `❌ **Error:** ${message}` }],
             isError: true,
         };
     }
 });
 // ─── Server Startup ─────────────────────────────────────────────────────────────
 async function run() {
-    const transport = new StdioServerTransport();
+    // A 10 MB source becomes ~13.4 MB in base64. Leave room for the 20 MB
+    // API JSON limit plus the MCP request envelope, while still bounding input.
+    const transport = new StdioServerTransport(process.stdin, process.stdout, { maxBufferSize: 24 * 1024 * 1024 });
     await server.connect(transport);
-    console.error("[CodingMantra MCP] Server v0.3.0 initialized and running on stdio (43 tools active)");
+    console.error("[CodingMantra MCP] Server v0.5.0 initialized and running on stdio (47 tools active)");
 }
 run().catch((error) => {
     console.error("Fatal error running CodingMantra MCP server:", error);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@codingmantra/mcp-server",
-  "version": "0.3.0",
-  "description": "Official Model Context Protocol (MCP) Server for CodingMantra AI Generation Tools",
+  "version": "0.5.0",
+  "description": "Official MCP server for CodingMantra AI tools and social media publishing and scheduling",
   "type": "module",
   "main": "build/index.js",
   "bin": {