DSPy + Scrapeless: MCP経由でDSPyプログラムにライブウェブツールを提供する

TL;DR:

• DSPyは、Scrapeless MCPサーバーのツールをdspy.Toolオブジェクトに変換し、dspy.Tool.from_mcp_toolを使用して、scrape_markdownからフルブラウザセットまでの21のウェブツールをDSPyプログラムに提供します。
• 各変換されたツールは、ライブのmcp.ClientSessionにバインドされているため、そのセッションが開いている間だけツールが機能します。すべてのフローを1つのasync with ClientSession(...)ブロック内に収めてください。
• ツールを変換し、acallで1つを直接呼び出すことは、言語モデルを設定せずに実行できます。dspy.ReActの実行のみがLMを必要とします。
• dspy.Tool.from_mcp_tool(session, tool)は、セッションと1つのMCPツールを受け取り、呼び出すことができるDSPyツールを返します。
• 直接のscrape_markdown呼び出しは、ページをMarkdownとして返し、DSPyシグネチャに入力できる状態になります。
• Scrapelessの無料プランに登録し、DSPyプログラムに本物のウェブツールを提供してください。

DSPyはほとんどのエージェントフレームワークとは異なるアイデアに基づいて構築されています：シグネチャで欲しいものを宣言し、DSPyにプロンプト処理を任せます。ツールはそのモデルにきれいに適合しますが、DSPyはライブウェブへのアクセス手段を提供しません。モデルコンテキストプロトコルがそれを提供します。MCPサーバーのツールをDSPyツールに変換すれば、dspy.ReActモジュールはそれらを他のツールと同様に呼び出すことができます。

このガイドはDSPyをScrapeless MCPサーバーに接続し、その21のツールを変換し、実際に1つを呼び出し、言語モデルキーが必要になる場所を示します。変換と直接呼び出しはライブサーバーに対して検証されています。モジュールの実行は、1つの前提条件としてマークされています。

なぜScrapeless MCPか

Scrapeless MCPサーバーは、エージェントが直接呼び出すことができるウェブスクレイピングおよびブラウザツールを公開しているため、スクレイピングレイヤーは開発またはホストするものではありません。1つの接続が21のツールを提供します：scrape_markdownおよびscrape_htmlによるコンテンツ、google_searchおよびgoogle_trendsによる検索データ、scrape_screenshotによるキャプチャ、およびクラウドブラウザを駆動するフルbrowser_*セット。DSPyは、各MCPツールをネイティブDSPyツールに変換するdspy.Tool.from_mcp_toolを介して、これらすべてに橋渡しをします。

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="Fetch https://quotes.toscrape.com/ and list the first three quotes with their authors."
)
print(result.answer)

実行時にモジュールはシグネチャを読み取り、ページを取得するために scrape_markdown を呼び出し、直接呼び出しで示された Markdown に基づいて推論し、answer フィールドを埋めます。ツールはモジュールが呼び出すときでも、あなたが呼び出すときでも同じオブジェクトです。

結論

DSPy と Scrapeless MCP サーバーは、DSPy の宣言的スタイルを維持しながら、実際のウェブへのアクセスを追加します。 dspy.Tool.from_mcp_tool が21のツールを変換し、acall がそれらの1つが機能することを証明し、dspy.ReAct がそれらを実行中のプログラムに変えます。覚えておくべき一つのルールは、ツールがセッションに存在するため、すべての流れを一つのセッションブロック内に留め、モジュールの実行時だけがモデルキーを必要とすることです。上記のスクリプトから始め、ツールをシグネチャが必要とするものにスコープし、DSPy にプロンプトを実行させてください。

無料のScrapelessアカウントを作成してAPIキーを取得し、定期的なプログラムを計画するときは Scrapelessの料金 を確認してください。

FAQ

Q: DSPy は MCP ツールをロードするために言語モデルが必要ですか？

いいえ。セッションを開き、ツールをリストし、dspy.Tool.from_mcp_toolで変換し、acall で1つを呼び出すことは、Scrapeless APIキーのみで実行できます。言語モデルキーは、モジュール自体がどのツールを呼び出すかを決定する際にのみ dspy.ReAct に必要です。

Q: なぜコードは1つの ClientSession ブロック内に留まらなければならないのですか？

dspy.Tool.from_mcp_tool は各ツールを渡した mcp.ClientSession にバインドするため、ツールはそのセッションを通して呼び出しを行います。async with ClientSession(...) ブロックを抜けると、セッションは閉じられ、ツールはもう実行できなくなります。そのため、ツールの変換と使用は同じブロック内で行う必要があります。
Q: DSPyのMCP統合はアダプターフレームワークとどのように異なりますか？

DSPyは、接続を管理する高レベルのアダプタを介さずに、dspy.Tool.from_mcp_toolを使用して生のmcp.ClientSessionからツールを変換します。このトレードオフは、依存関係が一つ減る代わりに、セッションのライフタイムを明示的に制御できることです。また、ツールは通常のdspy.Toolオブジェクトとして保持されます。

Q: モジュールを構築せずにツールを呼び出すにはどうすればよいですか？

変換されたすべてのツールはacallとキーワード引数を使って呼び出すことができるため、await scrape_markdown.acall(url="...")はツールの結果を直接返します。これは、接続を確認し、ツールをdspy.ReActモジュールにラップする前に出力を検査するのに便利です。

Q: モジュールに特定のツールだけを渡すにはどうすればよいですか？

from_mcp_toolはツールごとに実行されるため、必要なMCPツールだけからtoolsリストを構築するか、変換されたリストをフィルタリングしてdspy.ReActに渡します。タスクがコンテンツと検索だけを必要とする場合、モジュールにscrape_markdownとgoogle_searchのみにする方が、フル21ツールセットよりも安全です。

Q: ターゲットのルールに縛られてツールを使用してスクレイピングを行うことはできますか？

はい。ツールは公開ページを取得し、各ターゲットの条件とそのロボット除外プロトコルの指示を遵守する責任があります。ボリュームを制限し、データを公開のままにし、タスクに実際に必要なツールにスコープを絞ってモジュールを構築してください。