@codingmantra/mcp-server 0.2.2 → 0.4.0

package/README.md

@@ -2,14 +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.2.2
+## What's New in v0.4.0
+
+- 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:** 15 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.
 - **Terminal job handling:** Polling stops for completed, failed, or cancelled jobs.
 
 - 🖼️ **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 (28 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 (46 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.
 
@@ -17,7 +24,7 @@ The official **Model Context Protocol (MCP)** server connecting AI assistants (C
 
 ## Features & Tool Suite
 
-The server exposes **28 specialized generative and utility tools** over standard I/O (`stdio`):
+The server exposes **46 specialized generative and utility 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.
@@ -60,6 +67,65 @@ All generations automatically deduct credits from your CodingMantra wallet and p
 
 ---
 
+### 5. Social Content & Scheduling
+
+- **`get_social_workflow`** — Capabilities, workflow, content guidance, and platform limits.
+- **`list_social_accounts`** — Connected Facebook Pages and Instagram accounts; no provider tokens.
+- **`generate_social_caption`** — Generate or refine a caption and hashtags using images, brandBrief, and saved brand context. Uses credits.
+- **`list_social_drafts`** — Paginated saved drafts (20 per page).
+- **`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 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`** — 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`** — 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
+
+Connect accounts once in the [Social Media Hub](https://codingmantra.com/tools/digital-marketing/social-media-hub). The same `CODINGMANTRA_API_KEY` used for media generation identifies the owner of all drafts and schedules; browser cookies and Meta access tokens are not needed in your assistant. Account connection/reconnection remains in the browser. Any assistant supporting standard MCP stdio can discover the tools and their schemas. Responses include text plus structured JSON, UTC ISO timestamps, IDs, and pagination fields.
+
+Try: “Create three Facebook posts for my bakery’s launch. Use a warm voice and these verified opening hours. Save drafts for review, then schedule the approved posts at 9 AM Asia/Kolkata next week.” Or: “Show failed posts, explain their errors, and move this queued post to tomorrow at 6 PM Asia/Kolkata.”
+
+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.
+
+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.
+
+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
+{
+  "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"
+}
+```
+
+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.4.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
 
 General video tools require `prompt` (10–5000 characters), `model`, `timeDuration`, `resolution`, and `aspectRatio`. Use model-supported settings; Veo requires 8 seconds for 1080p, references, or an end frame. Choose one image mode: main image, frames, or references. Reference images accept URLs, data URIs, or local paths (up to 3 for Veo). Optional settings include characters, seed, guidanceScale, soundEffects, and styleAmbiance.
@@ -184,3 +250,5 @@ 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.

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

@@ -2,12 +2,14 @@
 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 { apiClient } from './api-client.js';
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+import { apiClient, CodingMantraApiError } from './api-client.js';
 import { formatImageToolResult, resolveImageInput, resolveImagesArray } from './image-utils.js';
 const server = new Server({
     name: "codingmantra-mcp",
-    version: "0.2.2",
+    version: "0.4.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 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: {},
     },
@@ -942,10 +944,246 @@ const CHECK_JOB_STATUS_TOOL = {
         required: ["jobId"]
     }
 };
+// Social tools share the same API key as media generation; social tokens stay on the server.
+const SOCIAL_ACCOUNT_SCHEMA = {
+    type: 'object', properties: {
+        platform: { type: 'string', enum: ['facebook', 'instagram'], description: 'Connected social platform.' },
+        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.' },
+    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.' },
+};
+const SOCIAL_SCHEDULE_PROPERTIES = {
+    draftId: { type: 'string', description: 'Optional saved draft ID. Scheduling consumes it atomically; repeating this request returns the same scheduled post.' },
+    socialContentId: { type: 'string', description: 'Optional media library content ID for tracking.' },
+    platforms: { type: 'array', minItems: 1, maxItems: 20, items: SOCIAL_ACCOUNT_SCHEMA, description: 'Connected accounts to publish to; select each account once.' },
+    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_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.' } },
+        ] },
+    caption: SOCIAL_CONTENT_PROPERTIES.caption,
+    hashtags: SOCIAL_CONTENT_PROPERTIES.hashtags,
+    images: { type: 'array', maxItems: 10, items: SOCIAL_API_IMAGE, description: 'Image inputs; Instagram requires exactly one. 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: '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_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: '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: 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 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 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: '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();
+const socialValidators = new Map(SOCIAL_TOOLS.map(tool => [tool.name, socialSchemaValidator.getValidator(tool.inputSchema)]));
+function normalizeSocialDates(value) {
+    if (Array.isArray(value))
+        return value.map(normalizeSocialDates);
+    if (value && typeof value === 'object') {
+        const object = value;
+        const seconds = object._seconds ?? object.seconds;
+        if (typeof seconds === 'number' && Object.keys(object).every(key => ['_seconds', '_nanoseconds', 'seconds', 'nanoseconds'].includes(key))) {
+            return new Date(seconds * 1000).toISOString();
+        }
+        return Object.fromEntries(Object.entries(object).map(([key, nested]) => [key, normalizeSocialDates(nested)]));
+    }
+    return value;
+}
+function socialImage(value) {
+    if (typeof value !== 'string')
+        throw new Error('Each media image must be a URL, data URI, or local file path.');
+    const resolved = resolveImageInput(value);
+    if (/^data:image\/(jpeg|png|webp);base64,/i.test(resolved))
+        return resolved;
+    try {
+        if (new URL(resolved).protocol === 'https:')
+            return resolved;
+    }
+    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)
+        if (args[key] !== undefined)
+            query.set(key, String(args[key]));
+    return query.size ? `?${query}` : '';
+}
+function socialId(args) {
+    if (typeof args.id !== 'string' || !/^[A-Za-z0-9_-]+$/.test(args.id))
+        throw new Error('Provide a valid post or draft ID.');
+    return encodeURIComponent(args.id);
+}
+async function executeSocialTool(name, rawArgs) {
+    const validated = socialValidators.get(name)(rawArgs);
+    if (!validated.valid)
+        throw new Error(`Invalid ${name} parameters: ${validated.errorMessage}`);
+    const args = { ...rawArgs };
+    if (args.mediaUrls !== undefined) {
+        if (!Array.isArray(args.mediaUrls))
+            throw new Error('mediaUrls must be an array.');
+        args.mediaUrls = args.mediaUrls.map(socialImage);
+    }
+    if (args.content !== undefined) {
+        if (!args.content || typeof args.content !== 'object' || Array.isArray(args.content))
+            throw new Error('content must be a post object.');
+        const content = { ...args.content };
+        if (content.mediaUrls !== undefined) {
+            if (!Array.isArray(content.mediaUrls))
+                throw new Error('content.mediaUrls must be an array.');
+            content.mediaUrls = content.mediaUrls.map(socialImage);
+        }
+        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, 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: { images: 1, captionIncludingHashtags: 2200 }, facebook: { maxImages: 10, 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.',
+            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 = '/v1/social/accounts';
+        if (name === 'generate_social_caption') {
+            endpoint = '/social/caption';
+            method = 'POST';
+            body = { caption: args.caption || '', brandBrief: args.brandBrief || '', mediaUrls: args.mediaUrls || [], platform: args.platform || 'instagram' };
+        }
+        if (name === 'list_social_drafts')
+            endpoint = '/social/drafts' + socialQuery(args, ['offset']);
+        if (name === 'save_social_draft') {
+            endpoint = '/social/drafts';
+            method = 'POST';
+            body = args;
+        }
+        if (name === 'delete_social_draft') {
+            endpoint = `/social/drafts?id=${socialId(args)}`;
+            method = 'DELETE';
+        }
+        if (name === 'list_social_media')
+            endpoint = '/social/gallery' + socialQuery({ ...args, type: 'image' }, ['type', 'page', 'limit']);
+        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 = '/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 === 'delete_social_post')
+                method = 'DELETE';
+        }
+        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']);
+        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 } : {}) };
+}
 // ─── Tool Registration ─────────────────────────────────────────────────────────
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
         tools: [
+            ...SOCIAL_TOOLS,
             GENERATE_JEWELLERY_RATE_POSTER_TOOL,
             GENERATE_PRODUCT_PHOTO_TOOL,
             GENERATE_LOGO_TOOL,
@@ -981,6 +1219,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         const { name, arguments: rawArgs } = request.params;
+        if (SOCIAL_TOOLS.some(tool => tool.name === name))
+            return await executeSocialTool(name, rawArgs || {});
         const args = rawArgs || {};
         if (name === 'generate_jewellery_rate_poster') {
             const response = await apiClient('/image/jewellery-rate-poster', {
@@ -1336,17 +1576,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.2.2 initialized and running on stdio (28 tools active)");
+    console.error("[CodingMantra MCP] Server v0.4.0 initialized and running on stdio (46 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.2.2",
-  "description": "Official Model Context Protocol (MCP) Server for CodingMantra AI Generation Tools",
+  "version": "0.4.0",
+  "description": "Official MCP server for CodingMantra AI tools and social media publishing and scheduling",
   "type": "module",
   "main": "build/index.js",
   "bin": {