x2llm 0.1.0__py3-none-any.whl

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/__main__.py

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

x2llm/cli.py

@@ -0,0 +1,145 @@
+"""Click CLI. Every command prints one JSON document; errors print {"error": ...} and exit 1."""
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+
+import click
+
+from . import cores
+from .client import XApiError, XClient
+from .config import Config, ConfigError
+
+
+def out(obj) -> None:
+    print(json.dumps(obj, default=str, ensure_ascii=False, indent=1))
+
+
+async def _run(make_coro: Callable[[XClient], Awaitable]) -> object:
+    config = Config.from_env()
+    client = XClient(config)
+    try:
+        return await make_coro(client)
+    finally:
+        await client.aclose()
+
+
+def invoke(make_coro) -> None:
+    try:
+        result = asyncio.run(_run(make_coro))
+    except (ConfigError, XApiError) as e:
+        out({"error": str(e)})
+        raise SystemExit(1) from None
+    out(result)
+
+
+@click.group()
+@click.version_option()
+def cli() -> None:
+    """x2llm - read-only x.com (Twitter) API client for agents. JSON out."""
+
+
+@cli.command()
+@click.option("--limit", type=int, default=20, show_default=True)
+@click.option("--cursor", default=None, help="Pagination cursor from a previous page.")
+@click.option("--tab", type=click.Choice(["for_you", "following"]), default="for_you", show_default=True)
+def home(limit: int, cursor: str | None, tab: str) -> None:
+    """Your home timeline (for_you or following); scroll with the returned cursor."""
+    invoke(lambda c: cores.home(c, limit=limit, cursor=cursor, tab=tab))
+
+
+@cli.command()
+def badges() -> None:
+    """Unread notification/DM counts. Cheapest auth check."""
+    invoke(lambda c: cores.badges(c))
+
+
+@cli.command()
+@click.argument("screen_name")
+def user(screen_name: str) -> None:
+    """Profile of a user by screen name: bio, follower counts, verification."""
+    invoke(lambda c: cores.user(c, screen_name))
+
+
+@cli.command()
+def me() -> None:
+    """Viewer identity + follower counts."""
+    invoke(lambda c: cores.me(c))
+
+
+@cli.command()
+@click.argument("query")
+def suggest(query: str) -> None:
+    """Search typeahead: topic and user suggestions for a prefix."""
+    invoke(lambda c: cores.suggest(c, query))
+
+
+@cli.command()
+@click.argument("query")
+@click.option("--limit", type=int, default=20, show_default=True)
+@click.option("--product", type=click.Choice(["Top", "Latest", "Media"]), default="Top", show_default=True)
+@click.option("--cursor", default=None, help="Pagination cursor from a previous page.")
+def search(query: str, limit: int, product: str, cursor: str | None) -> None:
+    """Full search. Supports operators: from:user, since:, lang:, min_faves: ..."""
+    invoke(lambda c: cores.search(c, query, limit=limit, product=product, cursor=cursor))
+
+
+@cli.command()
+@click.argument("tweet_id")
+@click.option("--cursor", default=None, help="Pagination cursor for more replies.")
+def tweet(tweet_id: str, cursor: str | None) -> None:
+    """One tweet plus its reply thread."""
+    invoke(lambda c: cores.tweet(c, tweet_id, cursor=cursor))
+
+
+@cli.command()
+@click.option("--limit", type=int, default=20, show_default=True)
+@click.option("--cursor", default=None, help="Pagination cursor from a previous page.")
+def notifications(limit: int, cursor: str | None) -> None:
+    """Your notification tab."""
+    invoke(lambda c: cores.notifications(c, limit=limit, cursor=cursor))
+
+
+@cli.command()
+@click.option("--days", type=int, default=7, show_default=True, help="Window length (1-28).")
+def analytics(days: int) -> None:
+    """Your engagement statistics (impressions, likes, follows ...)."""
+    invoke(lambda c: cores.analytics(c, days=days))
+
+
+@cli.command()
+@click.argument("user")
+@click.option("--limit", type=int, default=20, show_default=True)
+@click.option("--cursor", default=None, help="Pagination cursor from a previous page.")
+def following(user: str, limit: int, cursor: str | None) -> None:
+    """Accounts USER follows. USER is a numeric id or a screen name."""
+    invoke(lambda c: cores.following(c, user, limit=limit, cursor=cursor))
+
+
+@cli.command()
+def mcp() -> None:
+    """Run as a stdio MCP server (same tool surface, read-only)."""
+    from .mcp import serve
+
+    asyncio.run(serve())
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        cli(args=argv, standalone_mode=True)
+    except click.exceptions.Abort:
+        return 130
+    return 0
+
+
+
+@cli.command()
+@click.argument("tweet_id")
+def like(tweet_id: str) -> None:
+    """Like a tweet. REAL action: publicly visible, notifies the author."""
+    invoke(lambda c: cores.like(c, tweet_id))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

x2llm/client.py

