x-relay-mcp 1.0.0

package/.claude/skills/x-relay/SKILL.md

@@ -0,0 +1,130 @@
+# x-relay
+
+A **deep-research tool for X/Twitter** for AI agents — a CLI (`xrelay`), an MCP server, and this skill.
+Cast a wide net with live search, rank candidates cheaply on engagement/recency metadata, and read full
+threads only for the finalists. Cookies are **auto-extracted from your local browser** (Arc/Chrome/Brave/Edge
+on macOS) — no manual setup. No paid X API.
+
+The tool is **atomic** (search / user / user-posts / thread / bookmarks). YOU compose the strategy. This skill
+gives the **recommended funnel** first, then a per-command reference with cost so you can deviate intelligently.
+
+---
+
+## Recommended workflow (the funnel)
+
+Use this for "find the best X material / what's being said on <topic>" research tasks.
+
+**Golden rule — protect your context window:** threads and timelines are large. NEVER bulk-read them during
+exploration. Rank on cheap search metadata first; read a full thread only for the handful that survive.
+
+```
+GATE 1 — cast a wide net (CHEAP: search)
+  Run several query variants (synonyms / intent angles / operators), dedupe by id.
+    xrelay search "prompt engineering" --limit 40 --product Top
+    xrelay search "writing prompts for llms" --product Latest --min-faves 50
+    xrelay search "context engineering" --since 2026-01-01 --filter -replies
+  Each tweet already carries: author (+verified, followers), likes, retweets, replies, quotes,
+  bookmarks, views, date, lang, url. Rank on THESE alone.
+  Signals: authority (verified / known author / followers), validation (likes + views + bookmarks),
+  recency (date — matters for fast topics), specificity (the text), reach (retweets/quotes).
+  Keep the ~10–15 most promising. NO thread reads yet.
+
+GATE 2 — enrich the authors (1 CALL each: user)
+  xrelay user <handle>        # bio, follower count, verified, how active
+  Confirm an author is who you think. Drop weak sources. Optionally peek a source's recent posts:
+  xrelay user-posts <handle> --limit 20
+
+GATE 3 — full read (EXPENSIVE: thread — only the few that survive)
+  xrelay thread <id|url>      # the tweet + its replies/conversation
+
+Cross-source: your own saved material is a parallel input (a LOCAL cache —
+offline, instant, no rate limits) —
+  xrelay bookmarks -q "<topic>"   # fuse what you've already saved with live results
+  xrelay my-posts -q "<topic>"    # and what you've written
+```
+
+`--product Top` ranks by X's own engagement model (best for "the best on <topic>"); `--product Latest`
+gives recency (best for "what's being said right now" and incremental sweeps).
+
+---
+
+## Commands (atomic reference)
+
+All commands print a JSON envelope to stdout — `{ ok, command, data }` on success,
+`{ ok:false, command, error:{code,message,hint} }` on failure. Exit codes: 0 ok, 1 command error,
+2 unknown command.
+
+### `search` — COST: cheap, broad. The net.
+```
+xrelay search "<query>" [--limit N] [--product Top|Latest|Media|People]
+       [--from <h>] [--to <h>] [--since YYYY-MM-DD] [--until YYYY-MM-DD]
+       [--lang xx] [--min-faves N] [--min-retweets N] [--filter media|links|replies|-replies ...]
+```
+- X **advanced operators also work inside the query string** — the flags are just a typed shortcut that
+  get folded into it. `--filter -replies` excludes replies; `--filter media` keeps only media tweets.
+- Returns `{ query, product, tweets: [{ id, url, text, author:{handle,name,verified,followers},
+  metrics:{likes,retweets,replies,quotes,bookmarks,views}, createdAt, lang, media[], ... }], nextCursor }`.
+
+### `user` — COST: 1 call. Vet a source.
+```
+xrelay user <handle|url>
+```
+- Returns `{ id, handle, name, bio, verified, followers, following, tweets, createdAt, location, avatar, url }`.
+
+### `user-posts` — COST: medium. A source's timeline.
+```
+xrelay user-posts <handle|url> [--replies] [--limit N]
+```
+- `--replies` includes the user's replies (default: just their posts). Returns `{ tweets[], nextCursor }`.
+
+### `thread` — COST: expensive. The full read.
+```
+xrelay thread <id|url>
+```
+- Returns `{ root: <tweet>, replies: [<tweet>...], nextCursor }`. Use on finalists only.
+
+### `bookmarks` / `my-posts` — COST: cheap. Your local cache (offline, instant).
+```
+xrelay bookmarks [-q "<query>"] [--limit N] [--sort relevance|newest|likes|views|bookmarks]
+       [--sync] [--repair] [--live]
+xrelay my-posts  [-q "<query>"] [--limit N] [--sort ...] [--handle <you>] [--sync] [--live]
+```
+- Search YOUR saved posts / own posts in a local cache — no rate limits, instant, semantic-free keyword +
+  metadata ranking. Returns `{ source, cached, total, syncedAt, tweets[] }`.
+- `--sync` refreshes the cache first (incremental — only new since last sync). `--live` bypasses the cache and
+  hits X. If the cache is empty, the result carries a `hint` telling you to `sync` first.
+
+### `sync` — COST: medium. Refresh the local cache (incremental).
+```
+xrelay sync bookmarks|posts|all [--handle <you>] [--repair] [--max N]
+```
+- Pulls ONLY tweets newer than the last sync (snowflake-id watermark + newest-first early-break) — never a
+  full refetch. `--repair` refetches everything and patches records; `--max N` caps a run (good for a first
+  sync). `posts` needs your `--handle` once (it's remembered). Returns `{ source, added, total, watermark }`.
+
+---
+
+## Composition notes
+
+- **Dedupe by `id`** across multiple `search` calls — that's your job, not the tool's.
+- **Rank, don't read.** The whole point is to avoid reading threads you don't need. Engagement + recency +
+  authority on the search results is usually enough to pick the 2–3 worth a `thread` read.
+- **Operators are powerful**: `from:` (one author), `min_faves:` (quality floor), `since:`/`until:` (a window),
+  `filter:media`/`-filter:replies` (shape). Combine them to make the net precise instead of huge.
+
+## Error codes
+
+- `INVALID_INPUT` — empty query / missing handle or id. No network call.
+- `AUTH_FAILED` — session cookies expired/invalid. Re-log into x.com in your browser (or set XRELAY_COOKIES).
+- `RATE_LIMITED` — X throttled the token; back off and retry later.
+- `FEATURE_DRIFT` — X rotated its private API; the tool's query-ids/features need a refresh.
+- `NOT_FOUND` — the tweet/user is unavailable, or a transient API hiccup.
+- `UNKNOWN_COMMAND` — unrecognized command.
+
+## Setup
+
+```
+npm i -g x-relay-mcp
+```
+Cookies are read automatically from your logged-in browser (macOS Keychain). The first run may show a one-time
+Keychain "Always Allow" prompt. Assumes a residential IP (run locally); datacenter IPs are blocked by X.

package/README.md

@@ -0,0 +1,21 @@
+# x-relay
+
+A **deep-research tool for X/Twitter** for AI agents — a TypeScript **CLI** (`xrelay`), an **MCP server**
+(`x-relay-mcp`), and a **Claude Code skill**. Cast a wide net with live search, rank candidates cheaply on
+engagement metadata, and read full threads only for the finalists — plus a **local, incrementally-synced cache**
+of your own bookmarks and posts. **No paid X API**: a from-scratch engine on X's private GraphQL surface using
+your login cookies.
+
+> **Status:** scaffolding. Design and grounded engine research are in [`PLAN.md`](./PLAN.md) and
+> [`docs/ENGINE-RESEARCH.md`](./docs/ENGINE-RESEARCH.md). Built in the spirit of its sibling
+> [`youtube-relay-mcp`](../youtube-context): atomic capabilities, the agent composes the strategy, a generated
+> `SKILL.md` teaches the funnel.
+
+## Why a CLI + skill (not just an MCP server)
+
+The task is a search/fetch/rank pipeline. An agent shells out to `xrelay`, taught by the bundled `SKILL.md`.
+The MCP shim is provided for parity and non-CLI hosts.
+
+## License
+
+MIT © Tamas Gabor

package/dist/cli-DZkaLoUg.d.ts

@@ -0,0 +1,232 @@
+type Ok<T> = {
+    ok: true;
+    command: string;
+    data: T;
+};
+type Err = {
+    ok: false;
+    command: string;
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+    };
+};
+type Envelope<T> = Ok<T> | Err;
+/** A tweet's author, as it appears embedded in a tweet result. */
+type Author = {
+    id: string;
+    handle: string;
+    name: string;
+    verified: boolean;
+    followers?: number;
+    avatar?: string;
+};
+/** Engagement counters — all optional because X omits some in some contexts. */
+type Metrics = {
+    likes?: number;
+    retweets?: number;
+    replies?: number;
+    quotes?: number;
+    bookmarks?: number;
+    views?: number;
+};
+type MediaKind = 'photo' | 'video' | 'gif';
+/** A single tweet, normalized. The unit returned by search / timelines. */
+type Tweet = {
+    id: string;
+    url: string;
+    text: string;
+    lang?: string;
+    createdAt?: string;
+    author: Author;
+    metrics: Metrics;
+    hashtags?: string[];
+    mentions?: string[];
+    urls?: string[];
+    media?: MediaKind[];
+    isReply?: boolean;
+    isRetweet?: boolean;
+    isQuote?: boolean;
+    conversationId?: string;
+    /** Present when this tweet quotes another. */
+    quoted?: Tweet;
+};
+/** A full user profile (the `user` command). */
+type UserProfile = {
+    id: string;
+    handle: string;
+    name: string;
+    bio?: string;
+    verified: boolean;
+    followers: number;
+    following: number;
+    tweets: number;
+    createdAt?: string;
+    location?: string;
+    avatar?: string;
+    url: string;
+};
+/** A paginated set of tweets (search / timeline output). */
+type TweetPage = {
+    tweets: Tweet[];
+    nextCursor?: string;
+};
+/** A search result, carrying back the query context. */
+type SearchResult = TweetPage & {
+    query: string;
+    product: SearchProduct$1;
+};
+/** A tweet plus its reply thread (the `thread` command). */
+type ThreadResult = {
+    root: Tweet;
+    replies: Tweet[];
+    nextCursor?: string;
+};
+type SearchProduct$1 = 'Top' | 'Latest' | 'Media' | 'People';
+
+/** The two load-bearing cookies, plus any others the jar carries. */
+type Cookies = {
+    authToken: string;
+    ct0: string;
+    extra?: Record<string, string>;
+};
+/**
+ * Parse a browser cookie string (`auth_token=abc; ct0=def; ...`) or a JSON object
+ * string (`{"auth_token":"abc","ct0":"def"}`). Throws naming what's missing.
+ */
+declare function parseCookies(input: string): Cookies;
+
+/**
+ * Operation name → { queryId, operationName }. Values are the twscrape mid-2026
+ * snapshot from ENGINE-RESEARCH.md §2.
+ *
+ * IMPORTANT: query-ids ROTATE. They live here in config, never hardcoded in logic.
+ * A `(336) features cannot be null` (or a 404 on the URL) means the hashes drifted —
+ * refresh this config from the web bundle.
+ */
+declare const OPS: {
+    readonly SearchTimeline: {
+        readonly queryId: "Yw6L66Pw54NHKuq4Dp7b4Q";
+        readonly operationName: "SearchTimeline";
+    };
+    readonly UserByScreenName: {
+        readonly queryId: "IGgvgiOx4QZndDHuD3x9TQ";
+        readonly operationName: "UserByScreenName";
+    };
+    readonly UserByRestId: {
+        readonly queryId: "VQfQ9wwYdk6j_u2O4vt64Q";
+        readonly operationName: "UserByRestId";
+    };
+    readonly UserTweets: {
+        readonly queryId: "36rb3Xj3iJ64Q-9wKDjCcQ";
+        readonly operationName: "UserTweets";
+    };
+    readonly UserTweetsAndReplies: {
+        readonly queryId: "D5eKzDa5ZoJuC1TCeAXbWA";
+        readonly operationName: "UserTweetsAndReplies";
+    };
+    readonly UserMedia: {
+        readonly queryId: "9EovraBTXJYGSEQXZqlLmQ";
+        readonly operationName: "UserMedia";
+    };
+    readonly Bookmarks: {
+        readonly queryId: "XD0ViOeSOW4YoeNTGjVaYw";
+        readonly operationName: "Bookmarks";
+    };
+    readonly TweetDetail: {
+        readonly queryId: "oCon7R-cgWRFy6EfZjaKfg";
+        readonly operationName: "TweetDetail";
+    };
+    readonly Followers: {
+        readonly queryId: "_orfRBQae57vylFPH0Huhg";
+        readonly operationName: "Followers";
+    };
+    readonly Following: {
+        readonly queryId: "F42cDX8PDFxkbjjq6JrM2w";
+        readonly operationName: "Following";
+    };
+    readonly ListLatestTweetsTimeline: {
+        readonly queryId: "7UuJsFvnWuZo0HmxrzU42Q";
+        readonly operationName: "ListLatestTweetsTimeline";
+    };
+};
+type OpName = keyof typeof OPS;
+type Vars = Record<string, unknown>;
+type Feats = Record<string, boolean>;
+interface BuiltRequest {
+    variables: Vars;
+    features: Feats;
+    fieldToggles?: Vars;
+}
+type SearchProduct = 'Top' | 'Latest' | 'Media' | 'People';
+
+/** Yields the x-client-transaction-id for a request (method + path bound). */
+type TransactionProvider = (method: string, path: string) => Promise<string>;
+type ClientResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        status?: number;
+    };
+};
+
+/** A failure surfaced from the network/transport layer. Commands map it to an envelope. */
+declare class EngineError extends Error {
+    readonly code: string;
+    readonly status?: number;
+    constructor(code: string, message: string, status?: number);
+}
+/** The transport surface the engine needs — satisfied by createClient, fakeable in tests. */
+interface EngineClient {
+    get(op: OpName, request: BuiltRequest): Promise<ClientResult>;
+}
+interface SearchOpts {
+    product?: SearchProduct;
+    limit?: number;
+}
+interface UserTweetsOpts {
+    replies?: boolean;
+    limit?: number;
+    /** Stop paginating once a tweet with id <= this is seen (incremental sync watermark). */
+    stopAtId?: string;
+}
+interface PageOpts {
+    limit?: number;
+    /** Stop paginating once a tweet with id <= this is seen (incremental sync watermark). */
+    stopAtId?: string;
+}
+interface Engine {
+    search(query: string, opts?: SearchOpts): Promise<SearchResult>;
+    user(handle: string): Promise<UserProfile | null>;
+    userTweets(handle: string, opts?: UserTweetsOpts): Promise<TweetPage>;
+    bookmarks(opts?: PageOpts): Promise<TweetPage>;
+    thread(id: string): Promise<ThreadResult>;
+}
+interface EngineDeps {
+    /** Cookies for auth. Omit to auto-extract from the local browser (getCookies). */
+    cookies?: Cookies;
+    fetchImpl?: typeof fetch;
+    /** Injectable transport (tests). Defaults to a real client over the X API. */
+    client?: EngineClient;
+    /** Injectable transaction provider (tests). Defaults to the xctid generator. */
+    transaction?: TransactionProvider;
+}
+declare function createEngine(deps: EngineDeps): Engine;
+
+interface ParsedArgs {
+    command?: string;
+    positionals: string[];
+    flags: Record<string, string[]>;
+    bools: Set<string>;
+}
+declare function parseArgs(argv: string[]): ParsedArgs;
+/** Dispatch parsed args against an engine. Returns an envelope (does not print). */
+declare function dispatch(parsed: ParsedArgs, engine: Engine): Promise<Envelope<unknown>>;
+declare function run(argv: string[], engine?: Engine): Promise<number>;
+
+export { type Author as A, type Cookies as C, type Err as E, type MediaKind as M, type Ok as O, type PageOpts as P, type SearchProduct as S, type Tweet as T, type UserProfile as U, type Engine as a, type Envelope as b, type TweetPage as c, type SearchResult as d, type ThreadResult as e, type EngineDeps as f, EngineError as g, type Metrics as h, type SearchOpts as i, type SearchProduct$1 as j, type UserTweetsOpts as k, createEngine as l, dispatch as m, parseCookies as n, type ParsedArgs as o, parseArgs as p, run as r };

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export { o as ParsedArgs, m as dispatch, p as parseArgs, r as run } from './cli-DZkaLoUg.js';