DSPy + Scrapeless: Dê ao seu programa DSPy ferramentas web ao vivo via MCP

TL;DR:

• O DSPy converte as ferramentas do Servidor MCP do Scrapeless em objetos dspy.Tool com dspy.Tool.from_mcp_tool, oferecendo a um programa DSPy todas as 21 ferramentas web, de scrape_markdown a um conjunto completo de navegador.
• Cada ferramenta convertida está vinculada a uma mcp.ClientSession ativa, então as ferramentas só funcionam enquanto essa sessão estiver aberta; mantenha todo o fluxo dentro de um bloco async with ClientSession(...).
• A conversão das ferramentas e a chamada direta de uma com acall são executadas sem um modelo de linguagem configurado; apenas a execução do dspy.ReAct precisa de um LM.
• dspy.Tool.from_mcp_tool(session, tool) recebe a sessão e uma ferramenta MCP e retorna uma ferramenta DSPy que você pode chamar ou entregar a um módulo.
• Uma chamada direta a scrape_markdown retorna a página como Markdown, pronta para ser alimentada em uma assinatura DSPy.
• Comece no plano gratuito do Scrapeless e dê ao seu programa DSPy ferramentas web reais.

O DSPy é construído em uma ideia diferente da maioria dos frameworks de agentes: você declara o que deseja com uma assinatura e deixa o DSPy cuidar da solicitação. As ferramentas se encaixam nesse modelo de forma limpa, mas o DSPy não fornece um meio para acessar a web ao vivo. O Protocolo de Contexto de Modelos fornece isso. Converta as ferramentas de um servidor MCP em ferramentas DSPy, e um módulo dspy.ReAct pode chamá-las da mesma forma que chama qualquer outra ferramenta.

Este guia conecta o DSPy ao Servidor MCP do Scrapeless, converte suas 21 ferramentas, chama uma para valer e mostra onde uma chave de modelo de linguagem se torna necessária. A conversão e a chamada direta são verificadas contra o servidor ativo; a execução do módulo é marcada como a única pré-condição que precisa.

Por que Scrapeless MCP

O Servidor MCP do Scrapeless expõe ferramentas de web scraping e navegador que um agente pode chamar diretamente, então a camada de scraping não é algo que você constrói ou hospeda. Uma conexão serve 21 ferramentas: scrape_markdown e scrape_html para conteúdo, google_search e google_trends para dados de pesquisa, scrape_screenshot para capturas, e um conjunto completo browser_* que aciona um navegador em nuvem. O DSPy serve como ponte para todos eles através de dspy.Tool.from_mcp_tool, que transforma cada ferramenta MCP em uma ferramenta nativa DSPy.

As ferramentas browser_* acionam o navegador em nuvem Scrapeless, portanto, um programa pode navegar em uma página interativa e ler o que é renderizado, tudo na infraestrutura do Scrapeless. Para a visão do protocolo do mesmo servidor, o guia de integração MCP abrange como os clientes MCP se conectam em geral.

Pré-requisitos

• Python 3.10 ou posterior.
• Uma chave de API Scrapeless do painel, exportada como SCRAPELESS_API_KEY.
• Uma chave de modelo de linguagem (como OPENAI_API_KEY) apenas para a execução do dspy.ReAct. Converter e chamar as ferramentas não necessita de uma.

Instalação

Instale o DSPy e a biblioteca cliente MCP.

pip install dspy mcp

Defina sua chave Scrapeless no shell. Use a chave real em tempo de execução e mantenha o espaço reservado fora do seu código-fonte.

export SCRAPELESS_API_KEY="sk_your_key_here"

Abra uma Sessão e Converta as Ferramentas

A ponte MCP do DSPy funciona em uma sessão ativa. Abra uma conexão HTTP streamable, envolva-a em um mcp.ClientSession, inicialize-a, liste as ferramentas do servidor e converta cada uma com dspy.Tool.from_mcp_tool. A chave Scrapeless é enviada no cabeçalho x-api-token.

import asyncio
import os

