Mcp Aoai Web Browsing

MCP の実践：Web ブラウジング、プロトコル、アプリ

Azure OpenAI/OpenAI と連携する Playwright ブラウジングアプリケーションに加え、 MCP v1/v2、OAuth、インタラクティブな MCP Apps に焦点を当てたサンプルです。

1. 元のブラウジングアプリケーション — Azure OpenAI/OpenAI との連携、セットアップ、クライアント接続。
2. MCP v1 および v2 のサンプル — ブラウザツールとローカル OAuth フロー。
3. MCP Apps のサンプル — Prefab で構築された、インタラクティブなツール応答 UI。

1. Web ブラウジング MCP アプリケーション

Tkinter チャット UI と MCP から LLM へのブリッジを備えた、ローカルのブラウジングアプリケーションです。

• 元のサーバーはスタンドアロンの fastmcp パッケージを使用します。Playwright が 表示中の Chromium ブラウザーを操作し、ツール呼び出しの間も現在のページを保持します。
• ローカルの client_bridge 実装は、MCP ツール定義を OpenAI Chat Completions の関数呼び出しに適合させます。インプロセスの FastMCP サーバーと外部の stdio サーバーに対応しています。
• GUI は Azure OpenAI を使用します。Python の呼び出し元は標準の OpenAI 用にブリッジを設定できますが、元のブラウザーサーバーはセレクター抽出ツール用に別途独自の Azure クライアントを初期化します。

セットアップと実行

必要なもの：Python 3.13 以降、Tkinter、グラフィカルデスクトップセッション、 および uv。以下のコマンドでは、このプロジェクトの環境管理に uv を使用します。MCP 自体は特定の Python パッケージマネージャーを必要としません。リポジトリのルートから実行してください。

1. .env.template をローカルの .env ファイルにコピーし、 テンプレートはそのまま保持します。Chat Completions のツール呼び出しに対応する既存の Azure OpenAI デプロイを設定します。

   AZURE_OPEN_AI_ENDPOINT=
   AZURE_OPEN_AI_API_KEY=
   AZURE_OPEN_AI_DEPLOYMENT_MODEL=
   AZURE_OPEN_AI_API_VERSION=
   

   API バージョンが必要なのは、以下で説明する /openai/v1 パスではなく、従来の Azure エンドポイントです。.env はソース管理に含めないでください。gitignore に設定されています。

2. Python の依存関係と Chromium ブラウザーのバイナリをインストールします。

   uv sync
   uv run playwright install chromium
   

   Linux では、Playwright にシステム依存関係も必要になる場合があります。インストールガイドを参照してください。選択した Python インストール環境で Tkinter が利用できる必要があります。

3. プロジェクト環境で GUI を起動します。

   uv run python chatgui.py
   

ルートの依存関係宣言では、互換性の上限ではなく最小バージョンを指定しています。調査した環境では FastMCP 3.2.0 と MCP SDK 1.27.0 を使用していますが、新しいメジャーバージョンを新規に解決した場合に動作する保証はありません。学習用サンプルはそれぞれ別の環境に保管してください。

Azure v1 エンドポイントとモデルパラメーター

/openai/v1 で終わるエンドポイントの場合、AZURE_OPEN_AI_ENDPOINT に完全な URL を、AZURE_OPEN_AI_DEPLOYMENT_MODEL に既存のデプロイ名を設定します。このパスは OpenAI 互換クライアントを使用するため、API バージョンは不要です。 AZURE_OPEN_AI_API_KEY を使用するか、キーが未設定の場合はプロセス環境変数 AZURE_OPENAI_AD_TOKEN を通じて有効期間の短い Entra トークンを指定します。 トークンは自動更新されません。起動前に更新し、ファイルにコミットしないでください。

外部クライアントでの使用

外部クライアントは元のサーバーを stdio 経由で起動します。まず上記のセットアップを完了してください。 サーバーはリポジトリの .env を読み込み、ホストが別のモデルプロバイダーを使用する場合でも、起動時に Azure の設定を必要とします。共有の MCP JSON 設定に認証情報を記載しないでください。

