@thenavidm/threads-mcp-cli 1.1.0

package/dist/config.js

@@ -0,0 +1,185 @@
+/**
+ * Resolving credentials, and the multi-account model.
+ *
+ * Threads is not like a platform with app passwords. Every credential here is
+ * an OAuth token minted against a Meta app, it is bound to one Threads profile,
+ * and it dies after 60 days unless something refreshes it. That shapes the
+ * whole design: tokens arrive from three places, and the one that matters most
+ * is the token store `threads-mcp login` writes, because that is the only one
+ * this server can keep alive on its own.
+ *
+ * Three sources, in priority order:
+ *   1. THREADS_ACCOUNTS      a JSON array, for several profiles at once
+ *   2. THREADS_ACCESS_TOKEN  the single-account variable
+ *   3. the token store       ~/.threads-mcp/tokens.json, written by `login`
+ *
+ * The store is last rather than first so an explicit environment variable
+ * always wins. Someone who exports a token into one client's config expects
+ * that token to be the one used, not a stale one a login left on disk months
+ * ago.
+ *
+ * `user_id` is deliberately optional everywhere. Almost every Threads endpoint
+ * is keyed by the numeric profile id, and asking a person to find theirs before
+ * anything works is a setup step with no reason to exist: `GET /me` returns it,
+ * and the client resolves and caches it on first use.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_GRAPH_HOST = "https://graph.threads.net";
+/** Where `login` writes tokens, and where refreshed tokens are written back. */
+export function defaultStorePath() {
+    return process.env.THREADS_TOKEN_STORE || join(homedir(), ".threads-mcp", "tokens.json");
+}
+/** Strip a leading @ and lowercase. */
+export function normalizeUsername(raw) {
+    return raw.trim().replace(/^@/, "").toLowerCase();
+}
+function normalizeHost(raw, fallback) {
+    const t = (raw ?? "").trim();
+    if (!t)
+        return fallback;
+    const withScheme = /^https?:\/\//i.test(t) ? t : `https://${t}`;
+    return withScheme.replace(/\/+$/, "");
+}
+function envFlag(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    return /^(1|true|yes|on)$/i.test(raw.trim());
+}
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) {
+        process.stderr.write(`[threads-mcp] ${name}="${raw}" is not a positive number. Using ${fallback}.\n`);
+        return fallback;
+    }
+    return n;
+}
+/**
+ * Read `THREADS_ACCOUNTS`, a JSON array.
+ *
+ * Both snake_case and camelCase keys are accepted, because the same JSON gets
+ * pasted between a shell export and a client config file, and the two
+ * conventions do not survive that trip intact.
+ */
+export function accountsFromJson(raw) {
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        process.stderr.write("[threads-mcp] THREADS_ACCOUNTS is not valid JSON. Ignoring it.\n");
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const entry of parsed) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        const token = e.access_token ?? e.accessToken ?? e.token;
+        if (typeof token !== "string" || !token.trim())
+            continue;
+        const userId = e.user_id ?? e.userId ?? e.id;
+        const username = e.username ?? e.account_name ?? e.handle;
+        const expires = e.expires_at ?? e.expiresAt;
+        out.push({
+            accessToken: token.trim(),
+            userId: typeof userId === "string" ? userId : typeof userId === "number" ? String(userId) : undefined,
+            username: typeof username === "string" ? normalizeUsername(username) : undefined,
+            expiresAt: typeof expires === "number" ? expires : undefined,
+            source: "env-json",
+        });
+    }
+    return out;
+}
+function accountFromSingleEnv() {
+    const token = process.env.THREADS_ACCESS_TOKEN;
+    if (!token || !token.trim())
+        return [];
+    const userId = process.env.THREADS_USER_ID;
+    const username = process.env.THREADS_USERNAME;
+    return [
+        {
+            accessToken: token.trim(),
+            userId: userId?.trim() || undefined,
+            username: username ? normalizeUsername(username) : undefined,
+            source: "env",
+        },
+    ];
+}
+export function loadConfig(stored = []) {
+    const fromJson = accountsFromJson(process.env.THREADS_ACCOUNTS);
+    const fromEnv = accountFromSingleEnv();
+    const accounts = fromJson.length > 0 ? fromJson : fromEnv.length > 0 ? fromEnv : stored;
+    const preferred = (process.env.THREADS_DEFAULT_ACCOUNT ?? "")
+        .split(",")
+        .map((s) => normalizeUsername(s))
+        .filter(Boolean);
+    return {
+        accounts,
+        preferred,
+        appId: process.env.THREADS_APP_ID?.trim() || undefined,
+        appSecret: process.env.THREADS_APP_SECRET?.trim() || undefined,
+        readOnly: envFlag("THREADS_READ_ONLY", false),
+        allowDestructive: envFlag("THREADS_ALLOW_DESTRUCTIVE", true),
+        refreshWindowDays: envInt("THREADS_REFRESH_WINDOW_DAYS", 20),
+        persistTokens: envFlag("THREADS_PERSIST_TOKENS", true),
+        storePath: defaultStorePath(),
+        requestTimeoutMs: envInt("THREADS_REQUEST_TIMEOUT_MS", 30_000),
+        minRequestIntervalMs: envInt("THREADS_MIN_REQUEST_INTERVAL_MS", 120),
+        maxRetries: envInt("THREADS_MAX_RETRIES", 3),
+        containerTimeoutMs: envInt("THREADS_CONTAINER_TIMEOUT_MS", 120_000),
+        graphHost: normalizeHost(process.env.THREADS_GRAPH_HOST, DEFAULT_GRAPH_HOST),
+        userAgent: process.env.THREADS_USER_AGENT || "threads-mcp",
+        auditPath: process.env.THREADS_AUDIT_LOG || undefined,
+    };
+}
+/**
+ * Pick which profile a call acts as.
+ *
+ * With no hint: the first configured `THREADS_DEFAULT_ACCOUNT` that is actually
+ * connected, else the first account. Exact username match beats prefix match,
+ * because "navid" is a prefix of "navidmedia", and a prefix-first search would
+ * hand an unnamed post to the wrong profile whenever both are connected. A
+ * name that matches nothing fails and lists what is connected, rather than
+ * quietly posting somewhere else.
+ */
+export function selectAccount(config, hint) {
+    if (config.accounts.length === 0) {
+        throw new Error("No Threads account configured. Run `threads-mcp login` to authorise one, or set THREADS_ACCESS_TOKEN. Run `threads-mcp doctor` for details.");
+    }
+    if (!hint) {
+        for (const want of config.preferred) {
+            const exact = config.accounts.find((a) => a.username === want);
+            if (exact)
+                return exact;
+            const prefix = config.accounts.find((a) => a.username?.startsWith(want));
+            if (prefix)
+                return prefix;
+        }
+        return config.accounts[0];
+    }
+    const needle = normalizeUsername(hint);
+    // A numeric hint is a profile id, not a username.
+    if (/^\d+$/.test(needle)) {
+        const byId = config.accounts.find((a) => a.userId === needle);
+        if (byId)
+            return byId;
+    }
+    const exact = config.accounts.find((a) => a.username === needle);
+    if (exact)
+        return exact;
+    const prefix = config.accounts.find((a) => a.username?.startsWith(needle));
+    if (prefix)
+        return prefix;
+    const known = config.accounts.map((a) => a.username ?? a.userId ?? "(unresolved)").join(", ");
+    throw new Error(`No connected Threads account matches "${hint}". Connected: ${known || "(none)"}. Usernames are resolved on first use, so a freshly added token may need one call before it can be named.`);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/content/containers.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Publishing: the two-step container dance, in one place.
+ *
+ * Every write to Threads is the same shape.
+ *
+ *   1. POST /{user-id}/threads          build a container. Nothing is public.
+ *   2. wait                             the container transcodes.
+ *   3. POST /{user-id}/threads_publish  the post appears.
+ *
+ * Step 2 is the one everybody skips. A text container is usually ready by the
+ * time the next request lands, so code that omits the wait works during
+ * development and then fails the first time someone attaches a video. Meta's
+ * own guidance is to wait about 30 seconds; polling the container's status is
+ * better than sleeping, because it is both faster for text and correct for a
+ * five-minute video.
+ *
+ * The unpublished container is also the only draft state Threads has. It is
+ * invisible, it holds for 24 hours, and it can be published later by id. That
+ * is worth exposing as its own tool rather than hiding inside a helper, so an
+ * agent can stage a post for a human to look at before anything is public.
+ *
+ * A note on ordering in `publishChain`: every part is validated before the
+ * first one is posted. A thread is a chain of ordinary posts, each replying to
+ * the one before, so there is no transaction and no rollback. Discovering on
+ * part four that part five is 40 characters too long leaves four public posts
+ * and no way to finish, and deleting them costs four of the day's hundred
+ * deletions. Checking first costs nothing.
+ */
+import type { ThreadsClient } from "../api/client.js";
+import type { Account } from "../config.js";
+import { type MediaItem } from "./media.js";
+export type ReplyControl = "everyone" | "accounts_you_follow" | "mentioned_only" | "parent_post_author_only" | "followers_only";
+export type ContainerOptions = MediaItem & {
+    text?: string;
+    reply_to_id?: string;
+    quote_post_id?: string;
+    reply_control?: ReplyControl;
+    link_attachment?: string;
+    topic_tag?: string;
+    allowlisted_country_codes?: string[];
+    enable_reply_approvals?: boolean;
+    auto_publish_text?: boolean;
+    is_carousel_item?: boolean;
+    children?: string[];
+    media_type?: "TEXT" | "IMAGE" | "VIDEO" | "CAROUSEL";
+};
+export type PublishedPost = {
+    id: string;
+    permalink?: string;
+    timestamp?: string;
+    text?: string;
+    warnings?: string[];
+};
+/**
+ * Everything checkable without a network call.
+ *
+ * Returns warnings, throws on anything that would certainly be refused. The
+ * split matters: a `.webp` URL is a warning because it might be served as JPEG,
+ * while a 600-character post is an error because Threads will never take it.
+ */
+export declare function validate(options: ContainerOptions, label?: string): string[];
+/** Build the parameter map Meta expects, dropping anything unset. */
+export declare function containerParams(options: ContainerOptions): Record<string, unknown>;
+/** Step one. Builds a container and returns its id. Nothing is public yet. */
+export declare function createContainer(client: ThreadsClient, account: Account, options: ContainerOptions): Promise<string>;
+/** Step three. Publishes a container that has finished processing. */
+export declare function publishContainer(client: ThreadsClient, account: Account, containerId: string): Promise<PublishedPost>;
+/** Create, wait, publish. The single-call path most tools want. */
+export declare function publish(client: ThreadsClient, account: Account, options: ContainerOptions): Promise<PublishedPost>;
+/**
+ * Publish several posts as a chain, each replying to the one before.
+ *
+ * Threads has no thread endpoint. A "thread" is exactly this: ordinary posts
+ * linked by `reply_to_id`. Which means it can half-publish, so every part is
+ * validated first and the failure report names what did go out.
+ */
+export declare function publishChain(client: ThreadsClient, account: Account, parts: ContainerOptions[], rootReplyTo?: string): Promise<{
+    posts: PublishedPost[];
+    warnings: string[];
+}>;
+/**
+ * Stage a carousel: every child first, then the parent binding them together.
+ *
+ * Children are created in order and then waited on together rather than one at
+ * a time, so twenty images transcode in parallel instead of in series.
+ */
+export declare function publishCarousel(client: ThreadsClient, account: Account, items: MediaItem[], options?: Omit<ContainerOptions, "children" | "media_type">): Promise<PublishedPost>;
+/** Read a post back in full, for the tools that return one. */
+export declare function readPost(client: ThreadsClient, account: Account, id: string): Promise<Record<string, unknown>>;

package/dist/content/containers.js

@@ -0,0 +1,210 @@
+/**
+ * Publishing: the two-step container dance, in one place.
+ *
+ * Every write to Threads is the same shape.
+ *
+ *   1. POST /{user-id}/threads          build a container. Nothing is public.
+ *   2. wait                             the container transcodes.
+ *   3. POST /{user-id}/threads_publish  the post appears.
+ *
+ * Step 2 is the one everybody skips. A text container is usually ready by the
+ * time the next request lands, so code that omits the wait works during
+ * development and then fails the first time someone attaches a video. Meta's
+ * own guidance is to wait about 30 seconds; polling the container's status is
+ * better than sleeping, because it is both faster for text and correct for a
+ * five-minute video.
+ *
+ * The unpublished container is also the only draft state Threads has. It is
+ * invisible, it holds for 24 hours, and it can be published later by id. That
+ * is worth exposing as its own tool rather than hiding inside a helper, so an
+ * agent can stage a post for a human to look at before anything is public.
+ *
+ * A note on ordering in `publishChain`: every part is validated before the
+ * first one is posted. A thread is a chain of ordinary posts, each replying to
+ * the one before, so there is no transaction and no rollback. Discovering on
+ * part four that part five is 40 characters too long leaves four public posts
+ * and no way to finish, and deleting them costs four of the day's hundred
+ * deletions. Checking first costs nothing.
+ */
+import { POST_FIELDS } from "../api/client.js";
+import { checkMedia, mediaTypeFor } from "./media.js";
+import { countLinks, MAX_LINKS_PER_POST, normalizeTopicTag, overLimitMessage } from "./text.js";
+import { TextTooLongError } from "../api/errors.js";
+/**
+ * Everything checkable without a network call.
+ *
+ * Returns warnings, throws on anything that would certainly be refused. The
+ * split matters: a `.webp` URL is a warning because it might be served as JPEG,
+ * while a 600-character post is an error because Threads will never take it.
+ */
+export function validate(options, label = "This post") {
+    const warnings = [];
+    if (options.text !== undefined) {
+        const problem = overLimitMessage(options.text, label);
+        if (problem)
+            throw new TextTooLongError(problem);
+        const links = countLinks(options.text);
+        if (links > MAX_LINKS_PER_POST) {
+            warnings.push(`${label} contains ${links} distinct URLs. Threads accepts at most ${MAX_LINKS_PER_POST} and may refuse the post.`);
+        }
+    }
+    warnings.push(...checkMedia(options));
+    if (options.link_attachment) {
+        if (options.image_url || options.video_url) {
+            throw new Error("A link attachment renders as a preview card and Threads only allows it on a text-only post. Drop the media, or put the URL in the text instead.");
+        }
+        try {
+            const url = new URL(options.link_attachment);
+            if (url.protocol !== "https:" && url.protocol !== "http:") {
+                throw new Error("not http");
+            }
+        }
+        catch {
+            throw new Error(`link_attachment "${options.link_attachment}" is not a valid URL.`);
+        }
+    }
+    if (options.topic_tag)
+        normalizeTopicTag(options.topic_tag);
+    if (options.allowlisted_country_codes?.length) {
+        const bad = options.allowlisted_country_codes.filter((c) => !/^[A-Za-z]{2}$/.test(c.trim()));
+        if (bad.length) {
+            throw new Error(`Geo-gating takes ISO 3166-1 alpha-2 country codes, two letters each. These are not: ${bad.join(", ")}`);
+        }
+    }
+    if (options.reply_to_id && options.quote_post_id) {
+        throw new Error("A post is either a reply or a quote, not both.");
+    }
+    return warnings;
+}
+/** Build the parameter map Meta expects, dropping anything unset. */
+export function containerParams(options) {
+    const mediaType = options.media_type ?? mediaTypeFor(options);
+    return {
+        media_type: mediaType,
+        text: options.text,
+        image_url: options.image_url,
+        video_url: options.video_url,
+        alt_text: options.alt_text,
+        reply_to_id: options.reply_to_id,
+        quote_post_id: options.quote_post_id,
+        reply_control: options.reply_control,
+        link_attachment: options.link_attachment,
+        topic_tag: options.topic_tag ? normalizeTopicTag(options.topic_tag) : undefined,
+        allowlisted_country_codes: options.allowlisted_country_codes?.length
+            ? options.allowlisted_country_codes.map((c) => c.trim().toUpperCase())
+            : undefined,
+        enable_reply_approvals: options.enable_reply_approvals ? "true" : undefined,
+        auto_publish_text: options.auto_publish_text ? "true" : undefined,
+        is_carousel_item: options.is_carousel_item ? "true" : undefined,
+        children: options.children?.length ? options.children.join(",") : undefined,
+    };
+}
+/** Step one. Builds a container and returns its id. Nothing is public yet. */
+export async function createContainer(client, account, options) {
+    const userId = await client.userId(account);
+    const created = (await client.call(account, `/${userId}/threads`, {
+        method: "POST",
+        params: containerParams(options),
+    }));
+    if (!created.id) {
+        throw new Error("Threads accepted the container request but returned no container id.");
+    }
+    return String(created.id);
+}
+/** Step three. Publishes a container that has finished processing. */
+export async function publishContainer(client, account, containerId) {
+    const userId = await client.userId(account);
+    await client.awaitContainer(account, containerId);
+    const published = (await client.call(account, `/${userId}/threads_publish`, {
+        method: "POST",
+        params: { creation_id: containerId },
+    }));
+    if (!published.id) {
+        throw new Error(`Threads published container ${containerId} but returned no post id.`);
+    }
+    const detail = (await client.call(account, `/${published.id}`, {
+        params: { fields: "id,permalink,timestamp,text" },
+    }));
+    return {
+        id: String(published.id),
+        permalink: detail.permalink,
+        timestamp: detail.timestamp,
+        text: detail.text,
+    };
+}
+/** Create, wait, publish. The single-call path most tools want. */
+export async function publish(client, account, options) {
+    const warnings = validate(options);
+    const containerId = await createContainer(client, account, options);
+    const post = await publishContainer(client, account, containerId);
+    return warnings.length ? { ...post, warnings } : post;
+}
+/**
+ * Publish several posts as a chain, each replying to the one before.
+ *
+ * Threads has no thread endpoint. A "thread" is exactly this: ordinary posts
+ * linked by `reply_to_id`. Which means it can half-publish, so every part is
+ * validated first and the failure report names what did go out.
+ */
+export async function publishChain(client, account, parts, rootReplyTo) {
+    if (parts.length === 0)
+        throw new Error("A thread needs at least one post.");
+    // Everything, before anything.
+    const warnings = [];
+    parts.forEach((part, index) => {
+        warnings.push(...validate(part, `Part ${index + 1} of ${parts.length}`));
+    });
+    const posts = [];
+    let replyTo = rootReplyTo;
+    for (const [index, part] of parts.entries()) {
+        try {
+            const containerId = await createContainer(client, account, { ...part, reply_to_id: replyTo });
+            const post = await publishContainer(client, account, containerId);
+            posts.push(post);
+            replyTo = post.id;
+        }
+        catch (error) {
+            // Say exactly how far it got. A partially published thread is recoverable
+            // by hand; one that reports only "failed" is not.
+            const done = posts.length;
+            const summary = done
+                ? `Parts 1-${done} of ${parts.length} are published (last id ${posts[done - 1].id}). Part ${index + 1} failed.`
+                : `Nothing was published. Part ${index + 1} failed.`;
+            throw new Error(`${summary} ${error.message}`);
+        }
+    }
+    return { posts, warnings };
+}
+/**
+ * Stage a carousel: every child first, then the parent binding them together.
+ *
+ * Children are created in order and then waited on together rather than one at
+ * a time, so twenty images transcode in parallel instead of in series.
+ */
+export async function publishCarousel(client, account, items, options = {}) {
+    const warnings = validate({ ...options, image_url: undefined, video_url: undefined });
+    for (const [index, item] of items.entries()) {
+        warnings.push(...checkMedia(item).map((w) => `Item ${index + 1}: ${w}`));
+    }
+    const children = [];
+    for (const item of items) {
+        children.push(await createContainer(client, account, {
+            ...item,
+            media_type: mediaTypeFor(item) === "VIDEO" ? "VIDEO" : "IMAGE",
+            is_carousel_item: true,
+        }));
+    }
+    await Promise.all(children.map((id) => client.awaitContainer(account, id)));
+    const parentId = await createContainer(client, account, {
+        ...options,
+        media_type: "CAROUSEL",
+        children,
+    });
+    const post = await publishContainer(client, account, parentId);
+    return warnings.length ? { ...post, warnings, ...{} } : post;
+}
+/** Read a post back in full, for the tools that return one. */
+export async function readPost(client, account, id) {
+    return (await client.call(account, `/${id}`, { params: { fields: POST_FIELDS } }));
+}
+//# sourceMappingURL=containers.js.map

package/dist/content/containers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"containers.js","sourceRoot":"","sources":["../../src/content/containers.ts"],"names":[],"mappings":"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"}