import dspy
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main() -> None:
    async with streamablehttp_client(
        "https://api.scrapeless.com/mcp", headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            mcp_tools = (await session.list_tools()).tools
            tools = [dspy.Tool.from_mcp_tool(session, t) for t in mcp_tools]
            names = sorted(t.name for t in tools)
            print("ferramentas dspy:", len(tools))
            print("ferramentas:", ", ".join(names))


asyncio.run(main())

O servidor ativo gera 21 ferramentas DSPy, convertidas sem um modelo de linguagem configurado.

ferramentas dspy: 21
ferramentas: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

Cada ferramenta convertida mantém uma referência à sessão, razão pela qual a conversão e tudo que usa as ferramentas permanece dentro do bloco async with ClientSession(...). Feche a sessão e as ferramentas param de funcionar. A camada de transporte e a camada de mensagem seguem a especificação do Protocolo de Contexto de Modelo, que se baseia em a especificação JSON-RPC 2.0.

Chamar uma Ferramenta

Uma ferramenta DSPy pode ser chamada por si só, então você pode executar uma antes de construir um módulo. acall invoca a ferramenta com argumentos de palavra-chave e retorna seu resultado.

import asyncio
import os

import dspy
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main() -> None:
    async with streamablehttp_client(
        "https://api.scrapeless.com/mcp", headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            mcp_tools = (await session.list_tools()).tools
            tools = [dspy.Tool.from_mcp_tool(session, t) for t in mcp_tools]
            scrape_markdown = next(t for t in tools if t.name == "scrape_markdown")
            result = await scrape_markdown.acall(url="https://quotes.toscrape.com/")
            text = result if isinstance(result, str) else str(result)
            print("caracteres markdown:", len(text))
            print("contém uma citação:", "O mundo como o criamos" in text)


asyncio.run(main())

A chamada retorna a página em Markdown, e a verificação de conteúdo confirma que uma citação real está presente.

caracteres markdown: 4308
contém uma citação: True

Chamar uma ferramenta diretamente é a forma mais rápida de confirmar a conexão e inspecionar o que uma ferramenta retorna, e é o mesmo objeto que um módulo chamará. A documentação do DSPy aborda ferramentas, assinaturas e módulos de forma completa.

Integrar as Ferramentas em um Módulo

dspy.ReAct aceita uma assinatura e uma lista de ferramentas e executa o loop razão-ação. Este é o passo que precisa de um modelo de linguagem: configure um com dspy.configure, e então deixe o módulo decidir quando chamar scrape_markdown ou qualquer outra ferramenta. Como as ferramentas estão vinculadas à sessão, o módulo é executado dentro do mesmo bloco async with ClientSession(...) que as converteu.

Nota: dspy.configure(lm=...) e a execução dspy.ReAct precisam de uma chave de modelo de linguagem, como OPENAI_API_KEY, que não está configurada aqui. Converter as 21 ferramentas e a chamada direta de scrape_markdown acima funcionam sem isso. Este bloco é mostrado em sua forma exata; apenas a viagem de ida e volta do modelo é uma lacuna pré-requisito.

# dentro do bloco `async with ClientSession(...)`, após converter `tools`
dspy.configure(lm=dspy.LM("openai/gpt-4o"))
agent = dspy.ReAct("pergunta -> resposta", tools=tools)
result = await agent.acall(
    question="Busque https://quotes.toscrape.com/ e liste as três primeiras citações com seus autores."
)
print(result.answer)

Em tempo de execução, o módulo lê a assinatura, chama scrape_markdown para obter a página, raciocina sobre o Markdown que a chamada direta já demonstrou e preenche o campo answer. As ferramentas são os mesmos objetos, independentemente de o módulo chamá-las ou você fazê-lo.

Conclusão

O DSPy mais o Servidor MCP Scrapeless mantém o estilo declarativo do DSPy enquanto adiciona alcance real na web. dspy.Tool.from_mcp_tool converte as 21 ferramentas, acall prova que uma funciona, e dspy.ReAct as transforma em um programa em execução. A única regra a lembrar é que as ferramentas vivem na sessão, então mantenha o fluxo dentro de um bloco de sessão, e apenas a execução do módulo necessita de uma chave de modelo. Comece a partir dos scripts acima, delimite as ferramentas ao que sua assinatura necessita e deixe o DSPy fazer a solicitação.

Criar uma conta Scrapeless gratuita para obter uma chave de API e verifique os preços do Scrapeless quando planejar um programa recorrente.

FAQ

P: O DSPy precisa de um modelo de linguagem para carregar ferramentas MCP?

Não. Abrir a sessão, listar as ferramentas, convertê-las com dspy.Tool.from_mcp_tool e chamar uma com acall tudo funciona apenas com a chave da API Scrapeless. Uma chave de modelo de linguagem é necessária apenas para dspy.ReAct, quando o próprio módulo decide quais ferramentas chamar.

P: Por que o código deve permanecer dentro de um bloco ClientSession?

dspy.Tool.from_mcp_tool vincula cada ferramenta à mcp.ClientSession que você passa, então as ferramentas emitem suas chamadas através dessa sessão. Uma vez que o bloco async with ClientSession(...) sai, a sessão se fecha e as ferramentas não podem mais ser executadas, razão pela qual a conversão e o uso das ferramentas pertencem ao mesmo bloco.
Q: Como a integração MCP do DSPy é diferente das estruturas de adaptador?

O DSPy converte ferramentas a partir de um mcp.ClientSession bruto com dspy.Tool.from_mcp_tool, em vez de por meio de um adaptador de nível superior que gerencia a conexão para você. O compromisso é um controle explícito da duração da sessão em troca de uma dependência a menos, e mantém as ferramentas como objetos ordinários dspy.Tool.

Q: Como faço para chamar uma ferramenta sem construir um módulo?

Cada ferramenta convertida pode ser chamada com acall e argumentos de palavra-chave, então await scrape_markdown.acall(url="...") retorna diretamente o resultado da ferramenta. Isso é útil para confirmar a conexão e inspecionar a saída antes de envolver as ferramentas em um módulo dspy.ReAct.

Q: Como posso dar a um módulo apenas algumas das ferramentas?

from_mcp_tool é executado por ferramenta, então construa a lista de tools a partir das ferramentas MCP que você deseja, ou filtre a lista convertida antes de passá-la para dspy.ReAct. Passar a um módulo apenas scrape_markdown e google_search é mais seguro do que o conjunto completo de 21 ferramentas quando a tarefa precisa apenas de conteúdo e pesquisa.

Q: A raspagem por meio das ferramentas é limitada pelas regras do alvo?

Sim. As ferramentas acessam páginas públicas, e você continua responsável por respeitar os termos de cada alvo e suas diretrizes do Protocolo de Exclusão de Robots. Mantenha o volume limitado e os dados públicos, e escopo o módulo para as ferramentas que a tarefa realmente necessita.