DSPy + Scrapeless：通过MCP为您的DSPy程序提供实时网络工具

TL;DR：

• DSPy将Scrapeless MCP服务器的工具转换为dspy.Tool对象，使用dspy.Tool.from_mcp_tool，使DSPy程序获得21个网络工具，从scrape_markdown到完整的浏览器集合。
• 每个转换的工具都与一个活跃的mcp.ClientSession绑定，因此工具只在该会话打开时工作；将整个流程保留在一个async with ClientSession(...)块内。
• 转换工具并直接使用acall调用一个工具时无需配置语言模型；只有dspy.ReAct的运行需要一个语言模型。
• dspy.Tool.from_mcp_tool(session, tool)接受会话和一个MCP工具，并返回一个可以调用或交给模块的DSPy工具。
• 直接调用scrape_markdown会返回页面的Markdown格式，准备输入到DSPy签名中。
• 开始使用Scrapeless免费计划，让你的DSPy程序获得真实的网络工具。

DSPy基于一个与大多数代理框架不同的理念：你通过签名声明你的需求，让DSPy处理提示。工具完美契合这一模型，但DSPy没有提供访问实时网络的方式。模型上下文协议提供了这一途径。将MCP服务器的工具转换为DSPy工具后，dspy.ReAct模块可以像调用任何其他工具一样调用这些工具。

本指南将DSPy与Scrapeless MCP服务器连接，转换其21个工具，实际调用一个，并展示何时需要一个语言模型密钥。转换和直接调用经过实时服务器验证；模块运行标记为它所需的唯一前提条件。

为什么选择Scrapeless MCP

Scrapeless MCP服务器公开了可由代理直接调用的网络抓取和浏览器工具，因此抓取层不是你构建或托管的内容。一条连接提供21个工具：用于内容的scrape_markdown和scrape_html，用于搜索数据的google_search和google_trends，用于捕捉的scrape_screenshot，以及驱动云浏览器的完整browser_*工具集合。DSPy通过dspy.Tool.from_mcp_tool连接到它们，将每个MCP工具转换为原生DSPy工具。

browser_*工具驱动Scrapeless云浏览器，因此程序可以在Scrapeless基础设施上导航交互页面并读取渲染内容。关于同一服务器的协议视图，MCP集成指南涵盖了MCP客户端的一般连接方式。

先决条件

• Python 3.10或更高版本。
• 来自仪表板的Scrapeless API密钥，导出为SCRAPELESS_API_KEY。
• 仅用于dspy.ReAct运行的语言模型密钥（例如OPENAI_API_KEY）。转换和调用工具不需要此密钥。

安装

安装DSPy和MCP客户端库。

pip install dspy mcp

在终端中设置Scrapeless密钥。在运行时使用真实密钥，并在源代码中保留占位符。

export SCRAPELESS_API_KEY="sk_your_key_here"

打开会话并转换工具

DSPy的MCP桥接在一个活跃会话中工作。打开一个可流式的HTTP连接，将其包装在mcp.ClientSession中，初始化它，列出服务器的工具，并使用dspy.Tool.from_mcp_tool转换每个工具。Scrapeless密钥在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("dspy tools:", len(tools))
            print("tools:", ", ".join(names))


asyncio.run(main())

实时服务器提供21个DSPy工具，转换无需配置语言模型。

dspy tools: 21
tools: 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

每个转换的工具都持有对 session 的引用，这就是为什么转换以及所有使用这些工具的操作都保持在 async with ClientSession(...) 块内的原因。关闭会话后，工具将停止工作。传输和消息层遵循 模型上下文协议规范，该规范基于 JSON-RPC 2.0 规范。

调用工具

DSPy 工具可以独立调用，因此在构建模块之前可以先运行一个。acall 使用关键字参数调用工具并返回其结果。

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("markdown chars:", len(text))
            print("contains a quote:", "The world as we have created it" in text)


asyncio.run(main())

调用返回页面的 Markdown，内容检查确认存在真实的引用。

markdown chars: 4308
contains a quote: True

