X-Lookup

Navegador somente leitura, sem autenticação, para conteúdo público do X/Twitter, projetado especificamente para agentes de IA. Status e threads, perfis, busca, seguidores/seguindo

GitHub

Experimente este MCPPatrocinado

Documentação

x-lookup

Navegador somente leitura, sem autenticação, para conteúdo público do X/Twitter, criado especificamente para agentes de IA. Status e threads, perfis, busca, seguidores/seguindo — servidos como Markdown compacto por padrão, JSON estruturado sob solicitação, HTML Open Graph para bots de pré-visualização de aplicativos de chat, além de um endpoint oEmbed.

Hospedado em https://x-lookup.mynameistito.com como um único Cloudflare Worker. Sem banco de dados, sem login, sem chaves de API — os únicos upstreams são a API gratuita FxTwitter e o endpoint de sindicação do Twitter.

Não afiliado à X Corp.

Início rápido

Substitua x.com por x-lookup.mynameistito.com em qualquer URL pública de status:

https://x.com/handle/status/1234567890
https://x-lookup.mynameistito.com/handle/status/1234567890

curl -sS -H "Accept: text/markdown" "https://x-lookup.mynameistito.com/handle/status/1234567890"

curl -sS -G "https://x-lookup.mynameistito.com/api/convert" --data-urlencode "url=https://x.com/handle/status/1234567890"

Navegadores que solicitam HTML recebem uma página legível contendo o Markdown. Discord, Telegram, Slack e outros bots de pré-visualização recebem HTML de incorporação Open Graph.

Rotas

Rota	Finalidade	Parâmetros de consulta
`GET /api/convert?url=<x-status-url>` (ou `handle=` + `id=`)	Converter um status/thread	veja Parâmetros de conversão de post
`GET /:handle/status/:id`	O mesmo, via reescrita de URL	igual a `/api/convert`
`GET /api/browse?resource=profile\|search\|followers\|following&…`	Endpoint de navegação	veja Parâmetros de navegação
`GET /search?q=…`	Buscar posts	`q` (obrigatório), `feed`, `cursor`, `page`, `limit`, `full`, `format`, `nocache`
`GET /:handle`	Perfil + posts originais mais recentes	`cursor`, `page`, `limit`, `full`, `format`, `nocache`
`GET /:handle/followers`	Usuários seguidores	`cursor`, `page`, `limit`, `full`, `format`, `nocache`
`GET /:handle/following`	Usuários seguidos	`cursor`, `page`, `limit`, `full`, `format`, `nocache`
`GET /oembed?url=…`	JSON oEmbed	`url`; substituições opcionais `text`, `author`, `status`, `provider`
`GET /og.png`	Imagem de compartilhamento Open Graph / Twitter 1200×630	—
`GET /` (também `/docs`)	Documentação completa de uso (Markdown)	—

Todas as respostas da API enviam CORS *, suportam OPTIONS (204) e HEAD; outros métodos recebem 405. Erros são sempre { "error": string, "code": string } com um status verdadeiro: 400 entrada inválida, 404 conteúdo genuinamente ausente, 502 recusa ou falha do upstream.

Servidor MCP

As mesmas capacidades públicas e somente leitura estão disponíveis através do endpoint MCP sem estado:

https://x-lookup.mynameistito.com/mcp

Exemplo de configuração remota do MCP:

{
  "mcpServers": {
    "x-lookup": {
      "url": "https://x-lookup.mynameistito.com/mcp"
    }
  }
}

O servidor expõe estas ferramentas:

Ferramenta	Entrada obrigatória	Entrada opcional
`browse_x`	`resource`	`handle`, `q`, `feed`, `cursor`, `page`, `limit`, `full`, `format`, `nocache`
`convert_status`	`url`, ou `handle` + `id`	`format`, `thread`, `context`, `replies`, `userinfo`, `full`, `nocache`
`search_posts`	`q`	`feed`, `cursor`, `page`, `limit`, `full`, `format`, `nocache`
`get_profile`	`handle`	`cursor`, `page`, `limit`, `full`, `format`, `nocache`
`list_followers`	`handle`	`cursor`, `page`, `limit`, `full`, `format`, `nocache`
`list_following`	`handle`	`cursor`, `page`, `limit`, `full`, `format`, `nocache`
`get_oembed`	—	`url`, `text`, `author`, `status`, `provider`
`get_health`	—	—

As ferramentas de navegação retornam JSON estruturado com uma renderização Markdown incluída. A conversão retorna JSON estruturado com o Markdown renderizado, posts, avisos, provedor e status de cache. O endpoint MCP é sem estado; não requer ID de sessão MCP ou autenticação.

Parâmetros de conversão de post

Tanto GET /:handle/status/:id quanto GET /api/convert?url=… suportam:

Parâmetro	Padrão	Valores suportados
`format`	`markdown`	`markdown`, `obsidian`, `json`
`full`	false	`true`, `1`, ou `yes` ativa Markdown expandido; Obsidian é sempre expandido
`thread`	`full`	`off`, `full`, `conversation`, ou um limite de `2` a `100`
`context`	`full`	`full` inclui pais, thread do autor e respostas selecionadas; `thread` exclui respostas não relacionadas
`replies`	`top`	`top`, `recent`, `off`
`userinfo`	`off`	`off`, `author`, `all`
`nocache`	false	`true`, `1`, ou `yes` ignora o cache

Negociação de conteúdo: format=json ou Accept: application/json → JSON; User-Agents de bots de pré-visualização sem formato explícito → HTML OG; Accept: text/html → página HTML; caso contrário, Markdown.

Parâmetros de navegação

/api/browse, /search, /:handle e listas de seguidores aceitam:

Parâmetro	Padrão	Valores suportados
`q`	—	Consulta de busca; obrigatório em `/search` e `resource=search`. Suporta operadores do X como `from:`, `since:`
`feed`	`latest`	`latest`, `top`, `media` — somente busca
`cursor`	—	Token de continuação opaco de `Continue →` / `nextCursor`
`page`	1	`1`–`10`; percorre páginas quando nenhum `cursor` é fornecido
`limit`	20	`1`–`50` resultados por resposta
`full`	false	`true`, `1`, ou `yes` adiciona datas/métricas aos posts e contagens de seguidores/bios aos usuários
`format`	`markdown`	`markdown`, `json`
`nocache`	false	`true`, `1`, ou `yes` ignora o cache

Prefira o cursor opaco do link Continue → do Markdown ou nextCursor do JSON em vez de percorrer páginas.

Cabeçalhos de resposta significativos

X-Source (provedor de busca), X-Cache (HIT|MISS|BYPASS), X-Browse-Resource, X-Result-Count, X-Converter, X-Post-Count, X-Warnings, X-Embed.

Nota sobre disponibilidade da busca

FxTwitter recusa alguns IPs de egress de datacenter. Quando isso acontece, a busca retorna 502 com código search_unavailable — nunca um falso "post não encontrado". Consultas de status recorrem do FxTwitter ao endpoint de sindicação do Twitter.

Desenvolvimento

O repositório usa Bun 1.4.0. No Windows, instale o Bun pelas instruções oficiais do PowerShell e então execute:

bun install --frozen-lockfile
bun run dev        # local workerd, isolated dev_<user> stage
bun run test       # vitest
bun run typecheck  # tsc --noEmit
bun run plan       # preview the production diff
bun run deploy     # deploy the prod stage (attaches x-lookup.mynameistito.com)
bun run destroy    # tear down the prod stage (interactive confirm)

Alchemy usa o perfil default a menos que ALCHEMY_PROFILE ou um argumento explícito --profile selecione outro perfil. Para usar um perfil local nomeado nos scripts de pacote no PowerShell, defina-o no shell atual antes de executar um comando:

$env:ALCHEMY_PROFILE = "your-profile"
bun run plan
bun run dev

No Bash, use export ALCHEMY_PROFILE=your-profile. Os perfis são armazenados localmente em ~/.alchemy/profiles.json; configure um com bunx alchemy login --profile your-profile. GitHub Actions não usam perfis locais: jobs de deploy autenticam com os segredos do repositório CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID. A infraestrutura vive inteiramente em alchemy.run.ts e src/worker.ts — não há wrangler.jsonc. Em prod, o Worker mantém seu nome físico x-lookup e domínio personalizado x-lookup.mynameistito.com; todos os outros estágios (dev local, pré-visualizações de PR) derivam uma identidade isolada. A única variável é CACHE_TTL_SECONDS (padrão 3600). Não há segredos. O cache é em duas camadas: memória L1 no isolado mais Cloudflare Cache API L2.

CI executa lint/typecheck/testes sem credenciais, além de uma validação de stack sem estado (.github/workflows/ci.yml). .github/workflows/deploy.yml chama o workflow reutilizável fixado alchemy-deploy, que faz deploy somente após o CI passar para o commit exato: prod para main e uma pré-visualização isolada pr-<number> para pull requests do mesmo repositório. Stacks de pré-visualização são derrubados quando o PR fecha, e pull requests de forks nunca recebem credenciais do Cloudflare ou deploys de pré-visualização. A resolução de pré-visualização executa código confiável do branch padrão e aguarda o resultado exato do CI do head do PR antes de expor credenciais.

O workflow compartilhado é dono do relatório de deploy de pré-visualização e produção, resolução de URL e limpeza de pré-visualização. A limpeza usa segredos do Cloudflare mapeados explicitamente no escopo do repositório, faz checkout apenas do branch padrão confiável, destrói pr-<number> primeiro e remove registros de deploy do GitHub somente após o teardown bem-sucedido; falha na limpeza retém esses registros e o run de diagnóstico. O deploy workflow_run faz checkout do SHA exato que passou no CI.

A skill de agente incluída em skills/x-lookup/ encapsula esta API para uso via CLI; substitua seu alvo com X_API_BASE ao testar outro deploy.