{
  "mcpServers": {
    "browser-navigator": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-aoai-web-browsing", "run", "fastmcp", "run", "server/browser_navigator_server.py:app", "--transport", "stdio"]
    }
  }
}

{
  "servers": {
    "browser-navigator": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "fastmcp", "run", "server/browser_navigator_server.py:app", "--transport", "stdio"],
      "cwd": "${workspaceFolder}",
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

ブリッジをプログラムから使用する

stdio 経由で接続する

リポジトリのルートから、この例を実行します。ブリッジがモデルのループを処理し、子サーバーはローカルの .env から Azure の設定を独自に読み込みます。

import asyncio

from client_bridge import BridgeConfig, MCPServerConfig, BridgeManager
from client_bridge.llm_config import get_default_llm_config

config = BridgeConfig(
    server_config=MCPServerConfig(
        command="uv",
        args=["run", "fastmcp", "run", "server/browser_navigator_server.py:app", "--transport", "stdio"],
    ),
    llm_config=get_default_llm_config(),
    system_prompt="You are a helpful assistant.",
)

async def main():
  async with BridgeManager(config) as bridge:
    response = await bridge.process_message("Navigate to https://example.com")
    print(response)


if __name__ == "__main__":
  asyncio.run(main())

from dotenv import load_dotenv

from client_bridge.llm_config import get_openai_llm_config

load_dotenv()
llm_config = get_openai_llm_config()
# Set these explicitly to values supported by the chosen model.
llm_config.token_limit_parameter = "max_completion_tokens"
llm_config.temperature = None

config = BridgeConfig(
  server_config=MCPServerConfig(
    command="uv",
    args=["run", "fastmcp", "run", "server/browser_navigator_server.py:app", "--transport", "stdio"],
  ),
  llm_config=llm_config,
)

ツールを直接実行する

設定済みの config を使う非同期関数内で、ブリッジは独自の LLM ループを管理するクライアント向けに、ツールのメタデータと直接実行機能を提供します。

async with BridgeManager(config) as bridge:
    tools = bridge.get_tools()  # OpenAI function calling format
    result = await bridge.execute_tool("playwright_navigate", {"url": "https://example.com"})

2. MCP v1 および v2 のサンプル

上記の元のアプリケーションとは独立した、入門用のサンプルです。各フォルダーには個別の依存関係があります。ルート環境をアップグレードするのではなく、リポジトリのルートから各 README に記載されたディレクトリスコープのコマンドを使用してください。これらのサンプルに LLM API キーは必要ありません。

仕様への参照

フォルダー名の v1 と v2 は、ここで比較する2つのプロトコル改訂版を示すリポジトリ内の略称であり、MCP の公式なメジャーバージョン名ではありません。Python SDK のバージョンとプロトコルの日付は別のものです。

• Core MCP 2025-11-25 は、初期化とバージョンネゴシエーションを含むクライアント／サーバー間の通信を定義します。ブラウザーのサンプルでは、プロトコルの日付を固定せず、initialize() を呼び出します。v1 ブラウザーサンプルの固定された mcp==1.27.0 環境では、サポートされる最新バージョンは 2025-11-25 であり、このバージョンへのネゴシエーションが実行時に確認されています。
• Core MCP 2026-07-28 は、新しいブラウザーサンプルと OAuth サンプルが対象とするコア仕様です。これらのクライアントは、以前の initialize() API を呼び出すのではなく、mode="2026-07-28" を明示的に設定します。これはコードで意図されているプロトコルの経路であり、検証済みの統合結果ではありません。

3. MCP Apps のサンプル

MCP Apps は、コア MCP を基盤として、インタラクティブな UI リソースとホストを介したインタラクションを追加します。これは任意の拡張機能であり、SDK v2 専用の機能ではありません。これらの独立したサンプルに LLM API キーは不要です。各ガイドのセットアップコマンドに従ってください。

仕様とホストの要件

公式の Apps の概要から、2026-01-26 Apps 仕様にリンクされています。これらの例では、FastMCP 3.2.0、Prefab 0.20.2、MCP SDK 1.27.0 を使用しています。

公式のクライアントサポートマトリックスでは、ホストのサポート状況を確認できます。Apps の概要には、サポート対象クライアントとして Claude Desktop と VS Code GitHub Copilot が記載されていますが、これはこれらの Prefab サンプルがいずれかのホストで検証済みであることを示すものではありません。元の Tkinter GUI は MCP Apps ホストではありません。

サンプルのスクリーンショット

MCP チャットホストでのキャプチャではなく、単独の Prefab プレビューです。ブラウザーの結果は、実際のローカル Playwright 呼び出しによって生成され、別途レンダリングされました。

リアクティブな MCP App のプレビュー	ローカル Playwright の結果プレビュー

全画像とプレビューの制限については、Apps のサンプルガイドを参照してください。未検証の SDK v2 統合の証拠として提示しているスクリーンショットはありません。

プロトコルとツールに関する注意事項

stdio と JSON-RPC

stdio はローカルプロセスのトランスポートであり、JSON-RPC 2.0 はメッセージ形式を定義します。MCP は、stdio や Streamable HTTP などのトランスポートを介して JSON-RPC メッセージをやり取りします。stdio サーバーでは、標準出力にはプロトコルメッセージのみを出力し、診断情報は標準エラー出力に出力する必要があります。Python の辞書を標準出力に出力しても、MCP 通知にはなりません。

ツールの説明

FastMCP は、Python の docstring からツールの説明を、関数シグネチャから入力スキーマを生成します。元のサーバーでは、playwright_navigate の docstring に "Navigate to a URL." と記載されています。ブリッジはこのメタデータを OpenAI の関数ツール定義に変換します。実際のスキーマは tools/list で確認してください。型注釈のないパラメーターに数値型が推論されると想定しないでください。

参考資料

Model Context Protocol（MCP）

Model Context Protocol（MCP） は、AI アプリケーションをツール、リソース、プロンプトに接続するオープンプロトコルです。認証、同意、アクセス制御は、引き続きアプリケーションとホスト側で実装する必要があります。

公式ドキュメントとリポジトリ

• MCP Python SDK
• MCP サーバーを構築する：現在のガイドです。以前の create-python-server スキャフォルダーはアーカイブされています。
• MCP リファレンスサーバー：リファレンス実装であり、本番環境への対応を保証するものではありません。

関連プロジェクト

• FastMCP：スタンドアロンの Python MCP フレームワークです。以前は jlowin のもとでホストされていました。
• Chat MCP：MCP クライアント
• MCP-LLM Bridge：このリポジトリのローカルブリッジ実装で参照されている、アーカイブ済みの上流プロジェクトです。インストール済みの依存関係ではありません。

MCP Playwright

• Microsoft Playwright MCP：Microsoft が提供する別個の Playwright MCP サーバーです。このリポジトリにある Python サーバーではありません。
• ExecuteAutomation Playwright MCP：コミュニティによる実装です。
• Microsoft Playwright for Python

コミュニティリソース

• Awesome MCP Servers
• Reddit の MCP

開発のヒント

uv コマンド

• 機能

uv run: Run a command or script in the project environment.
uv venv: Create a new virtual environment. By default, '.venv'.
uv add: Add a project dependency; use --script for inline script metadata.
uv remove: Remove a project dependency; use --script for inline script metadata.
uv sync: Synchronize the project environment with the lockfile (updating it if needed).

プロセスのクリーンアップとデバッグ

• GUI は通常の手順で閉じるか、ターミナルから起動したプロセスは Ctrl+C で停止するか、クライアントが管理するサーバーはそのクライアントの MCP コントロールから停止してください。プロセスが応答しなくなった場合は、その PID のみを特定して終了してください。すべての Python プロセスを強制終了しないでください。
• Visual Studio Code では、プロジェクト環境を選択し、GUI 用の起動構成を使って Python Debugger 拡張機能を使用してください。Python デバッグガイドを参照してください。