@@ -0,0 +1,133 @@
+"""XClient: the only module that knows how x.com RPC works.
+
+Everything above this layer deals in plain dicts. Three primitives:
+
+- graphql(key, variables) -> dict          (GET /i/api/graphql/<queryId>/<Op>)
+- graphql_post(key, variables) -> dict    (POST /i/api/graphql/... — feeds + writes)
+- rest(path, params) -> dict               (GET /i/api/1.1/... legacy REST)
+
+Auth = public web bearer + cookie session (auth_token + ct0) + x-csrf-token
+mirroring ct0. Some endpoints additionally validate x-client-transaction-id
+(per operation in the X_TXIDS env var, path-bound, expire server-side).
+
+A client-side rate limiter spaces requests at most X_RATE_LIMIT per minute
+(default 30, 0 disables) so the tool stays inside power-user territory.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+
+import httpx
+
+from .config import Config
+from .endpoints import GRAPHQL
+
+
+class XApiError(Exception):
+    def __init__(self, message: str, status: int | None = None):
+        super().__init__(message)
+        self.status = status
+
+
+class XClient:
+    def __init__(self, config: Config, transport: httpx.AsyncBaseTransport | None = None):
+        self.config = config
+        self._http = httpx.AsyncClient(timeout=config.timeout, transport=transport)
+        self._min_interval = 60.0 / config.rate_per_min if config.rate_per_min > 0 else 0.0
+        self._rl_lock = asyncio.Lock()
+        self._next_slot = 0.0
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def graphql(self, key: str, variables: dict) -> dict:
+        """Read: GET with variables (+ per-endpoint features/fieldToggles) in the query string."""
+        ep = GRAPHQL[key]
+        params = {"variables": json.dumps(variables, separators=(",", ":"))}
+        if ep.get("features"):
+            params["features"] = json.dumps(ep["features"], separators=(",", ":"))
+        if ep.get("toggles"):
+            params["fieldToggles"] = json.dumps(ep["toggles"], separators=(",", ":"))
+        await self._throttle()
+        response = await self._http.get(
+            f"{self.config.api_base}/graphql/{ep['query_id']}/{ep['name']}",
+            params=params,
+            headers=self._headers(self.config.txids.get(key)),
+        )
+        return self._json(response, ep["name"])
+
+    async def graphql_post(self, key: str, variables: dict) -> dict:
+        """POST GraphQL: body carries variables+queryId (+features/fieldToggles
+        from the registry). Used for POST-fed timelines (home) and the like write."""
+        ep = GRAPHQL[key]
+        body = {"variables": variables, "queryId": ep["query_id"]}
+        if ep.get("features"):
+            body["features"] = ep["features"]
+        if ep.get("toggles"):
+            body["fieldToggles"] = ep["toggles"]
+        await self._throttle()
+        response = await self._http.post(
+            f"{self.config.api_base}/graphql/{ep['query_id']}/{ep['name']}",
+            json=body,
+            headers=self._headers(self.config.txids.get(key)),
+        )
+        return self._json(response, ep["name"])
+
+    async def rest(self, path: str, params: dict) -> dict:
+        await self._throttle()
+        response = await self._http.get(
+            f"{self.config.api_base}{path}", params=params, headers=self._headers(None)
+        )
+        return self._json(response, path)
+
+    async def _throttle(self) -> None:
+        if not self._min_interval:
+            return
+        async with self._rl_lock:
+            now = time.monotonic()
+            wait = self._next_slot - now
+            if wait > 0:
+                await asyncio.sleep(wait)
+                now = time.monotonic()
+            self._next_slot = now + self._min_interval
+
+    def _headers(self, txid: str | None) -> dict[str, str]:
+        headers = {
+            "authorization": self.config.bearer,
+            "cookie": self.config.cookie_header,
+            "x-csrf-token": self.config.ct0,
+            "x-twitter-auth-type": "OAuth2Session",
+            "x-twitter-active-user": "yes",
+            "x-twitter-client-language": "en",
+            "user-agent": self.config.user_agent,
+            "accept": "*/*",
+        }
+        if txid:
+            headers["x-client-transaction-id"] = txid
+        return headers
+
+    @staticmethod
+    def _json(response: httpx.Response, what: str) -> dict:
+        if response.status_code != 200:
+            hint = ""
+            if response.status_code == 404 and not response.content:
+                hint = (
+                    " | hint: empty 404 usually means this endpoint's "
+                    "x-client-transaction-id expired - refresh X_TXIDS from a "
+                    "fresh capture (README - Refreshing captured tokens)"
+                )
+            elif response.status_code in (401, 403):
+                hint = (
+                    " | hint: credentials rejected - check X_AUTH_TOKEN / X_CT0, "
+                    "or set X_COOKIE to the full browser Cookie header "
+                    "(incl. cf_clearance)"
+                )
+            elif response.status_code == 429:
+                hint = " | hint: rate limited by x.com - slow down or raise the wait"
+            raise XApiError(
+                f"{what}: HTTP {response.status_code} {response.text[:200]}{hint}",
+                status=response.status_code,
+            )
+        return response.json()

x2llm/config.py

@@ -0,0 +1,73 @@
+"""Environment-driven configuration (12-factor: all config from the env)."""
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from .endpoints import BEARER
+
+DEFAULT_USER_AGENT = "Mozilla/5.0 (X11; Linux x86_64; rv:152.0) Gecko/20100101 Firefox/152.0"
+REQUIRED = ("X_AUTH_TOKEN", "X_CT0")
+
+
+class ConfigError(Exception):
+    pass
+
+
+def _parse_txids(raw: str | None) -> dict[str, str]:
+    if not raw:
+        return {}
+    raw = raw.strip()
+    if len(raw) > 1 and raw[0] == raw[-1] and raw[0] in "'\"":
+        raw = raw[1:-1]  # tolerate quoting from `source .env` / make -include
+    try:
+        parsed = json.loads(raw)
+    except ValueError as e:
+        raise ConfigError(f"X_TXIDS is not valid JSON: {e}") from e
+    if not isinstance(parsed, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) for k, v in parsed.items()
+    ):
+        raise ConfigError("X_TXIDS must be a JSON object of {operation: transaction-id}")
+    return parsed
+
+
+@dataclass(frozen=True)
+class Config:
+    auth_token: str
+    ct0: str
+    cookie: str | None
+    bearer: str
+    user_agent: str
+    api_base: str
+    timeout: float
+    rate_per_min: int
+    txids: dict[str, str]
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] | None = None) -> Config:
+        env = os.environ if env is None else env
+        missing = [k for k in REQUIRED if not env.get(k)]
+        if missing:
+            raise ConfigError(
+                f"missing environment variables: {', '.join(missing)} "
+                "(see README - Credentials)"
+            )
+        return cls(
+            auth_token=env["X_AUTH_TOKEN"],
+            ct0=env["X_CT0"],
+            cookie=env.get("X_COOKIE") or None,
+            bearer=env.get("X_BEARER") or BEARER,
+            user_agent=env.get("X_USER_AGENT") or DEFAULT_USER_AGENT,
+            api_base=env.get("X_API_BASE", "https://x.com/i/api"),
+            timeout=float(env.get("X_TIMEOUT", "20")),
+            rate_per_min=int(env.get("X_RATE_LIMIT", "30")),
+            txids=_parse_txids(env.get("X_TXIDS")),
+        )
+
+    @property
+    def cookie_header(self) -> str:
+        if self.cookie:
+            return self.cookie
+        return f"auth_token={self.auth_token}; ct0={self.ct0}"

x2llm/cores.py

@@ -0,0 +1,218 @@
+"""Service cores - shared by CLI and MCP server. Reads + the like mutation."""
+from __future__ import annotations
+
+import base64
+from datetime import UTC, datetime
+
+from .client import XApiError
+from .parse import collect_cursors, collect_tweets, notification_rows, user_row
+
+DAY_MS = 86_400_000
+
+
+async def badges(c) -> dict:
+    data = await c.graphql("badges", {})
+    result = data["data"]["viewer_v2"]["user_results"]["result"]
+    return {"badges": result.get("badge_counts") or {}}
+
+
+async def suggest(c, query: str, lang: str = "en") -> dict:
+    data = await c.rest(
+        "/1.1/search/typeahead.json", {"q": query, "src": "search_box", "lang": lang}
+    )
+    return {
+        "topics": [t.get("topic") for t in data.get("topics") or []],
+        "users": [
+            {
+                "id": u.get("id_str"),
+                "screen_name": u.get("screen_name"),
+                "name": u.get("name"),
+            }
+            for u in data.get("users") or []
+        ],
+    }
+
+
+async def search(
+    c, query: str, limit: int = 20, product: str = "Top", cursor: str | None = None
+) -> dict:
+    variables = {
+        "rawQuery": query,
+        "count": limit,
+        "querySource": "typed_query",
+        "product": product,
+        "withGrokTranslatedBio": False,
+        "withQuickPromoteEligibilityTweetFields": False,
+    }
+    if cursor:
+        variables["cursor"] = cursor
+    data = await c.graphql("search", variables)
+    return {
+        "tweets": collect_tweets(data)[:limit],
+        "cursor": collect_cursors(data).get("bottom"),
+    }
+
+
+async def tweet(c, tweet_id: str, cursor: str | None = None) -> dict:
+    variables = {
+        "focalTweetId": str(tweet_id),
+        "referrer": "search",
+        "with_rux_injections": False,
+        "rankingMode": "Relevance",
+        "includePromotedContent": True,
+        "withCommunity": True,
+        "withQuickPromoteEligibilityTweetFields": True,
+        "withBirdwatchNotes": True,
+        "withVoice": True,
+    }
+    if cursor:
+        variables["cursor"] = cursor
+    data = await c.graphql("tweet", variables)
+    tweets = collect_tweets(data)
+    return {
+        "tweet": tweets[0] if tweets else None,
+        "replies": tweets[1:],
+        "cursor": collect_cursors(data).get("bottom"),
+    }
+
+
+async def notifications(c, limit: int = 20, cursor: str | None = None) -> dict:
+    variables = {"timeline_type": "All", "count": limit}
+    if cursor:
+        variables["cursor"] = cursor
+    data = await c.graphql("notifications", variables)
+    return {
+        "notifications": notification_rows(data)[:limit],
+        "cursor": collect_cursors(data).get("bottom"),
+    }
+
+
+def _analytics_variables(days: int) -> dict:
+    now = datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
+    to_ms, span = int(now.timestamp() * 1000), days * DAY_MS
+    prev_to_ms = to_ms - span
+
+    def iso(ms: int) -> str:
+        return datetime.fromtimestamp(ms / 1000, tz=UTC).isoformat().replace("+00:00", "Z")
+
+    return {
+        "current_from": to_ms - span,
+        "current_from_iso": iso(to_ms - span),
+        "current_to": to_ms,
+        "current_to_iso": now.isoformat().replace("+00:00", "Z"),
+        "prev_from": prev_to_ms - span,
+        "prev_from_iso": iso(prev_to_ms - span),
+        "prev_to": prev_to_ms,
+        "prev_to_iso": iso(prev_to_ms),
+        "backfill_from": to_ms - 2 * DAY_MS,
+        "backfill_to": to_ms,
+        "show_realtime_active_followers": True,
+        "show_verified_followers": True,
+    }
+
+
+def _viewer_id(encoded: str) -> str | None:
+    try:
+        decoded = base64.b64decode(encoded).decode()
+        return decoded.split(":")[-1]
+    except Exception:  # noqa: BLE001 - malformed id must not kill analytics
+        return None
+
+
+async def analytics(c, days: int = 7) -> dict:
+    days = max(1, min(days, 28))
+    data = await c.graphql("analytics", _analytics_variables(days))
+    user_results = data["data"]["viewer_v2"]["user_results"]
+    result = user_results.get("result") or {}
+    series: dict[str, int] = {}
+    for point in result.get("current_time_series") or []:
+        kind = point.get("engagement_type")
+        if kind:
+            series[kind] = series.get(kind, 0) + (point.get("count") or 0)
+    relationship = result.get("relationship_counts") or {}
+    return {
+        "viewer": {
+            "id": _viewer_id(user_results.get("id") or ""),
+            "followers": relationship.get("followers"),
+            "verified_followers": result.get("verified_follower_count"),
+            "realtime_active_followers": (result.get("realtime_active_followers") or {}).get(
+                "active_count"
+            ),
+        },
+        "series": dict(sorted(series.items())),
+        "window_days": days,
+    }
+
+
+async def me(c) -> dict:
+    return (await analytics(c, days=1))["viewer"]
+
+
+async def following(
+    c,
+    user: str,
+    limit: int = 20,
+    cursor: str | None = None,
+) -> dict:
+    params: dict[str, str | int] = {"count": limit, "skip_status": "1", "cursor": cursor or "-1"}
+    if str(user).isdigit():
+        params["user_id"] = user
+    else:
+        params["screen_name"] = user
+    data = await c.rest("/1.1/friends/following/list.json", params)
+    users = [
+        {
+            "id": u.get("id_str"),
+            "screen_name": u.get("screen_name"),
+            "name": u.get("name"),
+            "followers": u.get("followers_count"),
+        }
+        for u in data.get("users") or []
+    ]
+    next_cursor = data.get("next_cursor")
+    return {"users": users, "cursor": str(next_cursor) if next_cursor else None}
+
+
+async def like(c, tweet_id: str) -> dict:
+    data = await c.graphql_post("like", {"tweet_id": str(tweet_id)})
+    errors = data.get("errors") or []
+    if errors:
+        return {
+            "liked": str(tweet_id),
+            "result": "error",
+            "detail": errors[0].get("message"),
+        }
+    return {"liked": str(tweet_id), "result": (data.get("data") or {}).get("favorite_tweet")}
+
+
+async def user(c, screen_name: str) -> dict:
+    name = str(screen_name).lstrip("@")
+    data = await c.graphql("user", {"screen_name": name, "withGrokTranslatedBio": True})
+    result = ((data.get("data") or {}).get("user") or {}).get("result")
+    if not result:
+        raise XApiError(f"user not found: {name}")
+    return user_row(result)
+
+
+async def home(c, limit: int = 20, cursor: str | None = None, tab: str = "for_you") -> dict:
+    if tab == "following":
+        key, variables = "home_following", {
+            "count": limit,
+            "enableRanking": True,
+            "includePromotedContent": True,
+        }
+    else:
+        key, variables = "home", {
+            "count": limit,
+            "includePromotedContent": True,
+            "withCommunity": True,
+            "requestContext": "ptr",
+        }
+    if cursor:
+        variables["cursor"] = cursor
+    data = await c.graphql_post(key, variables)
+    return {
+        "tab": tab,
+        "tweets": collect_tweets(data)[:limit],
+        "cursor": collect_cursors(data).get("bottom"),
+    }

x2llm/endpoints.py

@@ -0,0 +1,6 @@
+# GENERATED by scripts/har_to_endpoints.py from browser HAR captures. Do not edit.
+# Public, session-independent constants only (query ids, features, toggles).
+# Session-scoped values (transaction ids) live in the X_TXIDS env var.
+# Regenerate: uv run python scripts/har_to_endpoints.py <archive.har> [...]
+BEARER = 'Bearer AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA'
+GRAPHQL = {'badges': {'query_id': 'q4Npr1-FYRWyXsRzPckwEA', 'name': 'ViewerBadgeCounts', 'method': 'get'}, 'notifications': {'query_id': '4TuDRWeusve2-BH2IqldBg', 'name': 'NotificationsTimeline', 'method': 'get', 'features': {'rweb_video_screen_enabled': False, 'rweb_cashtags_enabled': True, 'profile_label_improvements_pcf_label_in_post_enabled': True, 'responsive_web_profile_redirect_enabled': True, 'rweb_tipjar_consumption_enabled': False, 'verified_phone_label_enabled': False, 'creator_subscriptions_tweet_preview_api_enabled': True, 'responsive_web_graphql_timeline_navigation_enabled': True, 'premium_content_api_read_enabled': False, 'communities_web_enable_tweet_community_results_fetch': True, 'c9s_tweet_anatomy_moderator_badge_enabled': True, 'responsive_web_grok_analyze_button_fetch_trends_enabled': False, 'responsive_web_grok_analyze_post_followups_enabled': True, 'rweb_cashtags_composer_attachment_enabled': True, 'responsive_web_jetfuel_frame': True, 'rweb_sports_post_context_enabled': True, 'responsive_web_grok_share_attachment_enabled': True, 'responsive_web_grok_annotations_enabled': True, 'articles_preview_enabled': True, 'responsive_web_edit_tweet_api_enabled': True, 'rweb_conversational_replies_downvote_enabled': False, 'graphql_is_translatable_rweb_tweet_is_translatable_enabled': True, 'view_counts_everywhere_api_enabled': True, 'longform_notetweets_consumption_enabled': True, 'responsive_web_twitter_article_tweet_consumption_enabled': True, 'content_disclosure_indicator_enabled': True, 'content_disclosure_ai_generated_indicator_enabled': True, 'responsive_web_grok_show_grok_translated_post': True, 'responsive_web_grok_analysis_button_from_backend': True, 'post_ctas_fetch_enabled': False, 'freedom_of_speech_not_reach_fetch_enabled': True, 'standardized_nudges_misinfo': True, 'tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled': True, 'longform_notetweets_rich_text_read_enabled': True, 'longform_notetweets_inline_media_enabled': False, 'responsive_web_nested_quote_preview_enabled': True, 'responsive_web_grok_image_annotation_enabled': True, 'responsive_web_grok_imagine_annotation_enabled': True, 'responsive_web_grok_community_note_auto_translation_is_enabled': True, 'responsive_web_enhance_cards_enabled': False}}, 'home': {'query_id': 'V0wMxbYBxdrkfmV3kJSyRQ', 'name': 'HomeTimeline', 'method': 'post', 'features': {'rweb_video_screen_enabled': False, 'rweb_cashtags_enabled': True, 'profile_label_improvements_pcf_label_in_post_enabled': True, 'responsive_web_profile_redirect_enabled': True, 'rweb_tipjar_consumption_enabled': False, 'verified_phone_label_enabled': False, 'creator_subscriptions_tweet_preview_api_enabled': True, 'responsive_web_graphql_timeline_navigation_enabled': True, 'premium_content_api_read_enabled': False, 'communities_web_enable_tweet_community_results_fetch': True, 'c9s_tweet_anatomy_moderator_badge_enabled': True, 'responsive_web_grok_analyze_button_fetch_trends_enabled': False, 'responsive_web_grok_analyze_post_followups_enabled': True, 'rweb_cashtags_composer_attachment_enabled': True, 'responsive_web_jetfuel_frame': True, 'rweb_sports_post_context_enabled': True, 'responsive_web_grok_share_attachment_enabled': True, 'responsive_web_grok_annotations_enabled': True, 'articles_preview_enabled': True, 'responsive_web_edit_tweet_api_enabled': True, 'rweb_conversational_replies_downvote_enabled': False, 'graphql_is_translatable_rweb_tweet_is_translatable_enabled': True, 'view_counts_everywhere_api_enabled': True, 'longform_notetweets_consumption_enabled': True, 'responsive_web_twitter_article_tweet_consumption_enabled': True, 'content_disclosure_indicator_enabled': True, 'content_disclosure_ai_generated_indicator_enabled': True, 'responsive_web_grok_show_grok_translated_post': True, 'responsive_web_grok_analysis_button_from_backend': True, 'post_ctas_fetch_enabled': False, 'freedom_of_speech_not_reach_fetch_enabled': True, 'standardized_nudges_misinfo': True, 'tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled': True, 'longform_notetweets_rich_text_read_enabled': True, 'longform_notetweets_inline_media_enabled': False, 'responsive_web_nested_quote_preview_enabled': True, 'responsive_web_grok_image_annotation_enabled': True, 'responsive_web_grok_imagine_annotation_enabled': True, 'responsive_web_grok_community_note_auto_translation_is_enabled': True, 'responsive_web_enhance_cards_enabled': False}, 'toggles': {'withPayments': False}}, 'search': {'query_id': 'ph2fARFabkwfxqmSKQ1OPw', 'name': 'SearchTimeline', 'method': 'get', 'features': {'rweb_video_screen_enabled': False, 'rweb_cashtags_enabled': True, 'profile_label_improvements_pcf_label_in_post_enabled': True, 'responsive_web_profile_redirect_enabled': True, 'rweb_tipjar_consumption_enabled': False, 'verified_phone_label_enabled': False, 'creator_subscriptions_tweet_preview_api_enabled': True, 'responsive_web_graphql_timeline_navigation_enabled': True, 'premium_content_api_read_enabled': False, 'communities_web_enable_tweet_community_results_fetch': True, 'c9s_tweet_anatomy_moderator_badge_enabled': True, 'responsive_web_grok_analyze_button_fetch_trends_enabled': False, 'responsive_web_grok_analyze_post_followups_enabled': True, 'rweb_cashtags_composer_attachment_enabled': True, 'responsive_web_jetfuel_frame': True, 'rweb_sports_post_context_enabled': True, 'responsive_web_grok_share_attachment_enabled': True, 'responsive_web_grok_annotations_enabled': True, 'articles_preview_enabled': True, 'responsive_web_edit_tweet_api_enabled': True, 'rweb_conversational_replies_downvote_enabled': False, 'graphql_is_translatable_rweb_tweet_is_translatable_enabled': True, 'view_counts_everywhere_api_enabled': True, 'longform_notetweets_consumption_enabled': True, 'responsive_web_twitter_article_tweet_consumption_enabled': True, 'content_disclosure_indicator_enabled': True, 'content_disclosure_ai_generated_indicator_enabled': True, 'responsive_web_grok_show_grok_translated_post': True, 'responsive_web_grok_analysis_button_from_backend': True, 'post_ctas_fetch_enabled': False, 'freedom_of_speech_not_reach_fetch_enabled': True, 'standardized_nudges_misinfo': True, 'tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled': True, 'longform_notetweets_rich_text_read_enabled': True, 'longform_notetweets_inline_media_enabled': False, 'responsive_web_nested_quote_preview_enabled': True, 'responsive_web_grok_image_annotation_enabled': True, 'responsive_web_grok_imagine_annotation_enabled': True, 'responsive_web_grok_community_note_auto_translation_is_enabled': True, 'responsive_web_enhance_cards_enabled': False}}, 'tweet': {'query_id': 'z-3ZLa-NQ8Sp09diHkJNBg', 'name': 'TweetDetail', 'method': 'get', 'features': {'rweb_video_screen_enabled': False, 'rweb_cashtags_enabled': True, 'profile_label_improvements_pcf_label_in_post_enabled': True, 'responsive_web_profile_redirect_enabled': True, 'rweb_tipjar_consumption_enabled': False, 'verified_phone_label_enabled': False, 'creator_subscriptions_tweet_preview_api_enabled': True, 'responsive_web_graphql_timeline_navigation_enabled': True, 'premium_content_api_read_enabled': False, 'communities_web_enable_tweet_community_results_fetch': True, 'c9s_tweet_anatomy_moderator_badge_enabled': True, 'responsive_web_grok_analyze_button_fetch_trends_enabled': False, 'responsive_web_grok_analyze_post_followups_enabled': True, 'rweb_cashtags_composer_attachment_enabled': True, 'responsive_web_jetfuel_frame': True, 'rweb_sports_post_context_enabled': True, 'responsive_web_grok_share_attachment_enabled': True, 'responsive_web_grok_annotations_enabled': True, 'articles_preview_enabled': True, 'responsive_web_edit_tweet_api_enabled': True, 'rweb_conversational_replies_downvote_enabled': False, 'graphql_is_translatable_rweb_tweet_is_translatable_enabled': True, 'view_counts_everywhere_api_enabled': True, 'longform_notetweets_consumption_enabled': True, 'responsive_web_twitter_article_tweet_consumption_enabled': True, 'content_disclosure_indicator_enabled': True, 'content_disclosure_ai_generated_indicator_enabled': True, 'responsive_web_grok_show_grok_translated_post': True, 'responsive_web_grok_analysis_button_from_backend': True, 'post_ctas_fetch_enabled': False, 'freedom_of_speech_not_reach_fetch_enabled': True, 'standardized_nudges_misinfo': True, 'tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled': True, 'longform_notetweets_rich_text_read_enabled': True, 'longform_notetweets_inline_media_enabled': False, 'responsive_web_nested_quote_preview_enabled': True, 'responsive_web_grok_image_annotation_enabled': True, 'responsive_web_grok_imagine_annotation_enabled': True, 'responsive_web_grok_community_note_auto_translation_is_enabled': True, 'responsive_web_enhance_cards_enabled': False}, 'toggles': {'withPayments': False, 'withDmBlocks': False, 'withArticleRichContentState': True, 'withArticlePlainText': False, 'withArticleSummaryText': True, 'withArticleVoiceOver': True, 'withGrokAnalyze': False, 'withDisallowedReplyControls': False}}, 'analytics': {'query_id': '2hqAR3h2xhN1cUrUBZypyg', 'name': 'accountOverviewDailyQuery', 'method': 'get'}, 'like': {'query_id': 'lI07N6Otwv1PhnEgXILM7A', 'name': 'FavoriteTweet', 'method': 'post'}, 'user': {'query_id': 'AMIBMjtxEEATh4z8V9GtRg', 'name': 'UserByScreenName', 'method': 'get', 'features': {'hidden_profile_subscriptions_enabled': True, 'profile_label_improvements_pcf_label_in_post_enabled': True, 'responsive_web_profile_redirect_enabled': True, 'rweb_tipjar_consumption_enabled': False, 'verified_phone_label_enabled': False, 'subscriptions_verification_info_is_identity_verified_enabled': True, 'subscriptions_verification_info_verified_since_enabled': True, 'highlights_tweets_tab_ui_enabled': True, 'responsive_web_twitter_article_notes_tab_enabled': True, 'subscriptions_feature_can_gift_premium': False, 'creator_subscriptions_tweet_preview_api_enabled': True, 'responsive_web_graphql_timeline_navigation_enabled': True}, 'toggles': {'withPayments': False, 'withAuxiliaryUserLabels': True}}, 'home_following': {'query_id': '5URyiXQyz6_8NZnoV37OVQ', 'name': 'HomeLatestTimeline', 'method': 'post', 'features': {'rweb_video_screen_enabled': False, 'rweb_cashtags_enabled': True, 'profile_label_improvements_pcf_label_in_post_enabled': True, 'responsive_web_profile_redirect_enabled': True, 'rweb_tipjar_consumption_enabled': False, 'verified_phone_label_enabled': False, 'creator_subscriptions_tweet_preview_api_enabled': True, 'responsive_web_graphql_timeline_navigation_enabled': True, 'premium_content_api_read_enabled': False, 'communities_web_enable_tweet_community_results_fetch': True, 'c9s_tweet_anatomy_moderator_badge_enabled': True, 'responsive_web_grok_analyze_button_fetch_trends_enabled': False, 'responsive_web_grok_analyze_post_followups_enabled': True, 'rweb_cashtags_composer_attachment_enabled': True, 'responsive_web_jetfuel_frame': True, 'rweb_sports_post_context_enabled': True, 'responsive_web_grok_share_attachment_enabled': True, 'responsive_web_grok_annotations_enabled': True, 'articles_preview_enabled': True, 'responsive_web_edit_tweet_api_enabled': True, 'rweb_conversational_replies_downvote_enabled': False, 'graphql_is_translatable_rweb_tweet_is_translatable_enabled': True, 'view_counts_everywhere_api_enabled': True, 'longform_notetweets_consumption_enabled': True, 'responsive_web_twitter_article_tweet_consumption_enabled': True, 'content_disclosure_indicator_enabled': True, 'content_disclosure_ai_generated_indicator_enabled': True, 'responsive_web_grok_show_grok_translated_post': True, 'responsive_web_grok_analysis_button_from_backend': True, 'post_ctas_fetch_enabled': False, 'freedom_of_speech_not_reach_fetch_enabled': True, 'standardized_nudges_misinfo': True, 'tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled': True, 'longform_notetweets_rich_text_read_enabled': True, 'longform_notetweets_inline_media_enabled': False, 'responsive_web_nested_quote_preview_enabled': True, 'responsive_web_grok_image_annotation_enabled': True, 'responsive_web_grok_imagine_annotation_enabled': True, 'responsive_web_grok_community_note_auto_translation_is_enabled': True, 'responsive_web_enhance_cards_enabled': False}, 'toggles': {'withPayments': False}}}

x2llm/mcp.py

@@ -0,0 +1,173 @@
+"""Stdio MCP server exposing the same cores as the CLI (reads + like_tweet)."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+
+from . import cores
+from .client import XApiError, XClient
+from .config import Config, ConfigError
+
+MCP_INSTRUCTIONS = (
+    "Access to a logged-in x.com (Twitter) account via the private web API. "
+    "Credentials come from X_AUTH_TOKEN/X_CT0 environment variables - if they "
+    "expire every tool returns an auth error. All tools are read-only except "
+    "like_tweet, which performs a REAL, publicly visible action and notifies "
+    "the author - never call it unless the user explicitly asked to like that "
+    "specific post. search supports X operators (from:user, "
+    "since:YYYY-MM-DD, lang:, min_faves:, min_retweets:). get_tweet returns "
+    "the tweet plus its reply thread; paginate long threads and searches with "
+    "the returned cursor. analytics returns the account's own engagement "
+    "statistics. If search or like fails with an empty 404, the captured "
+    "x-client-transaction-id expired - see the x2llm README."
+)
+
+# (tool name, description, core, read_only)
+MCP_TOOLS = [
+    (
+        "get_home_timeline",
+        (
+            "The account's home timeline. tab: 'for_you' (algorithmic) or "
+            "'following' (chronological). Scroll deeper by passing the "
+            "returned cursor."
+        ),
+        cores.home,
+        True,
+    ),
+    (
+        "get_user",
+        (
+            "Profile of a user by screen name: bio, url, follower/following "
+            "counts, tweet counts, verification. Use to qualify authors "
+            "before engaging."
+        ),
+        cores.user,
+        True,
+    ),
+    (
+        "get_badges",
+        ("Unread notification and DM counts. Cheapest way to verify credentials work."),
+        cores.badges,
+        True,
+    ),
+    (
+        "me",
+        (
+            "Viewer identity: numeric user id, follower, verified-follower and "
+            "realtime-active-follower counts."
+        ),
+        cores.me,
+        True,
+    ),
+    (
+        "suggest",
+        ("Search typeahead for a prefix: matching topics and users (with ids)."),
+        cores.suggest,
+        True,
+    ),
+    (
+        "search",
+        (
+            "Search posts. Supports X operators: from:user, since:YYYY-MM-DD, "
+            "lang:, min_faves:, min_retweets:. Returns posts and a cursor for the "
+            "next page."
+        ),
+        cores.search,
+        True,
+    ),
+    (
+        "get_tweet",
+        ("One post by id plus its reply thread; cursor paginates deeper replies."),
+        cores.tweet,
+        True,
+    ),
+    (
+        "get_notifications",
+        ("The account's notification tab (mentions, likes, follows, reposts)."),
+        cores.notifications,
+        True,
+    ),
+    (
+        "get_analytics",
+        (
+            "The account's own engagement statistics aggregated over a window "
+            "(impressions, likes, reposts, follows, ...). days: 1-28."
+        ),
+        cores.analytics,
+        True,
+    ),
+    (
+        "get_following",
+        (
+            "Accounts a user follows. user is a numeric id or screen name; cursor paginates."
+        ),
+        cores.following,
+        True,
+    ),
+    (
+        "like_tweet",
+        (
+            "Like a post as the logged-in user. REAL action: publicly visible, "
+            "notifies the author, not undoable via this tool. Only call when "
+            "the user explicitly asked to like that specific post."
+        ),
+        cores.like,
+        False,
+    ),
+]
+
+_MCP_CLIENT: XClient | None = None
+_MCP_LOCK = asyncio.Lock()
+
+
+async def mcp_client() -> XClient:
+    global _MCP_CLIENT
+    async with _MCP_LOCK:
+        if _MCP_CLIENT is None:
+            try:
+                _MCP_CLIENT = XClient(Config.from_env())
+            except ConfigError as e:
+                raise RuntimeError(str(e)) from e
+        return _MCP_CLIENT
+
+
+def bind_tool(fn):
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())[1:]
+
+    async def bound(**kwargs):
+        from mcp.server.mcpserver.exceptions import ToolError
+
+        try:
+            return await fn(await mcp_client(), **kwargs)
+        except XApiError as e:
+            raise ToolError(str(e)) from e
+        except TypeError as e:
+            raise ToolError(f"bad arguments: {e}") from e
+
+    bound.__signature__ = inspect.Signature(params, return_annotation=dict)
+    return bound
+
+
+def build_mcp_server():
+    from mcp.server.mcpserver import MCPServer
+    from mcp.types import ToolAnnotations
+
+    server = MCPServer(name="x2llm", instructions=MCP_INSTRUCTIONS)
+    for name, description, fn, read_only in MCP_TOOLS:
+        server.add_tool(
+            bind_tool(fn),
+            name=name,
+            description=description,
+            annotations=ToolAnnotations(read_only_hint=read_only),
+        )
+    return server
+
+
+async def serve() -> None:
+    server = build_mcp_server()
+    try:
+        await server.run_stdio_async()
+    finally:
+        if _MCP_CLIENT is not None:
+            await _MCP_CLIENT.aclose()

