@exileum/meta-mcp 6.0.0 → 8.0.0

package/dist/tools/threads/publishing.js

@@ -2,6 +2,11 @@ import { z } from "zod";
 import { httpsUrl, metaId } from "../../schemas.js";
 import { waitForThreadsContainer, IMAGE_PROCESSING_TIMEOUT, VIDEO_PROCESSING_TIMEOUT } from "../../utils/container.js";
 import { formatErrorResponse, validationError } from "../../utils/errors.js";
+import { formatResponse } from "../../utils/response.js";
+import { buildParams } from "../../utils/params.js";
+import { makeProgressNotifier } from "../../utils/progress.js";
+import { READ_ONLY_TOOL, DESTRUCTIVE_TOOL, WRITE_TOOL } from "../annotations.js";
+import { THREADS_PROFILE_CACHE_PREFIX } from "./profile.js";
 export const topicTagSchema = z.string().min(1).max(50).regex(/^[^.&]+$/, "Topic tags cannot contain periods or ampersands").optional().describe("Topic tag for the post (1-50 chars, no periods or ampersands)");
 export const shareToIgStorySchema = z.enum(["light", "dark"]).optional().describe("Cross-share this post to linked Instagram as a Story. 'light' = normal, 'dark' = dark mode. Requires threads_share_to_instagram permission and a linked Instagram account. The Threads post still publishes even if cross-share fails.");
 export const pollOptionsSchema = z.array(z.string().min(1).max(25)).min(2).max(4).optional().describe("Poll options (2-4 choices, each 1-25 chars). Creates a poll attachment. Cannot be combined with text_attachment, link_attachment, or gif_id+gif_provider.");
