x2llm 0.1.0__tar.gz

x2llm-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.env*
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+*.har

x2llm-0.1.0/Makefile

@@ -0,0 +1,35 @@
+.PHONY: help setup install uninstall test lint fmt check refresh clean
+
+-include .env
+export
+
+UV ?= uv
+
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}'
+
+setup: ## Install dependencies into .venv (uv sync)
+	$(UV) sync
+
+install: ## Install x2llm system-wide via uv tool
+	$(UV) tool install --upgrade .
+
+uninstall: ## Remove system-wide x2llm
+	$(UV) tool uninstall x2llm
+
+test: ## Run test suite
+	$(UV) run pytest -q
+
+lint: ## Run ruff checks
+	$(UV) run ruff check src tests scripts
+
+fmt: ## Ruff autofix
+	$(UV) run ruff check --fix src tests scripts
+
+check: lint test ## Everything a change must pass
+
+refresh: ## Regenerate endpoints.py + .env.fresh (txids/cookies) from a HAR: make refresh HAR=…
+	$(UV) run python scripts/har_to_endpoints.py '$(HAR)'
+
+clean: ## Remove caches
+	rm -rf .pytest_cache .ruff_cache __pycache__ src/x2llm/__pycache__

x2llm-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.5
+Name: x2llm
+Version: 0.1.0
+Summary: Read-only x.com (Twitter) API client for LLM agents: library, CLI, and stdio MCP server
+Requires-Python: >=3.12
+Requires-Dist: click>=8
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=2

x2llm-0.1.0/README.md

