Por que razão a cola para ferramentas personalizadas falha

Os agentes precisam de ferramentas web reais, e não de wrappers personalizados em Python

Todas as equipas criam a mesma «cola»: uma ferramenta em Python por fonte de recolha de dados, um armazenamento de sessões meio avariado, um orquestrador caseiro que perde o contexto após uma chamada. Três semanas depois, o agente funciona uma vez, avaria-se duas vezes e ninguém se lembra de qual foi o proxy que expirou. Fornecemos as quatro componentes de que cada ciclo de agente necessita, prontas a utilizar — através do MCP, com um único ponto de extremidade HTTP.

Se o seu agente já atingiu o tempo limite na terceira etapa de um rastreio com várias etapas — isto é para si.

Uma ferramenta Python personalizada para cada fonte

O problema. Cada nova funcionalidade do agente representa mais um @tool decorador: um para a Amazon, outro para o eBay e outro para o wiki da empresa. Desvio de esquema, incompatibilidade de versões e um registo de ferramentas pelo qual ninguém se responsabiliza. A integração de um novo modelo implica reimplementar os wrappers a partir do zero.

Como o Yozh Scraper resolve o problema. Um ponto final HTTP MCP que localhost:8000/mcp expõe automaticamente todas as funcionalidades — scrape_page, scrape_batch, crawl, sessions, presets. Basta adicionar uma linha à configuração do Claude / Cursor / Cline e o modelo descobre as ferramentas em tempo de execução. O mesmo ponto de extremidade, para todos os clientes.

Um endpoint MCP
Deteção automática
Zero código de ligação

As chamadas à ferramenta sem estado perdem o contexto de início de sessão

O problema. As chamadas da ferramenta não mantêm o estado — cada chamada inicia um novo navegador, apaga os cookies e falha na segunda etapa da autenticação de duas etapas (2FA). Os agentes que ficam presos num ciclo de reautenticação esgotam os tokens e desistem na terceira tentativa. O armazenamento manual de cookies é frágil e perde-se entre execuções.

Como o Yozh Scraper resolve isso. API de sessões com um session_id que o agente transmite entre chamadas. DSL de login declarativo (goto / fill / click / wait) ou colar os cookies exportados uma única vez — o `storageState` persiste durante 24 horas. Cada chamada subsequente da ferramenta reutiliza a sessão, sem necessidade de nova autenticação.

session_id persistente
Login declarativo
TTL de 24h

Autenticação manual e configuração do proxy no código do agente

O problema. Todos os agentes acabam por ter de lidar com chaves API, rotação de proxies, códigos de país e novas tentativas — configurações que nada têm a ver com a função do modelo. Os segredos acabam por aparecer nos prompts, o agente toma decisões «criativas» sobre as novas tentativas e os orçamentos para proxies disparam numa semana.

Como o Yozh Scraper resolve o problema. CYBERYOZH_API_KEY No .env — o código do agente nunca tem acesso às credenciais. Escolha proxy: {country: "us", type: "mobile"} na chamada da ferramenta, o Yozh trata da rotação, da impressão digital e das tentativas de reenvio do lado do servidor. O agente mantém-se focado no raciocínio.

Autenticação no servidor
Proxy declarativo
Sem segredos nos prompts

Rastreamentos em várias etapas dentro de um ciclo de agente

O problema. «Encontrar todas as páginas de produtos neste site e extrair os preços» é uma intenção do utilizador — mas, no código do agente, traduz-se em 200 chamadas à ferramenta, uma fila, uma camada de deduplicação e a gestão do tempo de espera. O modelo desperdiça uma janela de contexto na gestão de URLs que nunca deveria ter de lidar.

Como o Yozh Scraper resolve o problema. O Yozh Crawler percorre o site do lado do servidor, transmite os URLs descobertos através do SSE e encaminha-os para o scraper sempre que encontra uma correspondência. O agente é acionado crawl_and_scrape uma vez e obtém um único fluxo de resultados estruturados. O servidor mantém a fila e o modelo mantém o seu contexto.

Streaming SSE
Fila no servidor
Uma chamada de ferramenta

