Metadata-Version: 2.4
Name: web-access-mcp
Version: 0.2.0
Summary: MCP server for browser automation over Chrome CDP
Author: renqingfei
License-Expression: MIT
Project-URL: Homepage, https://github.com/renqingfei/web-access-mcp
Project-URL: Repository, https://github.com/renqingfei/web-access-mcp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# web-access-mcp

把 [`eze-is/web-access`](https://github.com/eze-is/web-access) 里真正“可执行”的浏览器能力下沉成一个显式 MCP server，避免依赖 skill 自动激活。

当前版本已完全切到 Python 实现，安装、运行、发布都走 PyPI。

## 安装

推荐：

```bash
pipx install web-access-mcp
```

或：

```bash
pip install web-access-mcp
```

升级到最新版本：

```bash
pipx upgrade web-access-mcp
```

## 资源限制

- MCP 自己创建的受管 tab 最多 10 个
- 超过 10 个后，`new_tab` 会直接报错，防止 Chrome target 过多导致卡顿或内存爆掉
- `adopt_tab` 接管你原本已打开的 tab 后，不计入这 10 个配额
- `close_tab` 会释放配额
- 默认情况下，用户本来就打开的 Chrome tab 不计入这 10 个配额，除非你显式执行 `adopt_tab`

## 已实现能力

- `browser_health`: 只验证 MCP server 正常响应，不要求浏览器授权
- `browser_connect`: 在浏览器侧授权后，显式完成一次 Chrome CDP 连接验证
- `list_tabs`: 列出当前页面 tab，并标记 `isManaged` 与 `managedSource`
- `new_tab`: 新建后台 tab
- `close_tab`: 关闭 tab
- `close_all_managed_tabs`: 一键关闭全部受管 tab
- `close_created_tabs`: 只关闭 MCP 新开的 `created` tab，保留接管的 `adopted` tab
- `adopt_tab`: 接管一个用户已打开的 tab
- `navigate`: 页面跳转并等待加载
- `go_back`: 后退
- `page_info`: 读取标题、URL、readyState
- `eval`: 在页面内执行 JavaScript
- `click`: `element.click()`
- `click_at`: 真实鼠标点击
- `set_files`: 给 file input 注入本地文件
- `scroll`: 页面滚动
- `screenshot`: 截图，支持返回 base64 或落盘

## 前置条件

1. Python 3.10+
2. Chrome 已打开
3. 在 Chrome 打开 `chrome://inspect/#remote-debugging`
4. 勾选 `Allow remote debugging for this browser instance`

首次验证建议拆成两步：

1. 调 `browser_health`，只验证 MCP server 正常响应；这一步不要求浏览器授权
2. 若浏览器侧弹出授权或尚未勾选 remote debugging，先完成授权，再调 `browser_connect`

## 本地开发

开发安装：

```bash
pip install -e .
```

语法检查：

```bash
python -m compileall src
```

直接启动：

```bash
python -m web_access_mcp
```

## Codex MCP 配置

推荐直接用 Python module，避免依赖 Windows shell shim：

```toml
[mcp_servers.web-access]
command = "C:\\Users\\Admin\\AppData\\Local\\Programs\\Python\\Python313\\python.exe"
args = ["-m", "web_access_mcp"]
startup_timeout_sec = 60.0
```

如果机器里不存在旧的 npm 全局同名 shim，且 `web-access-mcp` 已通过 `pipx` 或 `pip` 安装进 PATH，也可以直接写：

```toml
[mcp_servers.web-access]
command = "web-access-mcp"
startup_timeout_sec = 60.0
```

## MCP 接入示例

其他支持 stdio 的 MCP 客户端也可直接这样配置：

```json
{
  "mcpServers": {
    "web-access": {
      "command": "web-access-mcp"
    }
  }
}
```

## 发布到 PyPI

构建：

```bash
python -m build
```

发布：

```bash
python -m twine upload dist/*
```

## 与原 skill 的差异

- 原 skill 的“自动选择 WebSearch / WebFetch / Jina / CDP”是提示词层能力，不是脚本层能力
- 本仓库把稳定、确定、可调用的部分下沉成 MCP tools
- 如果后续需要，可继续补 `fetch_url`、`fetch_html`、`site_pattern_lookup` 等工具

## 设计取舍

- 运行时无第三方依赖，WebSocket 与 MCP stdio 都用 Python standard library 自行实现
- 采用 stdio + JSON-RPC 实现最小 MCP server
- 保留原仓库的核心思路：复用用户自己的 Chrome 登录态，而不是启动独立浏览器