package/dist/content/media.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Media rules, checked before a container is created.
+ *
+ * Threads does not upload bytes. You hand it a public URL and it fetches the
+ * file itself, asynchronously, and reports the result minutes later as a
+ * container in state ERROR with a message like "Media download failed". By
+ * then the useful context is gone.
+ *
+ * So the checks that can be made locally are made locally, in the one place the
+ * numbers are written down. Everything here comes from Meta's published specs.
+ */
+export declare const IMAGE_SPEC: {
+    readonly formats: readonly ["jpeg", "jpg", "png"];
+    readonly maxBytes: number;
+    readonly minWidth: 320;
+    readonly maxWidth: 1440;
+    /** Widest and tallest Threads will accept, as width:height. */
+    readonly maxAspect: 10;
+};
+export declare const VIDEO_SPEC: {
+    readonly formats: readonly ["mp4", "mov"];
+    readonly maxBytes: number;
+    readonly maxSeconds: 300;
+    readonly codecs: readonly ["h264", "hevc"];
+    readonly recommendedAspect: "9:16";
+};
+export declare const CAROUSEL: {
+    readonly min: 2;
+    readonly max: 20;
+};
+/**
+ * Reject a media URL that cannot possibly work, before spending a container on
+ * it.
+ *
+ * Deliberately narrow. It refuses what is certainly wrong (not a URL, not
+ * HTTPS, a local path, a `data:` URI) and lets everything else through, because
+ * a URL with no file extension is completely normal for a CDN and refusing it
+ * would break more than it fixed.
+ */
+export declare function assertMediaUrl(url: string, kind: "image" | "video"): void;
+/** The extension, lowercased, when the URL has one. */
+export declare function extensionOf(url: string): string | undefined;
+/**
+ * Warn about an extension Threads does not support.
+ *
+ * A warning rather than an error: the extension in a URL is a hint, not a
+ * content type, and plenty of perfectly good CDN URLs end in `.webp?format=jpg`
+ * or nothing at all. Being told up front that a `.webp` is likely to fail is
+ * worth more than being stopped by it.
+ */
+export declare function formatWarning(url: string, kind: "image" | "video"): string | undefined;
+export type MediaItem = {
+    image_url?: string;
+    video_url?: string;
+    alt_text?: string;
+};
+/** Which container type a set of arguments implies. */
+export declare function mediaTypeFor(item: MediaItem): "TEXT" | "IMAGE" | "VIDEO";
+/** Validate one carousel item or post attachment. Returns any warnings. */
+export declare function checkMedia(item: MediaItem): string[];
+export declare function assertCarouselSize(count: number): void;