LlamaIndex + Scrapeless: Alimente Seu Índice com Páginas da Web ao Vivo

Um índice de recuperação é tão atual quanto os documentos que você coloca nele. O LlamaIndex lida bem com o particionamento, incorporação e recuperação; a parte que falha silenciosamente é a etapa anterior a tudo isso, onde páginas da web ao vivo precisam se tornar texto limpo.

Conectar o LlamaIndex ao Servidor MCP do Scrapeless cobre essa etapa. As ferramentas MCP retornam páginas renderizadas como markdown, o LlamaIndex as encapsula como objetos Document, e o restante do seu pipeline de ingestão prossegue inalterado. Este guia executa a conexão, a descoberta de ferramentas, uma recuperação de página real e a divisão de documento para nó de ponta a ponta.

O Que Esta Configuração Oferece ao Seu Índice

Seu código de ingestão obtém 21 ferramentas chamáveis de uma conexão, e elas chegam como ferramentas nativas do LlamaIndex em vez de algo que você encapsula por conta própria.

Os grupos são importantes para a ingestão:

• Recuperação de página — scrape_markdown retorna uma página já convertida para markdown, que é o formato que um divisor e um modelo de incorporação lidam melhor. scrape_html e scrape_screenshot retornam as outras duas formas.
• Busca — google_search e google_trends permitem que um trabalho de ingestão descubra URLs em vez de receber uma lista fixa.
• Controle do navegador ao vivo — dezesseis ferramentas browser_* para páginas que precisam de interação antes que o conteúdo exista.

A renderização, roteamento de proxy e manuseio de acesso acontecem no lado do servidor, de modo que o processo de ingestão permanece uma tarefa simples em Python, sem necessidade de instalar um navegador.

Por Que o Servidor MCP do Scrapeless

A especificação do Protocolo de Contexto do Modelo define como um cliente descobre ferramentas e seus esquemas de argumentos a partir de um servidor, o que torna isso diferente de escrever um helper de busca: a lista de ferramentas e os parâmetros de cada ferramenta vêm do servidor em vez de serem codificados diretamente em seu projeto. As chamadas viajam como mensagens de JSON-RPC 2.0.

O Scrapeless hospeda o endpoint, portanto não há processo de servidor para rodar ao lado do seu indexador. A autenticação é um cabeçalho. O grupo browser_* é apoiado pelo Navegador de Scraping do Scrapeless, e os parâmetros por ferramenta estão documentados na documentação do Scrapeless.

Pré-requisitos

• Python 3.10 ou superior. Tanto llama-index-core quanto llama-index-tools-mcp atualmente declaram >=3.10,<4.0.
• Uma chave API do Scrapeless do painel.
• Apenas para a seção de agente: um pacote de integração LLM como llama-index-llms-openai mais a chave daquele provedor.

Nota: Tudo através da seção de ingestão abaixo foi executado com uma chave do Scrapeless e sem a chave de um provedor de modelo. A conexão MCP, descoberta de ferramentas, esquemas de argumentos, a chamada de ferramenta ao vivo e a divisão Document-para-nó ocorreram. A etapa do agente no final é uma lacuna nos pré-requisitos - construir um FunctionAgent gera ImportError: pacote llama-index-llms-openai não encontrado sem uma integração LLM instalada, então aquele bloco é mostrado como o código que você adiciona em vez de como uma saída capturada.

Instalar

pip install "llama-index-tools-mcp==0.4.8"

Esse pacote traz llama-index-core e o cliente mcp com ele. Defina a chave no seu shell:

export SCRAPELESS_API_KEY="sua_chave_api_aqui"

Conectar e Listar as Ferramentas

BasicMCPClient recebe a URL do endpoint e os cabeçalhos; McpToolSpec transforma a lista de ferramentas do servidor em ferramentas do LlamaIndex:

import asyncio, os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

