Mcp Aoai Web Browsing

MCP 实践：Web 浏览、协议与应用

一个 Playwright 浏览应用，支持 Azure OpenAI/OpenAI，另附 MCP v1/v2、OAuth 和交互式 MCP Apps 的专项示例。

1. 原始浏览应用 — Azure OpenAI/OpenAI 集成、设置和客户端连接。
2. MCP v1 和 v2 示例 — 浏览器工具和本地 OAuth 流程。
3. MCP Apps 示例 — 使用 Prefab 构建的交互式工具响应界面。

1. Web 浏览 MCP 应用

一个本地浏览应用，带有 Tkinter 聊天界面和 MCP 到大模型的桥接。

• 原始服务使用独立的 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 版本是旧版 Azure 端点所需的，下面介绍的 /openai/v1 路径则不需要。请勿将 .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"
    }
  }
}

以编程方式使用 Bridge

通过 stdio 连接

在仓库根目录运行此示例。Bridge 负责处理模型循环；子服务会从本地 .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 的异步函数中，Bridge 会向自行管理 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 是仓库中用于指代这里对比的两个协议修订版的简称，并非 MCP 官方主版本名称。Python SDK 版本和协议日期彼此独立：

• Core MCP 2025-11-25 定义客户端与服务端之间的通信，包括 初始化和版本协商。 浏览器示例调用 initialize()，而不是硬编码协议日期。在 v1 浏览器示例固定使用的 mcp==1.27.0 环境中，最新支持版本为 2025-11-25，并已在运行时确认协商到该版本。
• Core MCP 2026-07-28 是较新的浏览器和 OAuth 示例所针对的 核心规范。 这些示例中的客户端会显式设置 mode="2026-07-28"，而不是调用较早的 initialize() API。这是代码预期采用的协议路径，并非已验证的集成结果。

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 宿主。

示例屏幕截图

这是独立的 Prefab 预览，而非 MCP 聊天宿主的截图。浏览器结果由真实的本地 Playwright 调用生成，并单独渲染。

响应式 MCP App 预览	本地 Playwright 结果预览

完整图片和预览限制请参阅 Apps 示例指南。本文未将任何屏幕截图作为未经验证的 SDK v2 集成的证据。

协议和工具说明

stdio 和 JSON-RPC

stdio 是本地进程传输方式；JSON-RPC 2.0 定义了消息格式。MCP 通过 stdio 或 Streamable HTTP 等传输方式传递 JSON-RPC 消息。对于 stdio 服务，stdout 只能包含协议消息；诊断信息应写入 stderr。打印到 stdout 的 Python 字典不是 MCP 通知。

工具描述

FastMCP 会根据 Python 文档字符串生成工具描述，并根据函数签名生成输入架构。在原始服务端中，playwright_navigate 使用的文档字符串是 "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 中，选择项目环境，并使用 Python Debugger 扩展及 GUI 的启动配置。请参阅 Python 调试指南。