@mgcrea/mcp-x-api 0.1.0

package/dist/server-BeRiqZxj.js

@@ -0,0 +1,4008 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { gunzipSync } from "node:zlib";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { McpServer } from "@modelcontextprotocol/server";
+import { execFile } from "node:child_process";
+//#region src/build-info.ts
+const readPackageJson = () => {
+	try {
+		const pkgUrl = new URL("../package.json", import.meta.url);
+		return JSON.parse(readFileSync(pkgUrl, "utf8"));
+	} catch {
+		return {
+			name: "@mgcrea/mcp-x-api",
+			version: "0.0.0"
+		};
+	}
+};
+const pkg = readPackageJson();
+const BUILD_INFO = {
+	name: pkg.name,
+	version: pkg.version,
+	gitCommit: "0e3b506",
+	gitCommitDate: "2026-08-30T20:26:25+02:00"
+};
+//#endregion
+//#region src/client/errors.ts
+var XApiRequestError = class extends Error {
+	name = "XApiRequestError";
+	status;
+	errors;
+	constructor(message, opts) {
+		super(message);
+		this.status = opts.status;
+		this.errors = opts.errors;
+	}
+};
+/**
+* Thrown when a tool needs a logged-in user and only an app-only Bearer token
+* is available. The message carries the fix, because "401 Unauthorized" tells
+* you nothing about which of two credentials was missing.
+*/
+var UserContextRequiredError = class extends Error {
+	name = "UserContextRequiredError";
+	constructor(what, reason) {
+		super(`${what} needs an OAuth2 user context — an app-only Bearer token cannot reach it. Set X_API_CLIENT_ID and run \`x-api-mcp login\` once (it opens a browser and stores a refresh token in your config directory with mode 600), then retry.` + (reason ? ` (${reason})` : ""));
+	}
+};
+/** Thrown when a write tool is reached while X_API_ALLOW_WRITES is off. */
+var WritesDisabledError = class extends Error {
+	name = "WritesDisabledError";
+	constructor(what) {
+		super(`${what} is a write operation, but writes are disabled. Set X_API_ALLOW_WRITES=1 to enable mutating tools. Note that x_compose_post posts for free via a web intent and needs no flag at all.`);
+	}
+};
+/**
+* Thrown when the Ads API is reachable but this account cannot use it — no Ads
+* entitlement on the app, or no ads account behind the logged-in user. Separate
+* from `UserContextRequiredError` because logging in again does not fix it: the
+* missing piece is an approval, not a token.
+*/
+var AdsAccessError = class extends Error {
+	name = "AdsAccessError";
+	details;
+	constructor(message, details = {}) {
+		super(message);
+		this.details = details;
+	}
+};
+/**
+* A local guard that fires *before* the request goes out, so an agent in a loop
+* cannot spend past the ceiling. Carries the arithmetic so the number is
+* auditable rather than mysterious.
+*/
+var BudgetExceededError = class extends Error {
+	name = "BudgetExceededError";
+	details;
+	constructor(opts) {
+		super(`${opts.what} would cost about $${opts.estimateUsd.toFixed(3)}, which takes this session past the $${opts.limitUsd.toFixed(2)} budget (about $${opts.spentUsd.toFixed(3)} spent so far). Raise or unset X_API_MONTHLY_BUDGET_USD, or ask for fewer results.`);
+		this.details = { ...opts };
+	}
+};
+/**
+* A local check that failed before we sent anything to X. Carries the state it
+* read, so the caller sees why rather than just that something was wrong.
+*/
+var PreconditionError = class extends Error {
+	name = "PreconditionError";
+	details;
+	constructor(message, details = {}) {
+		super(message);
+		this.details = details;
+	}
+};
+//#endregion
+//#region src/client/http.ts
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const backoffMs = (attempt) => Math.min(1e3 * 2 ** attempt, 8e3);
+const retryAfterMs = (res) => {
+	const header = res.headers.get("Retry-After");
+	if (header === null) return void 0;
+	const seconds = Number(header);
+	return Number.isFinite(seconds) ? Math.max(seconds, 0) * 1e3 : void 0;
+};
+const safeJsonParse = (text) => {
+	try {
+		return text ? JSON.parse(text) : void 0;
+	} catch {
+		return text;
+	}
+};
+const numberOrUndefined = (value) => {
+	if (value === null) return void 0;
+	const n = Number(value);
+	return Number.isFinite(n) ? n : void 0;
+};
+/**
+* X takes comma-separated lists for both field selection
+* (`tweet.fields=id,text,created_at`) and batch lookups (`ids=1,2,3`) — not
+* repeated keys. Same join as JSON:API happens to need, different reason.
+*/
+const buildQuery = (query) => {
+	if (!query) return "";
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		if (value === void 0) continue;
+		if (Array.isArray(value)) {
+			if (value.length === 0) continue;
+			params.append(key, value.join(","));
+			continue;
+		}
+		params.append(key, String(value));
+	}
+	const qs = params.toString();
+	return qs ? `?${qs}` : "";
+};
+/**
+* Collapse a concrete path to the shape X documents its rate limits against, so
+* `/2/tweets/1799…` and `/2/tweets/1798…` share one bucket instead of leaking a
+* new entry per post.
+*/
+const endpointKey = (method, path) => `${method} ${path.replace(/\/\d{5,}/g, "/:id").replace(/\?.*$/, "")}`;
+/** Run `perform` until it yields a non-retryable response or the budget runs out. */
+const withRetry = async (perform, policy) => {
+	let attempt = 0;
+	for (;;) {
+		policy.logger?.debug?.(`[x-api] ${policy.label} (attempt ${attempt + 1})`);
+		const res = await perform();
+		if (res.status === 401 && policy.onUnauthorized && attempt < policy.maxRetries) {
+			policy.logger?.warn?.(`[x-api] HTTP 401 — refreshing token and retrying`);
+			policy.onUnauthorized();
+			attempt += 1;
+			continue;
+		}
+		if ((res.status === 429 || res.status >= 500) && attempt < policy.maxRetries) {
+			const delay = retryAfterMs(res) ?? backoffMs(attempt);
+			policy.logger?.warn?.(`[x-api] HTTP ${res.status} — retrying in ${delay}ms`);
+			await sleep(delay);
+			attempt += 1;
+			continue;
+		}
+		return res;
+	}
+};
+//#endregion
+//#region src/config.ts
+const DEFAULT_BASE_URL = "https://api.x.com";
+const DEFAULT_ADS_BASE_URL = "https://ads-api.x.com";
+/**
+* The Ads API sandbox: free, isolated, and the only sane place to exercise the
+* write tools. Note the host — X's own docs say `ads-api-sandbox.x.com`, which
+* has no DNS record at all. `ads-api-sandbox.twitter.com` is the one that
+* resolves, so this is not a typo waiting to be "fixed".
+*/
+const SANDBOX_ADS_BASE_URL = "https://ads-api-sandbox.twitter.com";
+/**
+* A fixed loopback port, deliberately not an ephemeral one. Unlike most OAuth
+* providers, X matches the callback URL against the value registered in the
+* developer portal byte-for-byte, so a random port can never be authorized.
+*/
+const DEFAULT_REDIRECT_URI = "http://127.0.0.1:8723/callback";
+/**
+* `offline.access` is what makes a refresh token come back at all — without it
+* the user has to re-login every two hours. `tweet.write` is appended at
+* startup when the paid write backend is enabled, so a read-only install never
+* asks for a permission it cannot use.
+*/
+const DEFAULT_SCOPES = [
+	"tweet.read",
+	"users.read",
+	"bookmark.read",
+	"offline.access"
+];
+/**
+* X moved to pay-per-use on 2026-02-06; there is no free tier for new
+* developers. These are list prices in USD, overridable via the config file's
+* `pricing` key because a table baked into a schema with no escape hatch is
+* wrong the day X changes it.
+*
+* The 24h dedup window is the load-bearing rule: within one UTC day, re-reading
+* a resource id you already paid for is free. That is why the ledger keys on
+* (kind, id, utcDay) rather than counting requests.
+*/
+const DEFAULT_PRICING = {
+	postRead: .005,
+	userRead: .01,
+	/** Your own posts and profile — five times cheaper than reading someone else's. */
+	ownedRead: .001,
+	postCreate: .015,
+	/** A post containing a URL costs 40x a post read. Not a typo. */
+	postCreateWithUrl: .2,
+	monthlyReadCap: 2e6,
+	effectiveFrom: "2026-02-06"
+};
+const PricingSchema = z.object({
+	postRead: z.number().nonnegative().default(DEFAULT_PRICING.postRead),
+	userRead: z.number().nonnegative().default(DEFAULT_PRICING.userRead),
+	ownedRead: z.number().nonnegative().default(DEFAULT_PRICING.ownedRead),
+	postCreate: z.number().nonnegative().default(DEFAULT_PRICING.postCreate),
+	postCreateWithUrl: z.number().nonnegative().default(DEFAULT_PRICING.postCreateWithUrl),
+	monthlyReadCap: z.number().int().positive().default(DEFAULT_PRICING.monthlyReadCap),
+	effectiveFrom: z.string().default(DEFAULT_PRICING.effectiveFrom)
+}).strict();
+const ConfigSchema = z.object({
+	bearerToken: z.string().min(1).optional(),
+	clientId: z.string().min(1).optional(),
+	clientSecret: z.string().min(1).optional(),
+	redirectUri: z.string().min(1).default(DEFAULT_REDIRECT_URI),
+	scopes: z.array(z.string().min(1)).min(1).default(DEFAULT_SCOPES),
+	tokenFile: z.string().min(1),
+	allowWrites: z.boolean().default(false),
+	writeBackend: z.enum(["intent", "api"]).default("intent"),
+	autoOpenBrowser: z.boolean().default(true),
+	enableFullArchive: z.boolean().default(false),
+	defaultMaxResults: z.number().int().min(1).max(100).default(10),
+	monthlyBudgetUsd: z.number().nonnegative().optional(),
+	cacheEnabled: z.boolean().default(true),
+	cacheMaxEntries: z.number().int().min(0).max(1e5).default(5e3),
+	maxRetries: z.number().int().nonnegative().max(10).default(3),
+	baseUrl: z.string().min(1).default(DEFAULT_BASE_URL),
+	pricing: PricingSchema.default(DEFAULT_PRICING),
+	adsEnabled: z.boolean().default(false),
+	adsAllowWrites: z.boolean().default(false),
+	adsBaseUrl: z.string().min(1).default(DEFAULT_ADS_BASE_URL),
+	adsAccountId: z.string().min(1).optional(),
+	adsMaxDownloadBytes: z.number().int().positive().default(25e6)
+}).strict().superRefine((cfg, ctx) => {
+	if (cfg.writeBackend === "api" && !cfg.clientId) ctx.addIssue({
+		code: "custom",
+		message: "X_API_WRITE_BACKEND=api needs a user context: set X_API_CLIENT_ID and run `x-api-mcp login`. The default backend (intent) needs no credentials at all — it returns an x.com/intent/tweet URL you click, which costs nothing."
+	});
+	if (cfg.adsEnabled && !cfg.clientId) ctx.addIssue({
+		code: "custom",
+		message: "X_ADS_ENABLED=1 needs an OAuth 2.0 user context: set X_API_CLIENT_ID and run `x-api-mcp login`. The Ads API does not accept an app-only Bearer token."
+	});
+	if (cfg.adsAllowWrites && !cfg.adsEnabled) ctx.addIssue({
+		code: "custom",
+		message: "X_ADS_ALLOW_WRITES=1 has no effect without X_ADS_ENABLED=1 — the ads tools are not registered at all. Set both, or neither."
+	});
+});
+/**
+* The on-disk config document. Keys are camelCase to mirror `Config` rather than
+* the env var names: this is a typed JSON file, not a shell.
+*
+* `.strict()` on purpose — a typo'd `clientID` must be an error. Silently
+* ignoring an unknown key looks exactly like "that setting had no effect",
+* which is the worst way to learn your credentials came from somewhere else.
+*/
+const FileConfigSchema = z.object({
+	bearerToken: z.string().min(1).optional(),
+	clientId: z.string().min(1).optional(),
+	clientSecret: z.string().min(1).optional(),
+	redirectUri: z.string().min(1).optional(),
+	scopes: z.array(z.string().min(1)).min(1).optional(),
+	tokenFile: z.string().min(1).optional(),
+	allowWrites: z.boolean().optional(),
+	writeBackend: z.enum(["intent", "api"]).optional(),
+	autoOpenBrowser: z.boolean().optional(),
+	enableFullArchive: z.boolean().optional(),
+	defaultMaxResults: z.number().int().min(1).max(100).optional(),
+	monthlyBudgetUsd: z.number().nonnegative().optional(),
+	cacheEnabled: z.boolean().optional(),
+	cacheMaxEntries: z.number().int().min(0).max(1e5).optional(),
+	maxRetries: z.number().int().nonnegative().max(10).optional(),
+	baseUrl: z.string().min(1).optional(),
+	pricing: PricingSchema.optional(),
+	adsEnabled: z.boolean().optional(),
+	adsAllowWrites: z.boolean().optional(),
+	adsBaseUrl: z.string().min(1).optional(),
+	adsAccountId: z.string().min(1).optional(),
+	adsMaxDownloadBytes: z.number().int().positive().optional()
+}).strict();
+const parseBool = (value) => {
+	const t = trimmed(value);
+	if (t === void 0) return void 0;
+	return [
+		"1",
+		"true",
+		"yes",
+		"on"
+	].includes(t.toLowerCase());
+};
+const parseIntOpt = (value) => {
+	if (value === void 0 || value.trim() === "") return void 0;
+	const n = Number(value);
+	return Number.isInteger(n) ? n : void 0;
+};
+const parseFloatOpt = (value) => {
+	if (value === void 0 || value.trim() === "") return void 0;
+	const n = Number(value);
+	return Number.isFinite(n) ? n : void 0;
+};
+/** Scopes are space-separated in OAuth but commas are what people actually type. */
+const parseList = (value) => {
+	const t = trimmed(value);
+	if (t === void 0) return void 0;
+	const items = t.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+	return items.length > 0 ? items : void 0;
+};
+const trimmed = (value) => {
+	const t = value?.trim();
+	return t ? t : void 0;
+};
+const message$1 = (err) => err instanceof Error ? err.message : String(err);
+/** `readFileSync` does not expand `~`, but it is the natural thing to write in a config file. */
+const expandTilde = (path) => path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+/**
+* Where the config file lives, most specific first: an explicit override, then
+* the XDG location, then the conventional `~/.config`.
+*/
+const resolveConfigPath = (env = process.env) => {
+	const explicit = trimmed(env.X_API_CONFIG);
+	if (explicit) return expandTilde(explicit);
+	const base = trimmed(env.XDG_CONFIG_HOME) ?? join(homedir(), ".config");
+	return join(expandTilde(base), "x-api", "config.json");
+};
+/** The OAuth token file sits beside the config file unless told otherwise. */
+const resolveTokenPath = (env = process.env) => join(dirname(resolveConfigPath(env)), "tokens.json");
+/**
+* These files hold a bearer token or a refresh token, so being readable by
+* other users is worth saying out loud. It is a warning and not an error:
+* refusing to start would be a worse trade for someone on a single-user machine.
+*/
+const warnIfGroupReadable = (path) => {
+	if (process.platform === "win32") return;
+	try {
+		if (statSync(path).mode & 63) process.stderr.write(`[x-api] ${path} is readable by other users. Run: chmod 600 ${path}\n`);
+	} catch {}
+};
+/**
+* Read the config file, treating "absent" as "contributes nothing". Every other
+* failure throws and names the path, so a malformed file is never mistaken for
+* a missing one — that confusion would send you hunting for credentials that
+* were sitting right there.
+*/
+const readConfigFile = (path) => {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return {};
+		throw new Error(`Could not read the config file (${path}): ${message$1(err)}`, { cause: err });
+	}
+	warnIfGroupReadable(path);
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw new Error(`The config file (${path}) is not valid JSON: ${message$1(err)}`, { cause: err });
+	}
+	const result = FileConfigSchema.safeParse(parsed);
+	if (!result.success) {
+		const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
+		throw new Error(`The config file (${path}) is not valid: ${issues}`);
+	}
+	return result.data;
+};
+/**
+* Environment first, config file second, **per field** — not whole-source.
+* Docker and CI inject the environment and must keep working untouched, while a
+* one-off `X_API_ALLOW_WRITES=0` still has to override a file that says `true`.
+* Merging field by field is the only rule that gives both.
+*/
+const loadConfig = (env = process.env, configPath = resolveConfigPath(env)) => {
+	const file = readConfigFile(configPath);
+	const tokenFile = trimmed(env.X_API_TOKEN_FILE) ?? file.tokenFile ?? resolveTokenPath(env);
+	return ConfigSchema.parse({
+		bearerToken: trimmed(env.X_API_BEARER_TOKEN) ?? file.bearerToken,
+		clientId: trimmed(env.X_API_CLIENT_ID) ?? file.clientId,
+		clientSecret: trimmed(env.X_API_CLIENT_SECRET) ?? file.clientSecret,
+		redirectUri: trimmed(env.X_API_REDIRECT_URI) ?? file.redirectUri,
+		scopes: parseList(env.X_API_SCOPES) ?? file.scopes,
+		tokenFile: expandTilde(tokenFile),
+		allowWrites: parseBool(env.X_API_ALLOW_WRITES) ?? file.allowWrites,
+		writeBackend: trimmed(env.X_API_WRITE_BACKEND) ?? file.writeBackend,
+		autoOpenBrowser: parseBool(env.X_API_AUTO_OPEN_BROWSER) ?? file.autoOpenBrowser,
+		enableFullArchive: parseBool(env.X_API_ENABLE_FULL_ARCHIVE) ?? file.enableFullArchive,
+		defaultMaxResults: parseIntOpt(env.X_API_DEFAULT_MAX_RESULTS) ?? file.defaultMaxResults,
+		monthlyBudgetUsd: parseFloatOpt(env.X_API_MONTHLY_BUDGET_USD) ?? file.monthlyBudgetUsd,
+		cacheEnabled: parseBool(env.X_API_CACHE_ENABLED) ?? file.cacheEnabled,
+		cacheMaxEntries: parseIntOpt(env.X_API_CACHE_MAX_ENTRIES) ?? file.cacheMaxEntries,
+		maxRetries: parseIntOpt(env.X_API_MAX_RETRIES) ?? file.maxRetries,
+		baseUrl: trimmed(env.X_API_BASE_URL) ?? file.baseUrl,
+		pricing: file.pricing,
+		adsEnabled: parseBool(env.X_ADS_ENABLED) ?? file.adsEnabled,
+		adsAllowWrites: parseBool(env.X_ADS_ALLOW_WRITES) ?? file.adsAllowWrites,
+		adsBaseUrl: trimmed(env.X_ADS_BASE_URL) ?? file.adsBaseUrl,
+		adsAccountId: trimmed(env.X_ADS_ACCOUNT_ID) ?? file.adsAccountId,
+		adsMaxDownloadBytes: parseIntOpt(env.X_ADS_MAX_DOWNLOAD_BYTES) ?? file.adsMaxDownloadBytes
+	});
+};
+/**
+* Whether the ads tools should be registered. The Ads API rides the same OAuth
+* 2.0 user token as bookmarks and the home timeline — the `ads.read` /
+* `ads.write` scopes are what separate them — so a client id is the hard
+* requirement, not a second set of credentials.
+*/
+const hasAdsAccess = (config) => config.adsEnabled && Boolean(config.clientId);
+/** Whether anything at all is configured that can reach the X API. */
+const hasApiCredentials = (config) => Boolean(config.bearerToken ?? config.clientId);
+/**
+* What to do when nothing is configured. Returned by `x_auth_status` and
+* printed at startup, because this is the state a first-time user lands in and
+* the server can no longer signal it by refusing to start.
+*/
+const setupInstructions = (config) => [
+	"No X credentials are configured, so the tools that call the X API are not registered.",
+	"The free local tools still work: x_compose_post (posts via a browser click, no credentials, no cost), x_validate_post, and x_build_search_query.",
+	"Create an app at https://console.x.com (this replaced the old developer.x.com portal). Both credentials below are on the app's Keys and Tokens screen.",
+	"To enable reading and search, set X_API_BEARER_TOKEN to the app's Bearer Token. That alone covers post lookup, search, profiles and timelines — OAuth is not needed for any of it.",
+	`To enable bookmarks, your home timeline and API writes, also set X_API_CLIENT_ID. When creating the app choose Type of App = Native App: that makes it a public PKCE client with no client secret, which is what this server expects. Register the callback URL ${config.redirectUri} byte for byte (X's docs say to use 127.0.0.1 rather than localhost), then run \`x-api-mcp login\` or call x_auth_login.`,
+	"Enroll the app in the Pay-per-use package and the Production environment. An app left in the legacy Free/Development state logs in successfully and then fails every call with 403 client-not-enrolled.",
+	"Note that X removed its free tier on 2026-02-06: creating an app is free, but reads are pay-per-use and need prepurchased credits in the console."
+];
+/**
+* What to do when ads is enabled but the account cannot reach the Ads API.
+* Surfaced by `x_auth_status`, because the two steps people miss are invisible
+* from the error alone: the app needs the Ads Project attached, and any token
+* minted *before* approval does not carry the entitlement.
+*/
+const adsSetupInstructions = (config) => [
+	"The Ads API is separate from the X API v2: it needs its own approval, even though it uses the same OAuth 2.0 login.",
+	"At https://console.x.com open your app, then Project Access → MANAGE → Ads Project. That attaches Ads API access to the app id.",
+	"Request Ads API access for the app using X's Ads API Access Form. Standard Access covers campaigns, creatives, audiences and analytics.",
+	"After approval is granted, run `x-api-mcp login` again. A token minted before approval does not carry the entitlement, and re-using it fails every call.",
+	"Ads calls are billed separately from X's pay-per-use reads, so they do not appear in x_usage_report — but the campaigns they manage spend your advertising budget.",
+	`Point X_ADS_BASE_URL at ${SANDBOX_ADS_BASE_URL} for a free sandbox before touching a live account. Set X_ADS_ALLOW_WRITES=1 to register the campaign-mutating tools; without it they do not exist.`,
+	...config.adsAccountId ? [] : ["X_ADS_ACCOUNT_ID is unset. That is fine when you have exactly one ads account — it is resolved automatically — but with several you must pass accountId per call or set it."]
+];
+/**
+* The scopes actually requested at login. `tweet.write` is only asked for when
+* the paid write backend is on, so a reader never holds a permission it cannot
+* use — and the consent screen stays honest about what the server will do.
+*/
+const effectiveScopes = (config) => {
+	const scopes = [...config.scopes];
+	if (config.allowWrites && config.writeBackend === "api" && !scopes.includes("tweet.write")) scopes.push("tweet.write");
+	if (config.adsEnabled && !scopes.includes("ads.read")) scopes.push("ads.read");
+	if (config.adsEnabled && config.adsAllowWrites && !scopes.includes("ads.write")) scopes.push("ads.write");
+	return scopes;
+};
+//#endregion
+//#region src/client/ads.ts
+/** The default page size X uses. Its maximum is 1000. */
+const DEFAULT_COUNT = 200;
+/**
+* Hosts the async-analytics download is allowed to reach. The URL comes out of
+* an X response rather than from us, and following a server-supplied URL
+* unchecked is an SSRF primitive — not something to leave open in a project
+* whose pitch is a small attack surface.
+*/
+const DOWNLOAD_HOSTS = [
+	".x.com",
+	".twimg.com",
+	".twitter.com",
+	".amazonaws.com"
+];
+/**
+* `endpointKey` collapses long digit runs, which is right for v2 post ids and
+* useless here: ads ids are alphanumeric (`18ce54d4x5t`). Collapse the resource
+* segments by name instead, so one bucket per endpoint rather than per entity.
+*/
+const adsEndpointKey = (method, path) => endpointKey(method, path.replace(/\/(accounts|campaigns|line_items|promoted_tweets|targeting_criteria|custom_audiences|funding_instruments)\/[A-Za-z0-9_-]+/g, "/$1/:id"));
+const isRec = (value) => typeof value === "object" && value !== null;
+/**
+* Fetch-based client for the X Ads API v12. Deliberately not an `XApiClient`
+* subclass: the two share transport concerns and nothing else. Ads paginates by
+* cursor rather than `next_token`, answers errors in two envelopes neither of
+* which is v2's problem-details, reports three families of rate-limit headers,
+* and needs its own diagnostics — the v2 prose about the Pay-per-use package is
+* actively misleading here. What genuinely is shared lives in `./http.js`.
+*
+* Writes send their parameters in the query string, never a JSON body: that is
+* what the Ads API takes on POST and PUT, and what X's own SDKs send.
+*/
+var AdsApiClient = class {
+	sandbox;
+	baseUrl;
+	tokenProvider;
+	maxRetries;
+	maxDownloadBytes;
+	fetchImpl;
+	logger;
+	userAgent;
+	rateLimits = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.baseUrl = (opts.baseUrl ?? "https://ads-api.x.com").replace(/\/+$/, "");
+		this.sandbox = /ads-api-sandbox\./.test(this.baseUrl);
+		this.tokenProvider = opts.tokenProvider;
+		this.maxRetries = opts.maxRetries ?? 3;
+		this.maxDownloadBytes = opts.maxDownloadBytes ?? 25e6;
+		this.fetchImpl = opts.fetch ?? fetch;
+		this.logger = opts.logger;
+		this.userAgent = opts.userAgent ?? "mcp-x-api-js";
+	}
+	rateLimitStatus() {
+		return [...this.rateLimits.values()];
+	}
+	/**
+	* Ads reports three independent budgets, and a 429 can come from any of them.
+	* Recording only the endpoint family would leave the account-level limit —
+	* the one that actually bites during a bulk read — invisible.
+	*/
+	recordRateLimit(method, path, res) {
+		for (const { scope, prefix } of [
+			{
+				scope: "endpoint",
+				prefix: "x-rate-limit"
+			},
+			{
+				scope: "account",
+				prefix: "x-account-rate-limit"
+			},
+			{
+				scope: "cost",
+				prefix: "x-cost-rate-limit"
+			}
+		]) {
+			const limit = numberOrUndefined(res.headers.get(`${prefix}-limit`));
+			const remaining = numberOrUndefined(res.headers.get(`${prefix}-remaining`));
+			const reset = numberOrUndefined(res.headers.get(`${prefix}-reset`));
+			if (limit === void 0 && remaining === void 0 && reset === void 0) continue;
+			const endpoint = adsEndpointKey(method, path);
+			this.rateLimits.set(`${scope} ${endpoint}`, {
+				endpoint,
+				api: "ads",
+				scope,
+				...limit !== void 0 ? { limit } : {},
+				...remaining !== void 0 ? { remaining } : {},
+				...reset !== void 0 ? {
+					reset,
+					resetAt: (/* @__PURE__ */ new Date(reset * 1e3)).toISOString()
+				} : {}
+			});
+		}
+	}
+	async request(method, path, query) {
+		const url = `${this.baseUrl}${path}${buildQuery(query)}`;
+		const res = await withRetry(async () => {
+			const token = await this.tokenProvider.getToken("user");
+			return this.fetchImpl(url, {
+				method,
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${token}`,
+					"User-Agent": this.userAgent
+				}
+			});
+		}, {
+			maxRetries: this.maxRetries,
+			label: `${method} ${url}`,
+			logger: this.logger,
+			onUnauthorized: () => this.tokenProvider.invalidate("user")
+		});
+		this.recordRateLimit(method, path, res);
+		const text = await res.text();
+		if (!res.ok) throw new XApiRequestError(this.errorMessage(res, method, path, text), {
+			status: res.status,
+			errors: this.parseErrors(text)
+		});
+		if (res.status === 204 || text.trim() === "") return null;
+		return safeJsonParse(text);
+	}
+	get(path, query) {
+		return this.request("GET", path, query);
+	}
+	post(path, query) {
+		return this.request("POST", path, query);
+	}
+	put(path, query) {
+		return this.request("PUT", path, query);
+	}
+	del(path, query) {
+		return this.request("DELETE", path, query);
+	}
+	/**
+	* GET a collection, following `next_cursor` until the pages run out or a
+	* bound is hit.
+	*
+	* Unlike v2, the cursor is a top-level field rather than nested under `meta`,
+	* it is `null` (not absent) on the last page, and it goes back out as
+	* `cursor`. Everything else about the loop matches `XApiClient.paginate`,
+	* which is why this is a separate method rather than a shared one — the
+	* differences are exactly the parts that matter.
+	*/
+	async paginateCursor(path, query, opts) {
+		const maxPages = opts.maxPages ?? 5;
+		const collected = [];
+		let cursor;
+		let pages = 0;
+		let nextCursor;
+		let totalCount;
+		for (;;) {
+			const res = await this.request("GET", path, {
+				count: DEFAULT_COUNT,
+				...query,
+				...cursor ? { cursor } : {}
+			});
+			pages += 1;
+			if (Array.isArray(res?.data)) collected.push(...res.data);
+			if (typeof res?.total_count === "number") totalCount = res.total_count;
+			const next = res?.next_cursor;
+			cursor = typeof next === "string" && next ? next : void 0;
+			nextCursor = cursor;
+			if (!cursor || collected.length >= opts.maxItems || pages >= maxPages) break;
+		}
+		return {
+			data: collected.slice(0, opts.maxItems),
+			pages,
+			...nextCursor ? { nextCursor } : {},
+			...totalCount !== void 0 ? { totalCount } : {}
+		};
+	}
+	/**
+	* Fetch a finished analytics job's result file and decompress it.
+	*
+	* Three things here are load-bearing. The URL is a presigned object-store
+	* link on a different host, so it must go out with **no** Authorization
+	* header — signing it makes the store reject it. The host is checked first,
+	* because the URL came from a remote response. And both the compressed and
+	* decompressed sizes are capped: a 25 MB gzip of repetitive JSON expands to
+	* hundreds of megabytes, so an uncapped gunzip here is an OOM waiting for a
+	* big enough report.
+	*/
+	async downloadGzipped(url) {
+		let parsed;
+		try {
+			parsed = new URL(url);
+		} catch {
+			throw new PreconditionError(`The analytics result URL is not a valid URL: ${url}`, { url });
+		}
+		const host = parsed.hostname.toLowerCase();
+		if (parsed.protocol !== "https:" || !DOWNLOAD_HOSTS.some((d) => host.endsWith(d))) throw new PreconditionError(`Refusing to download the analytics result from ${host}: it is not an X-owned host. This URL came from an API response, so an unexpected host is worth stopping on.`, {
+			host,
+			allowed: DOWNLOAD_HOSTS
+		});
+		const res = await this.fetchImpl(url, { headers: {
+			Accept: "application/json",
+			"User-Agent": this.userAgent
+		} });
+		if (!res.ok) throw new XApiRequestError(`Downloading the analytics result failed: HTTP ${res.status} ${res.statusText}. These URLs expire — re-read the job with x_ads_get_stats_jobs for a fresh one.`, { status: res.status });
+		const declared = numberOrUndefined(res.headers.get("content-length"));
+		if (declared !== void 0 && declared > this.maxDownloadBytes) throw new PreconditionError(`The analytics result is ${declared} bytes, over the ${this.maxDownloadBytes}-byte limit. Re-run the job over fewer entity_ids, a shorter date range, or a coarser granularity, or raise X_ADS_MAX_DOWNLOAD_BYTES.`, {
+			bytes: declared,
+			limit: this.maxDownloadBytes
+		});
+		const buf = Buffer.from(await res.arrayBuffer());
+		if (buf.byteLength > this.maxDownloadBytes) throw new PreconditionError(`The analytics result is ${buf.byteLength} bytes, over the ${this.maxDownloadBytes}-byte limit. Narrow the job, or raise X_ADS_MAX_DOWNLOAD_BYTES.`, {
+			bytes: buf.byteLength,
+			limit: this.maxDownloadBytes
+		});
+		try {
+			const out = gunzipSync(buf, { maxOutputLength: this.maxDownloadBytes * 20 });
+			return {
+				text: out.toString("utf8"),
+				bytes: out.byteLength
+			};
+		} catch (err) {
+			if (err.code === "ERR_BUFFER_TOO_LARGE") throw new PreconditionError(`The analytics result decompressed past ${this.maxDownloadBytes * 20} bytes and was discarded. Re-run the job over a narrower range.`, { limit: this.maxDownloadBytes * 20 });
+			throw err;
+		}
+	}
+	parseErrors(text) {
+		const parsed = safeJsonParse(text);
+		if (isRec(parsed) && Array.isArray(parsed.errors)) return parsed.errors;
+		return parsed;
+	}
+	/**
+	* Ads answers in two envelopes. The gateway rejects bad auth with the legacy
+	* v1.1 shape and a *numeric* code — and with HTTP 400, not 401. Past that,
+	* application errors use CAPS_CASE string codes. Both are quoted here, and
+	* each status gets the sentence that actually fixes it: a bare
+	* "UNAUTHORIZED_ACCESS" sends people to re-check a token that is usually fine.
+	*/
+	errorMessage(res, method, path, text) {
+		const base = `X Ads API ${method} ${path} failed: HTTP ${res.status} ${res.statusText}`.trim();
+		const parsed = this.parseErrors(text);
+		const detail = Array.isArray(parsed) ? parsed.map((e) => [
+			e.code,
+			e.message ?? e.detail,
+			e.parameter
+		].filter(Boolean).join(" — ")).filter(Boolean).join("; ") : "";
+		const suffix = detail ? ` (${detail})` : "";
+		if (res.status === 400 && /"code":\s*2\d\d/.test(text)) return `${base} — X's gateway rejected the credentials outright. The access token is missing or malformed; run \`x-api-mcp login\` again${suffix}`;
+		if (res.status === 401) return `${base} — authenticated request refused. Most often the stored token predates your Ads API approval, or was minted before ads.read was in scope: run \`x-api-mcp login\` again so the new token carries the ads scopes${suffix}`;
+		if (res.status === 403) return `${base} — the token is valid, but this app is not approved for the Ads REST API. Attaching the Ads Project at console.x.com is only half of it: that switch enables X's hosted Ads MCP, while these /12/ endpoints additionally need X's Ads API Access Form to be approved, which is a human review rather than a toggle. Once it is granted, run \`x-api-mcp login\` again — a token minted before approval does not carry it` + suffix;
+		if (res.status === 404) return `${base} — no such entity at ${this.baseUrl}. Check the account id, and check you are pointed at the right environment: X_ADS_BASE_URL is currently ${this.sandbox ? "the SANDBOX" : "PRODUCTION"} (${this.baseUrl}), and ids do not carry across${suffix}`;
+		if (res.status === 429) {
+			const snapshot = [...this.rateLimits.values()].find((s) => s.endpoint === adsEndpointKey(method, path));
+			return `${base} — rate limited${snapshot ? ` (${snapshot.remaining ?? 0}/${snapshot.limit ?? "?"} remaining on the ${snapshot.scope} budget${snapshot.resetAt ? `, resets ${snapshot.resetAt}` : ""})` : ""}. Wait for the window to reset, or ask for less.`;
+		}
+		return base + suffix;
+	}
+};
+//#endregion
+//#region src/client/ads-shape.ts
+const isRecord$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** X states every money field in millionths of a currency unit. */
+const MICRO = 1e6;
+const toMicro = (major) => Math.round(major * MICRO);
+const fromMicro = (micro) => Math.round(micro / MICRO * 100) / 100;
+const MICRO_SUFFIX = "_amount_local_micro";
+/**
+* Pair every `*_amount_local_micro` field with the value a human would say.
+*
+* This is not cosmetic. A model that reads `daily_budget_amount_local_micro:
+* 50000000` and reasons about it concludes the budget is fifty million, and the
+* next thing it proposes is scaled by a factor of a million. The write path
+* guards against the same mistake by refusing micro inputs; this is the other
+* half, and without it the guard only covers one direction.
+*
+* The micro field is kept rather than replaced, so the raw value X returned
+* stays auditable.
+*/
+const shapeMoney = (value, currency) => {
+	if (Array.isArray(value)) return value.map((item) => shapeMoney(item, currency));
+	if (!isRecord$1(value)) return value;
+	const out = {};
+	for (const [key, raw] of Object.entries(value)) {
+		out[key] = shapeMoney(raw, currency);
+		if (!key.endsWith(MICRO_SUFFIX) || typeof raw !== "number") continue;
+		const base = key.slice(0, -19);
+		out[base] = fromMicro(raw);
+		if (currency) out[`${base}_currency`] = currency;
+	}
+	return out;
+};
+/**
+* Strip the Ads API's envelope down to what a caller wants.
+*
+* Every ads response echoes the request back under `request`, which is pure
+* noise in a tool result — the caller just sent it. `next_cursor` and
+* `total_count` are lifted out by the client's pagination instead.
+*/
+const adsData = (raw) => isRecord$1(raw) ? raw.data : void 0;
+const message = (err) => err instanceof Error ? err.message : String(err);
+const createTokenStore = (path) => ({
+	path,
+	read() {
+		let raw;
+		try {
+			raw = readFileSync(path, "utf8");
+		} catch (err) {
+			if (err.code === "ENOENT") return void 0;
+			throw new Error(`Could not read the token file (${path}): ${message(err)}`, { cause: err });
+		}
+		warnIfGroupReadable(path);
+		let parsed;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			process.stderr.write(`[x-api] ${path} is not valid JSON — run \`x-api-mcp login\` again.\n`);
+			return;
+		}
+		if (typeof parsed !== "object" || parsed === null || parsed.version !== 1) return;
+		return parsed;
+	},
+	write(tokens) {
+		mkdirSync(dirname(path), {
+			recursive: true,
+			mode: 448
+		});
+		const tmp = join(dirname(path), `.tokens.${process.pid}.tmp`);
+		writeFileSync(tmp, `${JSON.stringify(tokens, null, 2)}\n`, { mode: 384 });
+		renameSync(tmp, path);
+	},
+	clear() {
+		try {
+			unlinkSync(path);
+		} catch (err) {
+			if (err.code !== "ENOENT") throw err;
+		}
+	}
+});
+/** True when the stored tokens cannot serve the app or scopes we now need. */
+const tokensAreStale = (tokens, clientId, requiredScopes) => {
+	if (!tokens) return {
+		stale: true,
+		reason: "no stored tokens"
+	};
+	if (tokens.clientId !== clientId) return {
+		stale: true,
+		reason: "the stored tokens belong to a different X_API_CLIENT_ID"
+	};
+	const missing = requiredScopes.filter((scope) => !tokens.scopes.includes(scope));
+	if (missing.length > 0) return {
+		stale: true,
+		reason: `the stored tokens lack the scope(s): ${missing.join(", ")}`
+	};
+	return { stale: false };
+};
+/** Mode bits of the token file, for tests and `x_auth_status`. */
+const fileMode = (path) => {
+	try {
+		return statSync(path).mode & 511;
+	} catch {
+		return;
+	}
+};
+//#endregion
+//#region src/client/oauth.ts
+const AUTHORIZE_URL = "https://x.com/i/oauth2/authorize";
+const TOKEN_PATH = "/2/oauth2/token";
+const CALLBACK_TIMEOUT_MS = 12e4;
+const base64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+/**
+* PKCE S256. 32 random bytes base64url-encode to exactly 43 characters, the
+* minimum the spec allows for a verifier.
+*/
+const createPkcePair = (random = randomBytes) => {
+	const verifier = base64url(random(32));
+	return {
+		verifier,
+		challenge: base64url(createHash("sha256").update(verifier).digest())
+	};
+};
+const buildAuthorizeUrl = (opts) => {
+	const params = new URLSearchParams({
+		response_type: "code",
+		client_id: opts.clientId,
+		redirect_uri: opts.redirectUri,
+		scope: opts.scopes.join(" "),
+		state: opts.state,
+		code_challenge: opts.challenge,
+		code_challenge_method: "S256"
+	});
+	return `${AUTHORIZE_URL}?${params.toString()}`;
+};
+/** Constant-time compare, so a mismatched state cannot be probed byte by byte. */
+const statesMatch = (a, b) => {
+	const left = Buffer.from(a);
+	const right = Buffer.from(b);
+	return left.length === right.length && timingSafeEqual(left, right);
+};
+const formPost = async (fetchImpl, config, body) => {
+	const headers = {
+		"Content-Type": "application/x-www-form-urlencoded",
+		Accept: "application/json"
+	};
+	if (config.clientSecret) headers.Authorization = `Basic ${Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64")}`;
+	const res = await fetchImpl(`${config.baseUrl.replace(/\/+$/, "")}${TOKEN_PATH}`, {
+		method: "POST",
+		headers,
+		body: body.toString()
+	});
+	const text = await res.text();
+	if (!res.ok) throw new Error(`X rejected the OAuth token request: HTTP ${res.status} — ${text.slice(0, 400)}`);
+	return JSON.parse(text);
+};
+const createOAuthClient = (config, fetchImpl = fetch) => {
+	if (!config.clientId) throw new PreconditionError("X_API_CLIENT_ID is required for the OAuth2 flow.");
+	const clientId = config.clientId;
+	return {
+		exchangeCode: (code, verifier) => formPost(fetchImpl, config, new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: config.redirectUri,
+			code_verifier: verifier,
+			client_id: clientId
+		})),
+		refresh: (refreshToken) => formPost(fetchImpl, config, new URLSearchParams({
+			grant_type: "refresh_token",
+			refresh_token: refreshToken,
+			client_id: clientId
+		}))
+	};
+};
+const toStoredTokens = (res, opts) => ({
+	version: 1,
+	clientId: opts.clientId,
+	scopes: res.scope ? res.scope.split(/\s+/).filter(Boolean) : opts.requestedScopes,
+	accessToken: res.access_token,
+	...res.refresh_token ? { refreshToken: res.refresh_token } : {},
+	...opts.previousRefreshToken ? { previousRefreshToken: opts.previousRefreshToken } : {},
+	expiresAt: opts.now + (res.expires_in ?? 7200) * 1e3,
+	obtainedAt: opts.now,
+	...opts.userId ? { userId: opts.userId } : {},
+	...opts.username ? { username: opts.username } : {}
+});
+const SUCCESS_PAGE = `<!doctype html><meta charset="utf-8"><title>x-api-mcp</title>
+<body style="font-family:system-ui;max-width:32rem;margin:4rem auto;line-height:1.5">
+<h1>Signed in</h1><p>x-api-mcp stored your token. You can close this tab and return to your terminal.</p>
+</body>`;
+const FAILURE_PAGE = `<!doctype html><meta charset="utf-8"><title>x-api-mcp</title>
+<body style="font-family:system-ui;max-width:32rem;margin:4rem auto;line-height:1.5">
+<h1>Sign-in failed</h1><p>Check the terminal running x-api-mcp for the reason.</p>
+</body>`;
+/**
+* Run the browser half of the flow: open the authorize URL, listen on the
+* loopback port for exactly one callback, and hand back the code.
+*
+* The port is fixed rather than ephemeral because X matches the redirect URI
+* against the value registered in the developer portal byte for byte — an
+* ephemeral port could never be authorized.
+*/
+const awaitCallback = (opts) => {
+	const url = new URL(opts.redirectUri);
+	const port = Number(url.port);
+	const expectedPath = url.pathname;
+	let settle;
+	const code = new Promise((resolve, reject) => {
+		settle = {
+			resolve,
+			reject
+		};
+	});
+	const server = createServer((req, res) => {
+		const requestUrl = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+		if (requestUrl.pathname !== expectedPath) {
+			res.writeHead(404).end("Not found");
+			return;
+		}
+		const returnedState = requestUrl.searchParams.get("state") ?? "";
+		const returnedCode = requestUrl.searchParams.get("code");
+		const error = requestUrl.searchParams.get("error");
+		if (error) {
+			res.writeHead(400, { "content-type": "text/html" }).end(FAILURE_PAGE);
+			settle.reject(/* @__PURE__ */ new Error(`X denied the authorization: ${error}`));
+			return;
+		}
+		if (!statesMatch(returnedState, opts.state)) {
+			res.writeHead(400, { "content-type": "text/html" }).end(FAILURE_PAGE);
+			settle.reject(/* @__PURE__ */ new Error("The callback did not come from the login that was started (state mismatch)."));
+			return;
+		}
+		if (!returnedCode) {
+			res.writeHead(400, { "content-type": "text/html" }).end(FAILURE_PAGE);
+			settle.reject(/* @__PURE__ */ new Error("The callback carried no authorization code."));
+			return;
+		}
+		res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_PAGE);
+		settle.resolve(returnedCode);
+	});
+	const timer = setTimeout(() => {
+		settle.reject(/* @__PURE__ */ new Error(`No callback arrived within ${(opts.timeoutMs ?? CALLBACK_TIMEOUT_MS) / 1e3}s. Re-run the login and complete it in the browser.`));
+	}, opts.timeoutMs ?? CALLBACK_TIMEOUT_MS);
+	timer.unref?.();
+	server.on("error", (err) => {
+		settle.reject(err.code === "EADDRINUSE" ? /* @__PURE__ */ new Error(`Port ${port} is already in use, so the OAuth callback cannot be received. Free it, or set X_API_REDIRECT_URI to another loopback URL — and register that exact URL in the X developer console at console.x.com, which must match byte for byte.`) : err);
+	});
+	server.listen(port, "127.0.0.1");
+	const close = () => {
+		clearTimeout(timer);
+		server.close();
+	};
+	code.finally(close).catch(() => {});
+	return {
+		url: void 0,
+		code,
+		close
+	};
+};
+/** The whole login: PKCE, browser, callback, exchange, identify, persist. */
+const startLoginFlow = async (opts) => {
+	const { config, store } = opts;
+	if (!config.clientId) throw new PreconditionError("X_API_CLIENT_ID is required to log in. Create an OAuth 2.0 app in the X developer portal, enable PKCE, and add this exact callback URL: " + config.redirectUri);
+	const fetchImpl = opts.fetch ?? fetch;
+	const now = opts.now ?? Date.now;
+	const scopes = effectiveScopes(config);
+	const { verifier, challenge } = createPkcePair();
+	const state = base64url(randomBytes(16));
+	const authorizeUrl = buildAuthorizeUrl({
+		clientId: config.clientId,
+		redirectUri: config.redirectUri,
+		scopes,
+		state,
+		challenge
+	});
+	const listener = awaitCallback({
+		redirectUri: config.redirectUri,
+		state,
+		...opts.timeoutMs !== void 0 ? { timeoutMs: opts.timeoutMs } : {},
+		...opts.logger ? { logger: opts.logger } : {}
+	});
+	opts.logger?.warn?.(`Open this URL to authorize x-api-mcp:\n${authorizeUrl}`);
+	if (opts.openBrowser) await opts.openBrowser(authorizeUrl);
+	const code = await listener.code;
+	const res = await createOAuthClient(config, fetchImpl).exchangeCode(code, verifier);
+	let userId;
+	let username;
+	try {
+		const body = await (await fetchImpl(`${config.baseUrl.replace(/\/+$/, "")}/2/users/me`, { headers: {
+			Authorization: `Bearer ${res.access_token}`,
+			Accept: "application/json"
+		} })).json();
+		userId = body.data?.id;
+		username = body.data?.username;
+	} catch {}
+	const tokens = toStoredTokens(res, {
+		clientId: config.clientId,
+		requestedScopes: scopes,
+		now: now(),
+		...userId ? { userId } : {},
+		...username ? { username } : {}
+	});
+	store.write(tokens);
+	return {
+		tokens,
+		authorizeUrl
+	};
+};
+//#endregion
+//#region src/client/auth.ts
+/**
+* The app-only Bearer token, copied from the developer portal. It never
+* expires and cannot be reminted, so `invalidate` is a no-op: a 401 here means
+* the token is wrong, and retrying with the same string would only burn the
+* retry budget.
+*/
+const bearerTokenProvider = (token) => ({
+	getToken: async (context) => {
+		if (context === "user") throw new UserContextRequiredError("This tool", "only an app-only Bearer token is configured");
+		return token;
+	},
+	invalidate: () => {},
+	describe: () => ({
+		app: true,
+		user: {
+			authenticated: false,
+			reason: "no OAuth2 client id configured"
+		}
+	})
+});
+/**
+* An OAuth2 user token, refreshed on demand.
+*
+* Two rules make this safe against X's rotating refresh tokens, which are
+* invalidated the instant a refresh succeeds:
+*
+*  1. **Persist before use.** The new pair is written to disk before the access
+*     token is handed to the caller. Handing it out first and then crashing
+*     leaves the on-disk refresh token already dead, forcing a re-login.
+*  2. **Keep one generation.** A refresh that fails on the current token is
+*     retried once with `previousRefreshToken`, which recovers exactly the
+*     crash-between-response-and-write window rather than dumping the user back
+*     into a browser.
+*
+* A single in-flight promise coordinates concurrent callers: unlike a locally
+* signed JWT, an OAuth refresh is a network call that must not be issued twice
+* — the second would present a token the first had just invalidated.
+*/
+const userTokenProvider = (opts) => {
+	const now = opts.now ?? Date.now;
+	/** Refresh a minute early, so a token cannot expire mid-flight. */
+	const SKEW_MS = 6e4;
+	let inFlight;
+	const refresh = async (tokens) => {
+		const candidates = [tokens.refreshToken, tokens.previousRefreshToken].filter((t) => typeof t === "string" && t.length > 0);
+		if (candidates.length === 0) throw new UserContextRequiredError("This tool", "the stored token has expired and carries no refresh token — the `offline.access` scope was probably not granted");
+		let lastError;
+		for (const [index, candidate] of candidates.entries()) try {
+			const next = toStoredTokens(await opts.oauth.refresh(candidate), {
+				clientId: opts.clientId,
+				requestedScopes: tokens.scopes,
+				now: now(),
+				previousRefreshToken: candidate,
+				...tokens.userId ? { userId: tokens.userId } : {},
+				...tokens.username ? { username: tokens.username } : {}
+			});
+			opts.store.write(next);
+			return next.accessToken;
+		} catch (err) {
+			lastError = err;
+			if (index === 0 && candidates.length > 1) opts.logger?.warn?.("[x-api] refresh failed on the current token; retrying with the previous generation");
+		}
+		throw new UserContextRequiredError("This tool", `refreshing the stored token failed (${lastError instanceof Error ? lastError.message : String(lastError)})`);
+	};
+	const resolve = async () => {
+		const tokens = opts.store.read();
+		const staleness = tokensAreStale(tokens, opts.clientId, opts.requiredScopes);
+		if (staleness.stale) throw new UserContextRequiredError("This tool", staleness.reason);
+		const current = tokens;
+		if (current.expiresAt - SKEW_MS > now()) return current.accessToken;
+		return refresh(current);
+	};
+	return {
+		getToken: async (context) => {
+			if (context === "app") return resolve();
+			if (!inFlight) inFlight = resolve().finally(() => {
+				inFlight = void 0;
+			});
+			return inFlight;
+		},
+		invalidate: () => {
+			const tokens = opts.store.read();
+			if (tokens) opts.store.write({
+				...tokens,
+				expiresAt: 0
+			});
+			inFlight = void 0;
+		},
+		describe: () => {
+			const tokens = opts.store.read();
+			const staleness = tokensAreStale(tokens, opts.clientId, opts.requiredScopes);
+			if (staleness.stale) return {
+				app: false,
+				user: {
+					authenticated: false,
+					reason: staleness.reason
+				}
+			};
+			const current = tokens;
+			return {
+				app: false,
+				user: {
+					authenticated: true,
+					...current.username ? { username: current.username } : {},
+					...current.userId ? { userId: current.userId } : {},
+					scopes: current.scopes,
+					expiresAt: current.expiresAt
+				}
+			};
+		}
+	};
+};
+/**
+* Combine whichever providers are configured, dispatching by context. Either
+* side may be absent — a Bearer-only install is the common case, and a
+* user-only install is legitimate too (an OAuth2 access token can read
+* everything an app-only token can).
+*/
+const compositeTokenProvider = (parts) => ({
+	getToken: async (context) => {
+		if (context === "user") {
+			if (!parts.user) throw new UserContextRequiredError("This tool", "no OAuth2 client id is configured");
+			return parts.user.getToken("user");
+		}
+		if (parts.app) return parts.app.getToken("app");
+		if (parts.user) return parts.user.getToken("user");
+		throw new Error("No credentials configured. Set X_API_BEARER_TOKEN, or X_API_CLIENT_ID and run `x-api-mcp login`.");
+	},
+	invalidate: (context) => {
+		if (context === "user") parts.user?.invalidate("user");
+		else parts.app?.invalidate("app");
+	},
+	describe: () => ({
+		app: parts.app?.describe().app ?? false,
+		user: parts.user?.describe().user ?? {
+			authenticated: false,
+			reason: "no OAuth2 client id configured"
+		}
+	})
+});
+/** The test double: one token, both contexts, no network. */
+const staticTokenProvider = (token) => ({
+	getToken: async () => token,
+	invalidate: () => {},
+	describe: () => ({
+		app: true,
+		user: {
+			authenticated: true,
+			username: "test",
+			userId: "1",
+			scopes: [],
+			expiresAt: 0
+		}
+	})
+});
+//#endregion
+//#region src/client/cache.ts
+/**
+* The dedup window is the UTC calendar day, not a rolling 24 hours — so the
+* whole cache turns over at once at UTC midnight rather than expiring entry by
+* entry. Comparing a stored day string is both cheaper and more faithful than
+* per-entry timestamps.
+*/
+const utcDay = (now) => new Date(now).toISOString().slice(0, 10);
+const keyOf = (kind, id) => `${kind}:${id}`;
+const createDayCache = (opts) => {
+	const now = opts.now ?? Date.now;
+	const enabled = opts.enabled ?? true;
+	let day = utcDay(now());
+	let hits = 0;
+	let misses = 0;
+	const entries = /* @__PURE__ */ new Map();
+	const rollover = () => {
+		const today = utcDay(now());
+		if (today !== day) {
+			entries.clear();
+			day = today;
+		}
+	};
+	return {
+		get(kind, id) {
+			if (!enabled) return void 0;
+			rollover();
+			const key = keyOf(kind, id);
+			if (!entries.has(key)) {
+				misses += 1;
+				return;
+			}
+			hits += 1;
+			const value = entries.get(key);
+			entries.delete(key);
+			entries.set(key, value);
+			return value;
+		},
+		set(kind, id, value) {
+			if (!enabled || opts.maxEntries === 0) return;
+			rollover();
+			const key = keyOf(kind, id);
+			entries.delete(key);
+			entries.set(key, value);
+			while (entries.size > opts.maxEntries) {
+				const oldest = entries.keys().next();
+				if (oldest.done) break;
+				entries.delete(oldest.value);
+			}
+		},
+		stats() {
+			rollover();
+			const total = hits + misses;
+			return {
+				day,
+				entries: entries.size,
+				hits,
+				misses,
+				hit_rate: total === 0 ? 0 : Math.round(hits / total * 100) / 100
+			};
+		}
+	};
+};
+//#endregion
+//#region src/client/cost.ts
+const rate = (pricing, kind) => kind === "post" ? pricing.postRead : kind === "user" ? pricing.userRead : pricing.ownedRead;
+const round = (n) => Math.round(n * 1e3) / 1e3;
+const createLedger = (opts) => {
+	const now = opts.now ?? Date.now;
+	let day = utcDay(now());
+	let paid = /* @__PURE__ */ new Set();
+	const counts = {
+		post: 0,
+		user: 0,
+		owned: 0,
+		freeFromDedup: 0,
+		created: 0
+	};
+	let spent = 0;
+	const rollover = () => {
+		const today = utcDay(now());
+		if (today !== day) {
+			paid = /* @__PURE__ */ new Set();
+			day = today;
+		}
+	};
+	return {
+		record(kind, ids) {
+			rollover();
+			const billable = [];
+			const free = [];
+			for (const id of ids) {
+				const key = `${kind}:${id}`;
+				if (paid.has(key)) {
+					free.push(id);
+					counts.freeFromDedup += 1;
+					continue;
+				}
+				paid.add(key);
+				billable.push(id);
+				counts[kind] += 1;
+				spent += rate(opts.pricing, kind);
+			}
+			return {
+				billable,
+				free
+			};
+		},
+		estimate(kind, ids) {
+			rollover();
+			return ids.filter((id) => !paid.has(`${kind}:${id}`)).length * rate(opts.pricing, kind);
+		},
+		estimateCount(kind, count) {
+			return count * rate(opts.pricing, kind);
+		},
+		recordCreate(hasUrl) {
+			counts.created += 1;
+			spent += hasUrl ? opts.pricing.postCreateWithUrl : opts.pricing.postCreate;
+		},
+		spentUsd: () => round(spent),
+		report(cache) {
+			rollover();
+			const reads = counts.post + counts.user + counts.owned;
+			return {
+				day,
+				since_process_start: {
+					billable_post_reads: counts.post,
+					billable_user_reads: counts.user,
+					owned_reads: counts.owned,
+					free_from_dedup: counts.freeFromDedup,
+					posts_created: counts.created,
+					estimated_usd: round(spent)
+				},
+				read_cap: {
+					monthly_cap: opts.pricing.monthlyReadCap,
+					reads_this_session: reads,
+					cap_used_pct: Math.round(reads / opts.pricing.monthlyReadCap * 1e4) / 100
+				},
+				...opts.budgetUsd !== void 0 ? { budget: {
+					limit_usd: opts.budgetUsd,
+					remaining_usd: round(Math.max(0, opts.budgetUsd - spent))
+				} } : {},
+				cache,
+				pricing: opts.pricing,
+				disclaimer: "Estimated locally from X's published pay-per-use rates and counted only since this process started — it is not persisted across restarts, and does not know about spend from other clients. The X developer console (console.x.com) is the authoritative record."
+			};
+		}
+	};
+};
+//#endregion
+//#region src/client/shape.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const str = (value) => typeof value === "string" && value ? value : void 0;
+const num = (value) => typeof value === "number" && Number.isFinite(value) ? value : void 0;
+const indexBy = (items, key) => {
+	const map = /* @__PURE__ */ new Map();
+	if (!Array.isArray(items)) return map;
+	for (const item of items) {
+		if (!isRecord(item)) continue;
+		const id = str(item[key]);
+		if (id) map.set(id, item);
+	}
+	return map;
+};
+/**
+* Build the lookup tables from one `includes` block or several (paginated reads
+* return one per page).
+*
+* These are `Map`s rather than an `Array.find` per lookup on purpose: a 100-post
+* page with 100 distinct authors would otherwise be quadratic, and the whole
+* point of this module is that it stays cheap on the largest responses.
+*/
+const buildIncludesIndex = (includes) => {
+	const blocks = Array.isArray(includes) ? includes : includes ? [includes] : [];
+	const index = {
+		users: /* @__PURE__ */ new Map(),
+		tweets: /* @__PURE__ */ new Map(),
+		media: /* @__PURE__ */ new Map()
+	};
+	for (const block of blocks) {
+		for (const [id, user] of indexBy(block.users, "id")) index.users.set(id, user);
+		for (const [id, tweet] of indexBy(block.tweets, "id")) index.tweets.set(id, tweet);
+		for (const [key, media] of indexBy(block.media, "media_key")) index.media.set(key, media);
+	}
+	return index;
+};
+/** Pull the `includes` block out of a raw response envelope. */
+const includesOf = (response) => isRecord(response) && isRecord(response.includes) ? response.includes : void 0;
+/**
+* "@handle (Display Name)" in one field, because the model reads it as a name
+* and never has to look one up. An unresolved author degrades rather than
+* throwing — a deleted or suspended account is routine, not exceptional.
+*/
+const formatAuthor = (authorId, index) => {
+	if (!authorId) return "@unknown";
+	const user = index.users.get(authorId);
+	const username = user ? str(user.username) : void 0;
+	if (!username) return `@unknown (id ${authorId})`;
+	const name = user ? str(user.name) : void 0;
+	return name ? `@${username} (${name})` : `@${username}`;
+};
+const postUrl = (authorId, id, index) => {
+	return `https://x.com/${(authorId ? str(index.users.get(authorId)?.username) : void 0) ?? "i/web"}/status/${id}`;
+};
+/**
+* Replace each t.co link with where it actually points.
+*
+* Splices run right-to-left by `start` so earlier offsets stay valid as the
+* string changes length. The offsets are UTF-16 code units, which is exactly
+* what `String.prototype.slice` counts — no conversion needed. That is worth
+* saying out loud, because "fixing" this to use code points is a natural-looking
+* change that would corrupt every post containing an emoji.
+*/
+const expandUrls = (text, raw) => {
+	const entities = isRecord(raw.entities) ? raw.entities : void 0;
+	const spans = (entities && Array.isArray(entities.urls) ? entities.urls : []).filter(isRecord).map((u) => ({
+		start: num(u.start),
+		end: num(u.end),
+		expanded: str(u.expanded_url) ?? str(u.url)
+	})).filter((u) => u.start !== void 0 && u.end !== void 0 && u.expanded !== void 0).toSorted((a, b) => b.start - a.start);
+	let out = text;
+	for (const span of spans) {
+		if (span.start < 0 || span.end > out.length || span.start > span.end) continue;
+		out = out.slice(0, span.start) + span.expanded + out.slice(span.end);
+	}
+	return out;
+};
+const shapeMedia = (raw, index) => {
+	const attachments = isRecord(raw.attachments) ? raw.attachments : void 0;
+	const keys = attachments && Array.isArray(attachments.media_keys) ? attachments.media_keys : [];
+	const items = [];
+	for (const key of keys) {
+		const k = str(key);
+		if (!k) continue;
+		const media = index.media.get(k);
+		if (!media) {
+			items.push(`media (not expanded): ${k}`);
+			continue;
+		}
+		const type = str(media.type) ?? "media";
+		const url = str(media.url) ?? str(media.preview_image_url);
+		const alt = str(media.alt_text);
+		items.push(`${type}${url ? `: ${url}` : ""}${alt ? ` (alt: ${alt})` : ""}`);
+	}
+	return items.length > 0 ? items : void 0;
+};
+const shapeMetrics = (raw) => {
+	const m = isRecord(raw.public_metrics) ? raw.public_metrics : void 0;
+	if (!m) return void 0;
+	const metrics = {
+		likes: num(m.like_count),
+		reposts: num(m.retweet_count),
+		replies: num(m.reply_count),
+		quotes: num(m.quote_count),
+		views: num(m.impression_count)
+	};
+	const entries = Object.entries(metrics).filter(([, v]) => v !== void 0);
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+};
+/**
+* Resolve one referenced post from `includes.tweets`. Deliberately one hop and
+* no recursion: X only sideloads a single level anyway, and a
+* quote-of-a-quote-of-a-quote expanded in place is a context-window bomb for no
+* added meaning.
+*/
+const shapeRef = (id, index) => {
+	const raw = index.tweets.get(id);
+	if (!raw) return { id };
+	const text = str(raw.text);
+	const authorId = str(raw.author_id);
+	return {
+		id,
+		...authorId ? { author: formatAuthor(authorId, index) } : {},
+		...text ? { text: expandUrls(text, raw) } : {},
+		...str(raw.created_at) ? { created_at: str(raw.created_at) } : {}
+	};
+};
+const shapePost = (raw, index) => {
+	const id = str(raw.id) ?? "";
+	const authorId = str(raw.author_id);
+	const refs = Array.isArray(raw.referenced_tweets) ? raw.referenced_tweets.filter(isRecord) : [];
+	const refOf = (type) => {
+		const ref = refs.find((r) => str(r.type) === type);
+		const refId = ref ? str(ref.id) : void 0;
+		return refId ? shapeRef(refId, index) : void 0;
+	};
+	const reposts = refOf("retweeted");
+	const rawText = str(raw.text) ?? "";
+	const text = reposts?.text ? reposts.text : expandUrls(rawText, raw);
+	const metrics = shapeMetrics(raw);
+	const media = shapeMedia(raw, index);
+	const quotes = refOf("quoted");
+	const repliesTo = refOf("replied_to");
+	return {
+		id,
+		url: postUrl(authorId, id, index),
+		author: formatAuthor(authorId, index),
+		...str(raw.created_at) ? { created_at: str(raw.created_at) } : {},
+		text,
+		...str(raw.lang) ? { lang: str(raw.lang) } : {},
+		...metrics ? { metrics } : {},
+		...quotes ? { quotes } : {},
+		...repliesTo ? { replies_to: repliesTo } : {},
+		...reposts ? { reposts } : {},
+		...media ? { media } : {},
+		...str(raw.conversation_id) ? { conversation_id: str(raw.conversation_id) } : {}
+	};
+};
+const shapeUser = (raw) => {
+	const username = str(raw.username) ?? "";
+	const m = isRecord(raw.public_metrics) ? raw.public_metrics : void 0;
+	const metrics = m ? {
+		followers: num(m.followers_count),
+		following: num(m.following_count),
+		posts: num(m.tweet_count),
+		listed: num(m.listed_count)
+	} : void 0;
+	const hasMetrics = metrics && Object.values(metrics).some((v) => v !== void 0);
+	return {
+		id: str(raw.id) ?? "",
+		username,
+		...str(raw.name) ? { name: str(raw.name) } : {},
+		url: `https://x.com/${username}`,
+		...str(raw.description) ? { description: str(raw.description) } : {},
+		...typeof raw.verified === "boolean" ? { verified: raw.verified } : {},
+		...typeof raw.protected === "boolean" ? { protected: raw.protected } : {},
+		...str(raw.location) ? { location: str(raw.location) } : {},
+		...str(raw.created_at) ? { created_at: str(raw.created_at) } : {},
+		...hasMetrics ? { metrics } : {}
+	};
+};
+/**
+* X reports per-id failures in a top-level `errors` array *alongside* a 200, so
+* asking for five posts and getting three back is a success with a footnote.
+* Surfacing the missing ids beats letting the model wonder where they went.
+*/
+const notFoundIds = (response) => {
+	if (!isRecord(response) || !Array.isArray(response.errors)) return void 0;
+	const ids = response.errors.filter(isRecord).map((e) => str(e.value) ?? str(e.resource_id)).filter((v) => v !== void 0);
+	return ids.length > 0 ? ids : void 0;
+};
+/** Flatten a list-of-posts response. Accepts a single- or multi-page envelope. */
+const shapePostsResponse = (response) => {
+	const index = buildIncludesIndex(includesOf(response));
+	const data = isRecord(response) && Array.isArray(response.data) ? response.data : [];
+	const meta = isRecord(response) && isRecord(response.meta) ? response.meta : void 0;
+	const notFound = notFoundIds(response);
+	return {
+		posts: data.filter(isRecord).map((raw) => shapePost(raw, index)),
+		...meta && num(meta.result_count) !== void 0 ? { result_count: num(meta.result_count) } : {},
+		...meta && str(meta.next_token) ? { next_token: str(meta.next_token) } : {},
+		...notFound ? { not_found: notFound } : {}
+	};
+};
+/** Flatten a single-post response. */
+const shapePostResponse = (response) => {
+	const index = buildIncludesIndex(includesOf(response));
+	const data = isRecord(response) && isRecord(response.data) ? response.data : void 0;
+	if (!data) {
+		const notFound = notFoundIds(response);
+		return { error: notFound ? `X returned no post for id ${notFound.join(", ")} — it is deleted, protected, or from a suspended account.` : "X returned no post for that id." };
+	}
+	return shapePost(data, index);
+};
+const shapeUsersResponse = (response) => {
+	const raw = isRecord(response) ? response.data : void 0;
+	const list = Array.isArray(raw) ? raw : isRecord(raw) ? [raw] : [];
+	const notFound = notFoundIds(response);
+	return {
+		users: list.filter(isRecord).map(shapeUser),
+		...notFound ? { not_found: notFound } : {}
+	};
+};
+//#endregion
+//#region src/client/x.ts
+/**
+* Minimal fetch-based client for the X API v2. Paths are absolute (`/2/tweets`).
+* Retries a 401 (invalidating the token first) and 429/5xx with exponential
+* backoff honoring `Retry-After`, and records every response's rate-limit
+* headers so a 429 can say what it is waiting for.
+*/
+var XApiClient = class {
+	baseUrl;
+	tokenProvider;
+	maxRetries;
+	fetchImpl;
+	logger;
+	userAgent;
+	rateLimits = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.baseUrl = (opts.baseUrl ?? "https://api.x.com").replace(/\/+$/, "");
+		this.tokenProvider = opts.tokenProvider;
+		this.maxRetries = opts.maxRetries ?? 3;
+		this.fetchImpl = opts.fetch ?? fetch;
+		this.logger = opts.logger;
+		this.userAgent = opts.userAgent ?? "mcp-x-api-js";
+	}
+	/** Everything the last response said about each endpoint's remaining budget. */
+	rateLimitStatus() {
+		return [...this.rateLimits.values()];
+	}
+	recordRateLimit(method, path, res) {
+		const limit = numberOrUndefined(res.headers.get("x-rate-limit-limit"));
+		const remaining = numberOrUndefined(res.headers.get("x-rate-limit-remaining"));
+		const reset = numberOrUndefined(res.headers.get("x-rate-limit-reset"));
+		if (limit === void 0 && remaining === void 0 && reset === void 0) return;
+		const endpoint = endpointKey(method, path);
+		this.rateLimits.set(endpoint, {
+			endpoint,
+			...limit !== void 0 ? { limit } : {},
+			...remaining !== void 0 ? { remaining } : {},
+			...reset !== void 0 ? {
+				reset,
+				resetAt: (/* @__PURE__ */ new Date(reset * 1e3)).toISOString()
+			} : {}
+		});
+	}
+	async request(method, path, opts = {}) {
+		const url = `${this.baseUrl}${path}${buildQuery(opts.query)}`;
+		const hasBody = opts.body !== void 0;
+		const auth = opts.auth ?? "app";
+		const res = await withRetry(async () => {
+			const token = await this.tokenProvider.getToken(auth);
+			return this.fetchImpl(url, {
+				method,
+				headers: {
+					Accept: "application/json",
+					Authorization: `Bearer ${token}`,
+					"User-Agent": this.userAgent,
+					...hasBody ? { "Content-Type": "application/json" } : {}
+				},
+				...hasBody ? { body: JSON.stringify(opts.body) } : {}
+			});
+		}, {
+			maxRetries: this.maxRetries,
+			label: `${method} ${url}`,
+			logger: this.logger,
+			onUnauthorized: () => this.tokenProvider.invalidate(auth)
+		});
+		this.recordRateLimit(method, path, res);
+		const text = await res.text();
+		if (!res.ok) throw new XApiRequestError(this.errorMessage(res, method, path, text), {
+			status: res.status,
+			errors: this.parseErrors(text)
+		});
+		if (res.status === 204 || text.trim() === "") return null;
+		return safeJsonParse(text);
+	}
+	get(path, query, auth = "app") {
+		return this.request("GET", path, {
+			query,
+			auth
+		});
+	}
+	post(path, body, auth = "user") {
+		return this.request("POST", path, {
+			body,
+			auth
+		});
+	}
+	del(path, auth = "user") {
+		return this.request("DELETE", path, { auth });
+	}
+	/**
+	* GET a collection, following `meta.next_token` until the pages run out or a
+	* bound is hit.
+	*
+	* Both bounds exist because unbounded pagination here spends real money: at
+	* $0.005 a post, walking a busy hashtag to the end is a three-figure mistake
+	* an agent can make in one call. `maxItems` is the one callers actually set.
+	*
+	* X carries the cursor in `meta.next_token` and expects it back as
+	* `pagination_token`, so — unlike a `links.next` API — the original query has
+	* to be re-sent on every page rather than replaced.
+	*/
+	async paginate(path, query, opts) {
+		const maxPages = opts.maxPages ?? 10;
+		const collected = [];
+		const includes = [];
+		let token;
+		let pages = 0;
+		let nextToken;
+		for (;;) {
+			const res = await this.request("GET", path, {
+				query: {
+					...query,
+					...token ? { pagination_token: token } : {}
+				},
+				...opts.auth ? { auth: opts.auth } : {}
+			});
+			pages += 1;
+			if (Array.isArray(res?.data)) collected.push(...res.data);
+			if (res?.includes) includes.push(res.includes);
+			const next = res?.meta?.next_token;
+			token = typeof next === "string" && next ? next : void 0;
+			nextToken = token;
+			if (!token || collected.length >= opts.maxItems || pages >= maxPages) break;
+		}
+		return {
+			data: collected.slice(0, opts.maxItems),
+			pages,
+			...nextToken ? { nextToken } : {},
+			includes
+		};
+	}
+	parseErrors(text) {
+		const parsed = safeJsonParse(text);
+		if (parsed && typeof parsed === "object" && "errors" in parsed) return parsed.errors;
+		return parsed;
+	}
+	/**
+	* The three statuses that actually happen get a sentence naming the fix. A
+	* bare "HTTP 403" sends people to the wrong place — usually to re-check a
+	* token that was fine, when the real answer is that their access tier does
+	* not include the endpoint.
+	*/
+	errorMessage(res, method, path, text) {
+		const base = `X API ${method} ${path} failed: HTTP ${res.status} ${res.statusText}`.trim();
+		const parsed = this.parseErrors(text);
+		const detail = Array.isArray(parsed) ? parsed.map((e) => [e.title, e.detail ?? e.message].filter(Boolean).join(" — ")).filter(Boolean).join("; ") : this.problemDetail(parsed);
+		if (res.status === 401) return `${base} — the token was rejected. Check X_API_BEARER_TOKEN, or re-run \`x-api-mcp login\` if this call needed a user context` + (detail ? ` (${detail})` : "");
+		if (res.status === 403) return `${base} — authenticated, but the request was refused. Most often this means the app is not enrolled: at console.x.com open the app, and make sure it is in the Pay-per-use package and the Production environment (a "client-not-enrolled" or "client-forbidden" detail below confirms this). Otherwise, your access tier or this token's scopes do not cover the endpoint — full-archive search needs a paid tier, bookmarks need bookmark.read` + (detail ? ` (${detail})` : "");
+		if (res.status === 429) {
+			const snapshot = this.rateLimits.get(endpointKey(method, path));
+			return `${base} — rate limited${snapshot ? ` (${snapshot.remaining ?? 0}/${snapshot.limit ?? "?"} remaining` + (snapshot.resetAt ? `, resets ${snapshot.resetAt}` : "") + `)` : ""}. Wait for the window to reset, or lower maxResults.`;
+		}
+		return base + (detail ? ` — ${detail}` : "");
+	}
+	problemDetail(parsed) {
+		if (!parsed || typeof parsed !== "object") return "";
+		const p = parsed;
+		return [p.title, p.detail].filter(Boolean).join(" — ");
+	}
+};
+//#endregion
+//#region src/compose/weighted.ts
+/** Code point ranges that weigh 100 (i.e. one character). Everything else is 200. */
+const LIGHT_RANGES = [
+	[0, 4351],
+	[8192, 8205],
+	[8208, 8223],
+	[8242, 8247]
+];
+const DEFAULT_WEIGHT = 200;
+const SCALE = 100;
+const MAX_WEIGHTED_LENGTH = 280;
+/**
+* Every URL costs the same whatever its real length: X rewrites it to t.co.
+* There is a single value now — the old http/https split was deprecated once
+* every t.co link became https.
+*/
+const TCO_URL_LENGTH = 23;
+/**
+* Conservative URL detection. Scheme-ful URLs plus bare `domain.tld/path` for
+* the TLDs people actually paste. Deliberately narrow: over-matching would
+* silently under-count a draft (charging 23 for something X treats as plain
+* text), and a draft rejected at the composer is worse than one that looks a
+* few characters longer than it is.
+*/
+const URL_PATTERN = /\bhttps?:\/\/[^\s<>"']+|\b(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+(?:com|org|net|io|dev|co|ai|app|xyz|me|gg|so|sh|to|tv|fr|uk|de|jp)\b(?:\/[^\s<>"']*)?/gi;
+const isLight = (codePoint) => LIGHT_RANGES.some(([start, end]) => codePoint >= start && codePoint <= end);
+const EMOJI = /\p{Extended_Pictographic}/u;
+const segmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+/** Weight one grapheme cluster in twitter-text's internal units. */
+const clusterWeight = (cluster) => {
+	const first = cluster.codePointAt(0);
+	if (first === void 0) return 0;
+	if (EMOJI.test(cluster) || [...cluster].length > 1) return DEFAULT_WEIGHT;
+	return isLight(first) ? SCALE : DEFAULT_WEIGHT;
+};
+/**
+* Count a draft the way X will.
+*
+* NFC normalization comes first because twitter-text normalizes first: without
+* it a decomposed "café" counts 5 instead of 4, and the user is told they have
+* one character less than they do.
+*/
+const weightedLength = (text) => {
+	const normalized = text.normalize("NFC");
+	const urls = [];
+	const spans = [];
+	for (const match of normalized.matchAll(URL_PATTERN)) {
+		if (match.index === void 0) continue;
+		urls.push({
+			url: match[0],
+			countedAs: 23
+		});
+		spans.push([match.index, match.index + match[0].length]);
+	}
+	let total = urls.length * 23 * SCALE;
+	let index = 0;
+	let spanIndex = 0;
+	while (index < normalized.length) {
+		const span = spans[spanIndex];
+		if (span && index === span[0]) {
+			index = span[1];
+			spanIndex += 1;
+			continue;
+		}
+		const nextStart = span ? span[0] : normalized.length;
+		const chunk = normalized.slice(index, nextStart);
+		for (const { segment } of segmenter.segment(chunk)) total += clusterWeight(segment);
+		index = nextStart;
+	}
+	const weighted = Math.ceil(total / SCALE);
+	return {
+		weighted,
+		remaining: 280 - weighted,
+		valid: weighted > 0 && weighted <= 280,
+		urls
+	};
+};
+//#endregion
+//#region src/compose/intent.ts
+/**
+* X's web intent: a documented, credential-free URL that opens the composer
+* pre-filled. Nothing is posted until a human clicks Post, which is why it
+* needs no auth, consumes no API quota and costs nothing.
+*
+* The path is `/intent/tweet`, not `/intent/post`. X renamed Tweet to Post
+* throughout its docs prose but never changed the URL, and `/intent/post` is
+* undocumented with known edge-case bugs. `twitter.com` 301s to `x.com`, so
+* there is no reason to emit the legacy domain.
+*/
+const INTENT_BASE_URL = "https://x.com/intent/tweet";
+const stripLeading = (value, char) => value.startsWith(char) ? value.slice(1) : value;
+/**
+* What the composer will actually contain, in X's documented assembly order:
+* text, then url, then hashtags, then "via @handle".
+*
+* Validating `text` alone and then handing back a URL the composer rejects is
+* exactly the bug this module exists to prevent, so counting happens on this
+* string rather than on the input.
+*/
+const assembleComposerText = (input) => {
+	const parts = [input.text.trim()];
+	if (input.url) parts.push(input.url);
+	for (const tag of input.hashtags ?? []) {
+		const clean = stripLeading(tag.trim(), "#");
+		if (clean) parts.push(`#${clean}`);
+	}
+	if (input.via) parts.push(`via @${stripLeading(input.via.trim(), "@")}`);
+	return parts.filter(Boolean).join(" ");
+};
+const buildIntentUrl = (input) => {
+	const params = new URLSearchParams();
+	if (input.text) params.set("text", input.text);
+	if (input.url) params.set("url", input.url);
+	const hashtags = (input.hashtags ?? []).map((t) => stripLeading(t.trim(), "#")).filter(Boolean);
+	if (hashtags.length > 0) params.set("hashtags", hashtags.join(","));
+	if (input.via) params.set("via", stripLeading(input.via.trim(), "@"));
+	if (input.inReplyTo) params.set("in_reply_to", input.inReplyTo);
+	if (input.lang) params.set("lang", input.lang);
+	return `${INTENT_BASE_URL}?${params.toString()}`;
+};
+const validateIntent = (input) => {
+	const composed = assembleComposerText(input);
+	const { weighted, remaining, valid, urls } = weightedLength(composed);
+	const warnings = [];
+	if (urls.length > 0) warnings.push(`${urls.length} URL${urls.length > 1 ? "s" : ""} counted as ${urls.length * 23} characters (X rewrites every link to a fixed-length t.co URL, whatever its real length).`);
+	if ((input.hashtags?.length ?? 0) > 4) warnings.push("More than four hashtags reads as spam and tends to suppress reach.");
+	if (input.via?.trim().startsWith("@")) warnings.push("Stripped the leading '@' from `via` — X expects a bare handle.");
+	if (input.inReplyTo && !/^\d+$/.test(input.inReplyTo)) warnings.push(`inReplyTo "${input.inReplyTo}" is not a post id. Ids are digits only — the trailing number in a post's URL.`);
+	return {
+		valid,
+		weighted,
+		remaining,
+		composed,
+		intent_url: buildIntentUrl(input),
+		warnings,
+		...valid ? {} : { error: weighted === 0 ? "The post is empty." : `The assembled post is ${weighted} weighted characters, ${-remaining} over X's 280 limit. Note that the url, hashtags and via parts all count.` }
+	};
+};
+//#endregion
+//#region src/compose/open.ts
+/** Only ever X. This must not become a generic "open whatever the model asked for". */
+const ALLOWED_ORIGINS = /* @__PURE__ */ new Set(["https://x.com", "https://twitter.com"]);
+const isHeadless = () => {
+	if (existsSync("/.dockerenv")) return true;
+	if (process.platform === "linux" && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) return true;
+	return false;
+};
+const command = (url) => {
+	switch (process.platform) {
+		case "darwin": return {
+			file: "open",
+			args: [url]
+		};
+		case "win32": return {
+			file: "cmd",
+			args: [
+				"/c",
+				"start",
+				"",
+				url
+			]
+		};
+		default: return {
+			file: "xdg-open",
+			args: [url]
+		};
+	}
+};
+/**
+* Best effort, and deliberately non-throwing: the intent URL is the deliverable,
+* and Docker, SSH and headless CI are all normal places to run this server.
+* Callers always return the URL regardless of what this says.
+*/
+const openInBrowser = async (url) => {
+	let origin;
+	try {
+		origin = new URL(url).origin;
+	} catch {
+		return {
+			opened: false,
+			reason: "not a valid URL"
+		};
+	}
+	if (!ALLOWED_ORIGINS.has(origin)) return {
+		opened: false,
+		reason: `refusing to open a non-X origin (${origin})`
+	};
+	if (isHeadless()) return {
+		opened: false,
+		reason: "headless environment — open the URL yourself"
+	};
+	const { file, args } = command(url);
+	return new Promise((resolve) => {
+		execFile(file, args, { timeout: 5e3 }, (err) => {
+			resolve(err ? {
+				opened: false,
+				reason: `${file} failed: ${err.message}`
+			} : { opened: true });
+		});
+	});
+};
+//#endregion
+//#region src/tools/ads/util.ts
+/**
+* Ads calls are not metered by X's pay-per-use rates, so they carry a fixed
+* note rather than a ledger entry. Saying it on every result is deliberate: the
+* absence of a cost line would otherwise read as "not measured", and the real
+* point is that the tool is free while the campaigns it manages are not.
+*/
+const adsCostNote = () => ({
+	estimated_usd: 0,
+	note: "Ads API calls are not billed under X's pay-per-use read pricing, so this costs nothing and does not appear in x_usage_report. The campaigns it manages spend your advertising budget."
+});
+const accountIdArg = z.string().min(1).regex(/^[A-Za-z0-9]+$/, "An ads account id is letters and digits, e.g. \"18ce54d4x5t\".").optional().describe("The ads account to act on, e.g. \"18ce54d4x5t\". Omit it when you have exactly one account or X_ADS_ACCOUNT_ID is set — it is resolved automatically. List them with x_ads_get_accounts.");
+const entityIdArg = z.string().min(1).regex(/^[A-Za-z0-9]+$/).describe("An ads entity id, e.g. a campaign or line item id like \"8v7jo\".");
+const adsCountArg = z.number().int().min(1).max(1e3).default(200).describe("How many records to return (1-1000). X's own default is 200.");
+const adsConfirmArg = z.literal(true).describe("Must be true. Explicit acknowledgement that this changes a live advertising campaign and can spend your advertising budget.");
+const activateArg = z.boolean().default(false).describe("Create this ACTIVE instead of PAUSED. Defaults to false, which is the safe path: a PAUSED entity spends nothing until you activate it with x_ads_set_entity_status. Set true only when you intend spending to start the moment this call returns.");
+/**
+* Budgets are taken in major units and converted here, so a caller never sees a
+* `*_micro` field on the way in. A factor of a million is not a mistake anyone
+* catches by reading a number back, so the safest design is one where it cannot
+* be expressed.
+*/
+const budgetArg = z.number().positive().max(1e4).describe("Budget in MAJOR units of the funding instrument's currency — 50 means 50.00, not 50 million. Do NOT multiply by 1,000,000; this server converts to X's *_amount_local_micro field for you. Capped at 10,000 per call.");
+/** ISO-8601, which the Ads API requires at whole-hour boundaries. */
+const adsTimeArg = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:00:00Z$/, "X requires whole hours in ISO-8601 UTC, e.g. \"2026-08-01T00:00:00Z\".").describe("An ISO-8601 UTC time on a whole hour, e.g. \"2026-08-01T00:00:00Z\".");
+/** Shape one ads entity or list for a tool result. */
+const shapeAds = (raw, currency) => shapeMoney(adsData(raw) ?? raw, currency);
+/**
+* Resolve which ads account a call is about.
+*
+* Mirrors `resolveOwnUserId` for timelines: prefer what the caller said, fall
+* back to configuration, and only then ask X — caching the answer so it happens
+* at most once per process. Unlike that case there is no token file to persist
+* into, so the memo lives in the closure and dies with the process, which is
+* fine for something that costs one request.
+*
+* The multi-account branch deliberately refuses rather than guessing. Agency
+* users hit it immediately, and silently picking the first account would create
+* campaigns in the wrong client's account — a mistake that spends real money
+* and is not obvious from the response.
+*/
+const createAccountResolver = (client, ads) => {
+	let memo;
+	return async (explicit) => {
+		if (explicit) return explicit;
+		if (ads.accountId) return ads.accountId;
+		if (memo) return memo;
+		const raw = await client.get("/12/accounts", { count: 50 });
+		const list = isRecord$1(raw) && Array.isArray(raw.data) ? raw.data : [];
+		if (list.length === 0) throw new AdsAccessError("The logged-in account has access to no ads accounts, so there is nothing to act on. Either this X user has not been granted a role on an ads account (that is done in ads.x.com, not the developer console), or the app is not approved for the Ads API yet. Check x_auth_status for the setup steps." + (ads.sandbox ? " In the sandbox, call x_ads_create_sandbox_account to make one." : ""), {
+			baseUrl: ads.baseUrl,
+			sandbox: ads.sandbox
+		});
+		if (list.length > 1) {
+			const accounts = list.filter(isRecord$1).map((a) => ({
+				id: a.id,
+				name: a.name
+			}));
+			throw new PreconditionError(`This login can reach ${list.length} ads accounts, so there is no safe default. Pass accountId explicitly, or set X_ADS_ACCOUNT_ID.`, { accounts });
+		}
+		const only = list[0];
+		const id = isRecord$1(only) && typeof only.id === "string" ? only.id : void 0;
+		if (!id) throw new AdsAccessError("X returned an ads account with no id, so it cannot be addressed.", { received: only });
+		memo = id;
+		return id;
+	};
+};
+//#endregion
+//#region src/tools/util.ts
+const ok = (data) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(data ?? { ok: true }, null, 2)
+}] });
+const fail = (message, extra) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extra ? { details: extra } : {}
+		}, null, 2)
+	}],
+	isError: true
+});
+/** Render a thrown value as a tool error, preserving X's own detail. */
+const toFailure = (err) => {
+	if (err instanceof XApiRequestError) return fail(err.message, {
+		status: err.status,
+		errors: err.errors
+	});
+	if (err instanceof BudgetExceededError || err instanceof PreconditionError) return fail(err.message, err.details);
+	if (err instanceof UserContextRequiredError || err instanceof WritesDisabledError) return fail(err.message);
+	if (err instanceof Error) {
+		const details = err.details;
+		return fail(err.message, details);
+	}
+	return fail("Unknown error", err);
+};
+/** Run a tool body, JSON-formatting the result and turning errors into a tool error. */
+const wrap = async (fn) => {
+	try {
+		return ok(await fn());
+	} catch (err) {
+		return toFailure(err);
+	}
+};
+/**
+* Every read tool takes this. `maxResults` defaults low and says why in its
+* own description — an agent that reads the schema learns the cost model
+* without anyone having to document it elsewhere.
+*/
+const maxResultsArg = z.number().int().min(1).max(100).default(10).describe("How many results to return (1-100). Defaults to 10 because X bills about $0.005 per post read, so 100 results costs roughly $0.50. Raise it deliberately.");
+const postIdArg = z.string().regex(/^\d+$/, "A post id is digits only — the number at the end of a post's URL.").describe("A post (tweet) id: the digits ending its URL, e.g. \"1799000000000000001\".");
+const usernameArg = z.string().regex(/^@?[A-Za-z0-9_]{1,15}$/, "An X handle is 1-15 characters of letters, digits or _.").describe("An X handle, with or without the leading @, e.g. \"mgcrea\".");
+const userIdArg = z.string().regex(/^\d+$/).describe("A numeric X user id, e.g. \"44196397\". Prefer `username` unless you already have one.");
+const paginationTokenArg = z.string().min(1).optional().describe("The `next_token` from a previous call, to fetch the following page.");
+const confirmArg = z.literal(true).describe("Must be true. Explicit acknowledgement that this posts to X and costs money.");
+/** Drop undefined values so we never send `{"tweet.fields": undefined}` upstream. */
+const compact = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+const stripAt = (handle) => handle.startsWith("@") ? handle.slice(1) : handle;
+/**
+* The expansions and field sets every post read asks for. Kept in one place
+* because the shaping layer's output is only as good as what was requested —
+* omitting `author_id` here silently degrades every post to "@unknown".
+*/
+const POST_QUERY = {
+	expansions: [
+		"author_id",
+		"referenced_tweets.id",
+		"referenced_tweets.id.author_id",
+		"attachments.media_keys"
+	],
+	"tweet.fields": [
+		"created_at",
+		"public_metrics",
+		"entities",
+		"conversation_id",
+		"lang",
+		"referenced_tweets"
+	],
+	"user.fields": [
+		"username",
+		"name",
+		"verified"
+	],
+	"media.fields": [
+		"type",
+		"url",
+		"preview_image_url",
+		"alt_text"
+	]
+};
+const USER_QUERY = { "user.fields": [
+	"description",
+	"public_metrics",
+	"verified",
+	"created_at",
+	"location",
+	"protected"
+] };
+/**
+* Guard a read against the configured budget *before* issuing it, so a runaway
+* agent cannot discover the ceiling by crossing it.
+*/
+const assertWithinBudget = (deps, what, estimateUsd) => {
+	if (deps.budgetUsd === void 0) return;
+	const spent = deps.ledger.spentUsd();
+	if (spent + estimateUsd > deps.budgetUsd) throw new BudgetExceededError({
+		estimateUsd,
+		spentUsd: spent,
+		limitUsd: deps.budgetUsd,
+		what
+	});
+};
+/**
+* Serve whatever today's cache already holds and fetch only the rest.
+*
+* This mirrors X's own billing rule rather than merely optimizing: within one
+* UTC day the cached ids would not have been billed again anyway, so a hit is
+* genuinely free rather than just fast.
+*/
+const cachedByIds = async (deps, kind, ids, fetchMissing, label) => {
+	const cached = /* @__PURE__ */ new Map();
+	const missing = [];
+	for (const id of ids) {
+		const hit = deps.cache.get(kind, id);
+		if (hit !== void 0) cached.set(id, hit);
+		else missing.push(id);
+	}
+	if (missing.length > 0) {
+		assertWithinBudget(deps, label, deps.ledger.estimate(kind, missing));
+		const fetched = await fetchMissing(missing);
+		for (const [id, item] of fetched) {
+			deps.cache.set(kind, id, item);
+			cached.set(id, item);
+		}
+		deps.ledger.record(kind, [...fetched.keys()]);
+	}
+	const items = [];
+	const notFound = [];
+	for (const id of ids) {
+		const item = cached.get(id);
+		if (item !== void 0) items.push(item);
+		else notFound.push(id);
+	}
+	const billable = missing.filter((id) => cached.has(id)).length;
+	const free = ids.length - missing.length;
+	return {
+		items,
+		cost: buildCostNote(kind, billable, free, deps),
+		notFound
+	};
+};
+const buildCostNote = (kind, billable, free, deps) => {
+	const usd = deps.ledger.estimateCount(kind, billable);
+	return {
+		[kind === "post" ? "billable_post_reads" : kind === "user" ? "billable_user_reads" : "owned_reads"]: billable,
+		free_from_cache: free,
+		estimated_usd: Math.round(usd * 1e3) / 1e3,
+		...free > 0 ? { note: `${free} already read today — X does not bill those again until UTC midnight.` } : {}
+	};
+};
+/** Record the cost of a read whose ids were only known after the fact (searches). */
+const recordResultCost = (deps, kind, ids) => {
+	const { billable, free } = deps.ledger.record(kind, ids);
+	return buildCostNote(kind, billable.length, free.length, deps);
+};
+//#endregion
+//#region src/tools/ads/accounts.ts
+const registerAdsAccountTools = (server, client, ads, resolveAccount) => {
+	server.registerTool("x_ads_get_accounts", {
+		title: "X: Ads Get Accounts",
+		description: "List the advertising accounts this login can reach, with their name, currency, timezone and approval status. Start here: every other ads tool needs an account id, and the currency and timezone returned here decide how budgets and analytics dates are read.",
+		inputSchema: z.object({
+			count: adsCountArg,
+			withDeleted: z.boolean().default(false).describe("Include deleted accounts. Off by default.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ count, withDeleted }) => wrap(async () => {
+		const page = await client.paginateCursor("/12/accounts", {
+			count,
+			...withDeleted ? { with_deleted: true } : {}
+		}, { maxItems: count });
+		return {
+			accounts: page.data,
+			environment: ads.sandbox ? "sandbox" : "production",
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_get_funding_instruments", {
+		title: "X: Ads Get Funding Instruments",
+		description: "List an account's funding instruments — the payment sources campaigns draw from. A campaign cannot be created without one, and the instrument's `currency` is the currency every budget on that campaign is stated in. Check `able_to_fund` before using one.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			count: adsCountArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, count }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const page = await client.paginateCursor(`/12/accounts/${id}/funding_instruments`, { count }, { maxItems: count });
+		return {
+			account_id: id,
+			funding_instruments: shapeAds({ data: page.data }),
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+	if (!ads.sandbox) return;
+	server.registerTool("x_ads_create_sandbox_account", {
+		title: "X: Ads Create Sandbox Account",
+		description: "Create a throwaway ads account in the sandbox, complete with a funding instrument, so the campaign tools can be exercised without spending anything. Sandbox only — this tool is not registered against production.",
+		inputSchema: z.object({}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async () => wrap(async () => {
+		const created = await client.post("/12/accounts");
+		const data = isRecord$1(created) ? created.data : void 0;
+		const id = isRecord$1(data) && typeof data.id === "string" ? data.id : void 0;
+		return {
+			account: data,
+			...id ? { next_step: `Pass accountId: "${id}" to the other ads tools, or set X_ADS_ACCOUNT_ID to it. Call x_ads_get_funding_instruments to find the funding instrument id you will need to create a campaign.` } : {},
+			cost: adsCostNote()
+		};
+	}));
+};
+//#endregion
+//#region src/tools/ads/analytics.ts
+const ENTITIES = [
+	"ACCOUNT",
+	"CAMPAIGN",
+	"FUNDING_INSTRUMENT",
+	"LINE_ITEM",
+	"PROMOTED_ACCOUNT",
+	"PROMOTED_TWEET"
+];
+const METRIC_GROUPS = [
+	"ENGAGEMENT",
+	"BILLING",
+	"VIDEO",
+	"MEDIA",
+	"WEB_CONVERSION",
+	"MOBILE_CONVERSION",
+	"LIFE_TIME_VALUE_MOBILE_CONVERSION"
+];
+/**
+* The synchronous endpoint accepts only these three. `PUBLISHER_NETWORK` is a
+* valid line-item placement but not a valid analytics placement, and passing it
+* here is rejected — worth pinning in the schema rather than discovering at
+* runtime.
+*/
+const PLACEMENTS$1 = [
+	"ALL_ON_TWITTER",
+	"SPOTLIGHT",
+	"TREND"
+];
+const SEGMENTATIONS = [
+	"AGE",
+	"GENDER",
+	"METROS",
+	"PLATFORMS",
+	"CONVERSION_TAGS"
+];
+const HOUR = 3600 * 1e3;
+const SYNC_MAX_DAYS = 7;
+const SYNC_MAX_ENTITIES = 20;
+/** X answers job ids as JSON numbers too large for a JS number to hold exactly. */
+const jobIdOf = (job) => {
+	if (typeof job.id_str === "string" && job.id_str) return job.id_str;
+	if (typeof job.id === "string" && job.id) return job.id;
+};
+const registerAdsAnalyticsTools = (server, client, resolveAccount) => {
+	server.registerTool("x_ads_get_stats", {
+		title: "X: Ads Get Stats",
+		description: "Performance metrics for up to 20 entities over at most 7 days, returned immediately. This is the fast path — use it for \"how did this campaign do last week\". For longer ranges, segmentation, or more than 20 entities, use the async job tools instead. Times must be whole hours, and endTime is exclusive.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			entity: z.enum(ENTITIES).describe("What kind of thing the ids refer to."),
+			entityIds: z.array(entityIdArg).min(1).max(SYNC_MAX_ENTITIES).describe(`The entities to report on. X allows at most ${SYNC_MAX_ENTITIES} per call.`),
+			startTime: adsTimeArg.describe("Start of the window, ISO-8601 UTC on a whole hour."),
+			endTime: adsTimeArg.describe("End of the window, exclusive. At most 7 days after start."),
+			granularity: z.enum([
+				"DAY",
+				"HOUR",
+				"TOTAL"
+			]).default("DAY").describe("How finely to bucket. DAY and TOTAL expect startTime at midnight in the ACCOUNT's timezone, which is not necessarily UTC — check it with x_ads_get_accounts."),
+			placement: z.enum(PLACEMENTS$1).default("ALL_ON_TWITTER").describe("One placement per call. PUBLISHER_NETWORK is not valid here."),
+			metricGroups: z.array(z.enum(METRIC_GROUPS)).min(1).default(["ENGAGEMENT"]).describe("Which metric families to return. BILLING carries spend.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, entity, entityIds, startTime, endTime, granularity, placement, metricGroups }) => wrap(async () => {
+		const span = Date.parse(endTime) - Date.parse(startTime);
+		if (span <= 0) throw new PreconditionError("endTime must be after startTime.", {
+			startTime,
+			endTime
+		});
+		if (span > SYNC_MAX_DAYS * 24 * HOUR) throw new PreconditionError(`The synchronous stats endpoint covers at most ${SYNC_MAX_DAYS} days, and this asks for ${Math.round(span / (24 * HOUR))}. Narrow the window, or use x_ads_create_stats_job, which reaches 90 days.`, {
+			startTime,
+			endTime,
+			maxDays: SYNC_MAX_DAYS
+		});
+		const id = await resolveAccount(accountId);
+		const raw = await client.get(`/12/stats/accounts/${id}`, {
+			entity,
+			entity_ids: entityIds,
+			start_time: startTime,
+			end_time: endTime,
+			granularity,
+			placement,
+			metric_groups: metricGroups
+		});
+		return {
+			account_id: id,
+			entity,
+			granularity,
+			placement,
+			start_time: startTime,
+			end_time: endTime,
+			stats: isRecord$1(raw) ? raw.data : raw,
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_create_stats_job", {
+		title: "X: Ads Create Stats Job",
+		description: "Queue an asynchronous analytics job, for what the synchronous endpoint cannot do: up to 90 days (45 when segmented), segmentation by age, gender, platform or metro, and more than 20 entities. Returns a job id — poll it with x_ads_get_stats_jobs until its status is SUCCESS, then fetch the numbers with x_ads_download_stats_job. Queuing a job spends nothing and changes nothing.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			entity: z.enum(ENTITIES).describe("What kind of thing the ids refer to."),
+			entityIds: z.array(entityIdArg).min(1).max(200).describe("The entities to report on."),
+			startTime: adsTimeArg.describe("Start of the window, ISO-8601 UTC on a whole hour."),
+			endTime: adsTimeArg.describe("End of the window, exclusive."),
+			granularity: z.enum([
+				"DAY",
+				"HOUR",
+				"TOTAL"
+			]).default("DAY").describe("Bucket size."),
+			placement: z.enum(PLACEMENTS$1).default("ALL_ON_TWITTER").describe("One placement per job."),
+			metricGroups: z.array(z.enum(METRIC_GROUPS)).min(1).default(["ENGAGEMENT"]).describe("Which metric families to return."),
+			segmentation: z.enum(SEGMENTATIONS).optional().describe("Break the numbers down by this dimension. Segmented jobs are capped at 45 days. METROS additionally needs `country`."),
+			country: z.string().optional().describe("Targeting-value id of a country. Required when segmentation is METROS.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async (args) => wrap(async () => {
+		if (args.segmentation === "METROS" && !args.country) throw new PreconditionError("Segmenting by METROS needs a `country`. Find its id with x_ads_search_targeting_options type=locations, locationType=COUNTRIES.");
+		const id = await resolveAccount(args.accountId);
+		const raw = await client.post(`/12/stats/jobs/accounts/${id}`, compact({
+			entity: args.entity,
+			entity_ids: args.entityIds,
+			start_time: args.startTime,
+			end_time: args.endTime,
+			granularity: args.granularity,
+			placement: args.placement,
+			metric_groups: args.metricGroups,
+			segmentation_type: args.segmentation,
+			country: args.country
+		}));
+		const job = isRecord$1(raw) && isRecord$1(raw.data) ? raw.data : {};
+		return {
+			account_id: id,
+			job,
+			job_id: jobIdOf(job),
+			next_step: "Poll x_ads_get_stats_jobs until this job's status is SUCCESS, then call x_ads_download_stats_job with its url. Jobs typically take seconds to minutes.",
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_get_stats_jobs", {
+		title: "X: Ads Get Stats Jobs",
+		description: "List this account's analytics jobs and their status. A job is ready when its status is SUCCESS, at which point it carries a `url` to pass to x_ads_download_stats_job. Those URLs expire, so re-read the job rather than reusing an old one.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			jobIds: z.array(z.string().min(1)).max(200).optional().describe("Only these job ids. Omit to list recent jobs."),
+			count: z.number().int().min(1).max(200).default(50).describe("How many jobs to return.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, jobIds, count }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const raw = await client.get(`/12/stats/jobs/accounts/${id}`, compact({
+			count,
+			...jobIds?.length ? { job_ids: jobIds } : {}
+		}));
+		const jobs = isRecord$1(raw) && Array.isArray(raw.data) ? raw.data : [];
+		const ready = jobs.filter(isRecord$1).filter((j) => j.status === "SUCCESS").length;
+		return {
+			account_id: id,
+			jobs,
+			ready_count: ready,
+			...jobs.length > 0 && ready === 0 ? { note: "No job has finished yet. Poll again in a few seconds." } : {},
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_download_stats_job", {
+		title: "X: Ads Download Stats Job",
+		description: "Fetch and decompress a finished analytics job's results. By default it returns a per-entity summary rather than every row, because a segmented 90-day job is far larger than a useful answer. Set raw to true for the underlying rows, bounded by maxRows. If the download is refused as too large, re-run the job over fewer entities, a shorter range, or a coarser granularity.",
+		inputSchema: z.object({
+			url: z.string().url().describe("The `url` from a SUCCESS job in x_ads_get_stats_jobs. These expire."),
+			raw: z.boolean().default(false).describe("Return the underlying rows instead of the summary."),
+			maxRows: z.number().int().min(1).max(2e3).default(200).describe("Cap on rows returned when raw is true.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ url, raw, maxRows }) => wrap(async () => {
+		const { text, bytes } = await client.downloadGzipped(url);
+		const parsed = JSON.parse(text);
+		const rows = isRecord$1(parsed) && Array.isArray(parsed.data) ? parsed.data : [];
+		if (raw) return {
+			rows: rows.slice(0, maxRows),
+			row_count: rows.length,
+			truncated: rows.length > maxRows,
+			decompressed_bytes: bytes,
+			cost: adsCostNote()
+		};
+		return {
+			entities: rows.filter(isRecord$1).map((row) => {
+				const series = Array.isArray(row.id_data) ? row.id_data : [];
+				const totals = {};
+				for (const segment of series) {
+					if (!isRecord$1(segment) || !isRecord$1(segment.metrics)) continue;
+					for (const [metric, values] of Object.entries(segment.metrics)) {
+						if (!Array.isArray(values)) continue;
+						const sum = values.reduce((acc, v) => acc + (typeof v === "number" ? v : 0), 0);
+						totals[metric] = (totals[metric] ?? 0) + sum;
+					}
+				}
+				return {
+					id: row.id,
+					segments: series.length,
+					totals
+				};
+			}),
+			row_count: rows.length,
+			decompressed_bytes: bytes,
+			note: "Totals are summed across every bucket and segment in the job. Pass raw: true for the per-bucket rows.",
+			cost: adsCostNote()
+		};
+	}));
+};
+//#endregion
+//#region src/tools/ads/audiences.ts
+const registerAdsAudienceTools = (server, client, resolveAccount) => {
+	server.registerTool("x_ads_get_audiences", {
+		title: "X: Ads Get Audiences",
+		description: "List an account's custom audiences with their size and targetability. Use an audience's id as the targetingValue of a CUSTOM_AUDIENCE criterion. Read-only: uploading audience members means handling personal data and is deliberately not exposed here. Note that \"tailored audiences\" is the old name for these and its endpoints are long gone.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			count: adsCountArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, count }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const page = await client.paginateCursor(`/12/accounts/${id}/custom_audiences`, { count }, { maxItems: count });
+		return {
+			account_id: id,
+			audiences: shapeAds({ data: page.data }),
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+};
+//#endregion
+//#region src/tools/ads/campaigns.ts
+/** Line-item enums, verbatim from the v12 reference. */
+const OBJECTIVES = [
+	"APP_ENGAGEMENTS",
+	"APP_INSTALLS",
+	"REACH",
+	"FOLLOWERS",
+	"ENGAGEMENTS",
+	"VIDEO_VIEWS",
+	"PREROLL_VIEWS",
+	"WEBSITE_CLICKS"
+];
+const PRODUCT_TYPES = [
+	"MEDIA",
+	"PROMOTED_ACCOUNT",
+	"PROMOTED_TWEETS"
+];
+const PLACEMENTS = [
+	"ALL_ON_TWITTER",
+	"PUBLISHER_NETWORK",
+	"TAP_BANNER",
+	"TAP_FULL",
+	"TAP_FULL_LANDSCAPE",
+	"TAP_NATIVE",
+	"TAP_MRECT",
+	"TWITTER_PROFILE",
+	"TWITTER_REPLIES",
+	"TWITTER_SEARCH",
+	"TWITTER_TIMELINE"
+];
+const PATH_FOR = {
+	campaign: "campaigns",
+	line_item: "line_items",
+	promoted_tweet: "promoted_tweets"
+};
+/**
+* What a create tool sends for `entity_status`, and the sentence explaining it.
+* PAUSED is the default because an ACTIVE campaign begins spending the moment
+* it exists, and an agent that mis-set a budget should not discover that from
+* the invoice. `activateImmediately` is the deliberate way out.
+*/
+const statusFor = (activate) => activate ? {
+	status: "ACTIVE",
+	note: "Created ACTIVE, as requested — delivery and spending start now."
+} : {
+	status: "PAUSED",
+	note: "Created PAUSED, so it is spending nothing. Activate it with x_ads_set_entity_status when you are ready."
+};
+const registerAdsCampaignTools = (server, client, ads, resolveAccount) => {
+	/** The currency every budget on a campaign is denominated in. */
+	const currencyOf = async (accountId, fundingInstrumentId) => {
+		try {
+			const raw = await client.get(`/12/accounts/${accountId}/funding_instruments/${fundingInstrumentId}`);
+			const data = isRecord$1(raw) ? raw.data : void 0;
+			return isRecord$1(data) && typeof data.currency === "string" ? data.currency : void 0;
+		} catch {
+			return;
+		}
+	};
+	server.registerTool("x_ads_get_campaigns", {
+		title: "X: Ads Get Campaigns",
+		description: "List an account's campaigns with their budgets, funding instrument and status. Budgets come back in both major units (`daily_budget`) and X's raw millionths (`daily_budget_amount_local_micro`) — read the former. Note that in v12 campaigns carry no start or end date; flight dates live on their line items.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			campaignIds: z.array(entityIdArg).max(200).optional().describe("Only these campaign ids. Omit to list them all."),
+			count: adsCountArg,
+			withDeleted: z.boolean().default(false).describe("Include deleted campaigns.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, campaignIds, count, withDeleted }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const page = await client.paginateCursor(`/12/accounts/${id}/campaigns`, compact({
+			count,
+			...campaignIds?.length ? { campaign_ids: campaignIds } : {},
+			...withDeleted ? { with_deleted: true } : {}
+		}), { maxItems: count });
+		return {
+			account_id: id,
+			campaigns: shapeAds({ data: page.data }),
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_get_line_items", {
+		title: "X: Ads Get Line Items",
+		description: "List an account's line items — the ad groups that carry the objective, bid, placements and flight dates under a campaign. Targeting and creatives attach to a line item, not to its campaign, so this is the id you need for x_ads_get_targeting_criteria and x_ads_create_promoted_tweet.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			campaignIds: z.array(entityIdArg).max(200).optional().describe("Only line items under these campaigns."),
+			lineItemIds: z.array(entityIdArg).max(200).optional().describe("Only these line item ids."),
+			count: adsCountArg,
+			withDeleted: z.boolean().default(false).describe("Include deleted line items.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, campaignIds, lineItemIds, count, withDeleted }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const page = await client.paginateCursor(`/12/accounts/${id}/line_items`, compact({
+			count,
+			...campaignIds?.length ? { campaign_ids: campaignIds } : {},
+			...lineItemIds?.length ? { line_item_ids: lineItemIds } : {},
+			...withDeleted ? { with_deleted: true } : {}
+		}), { maxItems: count });
+		return {
+			account_id: id,
+			line_items: shapeAds({ data: page.data }),
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_get_promoted_tweets", {
+		title: "X: Ads Get Promoted Tweets",
+		description: "List the posts promoted under an account's line items. Each entry pairs a line item with the post id it is promoting; look the post itself up with x_get_post if you need its text.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			lineItemIds: z.array(entityIdArg).max(200).optional().describe("Only promoted posts under these line items."),
+			count: adsCountArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, lineItemIds, count }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const page = await client.paginateCursor(`/12/accounts/${id}/promoted_tweets`, compact({
+			count,
+			...lineItemIds?.length ? { line_item_ids: lineItemIds } : {}
+		}), { maxItems: count });
+		return {
+			account_id: id,
+			promoted_tweets: page.data,
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+	if (!ads.allowWrites) return;
+	server.registerTool("x_ads_create_campaign", {
+		title: "X: Ads Create Campaign",
+		description: "Create a campaign. SPENDS MONEY once activated. Budgets are given in MAJOR currency units — 50 means 50.00 — and converted to X's millionths for you; never pass a pre-multiplied figure. The campaign is created PAUSED unless you set activateImmediately, so the normal flow is: create, add a line item, add targeting, then activate. In v12 a campaign has no dates of its own; set them on the line item.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			fundingInstrumentId: entityIdArg.describe("Which funding instrument pays for this. List them with x_ads_get_funding_instruments."),
+			name: z.string().min(1).max(255).describe("Campaign name, up to 255 characters."),
+			dailyBudget: budgetArg.describe("Daily budget in MAJOR currency units of the funding instrument (50 means 50.00). Do NOT multiply by 1,000,000."),
+			totalBudget: budgetArg.optional().describe("Optional lifetime cap, in the same major units as dailyBudget."),
+			activateImmediately: activateArg,
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ accountId, fundingInstrumentId, name, dailyBudget, totalBudget, activateImmediately }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const { status, note } = statusFor(activateImmediately);
+		const dailyMicro = toMicro(dailyBudget);
+		const totalMicro = totalBudget === void 0 ? void 0 : toMicro(totalBudget);
+		const created = await client.post(`/12/accounts/${id}/campaigns`, compact({
+			funding_instrument_id: fundingInstrumentId,
+			name,
+			daily_budget_amount_local_micro: dailyMicro,
+			total_budget_amount_local_micro: totalMicro,
+			entity_status: status
+		}));
+		const currency = await currencyOf(id, fundingInstrumentId);
+		return {
+			account_id: id,
+			campaign: shapeAds(created, currency),
+			entity_status: status,
+			budget_sent: {
+				daily_budget: dailyBudget,
+				daily_budget_amount_local_micro: dailyMicro,
+				...totalBudget !== void 0 ? {
+					total_budget: totalBudget,
+					total_budget_amount_local_micro: totalMicro
+				} : {},
+				...currency ? { currency } : {}
+			},
+			next_step: note,
+			environment: ads.sandbox ? "sandbox" : "production",
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_update_campaign", {
+		title: "X: Ads Update Campaign",
+		description: "Change a campaign's name, budget or status. Budgets are in MAJOR currency units, as on create. Raising a daily budget on an ACTIVE campaign increases spending immediately.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			campaignId: entityIdArg.describe("The campaign to change."),
+			name: z.string().min(1).max(255).optional().describe("New name."),
+			dailyBudget: budgetArg.optional().describe("New daily budget, in major currency units."),
+			totalBudget: budgetArg.optional().describe("New lifetime cap, in major currency units."),
+			entityStatus: z.enum(["ACTIVE", "PAUSED"]).optional().describe("ACTIVE resumes delivery and spending; PAUSED stops it."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async ({ accountId, campaignId, name, dailyBudget, totalBudget, entityStatus }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const dailyMicro = dailyBudget === void 0 ? void 0 : toMicro(dailyBudget);
+		const totalMicro = totalBudget === void 0 ? void 0 : toMicro(totalBudget);
+		return {
+			account_id: id,
+			campaign: shapeAds(await client.put(`/12/accounts/${id}/campaigns/${campaignId}`, compact({
+				name,
+				daily_budget_amount_local_micro: dailyMicro,
+				total_budget_amount_local_micro: totalMicro,
+				entity_status: entityStatus
+			}))),
+			...dailyBudget !== void 0 ? { budget_sent: {
+				daily_budget: dailyBudget,
+				daily_budget_amount_local_micro: dailyMicro
+			} } : {},
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_delete_campaign", {
+		title: "X: Ads Delete Campaign",
+		description: "Delete a campaign. This also stops its line items. X keeps deleted campaigns visible to `withDeleted` reads but they cannot be revived — pause the campaign instead if you may want it back.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			campaignId: entityIdArg.describe("The campaign to delete."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async ({ accountId, campaignId }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			deleted: campaignId,
+			campaign: shapeAds(await client.del(`/12/accounts/${id}/campaigns/${campaignId}`)),
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_create_line_item", {
+		title: "X: Ads Create Line Item",
+		description: "Create a line item under a campaign — the ad group carrying the objective, bid, placements and flight dates. Created PAUSED unless activateImmediately is set. Bids are in MAJOR currency units. A line item with no targeting criteria and no promoted post will not deliver, so this is usually the second of three calls.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			campaignId: entityIdArg.describe("The campaign this belongs to."),
+			name: z.string().min(1).max(255).optional().describe("Line item name."),
+			objective: z.enum(OBJECTIVES).describe("What the line item optimises for."),
+			productType: z.enum(PRODUCT_TYPES).describe("The kind of ad. Usually PROMOTED_TWEETS."),
+			placements: z.array(z.enum(PLACEMENTS)).min(1).describe("Where ads may appear. ALL_ON_TWITTER is the usual choice."),
+			startTime: adsTimeArg.describe("When delivery starts, ISO-8601 UTC on a whole hour."),
+			endTime: adsTimeArg.optional().describe("When delivery stops. Omit to run open-ended."),
+			bid: budgetArg.optional().describe("Bid in MAJOR currency units. Omit to let X bid automatically."),
+			totalBudget: budgetArg.optional().describe("Lifetime cap for this line item."),
+			activateImmediately: activateArg,
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async (args) => wrap(async () => {
+		const id = await resolveAccount(args.accountId);
+		const { status, note } = statusFor(args.activateImmediately);
+		const bidMicro = args.bid === void 0 ? void 0 : toMicro(args.bid);
+		return {
+			account_id: id,
+			line_item: shapeAds(await client.post(`/12/accounts/${id}/line_items`, compact({
+				campaign_id: args.campaignId,
+				name: args.name,
+				objective: args.objective,
+				product_type: args.productType,
+				placements: args.placements,
+				start_time: args.startTime,
+				end_time: args.endTime,
+				bid_amount_local_micro: bidMicro,
+				total_budget_amount_local_micro: args.totalBudget === void 0 ? void 0 : toMicro(args.totalBudget),
+				entity_status: status
+			}))),
+			entity_status: status,
+			...args.bid !== void 0 ? { bid_sent: {
+				bid: args.bid,
+				bid_amount_local_micro: bidMicro
+			} } : {},
+			next_step: `${note} Attach targeting with x_ads_create_targeting_criterion and a post with x_ads_create_promoted_tweet before activating, or it will not deliver.`,
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_update_line_item", {
+		title: "X: Ads Update Line Item",
+		description: "Change a line item's name, bid, dates or status. Bids and budgets are in MAJOR currency units, as on create.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			lineItemId: entityIdArg.describe("The line item to change."),
+			name: z.string().min(1).max(255).optional().describe("New name."),
+			bid: budgetArg.optional().describe("New bid, in major currency units."),
+			totalBudget: budgetArg.optional().describe("New lifetime cap, in major currency units."),
+			startTime: adsTimeArg.optional().describe("New start time."),
+			endTime: adsTimeArg.optional().describe("New end time."),
+			entityStatus: z.enum(["ACTIVE", "PAUSED"]).optional().describe("Resume or stop delivery."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async (args) => wrap(async () => {
+		const id = await resolveAccount(args.accountId);
+		return {
+			account_id: id,
+			line_item: shapeAds(await client.put(`/12/accounts/${id}/line_items/${args.lineItemId}`, compact({
+				name: args.name,
+				bid_amount_local_micro: args.bid === void 0 ? void 0 : toMicro(args.bid),
+				total_budget_amount_local_micro: args.totalBudget === void 0 ? void 0 : toMicro(args.totalBudget),
+				start_time: args.startTime,
+				end_time: args.endTime,
+				entity_status: args.entityStatus
+			}))),
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_delete_line_item", {
+		title: "X: Ads Delete Line Item",
+		description: "Delete a line item. Irreversible — pause it instead if you may want it back. Its targeting criteria and promoted posts stop delivering with it.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			lineItemId: entityIdArg.describe("The line item to delete."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async ({ accountId, lineItemId }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			deleted: lineItemId,
+			line_item: shapeAds(await client.del(`/12/accounts/${id}/line_items/${lineItemId}`)),
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_create_promoted_tweet", {
+		title: "X: Ads Create Promoted Tweet",
+		description: "Promote existing posts under a line item. The posts must already exist — compose one first with x_compose_post, or pick an id from x_get_user_posts. Promotion begins when the line item is active.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			lineItemId: entityIdArg.describe("The line item that will carry these posts."),
+			postIds: z.array(z.string().regex(/^\d+$/)).min(1).max(50).describe("Post ids to promote, e.g. [\"1799000000000000001\"]."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ accountId, lineItemId, postIds }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			line_item_id: lineItemId,
+			promoted_tweets: shapeAds(await client.post(`/12/accounts/${id}/promoted_tweets`, {
+				line_item_id: lineItemId,
+				tweet_ids: postIds
+			})),
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_delete_promoted_tweet", {
+		title: "X: Ads Delete Promoted Tweet",
+		description: "Stop promoting a post by removing it from its line item. The post itself is untouched and stays on the timeline — use x_delete_post to remove that.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			promotedTweetId: entityIdArg.describe("The promoted-tweet id from x_ads_get_promoted_tweets, not the post id."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async ({ accountId, promotedTweetId }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			deleted: promotedTweetId,
+			promoted_tweet: shapeAds(await client.del(`/12/accounts/${id}/promoted_tweets/${promotedTweetId}`)),
+			note: "The post itself is unaffected and is still on the timeline.",
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_set_entity_status", {
+		title: "X: Ads Set Entity Status",
+		description: "Activate or pause a campaign or line item. This is the switch that starts and stops spending: ACTIVE begins delivery immediately at the entity's configured budget. Check the budget with x_ads_get_campaigns before activating something you did not just create.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			entityType: z.enum(["campaign", "line_item"]).describe("Which kind of entity the id refers to."),
+			entityId: entityIdArg.describe("The campaign or line item id."),
+			status: z.enum(["ACTIVE", "PAUSED"]).describe("ACTIVE starts delivery and spending. PAUSED stops it."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async ({ accountId, entityType, entityId, status }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			entity_type: entityType,
+			entity_id: entityId,
+			entity_status: status,
+			entity: shapeAds(await client.put(`/12/accounts/${id}/${PATH_FOR[entityType]}/${entityId}`, { entity_status: status })),
+			note: status === "ACTIVE" ? `Now ACTIVE${ads.sandbox ? " (sandbox — nothing is really spent)" : " — delivery and spending have started"}.` : "Now PAUSED. It is spending nothing.",
+			cost: adsCostNote()
+		};
+	}));
+};
+//#endregion
+//#region src/tools/ads/targeting.ts
+/**
+* The twelve targeting-option lookup endpoints that exist under
+* `/12/targeting_criteria/`. Deliberately a closed list: guessing a thirteenth
+* (`keywords` is the one people reach for) 404s, and keyword research lives at
+* `/12/insights/keywords/search` on a different path entirely.
+*/
+const OPTION_TYPES = [
+	"app_store_categories",
+	"conversations",
+	"devices",
+	"events",
+	"interests",
+	"languages",
+	"locations",
+	"network_operators",
+	"platform_versions",
+	"platforms",
+	"tv_markets",
+	"tv_shows"
+];
+const LOCATION_TYPES = [
+	"COUNTRIES",
+	"REGIONS",
+	"METROS",
+	"CITIES",
+	"POSTAL_CODES"
+];
+const registerAdsTargetingTools = (server, client, ads, resolveAccount) => {
+	server.registerTool("x_ads_get_targeting_criteria", {
+		title: "X: Ads Get Targeting Criteria",
+		description: "Read the targeting attached to one or more line items — the interests, locations, keywords, follower look-alikes and audiences that decide who sees the ads. Targeting hangs off line items, never off campaigns.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			lineItemIds: z.array(entityIdArg).min(1).max(200).describe("The line items whose targeting you want. At least one is required."),
+			count: adsCountArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ accountId, lineItemIds, count }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		const page = await client.paginateCursor(`/12/accounts/${id}/targeting_criteria`, {
+			count,
+			line_item_ids: lineItemIds
+		}, { maxItems: count });
+		return {
+			account_id: id,
+			targeting_criteria: page.data,
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_search_targeting_options", {
+		title: "X: Ads Search Targeting Options",
+		description: "Look up the valid values for a targeting type before using one. X's targeting takes opaque ids, not names — a location is something like \"96683cc9126741d1\", not \"Paris\" — so this is the step that turns an intention into a `targetingValue` you can pass to x_ads_create_targeting_criterion. There is no keyword option here: keywords are free text and need no lookup.",
+		inputSchema: z.object({
+			type: z.enum(OPTION_TYPES).describe("Which targeting dimension to search. Each maps to one X lookup endpoint."),
+			q: z.string().min(1).optional().describe("Free-text filter, e.g. \"Paris\" for locations or \"cycling\" for interests."),
+			locationType: z.enum(LOCATION_TYPES).optional().describe("For type=locations only: which granularity of place to return."),
+			locale: z.string().min(2).optional().describe("For type=tv_shows, which requires it, e.g. \"en-US\"."),
+			eventTypes: z.array(z.string().min(1)).optional().describe("For type=events, which requires it."),
+			countryCode: z.string().length(2).optional().describe("Two-letter country filter where the endpoint supports one, e.g. \"FR\"."),
+			count: adsCountArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ type, q, locationType, locale, eventTypes, countryCode, count }) => wrap(async () => {
+		const page = await client.paginateCursor(`/12/targeting_criteria/${type}`, compact({
+			count,
+			q,
+			location_type: locationType,
+			locale,
+			event_types: eventTypes,
+			country_code: countryCode
+		}), { maxItems: count });
+		return {
+			type,
+			options: page.data,
+			...page.nextCursor ? { next_cursor: page.nextCursor } : {},
+			note: "Pass an option's `targeting_value` (or `id`) as targetingValue to x_ads_create_targeting_criterion.",
+			cost: adsCostNote()
+		};
+	}));
+	if (!ads.allowWrites) return;
+	server.registerTool("x_ads_create_targeting_criterion", {
+		title: "X: Ads Create Targeting Criterion",
+		description: "Add one targeting criterion to a line item. Look the value up first with x_ads_search_targeting_options — X takes opaque ids for most types, and an invented one is rejected. Criteria of different types intersect (AND) while criteria of the same type union (OR), so adding two locations widens the audience while adding a location and an interest narrows it. Broadening targeting on an active line item increases spending.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			lineItemId: entityIdArg.describe("The line item to target."),
+			targetingType: z.string().min(1).describe("The criterion type, e.g. \"LOCATION\", \"INTEREST\", \"BROAD_KEYWORD\", \"FOLLOWERS_OF_USER\", \"CUSTOM_AUDIENCE\", \"PLATFORM\", \"LANGUAGE\"."),
+			targetingValue: z.string().min(1).describe("The value for that type — an id from x_ads_search_targeting_options, or free text for keyword types."),
+			operatorType: z.enum([
+				"EQ",
+				"NE",
+				"GTE",
+				"LT"
+			]).default("EQ").describe("How to compare. EQ is right for almost everything; NE excludes."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ accountId, lineItemId, targetingType, targetingValue, operatorType }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			line_item_id: lineItemId,
+			targeting_criterion: shapeAds(await client.post(`/12/accounts/${id}/targeting_criteria`, {
+				line_item_id: lineItemId,
+				targeting_type: targetingType,
+				targeting_value: targetingValue,
+				operator_type: operatorType
+			})),
+			cost: adsCostNote()
+		};
+	}));
+	server.registerTool("x_ads_delete_targeting_criterion", {
+		title: "X: Ads Delete Targeting Criterion",
+		description: "Remove one targeting criterion from a line item. Narrowing or widening targeting on an active line item changes who sees the ads immediately. Removing the last criterion leaves the line item targeting everyone, which usually spends faster, not slower.",
+		inputSchema: z.object({
+			accountId: accountIdArg,
+			targetingCriterionId: entityIdArg.describe("The criterion id from x_ads_get_targeting_criteria."),
+			confirm: adsConfirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async ({ accountId, targetingCriterionId }) => wrap(async () => {
+		const id = await resolveAccount(accountId);
+		return {
+			account_id: id,
+			deleted: targetingCriterionId,
+			targeting_criterion: shapeAds(await client.del(`/12/accounts/${id}/targeting_criteria/${targetingCriterionId}`)),
+			cost: adsCostNote()
+		};
+	}));
+};
+//#endregion
+//#region src/tools/ads/index.ts
+/**
+* Register the X Ads API tools.
+*
+* Reads and the analytics-job tools are registered whenever ads is enabled.
+* The campaign-mutating tools appear only when `X_ADS_ALLOW_WRITES` is on, so
+* with the defaults they are not merely refused — they do not exist and cannot
+* be called. Sandbox-only tools appear only when pointed at the sandbox.
+*
+* The analytics-job tools sit with the reads rather than behind the write gate
+* on purpose: queuing a job changes nothing an advertiser can see and spends
+* nothing, so gating it would make long-range analytics unreachable in exactly
+* the configuration most people should be running.
+*/
+const registerAdsTools = (server, client, ctx) => {
+	const ads = ctx.ads;
+	if (!ads) return;
+	const resolveAccount = createAccountResolver(client, ads);
+	registerAdsAccountTools(server, client, ads, resolveAccount);
+	registerAdsCampaignTools(server, client, ads, resolveAccount);
+	registerAdsTargetingTools(server, client, ads, resolveAccount);
+	registerAdsAudienceTools(server, client, resolveAccount);
+	registerAdsAnalyticsTools(server, client, resolveAccount);
+};
+//#endregion
+//#region src/tools/auth.ts
+const registerAuthTools = (server, ctx) => {
+	server.registerTool("x_auth_status", {
+		title: "X: Auth Status",
+		description: "Which credentials this server is holding: an app-only Bearer token (enough for public reads and search), an OAuth2 user session (needed for bookmarks and the home timeline), or neither. Shows the logged-in handle, granted scopes and token expiry, and whether the Ads API tools are registered and against which environment. Call this first if the X API tools seem to be missing — it explains exactly what to configure.",
+		inputSchema: z.object({}),
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => {
+		const status = ctx.tokenProvider.describe();
+		const mode = ctx.tokenFile ? fileMode(ctx.tokenFile) : void 0;
+		if (!ctx.hasCredentials) return {
+			configured: false,
+			app_only_bearer: false,
+			user: {
+				authenticated: false,
+				reason: "no credentials configured"
+			},
+			can_read_public: false,
+			can_read_bookmarks: false,
+			available_without_credentials: [
+				"x_compose_post",
+				"x_validate_post",
+				"x_build_search_query",
+				"x_auth_status"
+			],
+			setup: ctx.setup ?? []
+		};
+		return {
+			configured: true,
+			app_only_bearer: status.app,
+			user: status.user.authenticated ? {
+				...status.user,
+				expires_at: new Date(status.user.expiresAt).toISOString(),
+				expires_in_seconds: Math.max(0, Math.round((status.user.expiresAt - Date.now()) / 1e3))
+			} : status.user,
+			...ctx.tokenFile ? { token_file: {
+				path: ctx.tokenFile,
+				mode: mode === void 0 ? "absent" : `0${mode.toString(8)}`,
+				...mode !== void 0 && (mode & 63) !== 0 ? { warning: `Readable by other users. Run: chmod 600 ${ctx.tokenFile}` } : {}
+			} } : {},
+			can_read_public: status.app || status.user.authenticated,
+			can_read_bookmarks: status.user.authenticated,
+			ads: ctx.ads ? {
+				enabled: true,
+				environment: ctx.ads.sandbox ? "sandbox" : "production",
+				base_url: ctx.ads.baseUrl,
+				writes_enabled: ctx.ads.allowWrites,
+				default_account_id: ctx.ads.accountId ?? null,
+				note: ctx.ads.sandbox ? "Sandbox — campaigns here spend nothing." : "PRODUCTION — these tools read and can change campaigns that spend real money."
+			} : {
+				enabled: false,
+				reason: ctx.adsSetup ? "X_ADS_ENABLED is not set." : "no OAuth2 client id configured",
+				...ctx.adsSetup ? { setup: ctx.adsSetup } : {}
+			}
+		};
+	}));
+	if (!ctx.login) return;
+	const login = ctx.login;
+	server.registerTool("x_auth_login", {
+		title: "X: Auth Login",
+		description: "Start the OAuth2 login. Prints a URL (and opens your browser) for you to authorize the app, waits up to two minutes for the callback, then stores a refresh token in the token file with mode 600. Only needed for bookmarks, the home timeline and API writes — public reads and search work with the Bearer token alone.",
+		inputSchema: z.object({ open: z.boolean().default(true).describe("Open the authorize URL in your browser.") }),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false
+		}
+	}, async ({ open }) => wrap(async () => {
+		const result = await login(open);
+		return {
+			authenticated: true,
+			username: result.username,
+			userId: result.userId,
+			scopes: result.scopes,
+			token_file: result.tokenFile,
+			note: "The refresh token is stored with mode 600 and rotates on every refresh."
+		};
+	}));
+	server.registerTool("x_auth_logout", {
+		title: "X: Auth Logout",
+		description: "Delete the stored OAuth2 tokens. The app-only Bearer token is unaffected, so public reads and search keep working.",
+		inputSchema: z.object({ confirm: z.literal(true).describe("Must be true. You will need to run the login flow again to undo this.") }),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async () => wrap(async () => {
+		ctx.logout?.();
+		return {
+			logged_out: true,
+			note: "Public reads and search continue to work if a Bearer token is configured."
+		};
+	}));
+};
+//#endregion
+//#region src/tools/compose.ts
+const textArg = z.string().min(1).describe("The body of the post. Counted against X's 280 weighted-character limit.");
+const urlArg = z.string().url().optional().describe("A link to append. X shortens every link to a fixed 23 characters, so its real length does not matter — but those 23 do count.");
+const hashtagsArg = z.array(z.string()).optional().describe("Hashtags, with or without \"#\". More than four tends to suppress reach.");
+const viaArg = z.string().optional().describe("An attribution handle, appended as \"via @handle\".");
+const registerComposeTools = (server, client, ctx) => {
+	server.registerTool("x_validate_post", {
+		title: "X: Validate Post",
+		description: "Check a draft against X's 280-character limit before doing anything with it. X counts weighted characters, not plain ones: every URL costs 23 whatever its length, and CJK characters and emoji cost 2 each — so 140 Japanese characters is already a full post. Runs locally; no API call, no cost.",
+		inputSchema: z.object({
+			text: textArg,
+			url: urlArg,
+			hashtags: hashtagsArg,
+			via: viaArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ text, url, hashtags, via }) => wrap(async () => {
+		const { intent_url: _intentUrl, ...validation } = validateIntent({
+			text,
+			url,
+			hashtags,
+			via
+		});
+		return validation;
+	}));
+	server.registerTool("x_compose_post", {
+		title: "X: Compose Post",
+		description: "The default way to post. Validates the draft and returns an x.com/intent/tweet URL that opens X's composer pre-filled — you click Post yourself. This is FREE: no API quota, no write scope, no credentials, and nothing is published without a human click. Prefer it over x_create_post, which costs $0.015 per post ($0.200 with a URL). Web intents cannot attach media, create polls, make native quote posts, or build threads — those need the paid API. Replying to a post does work.",
+		inputSchema: z.object({
+			text: textArg,
+			url: urlArg,
+			hashtags: hashtagsArg,
+			via: viaArg,
+			inReplyTo: postIdArg.optional().describe("Post id to reply to. The composer opens in reply context."),
+			open: z.boolean().optional().describe("Open the URL in your browser. Defaults to the server's X_API_AUTO_OPEN_BROWSER setting. The URL is returned either way.")
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false
+		}
+	}, async ({ text, url, hashtags, via, inReplyTo, open }) => wrap(async () => {
+		const validation = validateIntent({
+			text,
+			url,
+			hashtags,
+			via,
+			inReplyTo
+		});
+		if (!validation.valid) return {
+			...validation,
+			cost: {
+				estimated_usd: 0,
+				note: "Nothing was sent — the draft is not postable."
+			}
+		};
+		const result = open ?? ctx.autoOpenBrowser ? await openInBrowser(validation.intent_url) : {
+			opened: false,
+			reason: "not requested"
+		};
+		return {
+			intent_url: validation.intent_url,
+			opened: result.opened,
+			...result.reason ? { open_note: result.reason } : {},
+			composed: validation.composed,
+			weighted_length: validation.weighted,
+			remaining: validation.remaining,
+			valid: true,
+			warnings: validation.warnings,
+			next_step: result.opened ? "X's composer is open in your browser — review it and click Post." : "Open the intent_url above to review and post it.",
+			cost: {
+				estimated_usd: 0,
+				note: "Web intent — no API call, no quota consumed, no credentials used."
+			}
+		};
+	}));
+	if (!ctx.allowWrites || ctx.writeBackend !== "api") return;
+	server.registerTool("x_create_post", {
+		title: "X: Create Post",
+		description: "Publish a post directly through the API. COSTS MONEY: about $0.015 per post, or $0.200 if it contains a URL — forty times a post read. x_compose_post does the same thing for free via a browser click; use this only when you specifically need unattended posting, a thread, or a native quote post.",
+		inputSchema: z.object({
+			text: textArg,
+			replyToPostId: postIdArg.optional().describe("Post id to reply to."),
+			quotePostId: postIdArg.optional().describe("Post id to quote."),
+			replySettings: z.enum([
+				"everyone",
+				"mentionedUsers",
+				"following"
+			]).optional().describe("Who may reply. Defaults to everyone."),
+			confirm: confirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false
+		}
+	}, async ({ text, replyToPostId, quotePostId, replySettings }) => wrap(async () => {
+		const validation = validateIntent({ text });
+		if (!validation.valid) return {
+			error: validation.error,
+			weighted_length: validation.weighted
+		};
+		const res = await client.post("/2/tweets", compact({
+			text,
+			...replyToPostId ? { reply: { in_reply_to_tweet_id: replyToPostId } } : {},
+			...quotePostId ? { quote_tweet_id: quotePostId } : {},
+			...replySettings ? { reply_settings: replySettings } : {}
+		}));
+		const hasUrl = validation.weighted !== void 0 && /https?:\/\/|\w+\.\w{2,}/.test(text);
+		ctx.ledger.recordCreate(hasUrl);
+		const data = isRecord(res) && isRecord(res.data) ? res.data : {};
+		const id = typeof data.id === "string" ? data.id : void 0;
+		return {
+			posted: true,
+			id,
+			...id ? { url: `https://x.com/i/web/status/${id}` } : {},
+			cost: {
+				estimated_usd: hasUrl ? ctx.pricing.postCreateWithUrl : ctx.pricing.postCreate,
+				note: hasUrl ? "Billed at the with-URL rate. x_compose_post would have cost nothing." : "x_compose_post would have cost nothing."
+			}
+		};
+	}));
+	server.registerTool("x_delete_post", {
+		title: "X: Delete Post",
+		description: "Delete one of your own posts. Irreversible — X keeps no undo, and the id cannot be reused.",
+		inputSchema: z.object({
+			postId: postIdArg,
+			confirm: confirmArg
+		}),
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async ({ postId }) => wrap(async () => {
+		await client.del(`/2/tweets/${postId}`);
+		return { deleted: postId };
+	}));
+};
+//#endregion
+//#region src/tools/posts.ts
+const registerPostTools = (server, client, ctx) => {
+	/** One batched lookup, shared by the single- and multi-id tools. */
+	const fetchPosts = async (ids) => {
+		const shaped = shapePostsResponse(await client.get("/2/tweets", compact({
+			ids,
+			...POST_QUERY
+		})));
+		return new Map(shaped.posts.map((post) => [post.id, post]));
+	};
+	server.registerTool("x_get_post", {
+		title: "X: Get Post",
+		description: "Get one post by id, with its author, metrics, media and any quoted or replied-to post already inlined. Reading the same post twice in one UTC day is free — X does not bill a repeat read.",
+		inputSchema: z.object({ postId: postIdArg }),
+		annotations: { readOnlyHint: true }
+	}, async ({ postId }) => wrap(async () => {
+		const { items, cost, notFound } = await cachedByIds(ctx, "post", [postId], fetchPosts, "x_get_post");
+		if (items.length === 0) return {
+			error: `X returned no post for id ${notFound[0]}. It is deleted, protected, or from a suspended account.`,
+			cost
+		};
+		return {
+			post: items[0],
+			cost
+		};
+	}));
+	server.registerTool("x_get_posts", {
+		title: "X: Get Posts",
+		description: "Get up to 100 posts by id in a single request. Always prefer this over calling x_get_post repeatedly — X bills per post either way, but one request is far faster and spends only one unit of rate limit. Ids that cannot be served come back under `not_found` rather than failing the call.",
+		inputSchema: z.object({ postIds: z.array(postIdArg).min(1).max(100).describe("Post ids to look up, up to 100 in one call.") }),
+		annotations: { readOnlyHint: true }
+	}, async ({ postIds }) => wrap(async () => {
+		const { items, cost, notFound } = await cachedByIds(ctx, "post", [...new Set(postIds)], fetchPosts, "x_get_posts");
+		return {
+			posts: items,
+			...notFound.length > 0 ? { not_found: notFound } : {},
+			cost
+		};
+	}));
+	server.registerTool("x_get_thread", {
+		title: "X: Get Thread",
+		description: "Reconstruct a conversation: every reply sharing the post's conversation_id, oldest first. Note that this searches the last 7 days only, so an older thread returns just the root post. Costs one post read per reply returned.",
+		inputSchema: z.object({
+			postId: postIdArg,
+			maxResults: maxResultsArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ postId, maxResults }) => wrap(async () => {
+		const rootRaw = await client.get(`/2/tweets/${postId}`, compact({ ...POST_QUERY }));
+		const root = shapePostsResponse({
+			...isRecord(rootRaw) ? rootRaw : {},
+			data: isRecord(rootRaw) && isRecord(rootRaw.data) ? [rootRaw.data] : []
+		}).posts[0];
+		if (!root) return {
+			error: `X returned no post for id ${postId}.`,
+			cost: recordResultCost(ctx, "post", [])
+		};
+		const conversationId = root.conversation_id ?? root.id;
+		const replies = await client.paginate("/2/tweets/search/recent", compact({
+			query: `conversation_id:${conversationId}`,
+			max_results: Math.min(Math.max(maxResults, 10), 100),
+			sort_order: "recency",
+			...POST_QUERY
+		}), { maxItems: maxResults });
+		const ordered = shapePostsResponse({
+			data: replies.data,
+			includes: replies.includes[0] ?? {}
+		}).posts.toReversed();
+		const ids = [root.id, ...ordered.map((p) => p.id)];
+		return {
+			conversation_id: conversationId,
+			posts: [root, ...ordered.filter((p) => p.id !== root.id)],
+			...replies.nextToken ? { next_token: replies.nextToken } : {},
+			note: "Recent search reaches back 7 days. Replies older than that are not returned even if the thread has more.",
+			cost: recordResultCost(ctx, "post", ids)
+		};
+	}));
+	server.registerTool("x_get_quotes", {
+		title: "X: Get Quotes",
+		description: "List posts quoting a given post, newest first.",
+		inputSchema: z.object({
+			postId: postIdArg,
+			maxResults: maxResultsArg,
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ postId, maxResults, paginationToken }) => wrap(async () => {
+		const res = await client.paginate(`/2/tweets/${postId}/quote_tweets`, compact({
+			max_results: Math.min(Math.max(maxResults, 10), 100),
+			pagination_token: paginationToken,
+			...POST_QUERY
+		}), { maxItems: maxResults });
+		const shaped = shapePostsResponse({
+			data: res.data,
+			includes: res.includes[0] ?? {}
+		});
+		return {
+			posts: shaped.posts,
+			result_count: shaped.posts.length,
+			...res.nextToken ? { next_token: res.nextToken } : {},
+			cost: recordResultCost(ctx, "post", shaped.posts.map((p) => p.id))
+		};
+	}));
+};
+//#endregion
+//#region src/tools/search.ts
+const queryArg = z.string().min(1).max(1024).describe("An X search query, e.g. \"rust -is:retweet lang:en\". Build one with x_build_search_query if you are unsure of the operators.");
+const timeArgs = {
+	startTime: z.string().optional().describe("Only posts at or after this ISO-8601 UTC time, e.g. \"2026-07-01T00:00:00Z\"."),
+	endTime: z.string().optional().describe("Only posts before this ISO-8601 UTC time.")
+};
+/**
+* Full-archive search is capped at one request per second on top of its 15-minute
+* window. Enforced with a real gate rather than hoped for: a paginated call
+* issues several requests back to back and would trip the limit on its own.
+*/
+const createRateGate = (minIntervalMs) => {
+	let last = 0;
+	return async () => {
+		const wait = last + minIntervalMs - Date.now();
+		if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+		last = Date.now();
+	};
+};
+/**
+* Registered separately from the rest of search because it runs entirely
+* locally — no API call, no credentials, no cost. It stays available on an
+* unconfigured server, where getting a query right for free is the most useful
+* thing left to do.
+*/
+const registerQueryBuilderTool = (server) => {
+	server.registerTool("x_build_search_query", {
+		title: "X: Build Search Query",
+		description: "Build an X search query from structured parts and explain each operator it used. Runs entirely locally: no API call, no cost, no credentials. Use this to get the query right for free, then pass the result to x_count_recent and only then to x_search_recent.",
+		inputSchema: z.object({
+			allWords: z.string().optional().describe("Words that must all appear, e.g. \"rust async\"."),
+			exactPhrase: z.string().optional().describe("A phrase that must appear verbatim."),
+			anyWords: z.array(z.string()).optional().describe("At least one of these must appear."),
+			noneWords: z.array(z.string()).optional().describe("None of these may appear."),
+			hashtags: z.array(z.string()).optional().describe("Hashtags, with or without \"#\"."),
+			from: z.array(usernameLike()).optional().describe("Only posts by these handles."),
+			to: z.array(usernameLike()).optional().describe("Only replies to these handles."),
+			mentioning: z.array(usernameLike()).optional().describe("Only posts mentioning these."),
+			lang: z.string().optional().describe("BCP-47 language code, e.g. \"en\", \"fr\", \"ja\"."),
+			hasMedia: z.boolean().optional().describe("Only posts with a photo or video."),
+			hasLinks: z.boolean().optional().describe("Only posts containing a link."),
+			isReply: z.boolean().optional().describe("true to require replies, false to exclude them."),
+			isRetweet: z.boolean().optional().describe("true to require reposts, false to exclude them. False is the usual choice."),
+			isQuote: z.boolean().optional().describe("true to require quote posts, false to exclude.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async (args) => wrap(async () => buildSearchQuery(args)));
+};
+const registerSearchTools = (server, client, ctx) => {
+	const runSearch = async (path, args, label, gate) => {
+		assertWithinBudget(ctx, label, ctx.ledger.estimateCount("post", args.maxResults));
+		if (gate) await gate();
+		const res = await client.paginate(path, compact({
+			query: args.query,
+			max_results: Math.min(Math.max(args.maxResults, 10), 100),
+			sort_order: args.sortOrder,
+			start_time: args.startTime,
+			end_time: args.endTime,
+			since_id: args.sinceId,
+			until_id: args.untilId,
+			pagination_token: args.paginationToken,
+			...POST_QUERY
+		}), {
+			maxItems: args.maxResults,
+			maxPages: 5
+		});
+		const shaped = shapePostsResponse({
+			data: res.data,
+			includes: res.includes[0] ?? {}
+		});
+		return {
+			query: args.query,
+			posts: shaped.posts,
+			result_count: shaped.posts.length,
+			...res.nextToken ? { next_token: res.nextToken } : {},
+			cost: recordResultCost(ctx, "post", shaped.posts.map((p) => p.id))
+		};
+	};
+	server.registerTool("x_search_recent", {
+		title: "X: Search Recent",
+		description: "Search posts from the last 7 days. Supports X's full query syntax: `from:handle`, `to:handle`, `#tag`, `\"exact phrase\"`, `lang:en`, `has:media`, `has:links`, `url:example.com`, `conversation_id:`, and negation with `-is:retweet` or `-is:reply`. Run x_count_recent first to see how big a query is before paying to read it.",
+		inputSchema: z.object({
+			query: queryArg,
+			maxResults: maxResultsArg,
+			sortOrder: z.enum(["recency", "relevancy"]).optional().describe("`recency` (newest first, the default) or `relevancy`."),
+			...timeArgs,
+			sinceId: z.string().regex(/^\d+$/).optional().describe("Only posts newer than this id."),
+			untilId: z.string().regex(/^\d+$/).optional().describe("Only posts older than this id."),
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async (args) => wrap(() => runSearch("/2/tweets/search/recent", args, "x_search_recent")));
+	server.registerTool("x_count_recent", {
+		title: "X: Count Recent",
+		description: "Count how many posts match a query over the last 7 days WITHOUT reading any of them. This endpoint returns only totals, so it costs nothing per post — always run it before a broad x_search_recent to find out whether you are about to read 10 posts or 10,000.",
+		inputSchema: z.object({
+			query: queryArg,
+			granularity: z.enum([
+				"minute",
+				"hour",
+				"day"
+			]).default("day").describe("Bucket size for the time series. Defaults to day."),
+			...timeArgs
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ query, granularity, startTime, endTime }) => wrap(async () => {
+		const raw = await client.get("/2/tweets/counts/recent", compact({
+			query,
+			granularity,
+			start_time: startTime,
+			end_time: endTime
+		}));
+		const meta = isRecord(raw) && isRecord(raw.meta) ? raw.meta : {};
+		const total = typeof meta.total_tweet_count === "number" ? meta.total_tweet_count : 0;
+		const estimated = ctx.ledger.estimateCount("post", total);
+		return {
+			query,
+			total_posts: total,
+			buckets: isRecord(raw) && Array.isArray(raw.data) ? raw.data : [],
+			cost: {
+				estimated_usd: 0,
+				note: "Counts are not billed per post."
+			},
+			reading_all_would_cost_usd: Math.round(estimated * 100) / 100,
+			...total > 100 ? { advice: `Reading all ${total} matches would cost about $${(Math.round(estimated * 100) / 100).toFixed(2)}. Narrow the query with -is:retweet, lang:, or a tighter time window before searching.` } : {}
+		};
+	}));
+	if (!ctx.enableFullArchive) return;
+	const archiveGate = createRateGate(1e3);
+	server.registerTool("x_search_all", {
+		title: "X: Search All",
+		description: "Search the FULL archive, back to X's first post in March 2006 — not just the last 7 days. Requires a paid access tier and is limited to one request per second, so it is slower than x_search_recent. Same query syntax. Costs the same per post read.",
+		inputSchema: z.object({
+			query: queryArg,
+			maxResults: maxResultsArg,
+			sortOrder: z.enum(["recency", "relevancy"]).optional(),
+			...timeArgs,
+			sinceId: z.string().regex(/^\d+$/).optional(),
+			untilId: z.string().regex(/^\d+$/).optional(),
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async (args) => wrap(() => runSearch("/2/tweets/search/all", args, "x_search_all", archiveGate)));
+};
+function usernameLike() {
+	return z.string().regex(/^@?[A-Za-z0-9_]{1,15}$/);
+}
+/** Grouped with OR and parenthesised, which is what X's `from:a OR from:b` needs. */
+const orGroup = (operator, values) => values.length === 1 ? `${operator}:${values[0]}` : `(${values.map((v) => `${operator}:${v}`).join(" OR ")})`;
+const buildSearchQuery = (parts) => {
+	const clauses = [];
+	const explanation = [];
+	if (parts.allWords?.trim()) {
+		clauses.push(parts.allWords.trim());
+		explanation.push(`\`${parts.allWords.trim()}\` — all of these words must appear.`);
+	}
+	if (parts.exactPhrase?.trim()) {
+		clauses.push(`"${parts.exactPhrase.trim()}"`);
+		explanation.push(`\`"${parts.exactPhrase.trim()}"\` — this exact phrase must appear.`);
+	}
+	if (parts.anyWords?.length) {
+		clauses.push(`(${parts.anyWords.join(" OR ")})`);
+		explanation.push(`\`(${parts.anyWords.join(" OR ")})\` — at least one of these must appear.`);
+	}
+	for (const word of parts.noneWords ?? []) {
+		clauses.push(`-${word}`);
+		explanation.push(`\`-${word}\` — excludes posts containing "${word}".`);
+	}
+	for (const tag of parts.hashtags ?? []) {
+		const clean = tag.startsWith("#") ? tag : `#${tag}`;
+		clauses.push(clean);
+		explanation.push(`\`${clean}\` — must carry this hashtag.`);
+	}
+	if (parts.from?.length) {
+		const handles = parts.from.map(stripAt);
+		clauses.push(orGroup("from", handles));
+		explanation.push(`\`from:\` — only posts authored by ${handles.map((h) => `@${h}`).join(" or ")}.`);
+	}
+	if (parts.to?.length) {
+		const handles = parts.to.map(stripAt);
+		clauses.push(orGroup("to", handles));
+		explanation.push(`\`to:\` — only replies addressed to ${handles.map((h) => `@${h}`).join(" or ")}.`);
+	}
+	for (const handle of (parts.mentioning ?? []).map(stripAt)) {
+		clauses.push(`@${handle}`);
+		explanation.push(`\`@${handle}\` — must mention this account.`);
+	}
+	if (parts.lang) {
+		clauses.push(`lang:${parts.lang}`);
+		explanation.push(`\`lang:${parts.lang}\` — only posts X detected as this language.`);
+	}
+	if (parts.hasMedia !== void 0) {
+		clauses.push(`${parts.hasMedia ? "" : "-"}has:media`);
+		explanation.push(`\`${parts.hasMedia ? "" : "-"}has:media\` — ${parts.hasMedia ? "requires" : "excludes"} posts with a photo or video.`);
+	}
+	if (parts.hasLinks !== void 0) {
+		clauses.push(`${parts.hasLinks ? "" : "-"}has:links`);
+		explanation.push(`\`${parts.hasLinks ? "" : "-"}has:links\` — ${parts.hasLinks ? "requires" : "excludes"} posts containing a link.`);
+	}
+	for (const [flag, name] of [
+		[parts.isReply, "reply"],
+		[parts.isRetweet, "retweet"],
+		[parts.isQuote, "quote"]
+	]) {
+		if (flag === void 0) continue;
+		clauses.push(`${flag ? "" : "-"}is:${name}`);
+		explanation.push(`\`${flag ? "" : "-"}is:${name}\` — ${flag ? "only" : "never"} ${name} posts.` + (name === "retweet" && !flag ? " This is the single most useful filter: it removes the duplicate noise of reposts." : ""));
+	}
+	const query = clauses.join(" ");
+	return {
+		query,
+		explanation,
+		length: query.length,
+		valid: query.length > 0 && query.length <= 1024,
+		...query.length === 0 ? { warning: "No criteria given — the query is empty." } : {},
+		...query.length > 1024 ? { warning: `Query is ${query.length} characters; X's limit is 1024.` } : {}
+	};
+};
+//#endregion
+//#region src/tools/timelines.ts
+/**
+* Both endpoints here are self-only: X permits reading *your* home timeline and
+* *your* bookmarks and nobody else's. So the user id comes from the stored
+* token rather than from an argument — accepting one would imply a capability
+* that does not exist.
+*/
+const resolveOwnUserId = async (client, ctx) => {
+	const status = ctx.tokenProvider.describe().user;
+	if (!status.authenticated) throw new UserContextRequiredError("This tool", status.reason);
+	if (status.userId) return status.userId;
+	const raw = await client.get("/2/users/me", {}, "user");
+	const id = isRecord(raw) && isRecord(raw.data) ? raw.data.id : void 0;
+	const username = isRecord(raw) && isRecord(raw.data) ? raw.data.username : void 0;
+	if (typeof id !== "string" || !id) throw new UserContextRequiredError("This tool", "X did not return your account id from /2/users/me, so there is no way to identify whose timeline to read. Re-run `x-api-mcp login`, and check the app is enrolled in the Pay-per-use package and Production environment at console.x.com");
+	ctx.ledger.record("owned", [id]);
+	const stored = ctx.tokenStore?.read();
+	if (stored) ctx.tokenStore?.write({
+		...stored,
+		userId: id,
+		...typeof username === "string" && username ? { username } : {}
+	});
+	return id;
+};
+const registerTimelineTools = (server, client, ctx) => {
+	server.registerTool("x_get_home_timeline", {
+		title: "X: Get Home Timeline",
+		description: "Your own reverse-chronological home timeline — the posts from accounts you follow. Requires `x-api-mcp login`; X only ever serves this for the authenticated account, so there is no way to read someone else's. Billed at the cheaper owned-read rate.",
+		inputSchema: z.object({
+			maxResults: maxResultsArg,
+			excludeReplies: z.boolean().default(false).describe("Leave out replies."),
+			excludeReposts: z.boolean().default(false).describe("Leave out reposts (retweets)."),
+			sinceId: z.string().regex(/^\d+$/).optional().describe("Only posts newer than this id — useful for polling."),
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ maxResults, excludeReplies, excludeReposts, sinceId, paginationToken }) => wrap(async () => {
+		const userId = await resolveOwnUserId(client, ctx);
+		const exclude = [...excludeReplies ? ["replies"] : [], ...excludeReposts ? ["retweets"] : []];
+		const res = await client.paginate(`/2/users/${userId}/timelines/reverse_chronological`, compact({
+			max_results: Math.min(Math.max(maxResults, 5), 100),
+			exclude: exclude.length > 0 ? exclude : void 0,
+			since_id: sinceId,
+			pagination_token: paginationToken,
+			...POST_QUERY
+		}), {
+			maxItems: maxResults,
+			auth: "user"
+		});
+		const shaped = shapePostsResponse({
+			data: res.data,
+			includes: res.includes[0] ?? {}
+		});
+		return {
+			posts: shaped.posts,
+			result_count: shaped.posts.length,
+			...res.nextToken ? { next_token: res.nextToken } : {},
+			cost: recordResultCost(ctx, "owned", shaped.posts.map((p) => p.id))
+		};
+	}));
+	server.registerTool("x_get_bookmarks", {
+		title: "X: Get Bookmarks",
+		description: "Your saved bookmarks, newest first. Requires `x-api-mcp login` with the `bookmark.read` scope — an app-only Bearer token cannot reach bookmarks at all.",
+		inputSchema: z.object({
+			maxResults: maxResultsArg,
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ maxResults, paginationToken }) => wrap(async () => {
+		const userId = await resolveOwnUserId(client, ctx);
+		const res = await client.paginate(`/2/users/${userId}/bookmarks`, compact({
+			max_results: Math.min(Math.max(maxResults, 1), 100),
+			pagination_token: paginationToken,
+			...POST_QUERY
+		}), {
+			maxItems: maxResults,
+			auth: "user"
+		});
+		const shaped = shapePostsResponse({
+			data: res.data,
+			includes: res.includes[0] ?? {}
+		});
+		return {
+			posts: shaped.posts,
+			result_count: shaped.posts.length,
+			...res.nextToken ? { next_token: res.nextToken } : {},
+			cost: recordResultCost(ctx, "owned", shaped.posts.map((p) => p.id))
+		};
+	}));
+};
+//#endregion
+//#region src/tools/usage.ts
+const registerUsageTools = (server, client, ctx) => {
+	server.registerTool("x_usage_report", {
+		title: "X: Usage Report",
+		description: "What this session has spent against X's pay-per-use rates, how much the dedup cache saved, and the pricing table used to compute it. Estimates only, counted since this process started — the X developer console (console.x.com) is the authoritative record.",
+		inputSchema: z.object({}),
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => ctx.ledger.report(ctx.cache.stats())));
+	server.registerTool("x_rate_limit_status", {
+		title: "X: Rate Limit Status",
+		description: "Rate-limit headroom per endpoint, as of the last response from each. Empty until at least one request has been made. Useful when a call has just been rate-limited and you need to know how long to wait. Covers both the X API v2 and the Ads API, which have separate budgets — the `api` field says which, and `scope` distinguishes the Ads endpoint, account and cost limits.",
+		inputSchema: z.object({}),
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(async () => {
+		const limits = [...client.rateLimitStatus().map((s) => ({
+			api: "v2",
+			...s
+		})), ...ctx.ads ? ctx.ads.client.rateLimitStatus().map((s) => ({
+			api: "ads",
+			...s
+		})) : []];
+		const adsSeen = limits.some((l) => l.api === "ads");
+		return {
+			endpoints: limits,
+			...limits.length === 0 ? { note: "No requests issued yet this session, so X has not reported any limits." } : {},
+			...ctx.ads && !adsSeen ? { ads_note: "Ads is configured but has not been called yet this session, so it reports no limits. That is not a failure." } : {}
+		};
+	}));
+};
+//#endregion
+//#region src/tools/users.ts
+/**
+* Resolve a handle to the numeric id X's timeline endpoints require. Cached and
+* billed as a user read, because that is exactly what it is.
+*/
+const resolveUserId = async (client, ctx, opts) => {
+	if (opts.userId) return { id: opts.userId };
+	if (!opts.username) throw new PreconditionError("Provide either `username` or `userId`.", { got: opts });
+	const handle = stripAt(opts.username);
+	const user = shapeUsersResponse(await client.get(`/2/users/by/username/${handle}`, compact({ ...USER_QUERY }))).users[0];
+	if (!user?.id) throw new PreconditionError(`No X account found for @${handle}.`, { username: handle });
+	ctx.ledger.record("user", [user.id]);
+	return {
+		id: user.id,
+		user
+	};
+};
+const registerUserTools = (server, client, ctx) => {
+	const fetchUsersByIds = async (ids) => {
+		const raw = await client.get("/2/users", compact({
+			ids,
+			...USER_QUERY
+		}));
+		return new Map(shapeUsersResponse(raw).users.map((u) => [u.id, u]));
+	};
+	server.registerTool("x_get_user", {
+		title: "X: Get User",
+		description: "Look up one profile by handle or numeric id: bio, follower and post counts, join date. A user read costs about $0.010, twice a post read.",
+		inputSchema: z.object({
+			username: usernameArg.optional(),
+			userId: userIdArg.optional()
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ username, userId }) => wrap(async () => {
+		if (!username && !userId) throw new PreconditionError("Provide either `username` (a handle like \"mgcrea\") or `userId` (digits).");
+		if (username && userId) throw new PreconditionError("Provide only one of `username` or `userId` — they may disagree.", {
+			username,
+			userId
+		});
+		if (userId) {
+			const { items, cost, notFound } = await cachedByIds(ctx, "user", [userId], fetchUsersByIds, "x_get_user");
+			return items[0] ? {
+				user: items[0],
+				cost
+			} : {
+				error: `No X account found for id ${notFound[0]}.`,
+				cost
+			};
+		}
+		const handle = stripAt(username);
+		const user = shapeUsersResponse(await client.get(`/2/users/by/username/${handle}`, compact({ ...USER_QUERY }))).users[0];
+		if (!user) return { error: `No X account found for @${handle}.` };
+		ctx.cache.set("user", user.id, user);
+		return {
+			user,
+			cost: recordResultCost(ctx, "user", [user.id])
+		};
+	}));
+	server.registerTool("x_get_users", {
+		title: "X: Get Users",
+		description: "Look up up to 100 profiles at once, by handle or by id. One request instead of many, billed per profile returned.",
+		inputSchema: z.object({
+			usernames: z.array(usernameArg).min(1).max(100).optional().describe("Handles to look up, e.g. [\"mgcrea\", \"acme\"]."),
+			userIds: z.array(userIdArg).min(1).max(100).optional()
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ usernames, userIds }) => wrap(async () => {
+		if (!usernames && !userIds) throw new PreconditionError("Provide either `usernames` or `userIds`.");
+		if (usernames && userIds) throw new PreconditionError("Provide only one of `usernames` or `userIds`.");
+		if (userIds) {
+			const { items, cost, notFound } = await cachedByIds(ctx, "user", [...new Set(userIds)], fetchUsersByIds, "x_get_users");
+			return {
+				users: items,
+				...notFound.length > 0 ? { not_found: notFound } : {},
+				cost
+			};
+		}
+		const handles = [...new Set(usernames.map(stripAt))];
+		const shaped = shapeUsersResponse(await client.get("/2/users/by", compact({
+			usernames: handles,
+			...USER_QUERY
+		})));
+		for (const user of shaped.users) ctx.cache.set("user", user.id, user);
+		return {
+			users: shaped.users,
+			...shaped.not_found ? { not_found: shaped.not_found } : {},
+			cost: recordResultCost(ctx, "user", shaped.users.map((u) => u.id))
+		};
+	}));
+	server.registerTool("x_get_user_posts", {
+		title: "X: Get User Posts",
+		description: "A user's own recent posts, newest first. Replies and reposts are excluded by default so you get their original writing; set the flags to include them. Reaches back roughly 3200 posts, X's timeline limit.",
+		inputSchema: z.object({
+			username: usernameArg.optional(),
+			userId: userIdArg.optional(),
+			maxResults: maxResultsArg,
+			excludeReplies: z.boolean().default(true).describe("Leave out replies to other people. Defaults to true."),
+			excludeReposts: z.boolean().default(true).describe("Leave out reposts (retweets). Defaults to true."),
+			startTime: z.string().optional().describe("Only posts at or after this ISO-8601 UTC time, e.g. \"2026-07-01T00:00:00Z\"."),
+			endTime: z.string().optional().describe("Only posts before this ISO-8601 UTC time."),
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ username, userId, maxResults, excludeReplies, excludeReposts, startTime, endTime, paginationToken }) => wrap(async () => {
+		const { id } = await resolveUserId(client, ctx, {
+			username,
+			userId
+		});
+		const exclude = [...excludeReplies ? ["replies"] : [], ...excludeReposts ? ["retweets"] : []];
+		const res = await client.paginate(`/2/users/${id}/tweets`, compact({
+			max_results: Math.min(Math.max(maxResults, 5), 100),
+			exclude: exclude.length > 0 ? exclude : void 0,
+			start_time: startTime,
+			end_time: endTime,
+			pagination_token: paginationToken,
+			...POST_QUERY
+		}), { maxItems: maxResults });
+		const shaped = shapePostsResponse({
+			data: res.data,
+			includes: res.includes[0] ?? {}
+		});
+		return {
+			user_id: id,
+			posts: shaped.posts,
+			result_count: shaped.posts.length,
+			...res.nextToken ? { next_token: res.nextToken } : {},
+			cost: recordResultCost(ctx, "post", shaped.posts.map((p) => p.id))
+		};
+	}));
+	server.registerTool("x_get_user_mentions", {
+		title: "X: Get User Mentions",
+		description: "Posts mentioning a user, newest first — who is talking about them, and what.",
+		inputSchema: z.object({
+			username: usernameArg.optional(),
+			userId: userIdArg.optional(),
+			maxResults: maxResultsArg,
+			startTime: z.string().optional().describe("Only posts at or after this ISO-8601 UTC time."),
+			endTime: z.string().optional().describe("Only posts before this ISO-8601 UTC time."),
+			paginationToken: paginationTokenArg
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ username, userId, maxResults, startTime, endTime, paginationToken }) => wrap(async () => {
+		const { id } = await resolveUserId(client, ctx, {
+			username,
+			userId
+		});
+		const res = await client.paginate(`/2/users/${id}/mentions`, compact({
+			max_results: Math.min(Math.max(maxResults, 5), 100),
+			start_time: startTime,
+			end_time: endTime,
+			pagination_token: paginationToken,
+			...POST_QUERY
+		}), { maxItems: maxResults });
+		const shaped = shapePostsResponse({
+			data: res.data,
+			includes: res.includes[0] ?? {}
+		});
+		return {
+			user_id: id,
+			posts: shaped.posts,
+			result_count: shaped.posts.length,
+			...res.nextToken ? { next_token: res.nextToken } : {},
+			cost: recordResultCost(ctx, "post", shaped.posts.map((p) => p.id))
+		};
+	}));
+};
+//#endregion
+//#region src/tools/index.ts
+/**
+* Register the X API tools.
+*
+* Read tools and the free compose tools are always registered. The paid write
+* tools appear only when `allowWrites` *and* `writeBackend === "api"`;
+* `x_search_all` only when full-archive access is enabled; and the login tools
+* and user-context timelines only when an OAuth client id is configured — so
+* with the defaults those tools are not merely refused, they are invisible and
+* cannot be called at all.
+*/
+const registerTools = (server, client, ctx) => {
+	registerComposeTools(server, client, ctx);
+	registerAuthTools(server, ctx);
+	registerQueryBuilderTool(server);
+	if (!ctx.hasCredentials) return;
+	registerPostTools(server, client, ctx);
+	registerUserTools(server, client, ctx);
+	registerSearchTools(server, client, ctx);
+	registerUsageTools(server, client, ctx);
+	if (ctx.login) {
+		registerTimelineTools(server, client, ctx);
+		if (ctx.ads) registerAdsTools(server, ctx.ads.client, ctx);
+	}
+};
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = BUILD_INFO.name;
+const SERVER_VERSION = BUILD_INFO.version;
+const USER_AGENT = `mcp-x-api-js/${BUILD_INFO.version}`;
+const createServer$1 = (opts) => {
+	const { config } = opts;
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const scopes = effectiveScopes(config);
+	const store = createTokenStore(config.tokenFile);
+	const tokenProvider = opts.tokenProvider ?? compositeTokenProvider({
+		...config.bearerToken ? { app: bearerTokenProvider(config.bearerToken) } : {},
+		...config.clientId ? { user: userTokenProvider({
+			store,
+			oauth: createOAuthClient(config, opts.fetch ?? fetch),
+			clientId: config.clientId,
+			requiredScopes: scopes,
+			...opts.logger ? { logger: opts.logger } : {},
+			...opts.now ? { now: opts.now } : {}
+		}) } : {}
+	});
+	const client = new XApiClient({
+		baseUrl: config.baseUrl,
+		tokenProvider,
+		maxRetries: config.maxRetries,
+		userAgent: USER_AGENT,
+		...opts.fetch ? { fetch: opts.fetch } : {},
+		...opts.logger ? { logger: opts.logger } : {}
+	});
+	const ads = hasAdsAccess(config) ? new AdsApiClient({
+		baseUrl: config.adsBaseUrl,
+		tokenProvider,
+		maxRetries: config.maxRetries,
+		maxDownloadBytes: config.adsMaxDownloadBytes,
+		userAgent: USER_AGENT,
+		...opts.fetch ? { fetch: opts.fetch } : {},
+		...opts.logger ? { logger: opts.logger } : {}
+	}) : void 0;
+	const cache = createDayCache({
+		maxEntries: config.cacheMaxEntries,
+		enabled: config.cacheEnabled,
+		...opts.now ? { now: opts.now } : {}
+	});
+	const ledger = createLedger({
+		pricing: config.pricing,
+		budgetUsd: config.monthlyBudgetUsd,
+		...opts.now ? { now: opts.now } : {}
+	});
+	registerTools(server, client, {
+		allowWrites: config.allowWrites,
+		writeBackend: config.writeBackend,
+		autoOpenBrowser: config.autoOpenBrowser,
+		enableFullArchive: config.enableFullArchive,
+		defaultMaxResults: config.defaultMaxResults,
+		pricing: config.pricing,
+		budgetUsd: config.monthlyBudgetUsd,
+		cache,
+		ledger,
+		tokenProvider,
+		hasCredentials: hasApiCredentials(config),
+		...hasApiCredentials(config) ? {} : { setup: setupInstructions(config) },
+		...ads ? { ads: {
+			client: ads,
+			allowWrites: config.adsAllowWrites,
+			sandbox: ads.sandbox,
+			baseUrl: config.adsBaseUrl,
+			...config.adsAccountId ? { accountId: config.adsAccountId } : {}
+		} } : { adsSetup: adsSetupInstructions(config) },
+		...config.clientId ? {
+			tokenFile: config.tokenFile,
+			tokenStore: store,
+			login: async (open) => {
+				const { tokens } = await startLoginFlow({
+					config,
+					store,
+					...opts.fetch ? { fetch: opts.fetch } : {},
+					...open ? { openBrowser: openInBrowser } : {},
+					...opts.logger ? { logger: opts.logger } : {},
+					...opts.now ? { now: opts.now } : {}
+				});
+				return {
+					username: tokens.username,
+					userId: tokens.userId,
+					scopes: tokens.scopes,
+					tokenFile: config.tokenFile
+				};
+			},
+			logout: () => store.clear()
+		} : {}
+	});
+	return {
+		server,
+		client,
+		tokenProvider,
+		cache,
+		ledger,
+		store,
+		...ads ? { ads } : {}
+	};
+};
+//#endregion
+export { AdsApiClient as A, setupInstructions as B, compositeTokenProvider as C, fromMicro as D, MICRO as E, effectiveScopes as F, WritesDisabledError as G, BudgetExceededError as H, hasAdsAccess as I, XApiRequestError as K, hasApiCredentials as L, DEFAULT_PRICING as M, SANDBOX_ADS_BASE_URL as N, shapeMoney as O, adsSetupInstructions as P, loadConfig as R, bearerTokenProvider as S, startLoginFlow as T, PreconditionError as U, AdsAccessError as V, UserContextRequiredError as W, shapeUser as _, openInBrowser as a, createDayCache as b, buildIntentUrl as c, TCO_URL_LENGTH as d, weightedLength as f, shapePostsResponse as g, shapePostResponse as h, registerTools as i, DEFAULT_ADS_BASE_URL as j, toMicro as k, validateIntent as l, buildIncludesIndex as m, SERVER_VERSION as n, INTENT_BASE_URL as o, XApiClient as p, BUILD_INFO as q, createServer$1 as r, assembleComposerText as s, SERVER_NAME as t, MAX_WEIGHTED_LENGTH as u, shapeUsersResponse as v, staticTokenProvider as w, utcDay as x, createLedger as y, resolveConfigPath as z };
+
+//# sourceMappingURL=server-BeRiqZxj.js.map