@mgcrea/mcp-x-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olivier Louvignes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,290 @@
+# @mgcrea/mcp-x-api
+
+[![npm version](https://img.shields.io/npm/v/@mgcrea/mcp-x-api.svg)](https://www.npmjs.com/package/@mgcrea/mcp-x-api)
+[![ci](https://github.com/mgcrea/mcp-x-api/actions/workflows/ci.yml/badge.svg)](https://github.com/mgcrea/mcp-x-api/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/@mgcrea/mcp-x-api.svg)](./LICENSE)
+
+Model Context Protocol server for the **X (Twitter) API v2** — built for reading and searching posts.
+
+> **Unofficial.** Not affiliated with, endorsed by, or supported by X Corp.
+
+## Features
+
+- **A serious reader.** Post lookup, recent and full-archive search, profiles, user timelines, thread reconstruction, bookmarks and your home timeline — with X's query syntax exposed properly.
+- **Readable output.** X returns posts whose author, quoted post and real URLs live in a separate `includes` sidecar. Every tool here resolves that first, so posts arrive with the handle inline, t.co links expanded, and retweets showing the original text.
+- **Free posting.** `x_compose_post` returns an [`x.com/intent/tweet`](https://docs.x.com/x-for-websites/post-button/guides/web-intent) URL you click. No credentials, no API quota, no cost — and nothing publishes without a human click.
+- **Cost-aware by design.** X is pay-per-use. Every read reports what it cost, repeat reads inside a UTC day are free, and a budget ceiling stops a runaway loop before the request goes out.
+- **Ads, when you ask for it.** Campaigns, line items, targeting, audiences and performance analytics through the [X Ads API](https://docs.x.com/x-ads-api/introduction). Needs its own approval from X and is off unless configured; campaign writes are a second switch again, and anything created starts PAUSED.
+- **Official API only.** No cookie scraping, no password automation, nothing that risks your account.
+
+## Cost — read this first
+
+**X removed its tiered pricing on 2026-02-06. There is no free tier for new developers**, and much of the ecosystem's documentation still says otherwise. Current list prices:
+
+| Action                                            | Price     |
+| ------------------------------------------------- | --------- |
+| Read a post                                       | ~$0.005   |
+| Read a user profile                               | ~$0.010   |
+| Read **your own** data (bookmarks, home timeline) | ~$0.001   |
+| Create a post                                     | ~$0.015   |
+| Create a post **containing a URL**                | ~$0.200   |
+| Monthly read cap                                  | 2,000,000 |
+
+Credits are prepurchased in the developer console; at zero credits, requests are blocked. Three things follow, and they shape the whole server:
+
+1. **`maxResults` defaults to 10, not 50.** A 100-result search is about $0.50.
+2. **Repeat reads are free.** X deduplicates per resource id within a UTC calendar day, so the built-in cache mirrors that exactly — a cache hit is genuinely free, not merely fast.
+3. **Posting should not cost anything.** `x_compose_post` is the default write path and uses a web intent. The paid `x_create_post` stays unregistered unless you opt in twice (`X_API_ALLOW_WRITES=1` **and** `X_API_WRITE_BACKEND=api`).
+
+Run `x_count_recent` before a broad search — it returns totals without reading any posts, so it costs nothing and tells you what the search would cost. `x_build_search_query` is likewise free and local.
+
+> Prices are X's published list rates, transcribed 2026-07-19. Override them via the config file's `pricing` key if they change. `x_usage_report` estimates locally and is not authoritative — the developer portal is.
+
+**Ads is billed elsewhere.** Ads API calls are not metered by X's pay-per-use read pricing, so they cost nothing and never appear in `x_usage_report`. What they manage does: a campaign spends your advertising budget, on X's invoice rather than the API's, and no tool here can see that number. Treat `x_usage_report` as silent on ads rather than as reporting zero.
+
+## Security
+
+- **Supply chain.** Two runtime dependencies: the MCP SDK and zod. The HTTP client is ~250 lines of `fetch`.
+- **Verified builds.** npm releases carry [provenance](https://docs.npmjs.com/generating-provenance-statements) via OIDC trusted publishing; container images are multi-arch, ship an SBOM, and are signed with [cosign](https://docs.sigstore.dev/cosign/signing/overview/).
+- **Your credentials.** Read from the environment or a config file you control, sent only to `api.x.com` (and `ads-api.x.com` when ads is enabled), never logged. The **one** file this server writes is `tokens.json` (mode 600), and only if you use OAuth — it has to persist a rotating refresh token. Everything else is read-only.
+- **Blast radius.** Paid writes are off by default and _unregistered_ rather than refused, so an agent cannot call what does not exist. The free compose path never publishes without a human clicking Post. Ads writes are a separate switch on the same principle, campaigns and line items are created `PAUSED` unless a call explicitly asks otherwise, and budgets are taken in major currency units — the ×1,000,000 mistake is not expressible.
+- **No scraping.** This server never touches session cookies or your password. Tools that do are a ban risk regardless of how they are marketed.
+
+## Configure
+
+**The server starts with no configuration at all.** In that state it registers only the tools that need no credentials — `x_compose_post`, `x_validate_post`, `x_build_search_query` and `x_auth_status` — and `x_auth_status` tells you exactly what to set for the rest. It never refuses to start over missing credentials, because an MCP server that exits shows up in the client as a bare `Connection closed` with the explanation swallowed.
+
+To read anything, one variable is required:
+
+```bash
+export X_API_BEARER_TOKEN="..."   # console.x.com → your app → Keys and Tokens
+```
+
+That covers every public read: lookup, search, profiles, timelines — no OAuth needed. See [Getting credentials](#getting-credentials) below, and [.env.example](./.env.example) for the rest.
+
+### Getting credentials
+
+Create an app at **[console.x.com](https://console.x.com)** — this replaced the old `developer.x.com` portal, and the legacy URL is a common dead end. Sign in, accept the Developer Agreement, then **New App**.
+
+Settings that matter:
+
+| Setting                   | Value                            | Why                                                                                                                                                                    |
+| ------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Type of App**           | **Native App**                   | Native App and Single Page App are _public_ clients — PKCE, no client secret. Web App and Automated App are confidential and issue a secret this server does not want. |
+| **App permissions**       | Read _(or Read and write)_       | Read covers search and bookmarks. Changing this later forces every user to re-authorize.                                                                               |
+| **Callback URI**          | `http://127.0.0.1:8723/callback` | Must match byte for byte. X's docs say to use `127.0.0.1`, not `localhost`, for local development.                                                                     |
+| **Package / Environment** | **Pay-per-use / Production**     | See the warning below.                                                                                                                                                 |
+
+Both credentials appear on the app's **Keys and Tokens** screen: the **Bearer Token** and the **Client ID**.
+
+> **The enrollment trap.** An app left in the legacy Free package or the Development environment logs in successfully and then fails _every_ user-context call with `403 client-not-enrolled`. If that happens, open the app at console.x.com and move it to Pay-per-use / Production. X's own `xurl` CLI documents this as the fix.
+
+Creating an app and getting credentials appears to be free; **making calls is not** — there has been no free tier since 2026-02-06, so you need prepurchased credits before any read succeeds.
+
+**OAuth 2.0** is needed only for bookmarks, your home timeline, and API writes:
+
+```bash
+export X_API_CLIENT_ID="..."      # the Client ID of a Native App (public PKCE client)
+npx @mgcrea/mcp-x-api login       # opens a browser, stores a refresh token (mode 600)
+```
+
+### Ads API access
+
+The Ads API is a separate product behind a separate approval, even though it uses the same OAuth 2.0 login. Three steps, in order:
+
+1. At [console.x.com](https://console.x.com), open the app → **Project Access** → **MANAGE** → select **Ads Project**. This attaches Ads API access to the app id.
+2. Request Ads API access for that app using X's **Ads API Access Form**. Standard Access covers campaigns, creatives, audiences and analytics.
+3. Once approved, run `x-api-mcp login` **again**, then set `X_ADS_ENABLED=1`.
+
+> **The regenerate trap.** A token minted _before_ your Ads API approval does not carry the entitlement. It logs in fine, reads posts fine, and then fails every ads call — which reads as a scope problem and is not one. If ads calls fail right after approval, log in again before debugging anything else.
+
+Your X user also needs a role on at least one ads account, granted in [ads.x.com](https://ads.x.com) rather than the developer console — the API only ever sees accounts you can already see there.
+
+Exercise the write tools against the free sandbox first:
+
+```bash
+export X_ADS_ENABLED=1
+export X_ADS_ALLOW_WRITES=1
+export X_ADS_BASE_URL=https://ads-api-sandbox.twitter.com   # note: not .x.com, which does not resolve
+```
+
+Campaigns and line items are created `PAUSED` unless a call passes `activateImmediately: true`, and every budget is given in major currency units — `50` means 50.00, never 50000000.
+
+### Config file
+
+Instead of environment variables, use `~/.config/x-api/config.json` (camelCase keys, the env names minus the `X_API_` prefix). Environment wins **per field**, so a one-off `X_API_ALLOW_WRITES=0` still overrides a file that says `true`. Unknown keys are an error rather than silently ignored.
+
+```json
+{
+  "bearerToken": "...",
+  "defaultMaxResults": 10,
+  "monthlyBudgetUsd": 25
+}
+```
+
+## Quick start
+
+**A. npx**
+
+```json
+{
+  "mcpServers": {
+    "x-api": {
+      "command": "npx",
+      "args": ["-y", "@mgcrea/mcp-x-api"],
+      "env": { "X_API_BEARER_TOKEN": "..." }
+    }
+  }
+}
+```
+
+**B. Docker (stdio)**
+
+```json
+{
+  "mcpServers": {
+    "x-api": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "-e", "X_API_BEARER_TOKEN", "ghcr.io/mgcrea/mcp-x-api"],
+      "env": { "X_API_BEARER_TOKEN": "..." }
+    }
+  }
+}
+```
+
+**C. From source**
+
+```bash
+pnpm install && pnpm build
+X_API_BEARER_TOKEN=... node dist/cli.js
+```
+
+**Inspect the tools**
+
+```bash
+X_API_BEARER_TOKEN=... npx @modelcontextprotocol/inspector node dist/cli.js
+```
+
+## Tools
+
+Writes are marked `*`, and `†` means a `confirm: true` argument is required. Tools that do not apply to your configuration are not registered at all.
+
+**Posts** — `x_get_post` · `x_get_posts` (batch up to 100 in one request) · `x_get_thread` · `x_get_quotes`
+
+**Users** — `x_get_user` · `x_get_users` · `x_get_user_posts` · `x_get_user_mentions`
+
+**Search** — `x_search_recent` · `x_count_recent` (free — totals only) · `x_build_search_query` (free — local) · `x_search_all` _(needs `X_API_ENABLE_FULL_ARCHIVE`)_
+
+**Compose** — `x_validate_post` (free, local) · `x_compose_post` (free, web intent) · `x_create_post` \*† · `x_delete_post` \*† _(the last two need `X_API_ALLOW_WRITES=1` **and** `X_API_WRITE_BACKEND=api`)_
+
+**Timelines** — `x_get_home_timeline` · `x_get_bookmarks` _(need OAuth login; X serves these for your own account only)_
+
+**Auth** — `x_auth_status` · `x_auth_login` \* · `x_auth_logout` \*† _(the last two need `X_API_CLIENT_ID`)_
+
+**Ads — reads** — `x_ads_get_accounts` · `x_ads_get_funding_instruments` · `x_ads_get_campaigns` · `x_ads_get_line_items` · `x_ads_get_promoted_tweets` · `x_ads_get_targeting_criteria` · `x_ads_search_targeting_options` · `x_ads_get_audiences` · `x_ads_get_stats` · `x_ads_create_stats_job` · `x_ads_get_stats_jobs` · `x_ads_download_stats_job` _(need `X_ADS_ENABLED` and an OAuth login)_
+
+**Ads — writes** \* † — `x_ads_create_campaign` · `x_ads_update_campaign` · `x_ads_delete_campaign` · `x_ads_create_line_item` · `x_ads_update_line_item` · `x_ads_delete_line_item` · `x_ads_create_targeting_criterion` · `x_ads_delete_targeting_criterion` · `x_ads_create_promoted_tweet` · `x_ads_delete_promoted_tweet` · `x_ads_set_entity_status` _(need `X_ADS_ALLOW_WRITES=1`)_
+
+**Usage** — `x_usage_report` · `x_rate_limit_status`
+
+### Reading posts
+
+Ask for a post and you get it resolved, not raw:
+
+```json
+{
+  "post": {
+    "id": "1799000000000000001",
+    "url": "https://x.com/mgcrea/status/1799000000000000001",
+    "author": "@mgcrea (Olivier)",
+    "text": "Shipping v2 today https://acme.dev/v2",
+    "metrics": { "likes": 88, "reposts": 12, "replies": 3, "quotes": 1, "views": 10400 },
+    "quotes": { "id": "1798…", "author": "@acme (Acme Inc)", "text": "v1 was great." },
+    "media": ["photo: https://pbs.twimg.com/media/x.jpg (alt: release notes screenshot)"]
+  },
+  "cost": { "billable_post_reads": 1, "free_from_cache": 0, "estimated_usd": 0.005 }
+}
+```
+
+The `includes` sidecar, `entities`, `edit_history_tweet_ids` and `author_id` never appear — the join is already done, so the model cannot get it wrong.
+
+### Searching without overspending
+
+The cheapest workflow is free until the last step:
+
+1. `x_build_search_query` — turn a description into `rust (from:a OR from:b) lang:en -is:retweet`, with each operator explained. Local, $0.
+2. `x_count_recent` — how many posts match, and what reading them all would cost. Totals only, $0.
+3. `x_search_recent` — actually read them, at ~$0.005 each.
+
+### Posting for free
+
+`x_compose_post` validates the draft against X's **weighted** 280-character limit (every URL counts 23 whatever its length; CJK characters and emoji count 2, so 140 Japanese characters is already full) and hands back a URL:
+
+```json
+{
+  "intent_url": "https://x.com/intent/tweet?text=Shipping+v2+today&url=https%3A%2F%2Facme.dev%2Fv2",
+  "opened": true,
+  "weighted_length": 41,
+  "remaining": 239,
+  "cost": { "estimated_usd": 0, "note": "Web intent — no API call, no quota consumed." }
+}
+```
+
+The URL comes back whether or not a browser could be opened, so Docker and SSH behave identically.
+
+**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 (`inReplyTo`).
+
+## Troubleshooting
+
+**`MCP error -32000: Connection closed`** — the server process died on startup. It does _not_ do this for missing credentials (see [Configure](#configure)), so check, in order:
+
+1. The command actually resolves. `@mgcrea/mcp-x-api` must be published for the `npx` form to work; while developing, point at a built file: `"command": "node", "args": ["/absolute/path/to/dist/cli.js"]`. A relative `./dist/cli.js` depends on the client's working directory.
+2. You ran `pnpm build` — `dist/cli.js` has to exist.
+3. Run it by hand to see stderr, which MCP clients swallow: `X_API_BEARER_TOKEN=... node dist/cli.js`. A config error prints one readable line; add `X_API_DEBUG=1` for the stack.
+
+**Only four tools show up** — no credentials are configured. Call `x_auth_status`; it returns the setup steps.
+
+**I want OAuth but see no way in** — OAuth needs an app you register. See [Getting credentials](#getting-credentials): create a **Native App** at console.x.com, set `X_API_CLIENT_ID` to its Client ID, register the callback, then run `npx @mgcrea/mcp-x-api login` (or call `x_auth_login`). There is no way to log in without a client id — X has nothing to authorize against.
+
+**`403 client-not-enrolled` right after a successful login** — the app is in the legacy Free package or the Development environment. Move it to **Pay-per-use / Production** at console.x.com. Nothing about your token or scopes is wrong.
+
+**Bookmarks or the home timeline say they cannot identify your account** — X's `/2/users/me` is unreliable, and login tolerates it failing. The server retries it lazily on first use and caches the result, so this usually resolves itself; if it persists, it is normally the enrollment trap above rather than a login problem.
+
+## Notes
+
+- **Recent search reaches back 7 days.** `x_get_thread` inherits that limit: an older conversation returns only its root post. Full-archive search (back to March 2006) needs a paid tier and `X_API_ENABLE_FULL_ARCHIVE=1`, and is capped at one request per second.
+- **Bookmarks and the home timeline are self-only.** X does not serve anyone else's, so those tools take no user argument — the id comes from your token.
+- **Rate limits are per endpoint and per credential**, not per plan: recent search allows 450 requests / 15 min app-only vs 300 with a user token. `x_rate_limit_status` shows the headroom X last reported.
+- **Search asks for at least 10 results.** X's minimum for `max_results` is 10, so a request for 3 fetches 10 and returns 3. Billing follows what X actually returned.
+- **`x_usage_report` counts this process only.** It is not persisted across restarts and does not know about spend from other clients.
+
+## Develop
+
+```bash
+pnpm install
+pnpm test          # vitest, fully offline — every test injects fetch
+pnpm typecheck
+pnpm lint && pnpm format:check
+pnpm build
+```
+
+Tests never touch the network: `createServer` accepts an injectable `fetch`, `logger` and `tokenProvider`, and `test/tools.test.ts` drives the real server through the MCP SDK's in-memory transport.
+
+### Publish
+
+```bash
+pnpm dlx release-it          # tags vX.Y.Z; CI publishes to npm and GHCR
+```
+
+### Verify a release
+
+```bash
+npm view @mgcrea/mcp-x-api --json | jq .dist.attestations
+cosign verify ghcr.io/mgcrea/mcp-x-api:latest \
+  --certificate-identity-regexp 'https://github.com/mgcrea/mcp-x-api/.*' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+```
+
+## License
+
+MIT © [Olivier Louvignes](https://github.com/mgcrea)

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { B as setupInstructions, I as hasAdsAccess, L as hasApiCredentials, R as loadConfig, T as startLoginFlow, a as openInBrowser, q as BUILD_INFO, r as createServer } from "./server-BeRiqZxj.js";
+import { ZodError } from "zod";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+//#region src/cli.ts
+const stderrLogger = {
+	debug: (...args) => {
+		if (process.env.X_API_DEBUG) console.error("[x-api-mcp]", ...args);
+	},
+	warn: (...args) => console.error("[x-api-mcp]", ...args),
+	error: (...args) => console.error("[x-api-mcp]", ...args)
+};
+/**
+* The ads segment of the startup banner. It spells out the environment because
+* "LIVE+writes" scrolling past is the last chance anyone has to notice before
+* an agent changes a campaign that spends real money.
+*/
+const describeAds = (config) => {
+	if (!hasAdsAccess(config)) return "off";
+	return `${/ads-api-sandbox\./.test(config.adsBaseUrl) ? "SANDBOX" : "LIVE"}${config.adsAllowWrites ? "+writes" : " read-only"}`;
+};
+const describeAuth = (config) => {
+	const parts = [];
+	if (config.bearerToken) parts.push("bearer");
+	if (config.clientId) parts.push("oauth2");
+	return parts.length > 0 ? parts.join("+") : "none";
+};
+/**
+* `login` / `logout` / `status` run and exit; anything else starts the stdio
+* server. Handled before the transport is created, so these never write to the
+* protocol channel.
+*/
+const runSubcommand = async (command) => {
+	if (![
+		"login",
+		"logout",
+		"status"
+	].includes(command)) return false;
+	const config = loadConfig();
+	const { store, tokenProvider } = createServer({
+		config,
+		logger: stderrLogger
+	});
+	if (command === "status") {
+		const status = tokenProvider.describe();
+		console.error(`ads: ${describeAds(config)}${hasAdsAccess(config) ? ` (${config.adsBaseUrl})` : ""}`);
+		console.error(`app-only bearer: ${status.app ? "configured" : "not configured"}`);
+		console.error(status.user.authenticated ? `oauth2 user: @${status.user.username ?? "?"} (scopes: ${status.user.scopes.join(", ")}, expires ${new Date(status.user.expiresAt).toISOString()})` : `oauth2 user: not authenticated — ${status.user.reason}`);
+		console.error(`token file: ${config.tokenFile}`);
+		return true;
+	}
+	if (command === "logout") {
+		store.clear();
+		console.error(`Removed ${config.tokenFile}. The app-only Bearer token is unaffected.`);
+		return true;
+	}
+	if (!config.clientId) {
+		console.error(`Cannot log in: X_API_CLIENT_ID is not set. Create an OAuth 2.0 app in the X developer portal, enable PKCE, and register this exact callback URL: ${config.redirectUri}`);
+		process.exit(1);
+	}
+	const { tokens } = await startLoginFlow({
+		config,
+		store,
+		openBrowser: openInBrowser,
+		logger: stderrLogger
+	});
+	console.error(`Logged in as @${tokens.username ?? "?"} (scopes: ${tokens.scopes.join(", ")}). Refresh token stored in ${config.tokenFile} with mode 600.`);
+	return true;
+};
+const main = async () => {
+	stderrLogger.warn(`${BUILD_INFO.name}@${BUILD_INFO.version} (git ${BUILD_INFO.gitCommit} ${BUILD_INFO.gitCommitDate}, node ${process.version})`);
+	const command = process.argv[2];
+	if (command && await runSubcommand(command)) return;
+	const config = loadConfig();
+	const { server } = createServer({
+		config,
+		logger: stderrLogger
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	stderrLogger.warn(`x-api-mcp connected (auth=${describeAuth(config)}, writes=${config.allowWrites ? `ENABLED via ${config.writeBackend}` : "disabled"}, compose=intent (free), full-archive=${config.enableFullArchive ? "on" : "off"}, ads=${describeAds(config)}, cache=${config.cacheEnabled ? "on" : "off"})`);
+	if (!hasApiCredentials(config)) {
+		for (const line of setupInstructions(config)) stderrLogger.warn(line);
+		stderrLogger.warn("Call the x_auth_status tool for this same guidance inside your client.");
+	}
+	const shutdown = (signal) => {
+		stderrLogger.warn(`received ${signal}, shutting down`);
+		process.exit(0);
+	};
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+};
+/**
+* A misconfiguration is the most likely first-run failure, and the config
+* schema's messages are written to be read. Dumping a raw ZodError with a stack
+* trace buries them, so unwrap it to just the messages — the stack tells the
+* user nothing they can act on.
+*/
+const describeFatal = (err) => {
+	if (err instanceof ZodError) return err.issues.map((issue) => {
+		const path = issue.path.join(".");
+		return path ? `${path}: ${issue.message}` : issue.message;
+	}).join("\n");
+	return err instanceof Error ? err.message : String(err);
+};
+main().catch((err) => {
+	console.error(`[x-api-mcp] ${describeFatal(err)}`);
+	if (process.env.X_API_DEBUG && err instanceof Error) console.error(err.stack);
+	process.exit(1);
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { StdioServerTransport } from \"@modelcontextprotocol/server/stdio\";\nimport { ZodError } from \"zod\";\n\nimport { BUILD_INFO } from \"#/build-info\";\nimport { startLoginFlow } from \"#/client/oauth\";\nimport { openInBrowser } from \"#/compose/open\";\nimport { hasAdsAccess, hasApiCredentials, loadConfig, setupInstructions } from \"#/config\";\nimport { createServer } from \"#/server\";\n\n// Everything goes to stderr: stdout is the MCP protocol channel, and a stray\n// log line there corrupts the stream.\nconst stderrLogger = {\n  debug: (...args: unknown[]) => {\n    if (process.env.X_API_DEBUG) console.error(\"[x-api-mcp]\", ...args);\n  },\n  warn: (...args: unknown[]) => console.error(\"[x-api-mcp]\", ...args),\n  error: (...args: unknown[]) => console.error(\"[x-api-mcp]\", ...args),\n};\n\n/**\n * The ads segment of the startup banner. It spells out the environment because\n * \"LIVE+writes\" scrolling past is the last chance anyone has to notice before\n * an agent changes a campaign that spends real money.\n */\nconst describeAds = (config: ReturnType<typeof loadConfig>): string => {\n  if (!hasAdsAccess(config)) return \"off\";\n  const env = /ads-api-sandbox\\./.test(config.adsBaseUrl) ? \"SANDBOX\" : \"LIVE\";\n  return `${env}${config.adsAllowWrites ? \"+writes\" : \" read-only\"}`;\n};\n\nconst describeAuth = (config: ReturnType<typeof loadConfig>): string => {\n  const parts: string[] = [];\n  if (config.bearerToken) parts.push(\"bearer\");\n  if (config.clientId) parts.push(\"oauth2\");\n  return parts.length > 0 ? parts.join(\"+\") : \"none\";\n};\n\n/**\n * `login` / `logout` / `status` run and exit; anything else starts the stdio\n * server. Handled before the transport is created, so these never write to the\n * protocol channel.\n */\nconst runSubcommand = async (command: string): Promise<boolean> => {\n  if (![\"login\", \"logout\", \"status\"].includes(command)) return false;\n\n  const config = loadConfig();\n  const { store, tokenProvider } = createServer({ config, logger: stderrLogger });\n\n  if (command === \"status\") {\n    const status = tokenProvider.describe();\n    console.error(\n      `ads: ${describeAds(config)}${hasAdsAccess(config) ? ` (${config.adsBaseUrl})` : \"\"}`,\n    );\n    console.error(`app-only bearer: ${status.app ? \"configured\" : \"not configured\"}`);\n    console.error(\n      status.user.authenticated\n        ? `oauth2 user: @${status.user.username ?? \"?\"} (scopes: ${status.user.scopes.join(\", \")}, ` +\n            `expires ${new Date(status.user.expiresAt).toISOString()})`\n        : `oauth2 user: not authenticated — ${status.user.reason}`,\n    );\n    console.error(`token file: ${config.tokenFile}`);\n    return true;\n  }\n\n  if (command === \"logout\") {\n    store.clear();\n    console.error(`Removed ${config.tokenFile}. The app-only Bearer token is unaffected.`);\n    return true;\n  }\n\n  if (!config.clientId) {\n    console.error(\n      \"Cannot log in: X_API_CLIENT_ID is not set. Create an OAuth 2.0 app in the X developer \" +\n        `portal, enable PKCE, and register this exact callback URL: ${config.redirectUri}`,\n    );\n    process.exit(1);\n  }\n\n  const { tokens } = await startLoginFlow({\n    config,\n    store,\n    openBrowser: openInBrowser,\n    logger: stderrLogger,\n  });\n  console.error(\n    `Logged in as @${tokens.username ?? \"?\"} (scopes: ${tokens.scopes.join(\", \")}). ` +\n      `Refresh token stored in ${config.tokenFile} with mode 600.`,\n  );\n  return true;\n};\n\nconst main = async (): Promise<void> => {\n  stderrLogger.warn(\n    `${BUILD_INFO.name}@${BUILD_INFO.version} (git ${BUILD_INFO.gitCommit} ${BUILD_INFO.gitCommitDate}, node ${process.version})`,\n  );\n\n  const command = process.argv[2];\n  if (command && (await runSubcommand(command))) return;\n\n  const config = loadConfig();\n  const { server } = createServer({ config, logger: stderrLogger });\n  const transport = new StdioServerTransport();\n  await server.connect(transport);\n\n  stderrLogger.warn(\n    `x-api-mcp connected (auth=${describeAuth(config)}, ` +\n      `writes=${config.allowWrites ? `ENABLED via ${config.writeBackend}` : \"disabled\"}, ` +\n      `compose=intent (free), ` +\n      `full-archive=${config.enableFullArchive ? \"on\" : \"off\"}, ` +\n      `ads=${describeAds(config)}, ` +\n      `cache=${config.cacheEnabled ? \"on\" : \"off\"})`,\n  );\n\n  // Connecting successfully but exposing only four tools is confusing unless we\n  // say why. The server no longer refuses to start over this, so the banner and\n  // x_auth_status are the only channels left.\n  if (!hasApiCredentials(config)) {\n    for (const line of setupInstructions(config)) stderrLogger.warn(line);\n    stderrLogger.warn(\"Call the x_auth_status tool for this same guidance inside your client.\");\n  }\n\n  const shutdown = (signal: string): void => {\n    stderrLogger.warn(`received ${signal}, shutting down`);\n    process.exit(0);\n  };\n  process.on(\"SIGINT\", () => shutdown(\"SIGINT\"));\n  process.on(\"SIGTERM\", () => shutdown(\"SIGTERM\"));\n};\n\n/**\n * A misconfiguration is the most likely first-run failure, and the config\n * schema's messages are written to be read. Dumping a raw ZodError with a stack\n * trace buries them, so unwrap it to just the messages — the stack tells the\n * user nothing they can act on.\n */\nconst describeFatal = (err: unknown): string => {\n  if (err instanceof ZodError) {\n    return err.issues\n      .map((issue) => {\n        const path = issue.path.join(\".\");\n        return path ? `${path}: ${issue.message}` : issue.message;\n      })\n      .join(\"\\n\");\n  }\n  return err instanceof Error ? err.message : String(err);\n};\n\nmain().catch((err: unknown) => {\n  console.error(`[x-api-mcp] ${describeFatal(err)}`);\n  if (process.env.X_API_DEBUG && err instanceof Error) console.error(err.stack);\n  process.exit(1);\n});\n"],"mappings":"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"}