x2llm/parse.py

@@ -0,0 +1,120 @@
+"""Parsers: x.com timeline/negotiation blobs -> flat LLM-friendly dicts."""
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+
+def walk(obj: Any) -> Iterator[dict]:
+    if isinstance(obj, dict):
+        yield obj
+        for v in obj.values():
+            yield from walk(v)
+    elif isinstance(obj, list):
+        for v in obj:
+            yield from walk(v)
+
+
+def _tweet_result(wrapper: dict | None) -> dict | None:
+    result = (wrapper or {}).get("result") or {}
+    if result.get("__typename") == "TweetWithVisibilityResults":
+        result = result.get("tweet") or {}
+    if result.get("__typename") != "Tweet" or not result.get("rest_id"):
+        return None
+    return result
+
+
+def _user_fields(user: dict) -> dict:
+    core = user.get("core") or {}
+    legacy = user.get("legacy") or {}
+    return {
+        "author": core.get("screen_name") or legacy.get("screen_name"),
+        "author_name": core.get("name") or legacy.get("name"),
+        "author_id": user.get("rest_id"),
+    }
+
+
+def tweet_row(result: dict) -> dict:
+    legacy = result.get("legacy") or {}
+    user = ((result.get("core") or {}).get("user_results") or {}).get("result") or {}
+    note = ((result.get("note_tweet") or {}).get("note_tweet_results") or {}).get("result") or {}
+    views = (result.get("views") or {}).get("count")
+    return {
+        "id": result.get("rest_id"),
+        "created_at": legacy.get("created_at"),
+        **_user_fields(user),
+        "text": note.get("text") or legacy.get("full_text"),
+        "lang": legacy.get("lang"),
+        "replies": legacy.get("reply_count"),
+        "reposts": legacy.get("retweet_count"),
+        "likes": legacy.get("favorite_count"),
+        "views": int(views) if isinstance(views, str) and views.isdigit() else views,
+        "bookmarks": legacy.get("bookmark_count"),
+    }
+
+
+def collect_tweets(obj: Any) -> list[dict]:
+    rows: list[dict] = []
+    seen: set[str] = set()
+    for node in walk(obj):
+        if "tweet_results" not in node:
+            continue
+        result = _tweet_result(node["tweet_results"])
+        if result and result["rest_id"] not in seen:
+            seen.add(result["rest_id"])
+            rows.append(tweet_row(result))
+    return rows
+
+
+def collect_cursors(obj: Any) -> dict[str, str]:
+    cursors: dict[str, str] = {}
+    for node in walk(obj):
+        if node.get("entryType") == "TimelineTimelineCursor" and node.get("value"):
+            kind = node.get("cursorType")
+            if kind in ("Top", "Bottom"):
+                cursors[kind.lower()] = node["value"]
+    return cursors
+
+
+def notification_rows(obj: Any) -> list[dict]:
+    rows: list[dict] = []
+    seen: set[str] = set()
+    for node in walk(obj):
+        item = node.get("itemContent")
+        if not isinstance(item, dict) or item.get("__typename") != "TimelineNotification":
+            continue
+        if item.get("id") in seen:
+            continue
+        seen.add(item.get("id"))
+        rich = item.get("rich_message") or {}
+        rows.append(
+            {
+                "id": item.get("id"),
+                "icon": item.get("notification_icon"),
+                "text": rich.get("text"),
+                "url": (item.get("notification_url") or {}).get("url"),
+            }
+        )
+    return rows
+
+
+def user_row(result: dict) -> dict:
+    core = result.get("core") or {}
+    bio = result.get("profile_bio") or {}
+    relationship = result.get("relationship_counts") or {}
+    counts = result.get("tweet_counts") or {}
+    urls = ((bio.get("entities") or {}).get("url") or {}).get("urls") or []
+    return {
+        "id": result.get("rest_id"),
+        "screen_name": core.get("screen_name"),
+        "name": core.get("name"),
+        "created_at": core.get("created_at"),
+        "bio": bio.get("description"),
+        "url": urls[0].get("expanded_url") if urls else None,
+        "location": (result.get("location") or {}).get("location"),
+        "followers": relationship.get("followers"),
+        "following": relationship.get("following"),
+        "tweets": counts.get("tweets"),
+        "media_tweets": counts.get("media_tweets"),
+        "blue_verified": result.get("is_blue_verified"),
+    }