直接调用工具是确认连接并检查工具返回内容的最快方法，并且这是模块将调用的相同对象。DSPy 文档 完整介绍了工具、签名和模块。

将工具插入模块

dspy.ReAct 接收一个签名和一个工具列表，然后运行推理-行动循环。这一步需要一个语言模型：使用 dspy.configure 配置一个，然后让模块决定何时调用 scrape_markdown 或任何其他工具。由于工具绑定到会话，模块在同一个转换它们的 async with ClientSession(...) 块内运行。

注意：dspy.configure(lm=...) 和 dspy.ReAct 运行需要一个语言模型密钥，例如 OPENAI_API_KEY，这里没有设置。转换 21 个工具和上面的直接 scrape_markdown 调用在没有它的情况下运行。这个块以其确切的形状显示；只有模型的往返是一个前提条件缺口。

# 在 `async with ClientSession(...)` 块内，转换完`tools` 后
dspy.configure(lm=dspy.LM("openai/gpt-4o"))
agent = dspy.ReAct("question -> answer", tools=tools)
result = await agent.acall(
    question="提取 https://quotes.toscrape.com/ 并列出前三个引用及其作者。"
)
print(result.answer)

在运行时，模块读取签名，调用 scrape_markdown 来获取页面，基于已演示的 Markdown 进行推理，并填充 answer 字段。无论是模块调用它们还是你自己调用，工具都是相同的对象。

结论

DSPy 加上 Scrapeless MCP 服务器保持了 DSPy 的声明风格，同时增加了真实的网络访问能力。dspy.Tool.from_mcp_tool 转换了 21 个工具，acall 证明一个工具可以工作，dspy.ReAct 将它们变成一个正在运行的程序。需要记住的唯一规则是工具是基于会话的，因此保持流程在一个会话块内，并且只有模块运行需要模型密钥。从以上脚本开始，将工具范围限定在你的签名需要的内容上，让 DSPy 来处理提示。

创建一个免费的 Scrapeless 账户 以获取 API 密钥，当你计划进行定期程序时，查看 Scrapeless 定价。

常见问题

问：DSPy 需要语言模型来加载 MCP 工具吗？

不需要。打开会话、列出工具、使用 dspy.Tool.from_mcp_tool 转换它们以及使用 acall 调用其中一个工具都只需 Scrapeless API 密钥。只有在 dspy.ReAct 中，模块本身决定调用哪些工具时才需要语言模型密钥。

问：为什么代码必须保留在一个 ClientSession 块内？

dspy.Tool.from_mcp_tool 将每个工具绑定到你传递的 mcp.ClientSession，因此工具通过该会话发出调用。一旦退出 async with ClientSession(...) 块，会话关闭，工具将无法再运行，这就是为什么转换和使用工具需要在同一个块中的原因。
问：DSPy的MCP集成与适配器框架有什么不同？

DSPy将工具从原始的mcp.ClientSession转换为dspy.Tool.from_mcp_tool，而不是通过为你管理连接的更高级别的适配器。这样做的权衡是可以显式控制会话的生命周期，以换取一个更少的依赖，并且将工具保持为普通的dspy.Tool对象。

问：如何在不构建模块的情况下调用工具？

每个转换后的工具都可以通过acall和关键字参数调用，因此await scrape_markdown.acall(url="...")会直接返回工具的结果。这在确认连接以及检查输出之前，将工具包装在dspy.ReAct模块中是很有用的。

问：如何只给模块提供部分工具？

from_mcp_tool是按工具运行的，因此从你想要的MCP工具中构建tools列表，或者在传递给dspy.ReAct之前过滤转换后的列表。仅将scrape_markdown和google_search交给模块在任务只需要内容和搜索时比全21个工具集更安全。

问：通过工具抓取是否受目标规则的约束？

是的。工具获取公共页面，你仍然负责遵守每个目标的条款及其机器人排除协议指令。要保持数据获取的数量有限，并确保数据是公开的，并将模块的范围限制在任务实际需要的工具上。