@@ -0,0 +1,401 @@
+# x2llm
+
+x.com (Twitter) client for LLM agents. One credential set from the
+environment, three faces: a Python library, a `click` CLI, and a stdio MCP
+server. Built for machines first: every command prints exactly one JSON
+document, every error prints `{"error": "..."}` and exits non-zero. Everything
+is read-only **except one deliberate write: `like`** — no posting, replying,
+following, or DMing.
+
+## Key Features
+
+- Search (full operator support: `from:user`, `since:`, `lang:`, `min_faves:` ...)
+- Tweet + reply-thread retrieval
+- Notification tab reading
+- Account analytics (impressions, likes, follows — your own statistics page)
+- Follower/following graphs, typeahead suggestions, unread badge counts
+- Like a tweet (the single write action, explicit everywhere)
+- Same core functions power both CLI and MCP server
+
+## Tech Stack
+
+- **Language**: Python 3.12+
+- **HTTP**: httpx (async)
+- **CLI**: click
+- **MCP**: official `mcp` SDK v2 (stdio transport)
+- **Packaging**: uv + hatchling (src layout)
+- **Tests**: pytest + pytest-asyncio, ruff for linting
+
+## How x.com authentication works (the 30-second version)
+
+The web app authenticates every API call with four pieces:
+
+| Piece | What it is | Secret? |
+|---|---|---|
+| `authorization: Bearer AAAA…` | Public web-client key, baked into x.com's JS bundle. Same for every user. | No |
+| Cookie `auth_token` | The session itself (httpOnly). **Whoever holds it IS the account** — read and write. | **Yes** |
+| Cookie `ct0` | CSRF token. Mirrored verbatim into the `x-csrf-token` header. | Semi |
+| `x-client-transaction-id` | Anti-automation header derived from page state. Only *some* endpoints validate it (search does, most others don't); validated copies are captured per endpoint and expire after a while. | No |
+
+There is no request signing. Bearer + cookies + mirrored CSRF header is the
+whole scheme. `x2llm` encapsulates all of this in `XClient` — nothing above
+that layer ever touches headers.
+
+## Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) (or pip + venv, but commands below assume uv)
+- A browser logged in to x.com (for credentials — 2 minutes, see below)
+
+## Getting Started
+
+### 1. Clone and install
+
+```bash
+cd x2llm
+make setup        # uv sync — creates .venv with all deps
+```
+
+### 2. Extract credentials from your logged-in browser
+
+You need two cookie values from a browser session that is logged in to x.com:
+`auth_token` and `ct0`.
+
+> [!IMPORTANT]
+> `document.cookie` in the devtools console will **not** show `auth_token` —
+> it is httpOnly. Use one of the methods below.
+
+#### Method A — DevTools Application tab (fastest, cookies only)
+
+1. Open `https://x.com` in your logged-in browser
+2. Press `F12` → **Storage** (Firefox) or **Application** (Chrome) → **Cookies** → `https://x.com`
+3. Find the rows `auth_token` and `ct0`, copy their **Value** columns
+4. Put them into `.env`:
+
+```bash
+cp .env.example .env
+```
+
+```
+X_AUTH_TOKEN=paste auth_token value here
+X_CT0=paste ct0 value here
+```
+
+#### Method B — Network tab (gets you everything, incl. transaction ids)
+
+1. `F12` → **Network** tab, filter for `i/api`
+2. Scroll your x.com home timeline once — badge-count calls appear
+3. Click any request, then **Headers** → **Request Headers** → find the `Cookie:` header
+4. Copy the values of `auth_token=…` and `ct0=…` from it into `.env` as above
+
+If you also want `search` to work, export a HAR (see
+[Refreshing captured tokens](#refreshing-captured-tokens)) — search validates
+`x-client-transaction-id`, which the HAR provides.
+
+> [!TIP]
+> Cookies from the Network tab can be pasted wholesale into `X_COOKIE` —
+> including `cf_clearance` — which helps if Cloudflare challenges your
+> machine: `X_COOKIE=auth_token=…; ct0=…; cf_clearance=…`
+
+#### Verifying credentials work
+
+```bash
+source .env && export X_AUTH_TOKEN X_CT0
+uv run x2llm badges
+```
+
+Expected output:
+
+```json
+{
+ "badges": {
+  "dm_unread_count": 0,
+  "ntab_unread_count": 1,
+  "total_unread_count": 1
+ }
+}
+```
+
+### 3. Install the CLI system-wide (optional)
+
+```bash
+make install       # uv tool install — puts `x2llm` on your PATH
+```
+
+## Architecture
+
+### Directory structure
+
+```
+├── src/x2llm/
+│   ├── config.py        # Config.from_env() — every knob is an env var
+│   ├── endpoints.py     # GENERATED: public wire constants (query ids, features, toggles)
+│   ├── client.py        # XClient — the ONLY module that knows the RPC protocol
+│   ├── parse.py         # response-blob walkers → flat dicts (tweet/user/cursor rows)
+│   ├── cores.py         # 8 async service cores, shared by CLI and MCP
+│   ├── cli.py           # click commands, one JSON doc per command
+│   └── mcp.py           # stdio MCP server wrapping the same cores
+├── scripts/
+│   └── har_to_endpoints.py   # regenerate endpoints.py + .env.fresh (txids, cookies) from a HAR
+├── tests/test_x2llm.py       # offline: MockTransport, FakeClient, CliRunner, stdio roundtrip
+├── Makefile
+└── .env.example
+```
+
+### Request lifecycle
+
+```
+click command / MCP tool
+        │
+        ▼
+cores.py  (search, tweet, notifications, … like — dicts in, dicts out)
+        │
+        ▼
+XClient.graphql(key, variables)          — reads
+XClient.graphql_post(key, variables)    — POST GraphQL (home feed, like write)
+XClient.rest(path, params)               — legacy REST reads
+        │   builds URL: GET https://x.com/i/api/graphql/<queryId>/<Operation>
+        │             ?variables=<json>&features=<json>
+        │   attaches: bearer, cookie session, x-csrf-token (== ct0),
+        │             x-twitter-auth-type, per-endpoint x-client-transaction-id
+        ▼
+httpx.AsyncClient
+        │
+        ▼
+x.com → 200 JSON (or XApiError with a human hint)
+        │
+        ▼
+parse.py walkers (walk / collect_tweets / collect_cursors / notification_rows)
+        │
+        ▼
+flat JSON row: {id, author, text, likes, views, …}
+```
+
+### Rate limiting
+
+XClient spaces requests so at most `X_RATE_LIMIT` per minute leave the process
+(default 30 — deliberately below what the session allows; x.com's own
+per-endpoint budgets seen in responses are far higher, e.g. 12 000 / 15 min
+for following-list). The limiter is a simple monotonic-clock slot allocator
+under an asyncio lock; 0 disables. Server-side 429s surface as errors with a
+hint instead of being retried — the right answer is to slow down.
+
+### Design invariants
+
+- **RPC is encapsulated.** Only `client.py` imports httpx or knows what a
+  header is. Only `endpoints.py` holds wire constants, and it is generated.
+- **Cores are transport-agnostic.** They call `graphql(key, variables)` /
+  `graphql_mutation(key, variables)` / `rest(path, params)` — anything with
+  those three async methods works (see `FakeClient` in the tests). This is
+  what keeps the suite offline.
+- **One code path.** CLI handlers and MCP tools bind the same core functions;
+  behavior can never drift between the two surfaces.
+- **Writes are isolated.** Read feeds are GET, except POST-fed timelines
+  (home — the browser itself scrolls via POST). The single write,
+  `like`, shares the POST primitive but nothing else does. The MCP server
+  registers it with `read_only_hint=false` and a loud description.
+- **One pagination model.** Every list core (`home`, `search`, `tweet`,
+  `notifications`, `following`) returns a `cursor`; feed it back for the next
+  page, `null` means end. The home timeline has two tabs served by different
+  operations: `for_you` (HomeTimeline, algorithmic) and `following`
+  (HomeLatestTimeline, chronological) — cursors are tab-specific, pass back
+  what the same tab returned.
+
+## Environment Variables
+
+### Required
+
+| Variable | Description | How to get it |
+|---|---|---|
+| `X_AUTH_TOKEN` | Session secret (`auth_token` cookie) | DevTools → Cookies (see Getting Started) |
+| `X_CT0` | CSRF token (`ct0` cookie) | same |
+
+### Optional
+
+| Variable | Description | Default |
+|---|---|---|
+| `X_COOKIE` | Full `Cookie` header verbatim (overrides the two vars; add `cf_clearance` here if Cloudflare challenges) | composed from the two above |
+| `X_BEARER` | Web-client bearer token | current public one (in `endpoints.py`) |
+| `X_USER_AGENT` | Should match the browser the cookies came from | Firefox/Linux UA |
+| `X_API_BASE` | API root | `https://x.com/i/api` |
+| `X_TIMEOUT` | Per-request timeout, seconds | `20` |
+| `X_RATE_LIMIT` | Max requests per minute, client-enforced (0 = unlimited) | `30` |
+| `X_TXIDS` | JSON `{"search": "<x-client-transaction-id>", ...}` — per-operation transaction ids; only some endpoints need them and they expire within hours. Written to `.env.fresh` by `make refresh`. | `{}` |
+
+The `Makefile` auto-exports `.env`; for other entry points source it yourself
+or use something like `direnv`.
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `x2llm home [--tab for_you\|following] [--limit N] [--cursor C]` | Home timeline; scroll with the returned cursor |
+| `x2llm badges` | Unread notification/DM counts — cheapest auth check |
+| `x2llm user SCREEN_NAME` | Profile lookup: bio, url, follower counts, verification |
+| `x2llm me` | Viewer id + follower counts |
+| `x2llm suggest QUERY` | Typeahead topics/users for a prefix |
+| `x2llm search QUERY [--limit N] [--product Top\|Latest\|Media] [--cursor C]` | Full search with X operators |
+| `x2llm tweet ID [--cursor C]` | Tweet + reply thread |
+| `x2llm notifications [--limit N] [--cursor C]` | Notification tab |
+| `x2llm analytics [--days N]` | Engagement statistics (1–28 days) |
+| `x2llm following USER [--limit N] [--cursor C]` | Accounts USER follows (id or screen name) |
+| `x2llm like TWEET_ID` | **Like a tweet — real, public, notifies the author** |
+| `x2llm mcp` | Run as stdio MCP server |
+
+All pagination works the same way: the response carries a `cursor`; feed it
+back via `--cursor` for the next page (`null` means end).
+
+Example — search, take the cursor, get page two:
+
+```bash
+uv run x2llm search "solana lang:en min_faves:100" --limit 10
+uv run x2llm search "solana lang:en min_faves:100" --limit 10 --cursor 'DAACCgACHUB…'
+```
+
+## MCP Server
+
+`x2llm mcp` speaks MCP over stdio with 11 tools — the same cores as the CLI.
+Ten are annotated `read_only_hint` (`get_home_timeline`, `get_user`,
+`get_badges`, `me`, `suggest`, `search`, `get_tweet`, `get_notifications`,
+`get_analytics`, `get_following`); the eleventh, `like_tweet`, is the one write and is registered with `read_only_hint=false`
+and a description that instructs agents to call it only on explicit user
+request. Liking an already-liked tweet returns the server's idempotent
+rejection (`{"result": "error", "detail": "... has already favorited ..."}`)
+— no state changes.
+
+Wire it into an MCP client config (example for Claude-style configs):
+
+```json
+{
+  "mcpServers": {
+    "x": {
+      "command": "/absolute/path/to/x2llm/.venv/bin/x2llm",
+      "args": ["mcp"],
+      "env": {
+        "X_AUTH_TOKEN": "…",
+        "X_CT0": "…"
+      }
+    }
+  }
+}
+```
+
+Quick smoke test by hand:
+
+```bash
+printf '%s\n%s\n%s\n' \
+ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
+ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+ '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
+ | uv run x2llm mcp
+```
+
+## Refreshing captured tokens
+
+The package ships only **public, session-independent constants**
+(`endpoints.py`: query ids, features blobs, fieldToggles — identical for every
+user, taken from x.com's JS bundles; they rotate on a months scale). Everything
+session-scoped comes from the environment: `X_AUTH_TOKEN`, `X_CT0`, `X_TXIDS`.
+**Transaction ids expire fast (observed: tens of minutes to hours)** and only
+some endpoints enforce them — `search` is the one that hurts. Nothing
+user-specific ever enters the package, so it is safe to publish.
+
+Refreshes are **incremental**: entries in the HARs you pass win; operations
+they don't contain keep their previous query ids from the existing
+`endpoints.py`. One small HAR that only captured a search is enough — the run
+fails only if the merged result is still incomplete. The generator prints
+which endpoints were refreshed vs kept, and writes `.env.fresh` with the
+session's `X_AUTH_TOKEN`, `X_CT0` and `X_TXIDS` (quoted so both
+`source .env` and the Makefile include parse it).
+
+When `search` or `like` starts failing with an empty 404 (the error text says
+so):
+
+1. Open x.com logged in → `F12` → Network → filter `i/api`
+2. Visit: the **home timeline** (badges), run one **search**, open one
+   **tweet**, open **notifications**, open **x.com/analytics**, open one
+   **user profile**, **like** one tweet, **scroll both home tabs** (FOR YOU
+   and FOLLOWING) two screens (that touches all nine operations)
+3. Export HAR: Network ⚙️ gear → *Save all as HAR*
+4. Regenerate:
+
+```bash
+make refresh HAR='../x.com_Archive [26-10-07 13-27-31].har'
+make check        # public constants only; CI-safe, no secrets touched
+cp .env.fresh .env  # your fresh session credentials + X_TXIDS
+```
+
+While `search`/`like` are down, everything else keeps working — tweet,
+notifications, analytics, following, suggest, both home tabs and user lookups
+work without any transaction id at all.
+Features blobs and fieldToggles are captured per endpoint (x.com ships
+several variants). The generator also extracts `X_AUTH_TOKEN`/`X_CT0` from
+the capture's cookies and writes them to `.env.fresh` (it never touches an
+existing `.env`; review and `cp .env.fresh .env`). Both files hold live
+session secrets and are gitignored. The generator accepts several HAR files
+and merges them, so captures can be split across sessions:
+
+```bash
+uv run python scripts/har_to_endpoints.py 'reads.har' 'like.har'
+```
+
+## Testing
+
+```bash
+make check        # ruff + pytest — the gate every change must pass
+uv run pytest -q tests/test_x2llm.py::test_search_core_truncates_and_returns_cursor   # single test
+```
+
+The suite is offline by design: `httpx.MockTransport` exercises the real
+`XClient` request construction, `FakeClient` exercises cores, `CliRunner`
+exercises commands, and one subprocess test does a full MCP stdio handshake
+(`initialize` + `tools/list`) with dummy credentials. No test needs your real
+account or network.
+
+## Troubleshooting
+
+### `{"error": "…: HTTP 404 … transaction-id expired"}`
+
+Search hit its transaction-id expiry. Refresh per the section above. Other
+commands are unaffected.
+
+### `{"error": "…: HTTP 401/403 …"}`
+
+Your `auth_token`/`ct0` are stale (logged out elsewhere? password change?
+long-lived capture?). Re-extract both from the browser. If your IP/UA changed
+since capture, also set `X_COOKIE` with the full header including
+`cf_clearance` and a matching `X_USER_AGENT`.
+
+### `{"error": "missing environment variables: X_AUTH_TOKEN, X_CT0"}`
+
+Self-explanatory — `.env` not loaded or empty. The Makefile auto-exports it;
+elsewhere `source .env && export X_AUTH_TOKEN X_CT0`.
+
+### Empty body with a `cf-ray` header
+
+Cloudflare edge rejection, not x.com. Keep the same User-Agent as the browser
+you captured from; if it persists, copy the full `Cookie` header into
+`X_COOKIE`.
+
+### `author: null` in results
+
+x.com is A/B-testing a new user-object shape. `parse.py` reads both the old
+(`legacy`) and new (`core`) paths; if both are null you are looking at a third
+shape — file it with a response sample.
+
+## Security Notes
+
+> [!CAUTION]
+> `auth_token` is a full-account bearer credential: read **and write** access
+> until it expires. A `.env`, a shell history line, or a HAR file containing
+> it must be treated like a password file. HAR exports additionally contain
+> every response body the browser saw. `*.har` is gitignored for a reason —
+> keep it that way.
+
+This project is API-usage of your own logged-in session for personal tooling
+(reads + likes you explicitly request). Respect x.com's terms of service and rate limits; the
+client sends plain GETs at human-scale speeds and has no retry hammering.
+
+## License
+
+Internal tool, no license granted. All rights reserved.

x2llm-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "x2llm"
+version = "0.1.0"
+description = "Read-only x.com (Twitter) API client for LLM agents: library, CLI, and stdio MCP server"
+requires-python = ">=3.12"
+dependencies = ["click>=8", "httpx>=0.27", "mcp>=2"]
+
+[project.scripts]
+x2llm = "x2llm.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/x2llm"]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.6"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

x2llm-0.1.0/scripts/har_to_endpoints.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""Regenerate src/x2llm/endpoints.py from browser HAR captures of x.com.
+
+Usage: uv run python scripts/har_to_endpoints.py archive1.har [archive2.har ...]
+
+The package ships only public, session-independent constants (query ids,
+features blobs, fieldToggles - from x.com's JS bundles, identical for every
+user). Session-scoped values come from the environment instead: the
+x-client-transaction-ids the browser sent are written to .env.fresh as
+X_TXIDS (JSON, per operation) - they expire within hours, so they could
+never ship in the package. Same for X_AUTH_TOKEN/X_CT0 (cookie session).
+.env.fresh never touches an existing .env - copy it over yourself. HARs and
+.env.fresh contain live session secrets; both are gitignored.
+
+Incremental: entries from the given HARs take precedence; operations they
+don't contain are carried over from the existing endpoints.py. A single-HAR
+refresh that only captured one page is fine. The run fails only if the
+merged result is still incomplete.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import urllib.parse
+from pathlib import Path
+
+READS = {
+    "SearchTimeline": "search",
+    "TweetDetail": "tweet",
+    "NotificationsTimeline": "notifications",
+    "ViewerBadgeCounts": "badges",
+    "accountOverviewDailyQuery": "analytics",
+    "UserByScreenName": "user",
+}
+POST_READS = {"HomeTimeline": "home",  # FOR YOU tab
+              "HomeLatestTimeline": "home_following"}  # FOLLOWING tab
+MUTATIONS = {"FavoriteTweet": "like"}
+
+
+def load_existing(endpoints: Path) -> tuple[dict, str]:
+    if not endpoints.exists():
+        return {}, ""
+    namespace: dict = {}
+    exec(endpoints.read_text(), namespace)  # noqa: S102 - our own generated file
+    return dict(namespace.get("GRAPHQL") or {}), namespace.get("BEARER") or ""
+
+
+def run(paths: list[str], out: Path) -> tuple[dict, str]:
+    graphql, bearer = load_existing(out)
+    previous = set(graphql)
+    fresh: set[str] = set()
+    for arg in paths:
+        har = json.loads(Path(arg).read_text())
+        for e in har["log"]["entries"]:
+            req = e["request"]
+            url = req["url"]
+            if "/i/api/graphql/" not in url:
+                continue
+            op = url.split("/graphql/", 1)[1].split("/", 1)[1].split("?", 1)[0]
+            key = READS.get(op) or POST_READS.get(op) or MUTATIONS.get(op)
+            if key is None or key in fresh:
+                continue
+            if op in POST_READS and req["method"] != "POST":
+                continue  # first page may arrive as GET; capture the scroll POST
+            headers = {h["name"].lower(): h["value"] for h in req["headers"]}
+            entry = {
+                "query_id": url.split("/graphql/", 1)[1].split("/", 1)[0],
+                "name": op,
+                "method": "post" if op in MUTATIONS or op in POST_READS else "get",
+            }
+            if req["method"] == "POST" and req.get("postData", {}).get("text"):
+                body = json.loads(req["postData"]["text"])
+                if "features" in body:
+                    entry["features"] = body["features"]
+                if "fieldToggles" in body:
+                    entry["toggles"] = body["fieldToggles"]
+            else:
+                q = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+                if "features" in q:
+                    entry["features"] = json.loads(q["features"][0])
+                if "fieldToggles" in q:
+                    entry["toggles"] = json.loads(q["fieldToggles"][0])
+            graphql[key] = entry
+            fresh.add(key)
+            if not bearer:
+                bearer = headers.get("authorization", "")
+    wanted = set(READS.values()) | set(POST_READS.values()) | set(MUTATIONS.values())
+    missing = sorted(wanted - set(graphql))
+    if missing:
+        sys.exit(f"HARs are missing operations: {missing} - capture those pages, re-export")
+    out.write_text(
+        "# GENERATED by scripts/har_to_endpoints.py from browser HAR captures. Do not edit.\n"
+        "# Public, session-independent constants only (query ids, features, toggles).\n"
+        "# Session-scoped values (transaction ids) live in the X_TXIDS env var.\n"
+        "# Regenerate: uv run python scripts/har_to_endpoints.py <archive.har> [...]\n"
+        f'BEARER = {bearer!r}\n'
+        f"GRAPHQL = {graphql!r}\n"
+    )
+    print(f"wrote {out} ({len(graphql)} endpoints; refreshed: {sorted(fresh) or 'none'}; "
+          f"kept from previous: {sorted(previous - fresh) or 'none'})")
+    return graphql, bearer
+
+
+def write_env_fresh(paths: list[str]) -> None:
+    txids: dict[str, str] = {}
+    cookie_header = user_agent = ""
+    auth_token = ct0 = ""
+    for arg in paths:
+        har = json.loads(Path(arg).read_text())
+        for e in har["log"]["entries"]:
+            req = e["request"]
+            headers = {h["name"].lower(): h["value"] for h in req["headers"]}
+            cookies = {}
+            for part in headers.get("cookie", "").split("; "):
+                name, _, value = part.partition("=")
+                cookies[name] = value
+            if not auth_token and cookies.get("auth_token") and cookies.get("ct0"):
+                auth_token, ct0 = cookies["auth_token"], cookies["ct0"]
+                cookie_header = headers.get("cookie", "")
+                user_agent = headers.get("user-agent", "")
+            op = req["url"].split("/graphql/", 1)[1].split("/", 1)[1].split("?", 1)[0] \
+                if "/i/api/graphql/" in req["url"] else ""
+            key = READS.get(op) or POST_READS.get(op) or MUTATIONS.get(op)
+            if key and key not in txids:
+                tx = headers.get("x-client-transaction-id", "")
+                if tx:
+                    txids[key] = tx
+    if not auth_token:
+        return
+    env_out = Path(__file__).resolve().parents[1] / ".env.fresh"
+    env_out.write_text(
+        "# Generated by har_to_endpoints.py - live session secrets. Keep private.\n"
+        f"X_AUTH_TOKEN={auth_token}\n"
+        f"X_CT0={ct0}\n"
+        "X_TXIDS='" + json.dumps(txids, separators=(",", ":")) + "'\n"
+        f"# X_USER_AGENT={user_agent}\n"
+        f"# X_COOKIE={cookie_header}\n"
+    )
+    print(f"wrote {env_out} ({len(txids)} txids) - review and: cp .env.fresh .env")
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        sys.exit(__doc__)
+    out = Path(__file__).resolve().parents[1] / "src" / "x2llm" / "endpoints.py"
+    run(sys.argv[1:], out)
+    write_env_fresh(sys.argv[1:])
+    return 0
+
+
+if __name__ == "__main__":
+    main()

x2llm-0.1.0/src/x2llm/__init__.py

@@ -0,0 +1,5 @@
+"""x2llm - read-only x.com (Twitter) API client for LLM agents.
+
+Library + CLI + stdio MCP server. Credentials come exclusively from the
+environment (12-factor); the HTTP/RPC layer is encapsulated in XClient.
+"""

x2llm-0.1.0/src/x2llm/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()