x2llm-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+x2llm/__init__.py,sha256=8LIrJ89MZnx-iwrs5_EfBaw_IFFUhdbtiXXQcb9Funo,213
+x2llm/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+x2llm/cli.py,sha256=EFhLfc6Vnb2qTLHeYULse-ysW6oc40hYk2IXkK0RKr0,4586
+x2llm/client.py,sha256=czvikbPQhUY_HcXhVfSEszRXH0ApMlt7BhjIw-mCNBI,5377
+x2llm/config.py,sha256=8KZNRui14bqHFxNxWejB8_myffoiYzPa7b4cECCLfOE,2311
+x2llm/cores.py,sha256=AXiHTwmxiRHh7_TiMYcJPPkFJ9wmaEfQC1hNHKFdUKQ,7069
+x2llm/endpoints.py,sha256=Wvlvj_zrm4PU2DKeF6KszWdwr2P7oCD1sYh-vl0LvVs,12734
+x2llm/mcp.py,sha256=WmZeZW8lpu7h2Jq8eJCBKAwAOVH3DnAk5v3uCu1KsOc,5117
+x2llm/parse.py,sha256=nlzpVy6aR4usHn40xgrIcwr0RAR1mz8mh9_2mB-6qB0,4211
+x2llm-0.1.0.dist-info/METADATA,sha256=QUBMPsS_Qkyqula4PL3T2xhtU9z7WU_E-Pjqy7_DfPY,243
+x2llm-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+x2llm-0.1.0.dist-info/entry_points.txt,sha256=Sbp0vDeQrQDW2yT12_h10jz98wyhq_Bp2Oq6F6P4mTc,41
+x2llm-0.1.0.dist-info/RECORD,,

x2llm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

x2llm-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+x2llm = x2llm.cli:main