Construí um Firecrawl local sem chave para Claude Code — aqui está o porquê

Um modelo de linguagem paga por cada token de navegação, anúncios e rodapé que lê.

Essa única frase é a razão pela qual tearsheet existe. Eu faço muito trabalho de pesquisa dentro do Claude Code, e uma grande parte disso é "vá ler esta página e me diga o que ela diz." Ferramentas no estilo Firecrawl são realmente boas para isso — mas elas são SaaS. Chaves de API, cotas, uma conta, e suas URLs saindo da sua máquina para chegar lá. Eu queria o mesmo conjunto de ferramentas, rodando inteiramente no meu próprio laptop, alimentando meu agente com conteúdo limpo sem nada disso.

Então eu construí. Chama-se tearsheet, é licenciado sob MIT, e esta é a história do porquê.

tearsheet (n.): uma página rasgada de uma publicação e arquivada como prova de que foi publicada.

Essa definição está no repositório por uma razão. Toda a ferramenta é construída em torno da ideia de que o que ela devolve deve ser confiável o suficiente para ser arquivado como evidência. Mais sobre isso abaixo — é a parte que mais me importa.

Por que eu a construí

Duas coisas me empurraram para o limite.

Tokens são dinheiro. Quando você raspa uma página e despeja o HTML bruto — ou mesmo uma conversão "legível" ingênua — no contexto de um modelo, você está pagando pelo banner de cookies, o mega-menu, o modal de newsletter e o rodapé de seis níveis. Em uma execução de pesquisa que se espalha por dezenas de páginas, esse desperdício se acumula rapidamente. Eu queria uma ferramenta cujo primeiro princípio fosse "retornar o menor texto que responde completamente à pergunta."

Eu não queria um intermediário. Nenhuma chave de API para gerenciar, nenhum serviço para confiar com minha navegação, nenhuma telemetria, nenhum limite de taxa que não seja o meu. Apenas uma coisa na minha máquina que o Claude Code pode chamar. Tudo que o tearsheet faz — buscar, extrair, armazenar em cache, rastrear — acontece localmente.

O que é

tearsheet é um servidor MCP expondo cinco ferramentas. Se você já usou o Firecrawl, essas parecerão familiares:

• scrape — uma URL de entrada, markdown de conteúdo principal limpo de saída.
• search — metapesquisa sem chave (nenhuma chave de API de pesquisa necessária).
• map — lista todas as URLs em um site sem raspá-lo.
• crawl — percorre um site e escreve cada página no disco como markdown.
• extract — puxa dados estruturados (JSON-LD, OpenGraph, tabelas) como JSON, sem LLM envolvido.

O fluxo pretendido é deliberadamente barato: map → escolha as URLs que importam → scrape aquelas, ou crawl → leia os arquivos que ele escreveu. Você nunca joga um site inteiro no contexto para encontrar as três páginas que você realmente precisava.

Três escolhas de design fazem o trabalho de economia de tokens:

1. Apenas conteúdo principal. A extração passa pelo trafilatura, então navegação/anúncios/chrome são removidos antes que qualquer coisa chegue ao modelo.
2. Transbordo em disco em vez de truncamento por adivinhação. Quando uma página é maior que seu limite, o tearsheet escreve a cópia completa em ~/.tearsheet/pages/ e imprime o caminho. O modelo lê o arquivo se precisar de mais, em vez de você re-raspar com um limite maior.
3. Crawl retorna um índice, não corpos. Um crawl nunca despeja o conteúdo da página na saída da ferramenta — ele escreve arquivos e devolve um índice compacto (nome do arquivo, ~contagem de tokens, título, caminho). O modelo consumidor decide o que realmente ler.

Por trás das câmeras, é fastmcp para o servidor, trafilatura para extração, ddgs para pesquisa sem chave, extruct + lxml para dados estruturados, e um fallback de playwright Chromium carregado de forma preguiçosa para as páginas que só JavaScript pode ver e que uma simples busca não consegue acessar.

A parte da qual mais me orgulho: ele se recusa a mentir

Aqui está a coisa que torna o tearsheet diferente de um raspador de fim de semana.

Todo extrator falha às vezes. A questão é como. O modo de falha do tearsheet é omissão, nunca fabricação — e cada proteção nele existe para tornar a omissão barulhenta em vez de silenciosa. Uma ferramenta que silenciosamente descarta metade de uma tabela de preços é muito mais perigosa do que uma que diz "não consegui ler isso claramente," porque você citará a versão limpa, mas errada, sem pensar duas vezes.

Portanto, o tearsheet é construído para ser barulhento sobre seus próprios pontos cegos:

• warning: linhas no cabeçalho. Cada resultado de scrape começa com um cabeçalho (url, title, contagem de tokens, avisos) antes do conteúdo. Uma linha warning: significa que a extração é conhecida como não confiável — não cite figuras dela, re-execute com raw=true.
• Ele não armazenará lixo em cache. Se uma página serve um muro de cookies/consentimento ou um desafio de proteção contra bots em vez de conteúdo, o tearsheet detecta isso, diz isso claramente e se recusa a armazená-lo em cache — assim, um resultado envenenado não pode ser reproduzido mais tarde.
• Um guardião de preços. Páginas comerciais e tabulares são onde os extratores silenciosamente perdem dados — o markdown parece limpo enquanto os valores em dólar desaparecem. O tearsheet conta os distintos valores monetários na página em comparação com a extração e avisa você quando muitos foram perdidos. Isso foi calibrado em páginas reais que o quebraram: uma página de preços veio com apenas 4 de seus 24 preços e uma matriz de três colunas achatada. Essa é exatamente a falha silenciosa que o guardião agora captura.
• Um raw=true escape hatch. Quando você não confia na extração limpa, raw ignora completamente o trafilatura e devolve o texto visível da página para que você possa ver por si mesmo.

O objetivo de design — e o histórico até agora — é zero conteúdo fabricado. Ele omite, e te avisa quando o fez.

Instale e conecte ao Claude Code

Aviso justo: isto é inicial. Não está no PyPI ainda — isso é deliberado, ainda estou refinando e prefiro enviar algo limpo do que rápido. Por enquanto, é apenas git-clone. Se você não se importa com um pouco de aspereza, aqui está toda a configuração.

Clone e instale (requer Python ≥ 3.12):

git clone https://github.com/Wynelson94/tearsheet.git
cd tearsheet
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Opcional, para páginas renderizadas em JavaScript:

playwright install chromium

(Sem isso, o tearsheet degrada graciosamente e te avisa quando uma página precisava de renderização.)

Então registre-o com o Claude Code como um servidor MCP:

claude mcp add --scope user tearsheet -- ~/Projects/tearsheet/.venv/bin/tearsheet-mcp

É isso. Reinicie o Claude Code e você terá scrape, search, map, crawl, e extract disponíveis como ferramentas.

Onde ainda está áspero

Eu prefiro te contar os pontos fracos do que deixar você encontrá-los.

Páginas comerciais e tabulares são o caso difícil — todo o sistema de guardião de preços existe porque é onde a extração é frágil. E alguns números são invisíveis para qualquer busca não interativa: preços renderizados no lado do cliente em um payload JavaScript, marcadores literais "null", ou números desenhados dentro de uma imagem.