@codingmantra/mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -2,13 +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.4.0
+## 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:** 15 tools for connected accounts, caption creation, drafts, gallery images, immediate publishing, scheduling, status, cancellation, and analytics. Uses the same CodingMantra API key.
+- **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.
@@ -16,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 (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.
+- ⚡ **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.
 
@@ -24,7 +32,7 @@ The official **Model Context Protocol (MCP)** server connecting AI assistants (C
 
 ## Features & Tool Suite
 
-The server exposes **46 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.
@@ -96,7 +104,7 @@ 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.
 
@@ -123,7 +131,7 @@ Versioned social responses retain the REST `{data: ...}` envelope in MCP text an
 
 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`.
+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
@@ -252,3 +260,14 @@ CODINGMANTRA_API_KEY=your_key node build/index.js
 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/index.js

@@ -7,7 +7,7 @@ import { apiClient, CodingMantraApiError } from './api-client.js';
 import { formatImageToolResult, resolveImageInput, resolveImagesArray } from './image-utils.js';
 const server = new Server({
     name: "codingmantra-mcp",
-    version: "0.4.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 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: {
@@ -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",
@@ -954,9 +954,10 @@ const SOCIAL_ACCOUNT_SCHEMA = {
 };
 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.' },
@@ -980,9 +981,10 @@ const SOCIAL_POST_PROPERTIES = {
             { 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 exactly one. Use reusable mediaId for large images.' },
+    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.' };
@@ -996,6 +998,7 @@ const SOCIAL_TOOLS = [
     { 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: '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'] } },
@@ -1096,7 +1099,7 @@ async function executeSocialTool(name, rawArgs) {
             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 },
+            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.',
             accountIds: 'Use accounts[].id for publishing/scheduling (facebook:123 or instagram:456); draft/edit/analytics tools use the raw platformAccountId plus platform.',
@@ -1130,6 +1133,8 @@ 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_draft') {
@@ -1590,7 +1595,7 @@ async function run() {
     // 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.4.0 initialized and running on stdio (46 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,6 +1,6 @@
 {
   "name": "@codingmantra/mcp-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Official MCP server for CodingMantra AI tools and social media publishing and scheduling",
   "type": "module",
   "main": "build/index.js",