Como funciona

De `docker compose up` até às ferramentas de chamadas dos agentes — em 3 passos

Um ponto final MCP, uma linha de configuração no seu cliente, sem código de ligação. O mesmo fluxo funciona para o Claude Desktop, o Cursor, o Cline ou o seu próprio ciclo de agente.

1 Iniciar o ponto de extremidade MCP

Clona o repositório e docker compose up. O servidor MCP está ativo em localhost:8000/mcp — o scraper, o crawler, as sessões e as predefinições são todos automaticamente disponibilizados como ferramentas.

# one-time setup
git clone 
  github.com/CyberYozh-data/yozh-scraper
cd yozh-scraper
docker compose up -d

2 Ligue-o ao seu cliente

Uma linha em claude_desktop_config.json (ou equivalente no Cursor / Cline). Reinicie o cliente — as ferramentas são detetadas automaticamente, sem necessidade de wrappers por fonte.

{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

3 Ferramentas para que o agente possa ligar

O modelo seleciona a ferramenta, preenche os parâmetros e recebe um JSON estruturado em resposta. As sessões são mantidas entre chamadas. Os rastreios em várias etapas são transmitidos através do SSE.

// claude calls scrape_page autonomously
{
  "tool":   "scrape_page",
  "input":  {"url": "…",
              "preset": "amazon_product"},
  "result": { /* structured JSON */ }
}

Exemplo prático

O que ganha em troca — um único formato, para todos os mercados

Escolha uma predefinição para ver como fica a resposta. O conjunto de campos varia consoante a fonte, mas o formato do pedido é idêntico.

Receitas

Como os agentes fazem as ligações — em 10 linhas cada

Três configurações de agentes concretas, prontas a serem coladas. Desde comandos de uma linha do Claude Desktop até um ciclo completo do LangChain — todas elas utilizam o mesmo ponto de extremidade MCP.

1 Claude, agente de pesquisa documental

Ligue o Yozh ao Claude Desktop uma vez. Peça ao modelo para pesquisar um tema — ele escolhe scrape_page / crawl de forma autónoma e sintetiza a resposta.

# claude_desktop_config.json (~/Library/...)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# restart Claude · prompt:
# "compare ssd prices on amazon vs walmart"
# → claude calls scrape_page on each PDP

Transporte HTTP deteção automática de ferramentas sem código de ligação

2 Cursor Copilot com ferramentas web

Adicione o mesmo servidor MCP ao Cursor — o seu agente IDE já pode obter documentação em tempo real, verificar os preços da concorrência ou extrair uma resposta do Stack Overflow a meio de um prompt.

# .cursor/mcp.json (project root)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# prompt in Cmd+L composer:
# "fetch the latest pricing from acme.com/plans
#  and update PricingTable.tsx"

configuração por projeto mesmo endpoint MCP chamadas de ferramentas no chat

3 Ciclo do LangChain / SDK da Anthropic

Agente Python simples — SDK da Anthropic com mcp_servers lista. Basta uma URL HTTP para que o modelo obtenha todas as ferramentas do Yozh. Funciona da mesma forma com o adaptador MCP do LangChain.

# anthropic SDK · plain python
client = Anthropic()
resp   = client.messages.create(
  model="claude-sonnet-4-5",
  mcp_servers=[{
    "type": "url",
    "url":  "https://your-host/mcp"
  }],
  messages=[{
    "role": "user",
    "content": "crawl docs.x.com, summarize"
  }],
)

Streaming SSE piloto automático multiferramenta o teu orquestrador

FAQ

Perguntas frequentes sobre o MCP e a integração de agentes

Quais são os clientes MCP suportados?

Qualquer elemento que utilize o protocolo de contexto de modelo (MCP) com transporte HTTP: Claude Desktop, Cursor, Cline, Continue, Zed, o nó MCP do n8n, o adaptador MCP do LangChain e o mcp_servers param. O ponto final em localhost:8000/mcp é uma única URL — basta apontar qualquer um deles para lá. Não é necessário manter wrappers específicos por cliente nem shims stdio.

Como é que as ferramentas são registadas no agente?

Detecção automática através do MCP. Quando o cliente se liga ao /mcp, o servidor lista todas as ferramentas disponíveis com o respetivo esquema JSON: scrape_page, scrape_batch, crawl, create_session, list_presets, generate_preset. O modelo reconhece-as como ferramentas nativas em tempo de execução — sem decoradores, sem esquema manual. Novas funcionalidades no upstream yozh-scraper aparecem automaticamente após a próxima atualização.

O meu agente pode transmitir um rastreio em várias etapas?

Sim — o Yozh Crawler rastreia o site do lado do servidor e transmite os URLs detetados através do SSE. O agente é acionado crawl uma única vez, obtendo um fluxo único de eventos com resultados estruturados à medida que estes vão chegando. Cada rastreio suporta definições de âmbito (mesmo domínio / mesmo anfitrião / lista de permissões), RPS por domínio e encadeamento opcional para o scraper, de modo a que cada URL encontrada seja analisada antes de chegar ao fluxo. O cancelamento com DELETE /scrape/{id} — a paragem suave permite que as páginas em processamento sejam concluídas; a paragem forçada é uma segunda chamada.

Como é que as sessões se mantêm entre chamadas à ferramenta?

API de sessões. Crie uma sessão uma única vez utilizando a DSL de login declarativa (goto / fill / click / wait) ou colando cookies exportados. O Yozh armazena cookies + Playwright storageState no lado do servidor e fornece-lhe um session_id. Cada chamada subsequente da ferramenta que passe esse ID reutiliza o mesmo estado do navegador — incluindo portais protegidos por autenticação de dois fatores (2FA), LinkedIn e administradores de parceiros. O TTL é de 24 horas por predefinição, mas pode ser atualizado. O agente nunca acede às credenciais; limita-se a reencaminhar o ID de sessão que recebeu.

Como posso ampliar as funcionalidades com ferramentas personalizadas?

Três opções. (1) Predefinição personalizada — coloque um ficheiro JSON em src/presets/custom/ ou chame POST /api/v1/presets/generate com um URL de exemplo e deixe que um LLM infira o esquema. A predefinição aparece como um parâmetro na scrape_page . (2) Ferramenta MCP personalizada — registe o seu próprio manipulador em src/mcp/tools/, que passa a integrar a lista de descoberta automática. (3) Fork — o repositório tem licença MIT, o servidor MCP reside num único módulo Python (src/mcp/server.py) e é fácil de ampliar.

Ferramentas que o seu agente pode realmente utilizar

Os agentes precisam de ferramentas web reais, e não de wrappers personalizados em Python

Uma ferramenta Python personalizada para cada fonte

As chamadas à ferramenta sem estado perdem o contexto de início de sessão

Autenticação manual e configuração do proxy no código do agente

Rastreamentos em várias etapas dentro de um ciclo de agente

De `docker compose up` até às ferramentas de chamadas dos agentes — em 3 passos

O que ganha em troca — um único formato, para todos os mercados

Como os agentes fazem as ligações — em 10 linhas cada

Perguntas frequentes sobre o MCP e a integração de agentes

Está pronto para dar ao seu agente ferramentas eficazes?

Apreciado pelas equipas de dados e pelos criadores de IA

Ferramentas que o seu agente pode realmente utilizar

Os agentes precisam de ferramentas web reais, e não de wrappers personalizados em Python

Uma ferramenta Python personalizada para cada fonte

As chamadas à ferramenta sem estado perdem o contexto de início de sessão

Autenticação manual e configuração do proxy no código do agente

Rastreamentos em várias etapas dentro de um ciclo de agente

De docker compose up até às ferramentas de chamadas dos agentes — em 3 passos

O que ganha em troca — um único formato, para todos os mercados

Como os agentes fazem as ligações — em 10 linhas cada

Perguntas frequentes sobre o MCP e a integração de agentes

Está pronto para dar ao seu agente ferramentas eficazes?

Apreciado pelas equipas de dados e pelos criadores de IA

De `docker compose up` até às ferramentas de chamadas dos agentes — em 3 passos