@@ -34,24 +39,31 @@ function applyAllowlistedCountryCodes(params, codes) {
 }
 export function registerThreadsPublishingTools(server, client) {
     // ─── threads_publish_text ────────────────────────────────────
-    server.tool("threads_publish_text", "Publish a text-only post on Threads. By default publishes in a single API call via auto_publish_text=true (faster and avoids the 4279009 'container not propagated' race condition). Supports optional link attachment, poll, GIF, topic tag, quote post, cross-share to Instagram Stories, geo-gating via allowlisted_country_codes, and text_attachment for long-form content (up to 10,000 chars with optional styling and link). Only one attachment type per post — text_attachment, poll_options, link_attachment, and gif_id+gif_provider are mutually exclusive. Set auto_publish=false to fall back to the legacy two-step create-then-publish flow.", {
-        text: z.string().max(500).describe("Post text (max 500 chars)"),
-        reply_control: replyControlSchema,
-        link_attachment: z.string().url().optional().describe("URL to attach as a link preview card (max 5 links per post). Cannot be combined with text_attachment, poll_options, or gif_id+gif_provider."),
-        topic_tag: topicTagSchema,
-        quote_post_id: z.string().optional().describe("ID of a post to quote"),
-        poll_options: pollOptionsSchema,
-        gif_id: z.string().min(1).optional().describe("GIPHY GIF ID. Must be provided together with gif_provider — providing only one returns an error."),
-        gif_provider: z.enum(["GIPHY"]).optional().describe("GIF provider. Only GIPHY is currently supported. Must be provided together with gif_id — providing only one returns an error."),
-        is_spoiler: z.boolean().optional().describe("Mark content as spoiler"),
-        share_to_ig_story: shareToIgStorySchema,
-        allowlisted_country_codes: allowlistedCountryCodesSchema,
-        text_attachment: z.string().min(1).max(10000).optional().describe("Long-form text attachment (max 10,000 chars). Renders as expandable 'Read more' block beneath the primary text. Cannot be combined with poll_options, link_attachment, or gif_id+gif_provider."),
-        text_attachment_link: z.string().url().optional().describe("URL to include inside the text attachment card. Requires text_attachment."),
-        text_attachment_styling: textAttachmentStylingSchema,
-        auto_publish: z.boolean().optional().default(true).describe("When true (default), combine container creation and publishing into a single API call via auto_publish_text=true — one HTTP request instead of two, and no risk of the 4279009 'container not propagated yet' race. Set to false to fall back to the legacy two-step flow (POST /threads, then POST /threads_publish)."),
-        alt_text: z.never("alt_text is not supported on text-only Threads posts (media_type=TEXT). Use threads_publish_image, threads_publish_video, or threads_publish_carousel for accessibility labels — those tools accept alt_text on IMAGE/VIDEO/CAROUSEL containers.").optional().describe("Reserved — must be omitted. alt_text is only supported on image, video, and carousel posts; passing it here raises a Zod schema error."),
-    }, async ({ text, reply_control, link_attachment, topic_tag, quote_post_id, poll_options, gif_id, gif_provider, is_spoiler, share_to_ig_story, allowlisted_country_codes, text_attachment, text_attachment_link, text_attachment_styling, auto_publish }) => {
+    server.registerTool("threads_publish_text", {
+        description: "Publish a text-only post on Threads. By default publishes in a single API call via auto_publish_text=true (faster and avoids the 4279009 'container not propagated' race condition). Supports optional link attachment, poll, GIF, topic tag, quote post, cross-share to Instagram Stories, geo-gating via allowlisted_country_codes, location tagging via location_id, and text_attachment for long-form content (up to 10,000 chars with optional styling and link). Only one attachment type per post — text_attachment, poll_options, link_attachment, and gif_id+gif_provider are mutually exclusive. Set auto_publish=false to fall back to the legacy two-step create-then-publish flow.",
+        inputSchema: {
+            text: z.string().max(500).describe("Post text (max 500 chars)"),
+            reply_control: replyControlSchema,
+            link_attachment: z.string().url().optional().describe("URL to attach as a link preview card (max 5 links per post). Cannot be combined with text_attachment, poll_options, or gif_id+gif_provider."),
+            topic_tag: topicTagSchema,
+            quote_post_id: z.string().optional().describe("ID of a post to quote"),
+            poll_options: pollOptionsSchema,
+            gif_id: z.string().min(1).optional().describe("GIPHY GIF ID. Must be provided together with gif_provider — providing only one returns an error."),
+            gif_provider: z.enum(["GIPHY"]).optional().describe("GIF provider. Only GIPHY is currently supported. Must be provided together with gif_id — providing only one returns an error."),
+            is_spoiler: z.boolean().optional().describe("Mark content as spoiler"),
+            share_to_ig_story: shareToIgStorySchema,
+            allowlisted_country_codes: allowlistedCountryCodesSchema,
+            location_id: z.string().optional().describe("Location ID for tagging the post. Use threads_search_locations to find IDs. Requires the threads_location_tagging permission on the access token."),
+            text_attachment: z.string().min(1).max(10000).optional().describe("Long-form text attachment (max 10,000 chars). Renders as expandable 'Read more' block beneath the primary text. Cannot be combined with poll_options, link_attachment, or gif_id+gif_provider."),
+            text_attachment_link: z.string().url().optional().describe("URL to include inside the text attachment card. Requires text_attachment."),
+            text_attachment_styling: textAttachmentStylingSchema,
+            auto_publish: z.boolean().optional().default(true).describe("When true (default), combine container creation and publishing into a single API call via auto_publish_text=true — one HTTP request instead of two, and no risk of the 4279009 'container not propagated yet' race. Set to false to fall back to the legacy two-step flow (POST /threads, then POST /threads_publish)."),
+            alt_text: z.never("alt_text is not supported on text-only Threads posts (media_type=TEXT). Use threads_publish_image, threads_publish_video, or threads_publish_carousel for accessibility labels — those tools accept alt_text on IMAGE/VIDEO/CAROUSEL containers.").optional().describe("Reserved — must be omitted. alt_text is only supported on image, video, and carousel posts; passing it here raises a Zod schema error."),
+        },
+        annotations: WRITE_TOOL,
+    }, async ({ text, reply_control, link_attachment, topic_tag, quote_post_id, poll_options, gif_id, gif_provider, is_spoiler, share_to_ig_story, allowlisted_country_codes, location_id, text_attachment, text_attachment_link, text_attachment_styling, auto_publish }) => {
+        let step = "container creation";
+        let containerId;
         try {
             // Validate mutual exclusions
             if (text_attachment && poll_options) {
@@ -79,8 +91,9 @@ export function registerThreadsPublishingTools(server, client) {
                     const sorted = [...text_attachment_styling].sort((a, b) => a.offset - b.offset);
                     for (let i = 1; i < sorted.length; i++) {
                         const prev = sorted[i - 1];
-                        if (sorted[i].offset < prev.offset + prev.length) {
-                            return validationError(`text_attachment_styling ranges must not overlap: range at offset ${sorted[i].offset} overlaps with range at offset ${prev.offset}`);
+                        const curr = sorted[i];
+                        if (curr.offset < prev.offset + prev.length) {
+                            return validationError(`text_attachment_styling ranges must not overlap: range at offset ${curr.offset} overlaps with range at offset ${prev.offset}`);
                         }
                     }
                 }
@@ -91,15 +104,7 @@ export function registerThreadsPublishingTools(server, client) {
             if (gif_id && (text_attachment || poll_options || link_attachment)) {
                 return validationError("GIF attachment cannot be combined with text_attachment, poll_options, or link_attachment");
             }
-            const params = { media_type: "TEXT", text };
-            if (reply_control)
-                params.reply_control = reply_control;
-            if (link_attachment)
-                params.link_attachment = link_attachment;
-            if (topic_tag)
-                params.topic_tag = topic_tag;
-            if (quote_post_id)
-                params.quote_post_id = quote_post_id;
+            let pollAttachment;
             if (poll_options) {
                 const pollObj = {};
                 poll_options.forEach((opt, i) => {
@@ -107,13 +112,12 @@ export function registerThreadsPublishingTools(server, client) {
                     if (key)
                         pollObj[key] = opt;
                 });
-                params.poll_attachment = JSON.stringify(pollObj);
+                pollAttachment = JSON.stringify(pollObj);
             }
-            if (gif_id && gif_provider) {
-                params.gif_attachment = JSON.stringify({ gif_id, provider: gif_provider });
-            }
-            if (is_spoiler)
-                params.is_spoiler_media = true;
+            const gifAttachment = gif_id && gif_provider
+                ? JSON.stringify({ gif_id, provider: gif_provider })
+                : undefined;
+            let textAttachmentJson;
             if (text_attachment) {
                 const obj = { plaintext: text_attachment };
                 if (text_attachment_link)
@@ -127,199 +131,258 @@ export function registerThreadsPublishingTools(server, client) {
                         styling_info: s.styles,
                     }));
                 }
-                params.text_attachment = JSON.stringify(obj);
+                textAttachmentJson = JSON.stringify(obj);
             }
-            applyShareToIgStory(params, share_to_ig_story);
-            applyAllowlistedCountryCodes(params, allowlisted_country_codes);
             // Treat `undefined` as the default (true) so the behavior is stable even
             // if a caller bypasses Zod's schema-level default (e.g., direct handler
             // invocation in tests). Only an explicit `false` takes the legacy path.
             const useAutoPublish = auto_publish !== false;
-            if (useAutoPublish)
-                params.auto_publish_text = true;
+            const params = buildParams({ media_type: "TEXT", text }, {
+                reply_control,
+                link_attachment,
+                topic_tag,
+                quote_post_id,
+                poll_attachment: pollAttachment,
+                gif_attachment: gifAttachment,
+                is_spoiler_media: is_spoiler ? true : undefined,
+                text_attachment: textAttachmentJson,
+                location_id,
+                auto_publish_text: useAutoPublish ? true : undefined,
+            });
+            applyShareToIgStory(params, share_to_ig_story);
+            applyAllowlistedCountryCodes(params, allowlisted_country_codes);
             // `createResponse.id` is the published post id when useAutoPublish is true,
             // and the unpublished container id otherwise.
             const { data: createResponse, rateLimit: createRateLimit } = await client.threads("POST", `/${client.threadsUserId}/threads`, params);
             if (typeof createResponse.id !== "string")
                 throw new Error("Container creation did not return a valid id");
             if (useAutoPublish) {
-                return { content: [{ type: "text", text: JSON.stringify({ ...createResponse, _rateLimit: createRateLimit }, null, 2) }] };
+                client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+                return formatResponse(createResponse, createRateLimit);
             }
+            containerId = createResponse.id;
+            step = "publishing";
             const { data, rateLimit } = await client.threads("POST", `/${client.threadsUserId}/threads_publish`, {
-                creation_id: createResponse.id,
+                creation_id: containerId,
             });
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
-            return formatErrorResponse(error, "Publish text");
+            return formatErrorResponse(error, "Publish text", { step, containerId });
         }
     });
     // ─── threads_publish_image ───────────────────────────────────
-    server.tool("threads_publish_image", "Publish an image post on Threads. Supports topic tag, quote post, alt text, spoiler flag, cross-share to Instagram Stories, and geo-gating via allowlisted_country_codes.", {
-        image_url: httpsUrl.describe("Public HTTPS URL of the image (JPEG/PNG, max 8MB)"),
-        text: z.string().max(500).optional().describe("Caption text"),
-        reply_control: replyControlSchema,
-        topic_tag: topicTagSchema,
-        quote_post_id: z.string().optional().describe("ID of a post to quote"),
-        alt_text: z.string().max(1000).optional().describe("Alt text for accessibility (max 1000 chars)"),
-        is_spoiler: z.boolean().optional().describe("Mark content as spoiler"),
-        share_to_ig_story: shareToIgStorySchema,
-        allowlisted_country_codes: allowlistedCountryCodesSchema,
-    }, async ({ image_url, text, reply_control, topic_tag, quote_post_id, alt_text, is_spoiler, share_to_ig_story, allowlisted_country_codes }) => {
+    server.registerTool("threads_publish_image", {
+        description: "Publish an image post on Threads. Supports topic tag, quote post, alt text, spoiler flag, cross-share to Instagram Stories, geo-gating via allowlisted_country_codes, and location tagging via location_id.",
+        inputSchema: {
+            image_url: httpsUrl.describe("Public HTTPS URL of the image (JPEG/PNG, max 8MB)"),
+            text: z.string().max(500).optional().describe("Caption text"),
+            reply_control: replyControlSchema,
+            topic_tag: topicTagSchema,
+            quote_post_id: z.string().optional().describe("ID of a post to quote"),
+            alt_text: z.string().max(1000).optional().describe("Alt text for accessibility (max 1000 chars)"),
+            is_spoiler: z.boolean().optional().describe("Mark content as spoiler"),
+            share_to_ig_story: shareToIgStorySchema,
+            allowlisted_country_codes: allowlistedCountryCodesSchema,
+            location_id: z.string().optional().describe("Location ID for tagging the post. Use threads_search_locations to find IDs. Requires the threads_location_tagging permission on the access token."),
+        },
+        annotations: WRITE_TOOL,
+    }, async ({ image_url, text, reply_control, topic_tag, quote_post_id, alt_text, is_spoiler, share_to_ig_story, allowlisted_country_codes, location_id }, extra) => {
+        let step = "container creation";
+        let containerId;
         try {
-            const params = { media_type: "IMAGE", image_url };
-            if (text)
-                params.text = text;
-            if (reply_control)
-                params.reply_control = reply_control;
-            if (topic_tag)
-                params.topic_tag = topic_tag;
-            if (quote_post_id)
-                params.quote_post_id = quote_post_id;
-            if (alt_text)
-                params.alt_text = alt_text;
-            if (is_spoiler)
-                params.is_spoiler_media = true;
+            const params = buildParams({ media_type: "IMAGE", image_url }, {
+                text,
+                reply_control,
+                topic_tag,
+                quote_post_id,
+                alt_text,
+                is_spoiler_media: is_spoiler ? true : undefined,
+                location_id,
+            });
             applyShareToIgStory(params, share_to_ig_story);
             applyAllowlistedCountryCodes(params, allowlisted_country_codes);
             const { data: container } = await client.threads("POST", `/${client.threadsUserId}/threads`, params);
             if (typeof container.id !== "string")
                 throw new Error("Container creation did not return a valid id");
-            const containerId = container.id;
-            await waitForThreadsContainer(client, containerId);
+            containerId = container.id;
+            step = "processing";
+            await waitForThreadsContainer(client, containerId, IMAGE_PROCESSING_TIMEOUT, { onProgress: makeProgressNotifier(extra) });
+            step = "publishing";
             const { data, rateLimit } = await client.threads("POST", `/${client.threadsUserId}/threads_publish`, {
                 creation_id: containerId,
             });
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
-            return formatErrorResponse(error, "Publish image");
+            return formatErrorResponse(error, "Publish image", { step, containerId });
         }
     });
     // ─── threads_publish_video ───────────────────────────────────
-    server.tool("threads_publish_video", "Publish a video post on Threads. Waits for video processing. Supports topic tag, quote post, alt text, spoiler flag, cross-share to Instagram Stories, and geo-gating via allowlisted_country_codes. Note: cross-share to IG Stories may silently fail for video posts (the Threads post still publishes).", {
-        video_url: httpsUrl.describe("Public HTTPS URL of the video (MP4/MOV, max 1GB, up to 5 min)"),
-        text: z.string().max(500).optional().describe("Caption text"),
-        reply_control: replyControlSchema,
-        topic_tag: topicTagSchema,
-        quote_post_id: z.string().optional().describe("ID of a post to quote"),
-        alt_text: z.string().max(1000).optional().describe("Alt text for accessibility (max 1000 chars)"),
-        is_spoiler: z.boolean().optional().describe("Mark content as spoiler"),
-        share_to_ig_story: shareToIgStorySchema,
-        allowlisted_country_codes: allowlistedCountryCodesSchema,
-    }, async ({ video_url, text, reply_control, topic_tag, quote_post_id, alt_text, is_spoiler, share_to_ig_story, allowlisted_country_codes }) => {
+    server.registerTool("threads_publish_video", {
+        description: "Publish a video post on Threads. Waits for video processing. Supports topic tag, quote post, alt text, spoiler flag, cross-share to Instagram Stories, geo-gating via allowlisted_country_codes, and location tagging via location_id. Note: cross-share to IG Stories may silently fail for video posts (the Threads post still publishes).",
+        inputSchema: {
+            video_url: httpsUrl.describe("Public HTTPS URL of the video (MP4/MOV, max 1GB, up to 5 min)"),
+            text: z.string().max(500).optional().describe("Caption text"),
+            reply_control: replyControlSchema,
+            topic_tag: topicTagSchema,
+            quote_post_id: z.string().optional().describe("ID of a post to quote"),
+            alt_text: z.string().max(1000).optional().describe("Alt text for accessibility (max 1000 chars)"),
+            is_spoiler: z.boolean().optional().describe("Mark content as spoiler"),
+            share_to_ig_story: shareToIgStorySchema,
+            allowlisted_country_codes: allowlistedCountryCodesSchema,
+            location_id: z.string().optional().describe("Location ID for tagging the post. Use threads_search_locations to find IDs. Requires the threads_location_tagging permission on the access token."),
+        },
+        annotations: WRITE_TOOL,
+    }, async ({ video_url, text, reply_control, topic_tag, quote_post_id, alt_text, is_spoiler, share_to_ig_story, allowlisted_country_codes, location_id }, extra) => {
+        let step = "container creation";
+        let containerId;
         try {
-            const params = { media_type: "VIDEO", video_url };
-            if (text)
-                params.text = text;
-            if (reply_control)
-                params.reply_control = reply_control;
-            if (topic_tag)
-                params.topic_tag = topic_tag;
-            if (quote_post_id)
-                params.quote_post_id = quote_post_id;
-            if (alt_text)
-                params.alt_text = alt_text;
-            if (is_spoiler)
-                params.is_spoiler_media = true;
+            const params = buildParams({ media_type: "VIDEO", video_url }, {
+                text,
+                reply_control,
+                topic_tag,
+                quote_post_id,
+                alt_text,
+                is_spoiler_media: is_spoiler ? true : undefined,
+                location_id,
+            });
             applyShareToIgStory(params, share_to_ig_story);
             applyAllowlistedCountryCodes(params, allowlisted_country_codes);
             const { data: container } = await client.threads("POST", `/${client.threadsUserId}/threads`, params);
             if (typeof container.id !== "string")
                 throw new Error("Container creation did not return a valid id");
-            const containerId = container.id;
-            await waitForThreadsContainer(client, containerId, VIDEO_PROCESSING_TIMEOUT);
+            containerId = container.id;
+            step = "processing";
+            await waitForThreadsContainer(client, containerId, VIDEO_PROCESSING_TIMEOUT, { onProgress: makeProgressNotifier(extra) });
+            step = "publishing";
             const { data, rateLimit } = await client.threads("POST", `/${client.threadsUserId}/threads_publish`, {
                 creation_id: containerId,
             });
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
-            return formatErrorResponse(error, "Publish video");
+            return formatErrorResponse(error, "Publish video", { step, containerId });
         }
     });
     // ─── threads_publish_carousel ────────────────────────────────
-    server.tool("threads_publish_carousel", "Publish a carousel post on Threads with 2-20 images/videos. Supports cross-share to Instagram Stories and geo-gating via allowlisted_country_codes (parent container only).", {
-        items: z.array(z.object({
-            type: z.enum(["IMAGE", "VIDEO"]).describe("Media type"),
-            url: httpsUrl.describe("Public HTTPS URL"),
-            alt_text: z.string().max(1000).optional().describe("Alt text for this item"),
-        })).min(2).max(20).describe("Array of media items"),
-        text: z.string().max(500).optional().describe("Caption text"),
-        reply_control: replyControlSchema,
-        topic_tag: topicTagSchema,
-        quote_post_id: z.string().optional().describe("ID of a post to quote"),
-        share_to_ig_story: shareToIgStorySchema,
-        allowlisted_country_codes: allowlistedCountryCodesSchema,
-    }, async ({ items, text, reply_control, topic_tag, quote_post_id, share_to_ig_story, allowlisted_country_codes }) => {
+    server.registerTool("threads_publish_carousel", {
+        description: "Publish a carousel post on Threads with 2-20 images/videos. Supports cross-share to Instagram Stories, geo-gating via allowlisted_country_codes, and location tagging via location_id (parent container only).",
+        inputSchema: {
+            items: z.array(z.object({
+                type: z.enum(["IMAGE", "VIDEO"]).describe("Media type"),
+                url: httpsUrl.describe("Public HTTPS URL"),
+                alt_text: z.string().max(1000).optional().describe("Alt text for this item"),
+            })).min(2).max(20).describe("Array of media items"),
+            text: z.string().max(500).optional().describe("Caption text"),
+            reply_control: replyControlSchema,
+            topic_tag: topicTagSchema,
+            quote_post_id: z.string().optional().describe("ID of a post to quote"),
+            share_to_ig_story: shareToIgStorySchema,
+            allowlisted_country_codes: allowlistedCountryCodesSchema,
+            location_id: z.string().optional().describe("Location ID for tagging the post. Use threads_search_locations to find IDs. Requires the threads_location_tagging permission on the access token."),
+        },
+        annotations: WRITE_TOOL,
+    }, async ({ items, text, reply_control, topic_tag, quote_post_id, share_to_ig_story, allowlisted_country_codes, location_id }, extra) => {
+        // See ig_publish_carousel — shared notifier keeps progress monotonic
+        // across parallel child polls.
+        const onProgress = makeProgressNotifier(extra, "shared");
+        let step = "child container creation";
+        let containerId;
+        // Promise.all rejects with the first child to throw; JS is single-threaded,
+        // so the first catch wins the `=== undefined` race here.
+        let firstFailingChildStep;
+        let firstFailingChildId;
         try {
-            const childIds = [];
-            for (const item of items) {
-                const params = { media_type: item.type, is_carousel_item: true };
-                if (item.type === "IMAGE") {
-                    params.image_url = item.url;
+            // Children are independent — create them in parallel. Errors propagate
+            // unwrapped so formatErrorResponse keeps MetaApiError categorization.
+            const childIds = await Promise.all(items.map(async (item) => {
+                let myStep = "child container creation";
+                let myContainerId;
+                try {
+                    const params = buildParams({ media_type: item.type, is_carousel_item: true }, {
+                        image_url: item.type === "IMAGE" ? item.url : undefined,
+                        video_url: item.type === "VIDEO" ? item.url : undefined,
+                        alt_text: item.alt_text,
+                    });
+                    const { data: child } = await client.threads("POST", `/${client.threadsUserId}/threads`, params);
+                    if (typeof child.id !== "string")
+                        throw new Error("Container creation did not return a valid id");
+                    myContainerId = child.id;
+                    myStep = "child processing";
+                    await waitForThreadsContainer(client, myContainerId, item.type === "VIDEO" ? VIDEO_PROCESSING_TIMEOUT : IMAGE_PROCESSING_TIMEOUT, { onProgress });
+                    return myContainerId;
                 }
-                else {
-                    params.video_url = item.url;
+                catch (e) {
+                    if (firstFailingChildStep === undefined) {
+                        firstFailingChildStep = myStep;
+                        firstFailingChildId = myContainerId;
+                    }
+                    throw e;
                 }
-                if (item.alt_text)
-                    params.alt_text = item.alt_text;
-                const { data: child } = await client.threads("POST", `/${client.threadsUserId}/threads`, params);
-                if (typeof child.id !== "string")
-                    throw new Error("Container creation did not return a valid id");
-                const childId = child.id;
-                await waitForThreadsContainer(client, childId, item.type === "VIDEO" ? VIDEO_PROCESSING_TIMEOUT : IMAGE_PROCESSING_TIMEOUT);
-                childIds.push(childId);
-            }
-            const carouselParams = {
-                media_type: "CAROUSEL",
-                children: childIds.join(","),
-            };
-            if (text)
-                carouselParams.text = text;
-            if (reply_control)
-                carouselParams.reply_control = reply_control;
-            if (topic_tag)
-                carouselParams.topic_tag = topic_tag;
-            if (quote_post_id)
-                carouselParams.quote_post_id = quote_post_id;
+            }));
+            step = "parent container creation";
+            const carouselParams = buildParams({ media_type: "CAROUSEL", children: childIds.join(",") }, { text, reply_control, topic_tag, quote_post_id, location_id });
             applyShareToIgStory(carouselParams, share_to_ig_story);
             applyAllowlistedCountryCodes(carouselParams, allowlisted_country_codes);
             const { data: carousel } = await client.threads("POST", `/${client.threadsUserId}/threads`, carouselParams);
             if (typeof carousel.id !== "string")
                 throw new Error("Container creation did not return a valid id");
-            const carouselId = carousel.id;
-            await waitForThreadsContainer(client, carouselId);
+            containerId = carousel.id;
+            step = "parent processing";
+            await waitForThreadsContainer(client, containerId, IMAGE_PROCESSING_TIMEOUT, { onProgress });
+            step = "publishing";
             const { data, rateLimit } = await client.threads("POST", `/${client.threadsUserId}/threads_publish`, {
-                creation_id: carouselId,
+                creation_id: containerId,
             });
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
-            return formatErrorResponse(error, "Publish carousel");
+            return formatErrorResponse(error, "Publish carousel", {
+                step: firstFailingChildStep ?? step,
+                containerId: firstFailingChildId ?? containerId,
+            });
+        }
+        finally {
+            // Sibling polls still in-flight after a Promise.all rejection must
+            // not keep emitting progress for the now-completed request.
+            onProgress?.stop();
         }
     });
     // ─── threads_delete_post ──────────────────────────────────────
-    server.tool("threads_delete_post", "Delete a Threads post. This action is irreversible. Rate limited to 100 deletions per 24 hours.", {
-        post_id: metaId.describe("Threads post ID to delete"),
+    server.registerTool("threads_delete_post", {
+        description: "Delete a Threads post. This action is irreversible. Rate limited to 100 deletions per 24 hours.",
+        inputSchema: {
+            post_id: metaId.describe("Threads post ID to delete"),
+        },
+        annotations: DESTRUCTIVE_TOOL,
     }, async ({ post_id }) => {
         try {
             const { data, rateLimit } = await client.threads("DELETE", `/${post_id}`);
-            return { content: [{ type: "text", text: JSON.stringify({ success: true, ...data, _rateLimit: rateLimit }, null, 2) }] };
+            client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+            return formatResponse({ success: true, ...data }, rateLimit);
         }
         catch (error) {
             return formatErrorResponse(error, "Delete post");
         }
     });
     // ─── threads_get_container_status ────────────────────────────
-    server.tool("threads_get_container_status", "Check the processing status of a Threads media container. Only works with unpublished container IDs (returned from container creation endpoints) — not with published post IDs.", {
-        container_id: metaId.describe("Unpublished container ID to check (from container creation, not a published post ID)"),
+    server.registerTool("threads_get_container_status", {
+        description: "Check the processing status of a Threads media container. Only works with unpublished container IDs (returned from container creation endpoints) — not with published post IDs.",
+        inputSchema: {
+            container_id: metaId.describe("Unpublished container ID to check (from container creation, not a published post ID)"),
+        },
+        annotations: READ_ONLY_TOOL,
     }, async ({ container_id }) => {
         try {
             const { data, rateLimit } = await client.threads("GET", `/${container_id}`, {
                 fields: "id,status,error_message",
             });
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
@@ -330,28 +393,68 @@ export function registerThreadsPublishingTools(server, client) {
         }
     });
     // ─── threads_get_publishing_limit ────────────────────────────
-    server.tool("threads_get_publishing_limit", "Check how many posts you can still publish within the current 24-hour window (max 250 posts/day).", {}, async () => {
+    server.registerTool("threads_get_publishing_limit", {
+        description: "Check how many posts you can still publish within the current 24-hour window (max 250 posts/day).",
+        inputSchema: {},
+        annotations: READ_ONLY_TOOL,
+    }, async () => {
         try {
             const { data, rateLimit } = await client.threads("GET", `/${client.threadsUserId}/threads_publishing_limit`, {
                 fields: "quota_usage,config",
             });
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
             return formatErrorResponse(error, "Get publishing limit");
         }
     });
     // ─── threads_repost ──────────────────────────────────────────
-    server.tool("threads_repost", "Repost an existing Threads post to your own profile. Reposts appear under the Reposts tab on your profile. Requires the threads_content_publish permission. Note: this is a simple repost — for quote-reposts use threads_publish_text with quote_post_id.", {
-        post_id: metaId.describe("Threads post ID to repost"),
+    server.registerTool("threads_repost", {
+        description: "Repost an existing Threads post to your own profile. Reposts appear under the Reposts tab on your profile. Requires the threads_content_publish permission. Note: this is a simple repost — for quote-reposts use threads_publish_text with quote_post_id.",
+        inputSchema: {
+            post_id: metaId.describe("Threads post ID to repost"),
+        },
+        annotations: WRITE_TOOL,
     }, async ({ post_id }) => {
         try {
             const { data, rateLimit } = await client.threads("POST", `/${post_id}/repost`, {});
-            return { content: [{ type: "text", text: JSON.stringify({ ...data, _rateLimit: rateLimit }, null, 2) }] };
+            client.invalidateCache(THREADS_PROFILE_CACHE_PREFIX);
+            return formatResponse(data, rateLimit);
         }
         catch (error) {
             return formatErrorResponse(error, "Repost");
         }
     });
+    // ─── threads_search_locations ────────────────────────────────
+    server.registerTool("threads_search_locations", {
+        description: "Search Threads-supported locations by keyword or coordinates. Returns a list of location objects (id, name, address, city, country, latitude, longitude, postal_code) whose id can be passed as location_id to the four threads_publish_* tools to tag a post. Either q or both latitude+longitude must be provided. Requires the threads_location_tagging permission; without app approval, the endpoint restricts results to the literal query 'Menlo Park' for testing.",
+        inputSchema: {
+            q: z.string().min(1).optional().describe("Search query (e.g., 'Menlo Park'). Either q or both latitude+longitude must be provided. If your app does not yet have the threads_location_tagging permission, the API restricts results to the literal query 'Menlo Park' for testing."),
+            latitude: z.number().min(-90).max(90).optional().describe("Latitude in decimal degrees (-90..90). Must be provided together with longitude."),
+            longitude: z.number().min(-180).max(180).optional().describe("Longitude in decimal degrees (-180..180). Must be provided together with latitude."),
+        },
+        annotations: READ_ONLY_TOOL,
+    }, async ({ q, latitude, longitude }) => {
+        try {
+            const hasLat = latitude !== undefined;
+            const hasLng = longitude !== undefined;
+            const hasCoords = hasLat || hasLng;
+            if (q === undefined && !hasCoords) {
+                return validationError("threads_search_locations requires either q or both latitude and longitude.");
+            }
+            if (q !== undefined && hasCoords) {
+                return validationError("threads_search_locations accepts either q or latitude+longitude, not both.");
+            }
+            if (hasCoords && !(hasLat && hasLng)) {
+                return validationError("threads_search_locations requires both latitude and longitude when searching by coordinates.");
+            }
+            const params = buildParams({}, { q, latitude, longitude });
+            const { data, rateLimit } = await client.threads("GET", "/location_search", params);
+            return formatResponse(data, rateLimit);
+        }
+        catch (error) {
+            return formatErrorResponse(error, "Search locations");
+        }
+    });
 }
 //# sourceMappingURL=publishing.js.map