async def main():
    client = BasicMCPClient(
        "https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    spec = McpToolSpec(client=client)
    tools = await spec.to_tool_list_async()
    print("contagem de ferramentas:", len(tools))
    print("nomes de exemplo:", sorted(t.metadata.name for t in tools)[:6])

asyncio.run(main())

contagem de ferramentas: 21
nomes de exemplo: ['browser_click', 'browser_close', 'browser_create', 'browser_get_html', 'browser_get_text', 'browser_go_back']

A API é assíncrona em todo o processo, por isso o exemplo é executado dentro do asyncio.run. Os nomes das ferramentas chegam de forma simples, sem prefixo de servidor ou namespace pontuado, então scrape_markdown é o nome literal que seu código e seu agente usarão.

Levar Apenas as Ferramentas que o Trabalho Necessita

Um trabalho de ingestão raramente precisa de controle de sessão do navegador. McpToolSpec aceita allowed_tools e retorna apenas essas, mantendo a superfície pequena e os esquemas fáceis de ler:

import asyncio, os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

async def main():
    client = BasicMCPClient(
        "https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
```text
contagem filtrada: 1
nome: scrape_markdown
campos do fn_schema: ['url']

O esquema vem do servidor, portanto, é o contrato real em vez de uma suposição: scrape_markdown aceita uma única url. LlamaIndex o expõe como fn_schema, o mesmo modelo Pydantic que um agente usaria para construir sua chamada.

Pronto para direcionar isso para suas próprias fontes? Crie uma conta gratuita no Scrapeless e conecte-se com a chave do seu painel.

Transforme Páginas Ao Vivo em Nós

Esta é a parte que importa para a recuperação. Chame a ferramenta diretamente, envolva cada resultado como um Document com sua fonte nos metadados e, em seguida, divida em nós:

import asyncio, os
from llama_index.tools.mcp import BasicMCPClient, McpToolSpec
from llama_index.core import Document
from llama_index.core.node_parser import SentenceSplitter

async def main():
    client = BasicMCPClient(
        "https://api.scrapeless.com/mcp",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    )
    spec = McpToolSpec(client=client, allowed_tools=["scrape_markdown"])
    tool = (await spec.to_tool_list_async())[0]

    urls = [
        "https://quotes.toscrape.com/js/",
        "https://quotes.toscrape.com/page/2/",
    ]

    docs = []
    for url in urls:
        markdown = str(await tool.acall(url=url))
        docs.append(Document(text=markdown, metadata={"source": url}))
    print(f"documentos: {len(docs)}")

    splitter = SentenceSplitter(chunk_size=256, chunk_overlap=32)
    nodes = splitter.get_nodes_from_documents(docs)
    print(f"nós após a divisão: {len(nodes)}")
    print(f"primeira fonte do nó: {nodes[0].metadata['source']}")
    print(f"primeiro nó caracteres: {len(nodes[0].get_content())}")

asyncio.run(main())

documentos: 2
nós após a divisão: 14
primeira fonte do nó: https://quotes.toscrape.com/js/
primeiro nó caracteres: 571

Várias coisas nessa saída valem a pena serem lidas com atenção.

A primeira URL é uma página renderizada pelo cliente — seu conteúdo é escrito no DOM por um script — e ainda assim produziu markdown utilizável, porque a renderização ocorreu no lado do servidor antes da conversão. Uma simples busca HTTP dessa mesma URL retorna uma marcação sem nenhum conteúdo.

chunk_size=256 conta tokens, não caracteres, que é o motivo pelo qual o primeiro nó tem 571 caracteres de comprimento. Dimensionar um divisor em caracteres é uma maneira comum de acabar com partes que transbordam o contexto de um modelo de incorporação.

O metadata={"source": url} em cada Document sobrevive à divisão e é mantido em cada nó derivado dele. Isso é o que permite que um resultado de recuperação cite de onde veio, e é muito mais fácil anexar aqui do que reconstruir mais tarde.

Markdown é o formato intermediário certo para isso: cabeçalhos e links sobrevivem, enquanto scripts, estilos e marcações de layout não, de modo que o orçamento de incorporação vai para o conteúdo.

Dê as Ferramentas a um Agente

Uma vez que as ferramentas estão em mãos, um agente pode decidir qual chamar em vez de seguir uma lista fixa de URLs. Este passo precisa de um pacote de integração LLM e da chave do provedor.

Nota: Este bloco é uma lacuna de pré-requisito. Sem uma integração LLM instalada, construir o agente gera ImportError: pacote llama-index-llms-openai não encontrado, por favor, execute pip install llama-index-llms-openai, então nenhuma saída é exibida para ele.

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI

agent = FunctionAgent(
    tools=tools,
    llm=OpenAI(model="gpt-4.1-mini"),
    system_prompt="Pesquise páginas públicas e retorne notas limpas com fontes.",
)

response = await agent.run("Resuma os autores citados em quotes.toscrape.com")
print(response)

Conclusão

Conectar LlamaIndex ao Servidor MCP do Scrapeless requer um cliente, uma especificação de ferramenta e um cabeçalho. O servidor fornece 21 ferramentas com seus próprios esquemas de argumento, allowed_tools os restringe ao que um trabalho de ingestão realmente precisa, e scrape_markdown retorna páginas no formato que tanto um divisor quanto um modelo de incorporação preferem.

O hábito que vale a pena levar adiante é anexar a URL fonte como metadados do Document no momento da busca. Custa um dicionário, sobrevive à divisão do nó e é o que transforma um acerto de recuperação em uma resposta que você pode rastrear de volta a uma página.
Comece no plano gratuito Scrapeless para obter uma chave, verifique os preços do Scrapeless ao dimensionar uma execução de ingestão e veja a visão geral do Scrapeless MCP Server para a referência completa da ferramenta.

FAQ

Q: Qual é o endpoint do Scrapeless MCP Server para LlamaIndex?

O endpoint hospedado é https://api.scrapeless.com/mcp, acessado com sua chave no cabeçalho x-api-token via BasicMCPClient. Não há processo de servidor local para ser executado, pois as ferramentas são servidas remotamente.

Q: Quantas ferramentas o Scrapeless MCP Server expõe ao LlamaIndex?

Uma conexão ao vivo retorna 21: dezesseis ferramentas de controle de sessão browser_*, três ferramentas de recuperação de página (scrape_markdown, scrape_html, scrape_screenshot) e duas ferramentas de busca (google_search, google_trends). Enumere-as em tempo de execução, em vez de assumí-las, pois um servidor pode adicionar ferramentas entre lançamentos.

Q: Posso carregar apenas algumas ferramentas MCP?

Sim. Passe allowed_tools=["scrape_markdown"] para McpToolSpec e a lista voltará apenas com essa ferramenta. Para ingestão, isso vale a pena — mantém os esquemas legíveis e impede que um agente abra sessões de navegador que não precisa.

Q: Preciso de uma chave LLM para buscar páginas por meio do MCP?

Não. A conexão, descoberta de ferramentas, inspeção de esquema e tool.acall(...) direto funcionam apenas com a chave Scrapeless. Um provedor de modelo é necessário assim que você entrega as ferramentas a um agente, pois é nesse momento que algo precisa decidir qual ferramenta chamar.

Q: Por que usar markdown em vez de HTML para recuperação?

Markdown mantém a estrutura que ajuda na recuperação — cabeçalhos, listas, links — e elimina os scripts, estilos e marcação de layout que consomem contexto de incorporação sem adicionar significado. scrape_html ainda é a escolha certa quando você pretende executar seus próprios seletores em vez de incorporar o texto.

Q: Como posso acompanhar de qual página um trecho recuperado veio?

Coloque a URL em Document(metadata={"source": url}) ao criar o documento. Essa metadata é copiada em cada nó que o divisor deriva dele, para que cada trecho recuperado carrega sua origem sem nenhuma contabilidade extra.

Q: O que devo verificar antes de ingerir um site?

Revise os termos do site e suas diretrizes /robots.txt, que seguem o padrão do Protocolo de Exclusão de Robôs. Mantenha a ingestão a páginas públicas, trabalhe a partir de uma lista de URLs explícita ou de um passo de descoberta delimitado, e registre a URL de origem em cada documento para que a proveniência de qualquer coisa que o índice retorne permaneça clara.