@wuxinhuahua/webgpt

v0.1.2

Published

25 days ago

MCP stdio proxy client for WebGPT Bridge.

0High
0Medium
0Low

wuxinhuahua

WebGPT Bridge

WebGPT Bridge 用来把本地 AI 编程工具连接到 ChatGPT 网页版：本地 AI 发起任务，浏览器插件把内容发送到网页，网页返回的结果会保存回本地。

单纯的npm MCP 客户端,服务端和浏览器插件,chatgpt账号他人提供.

如果你只是要在 Codex 中连接一个已经部署好的 WebGPT Bridge，不需要 clone 本仓库，也不需要本机绝对路径。直接用 npm 包启动 MCP stdio proxy：

[mcp_servers.webgpt]
command = "npx"
args = ["-y", "@wuxinhuahua/webgpt"]
env = {
  WEBGPT_BRIDGE_URL = "https://your-bridge.example.com",
  WEBGPT_BRIDGE_TOKEN = "YOUR_WEBGPT_MCP_TOKEN"
}
startup_timeout_sec = 60
tool_timeout_sec = 7200

WEBGPT_BRIDGE_URL 必须是用户自己,或者他人的 bridge 地址；WEBGPT_BRIDGE_TOKEN 必须是该 bridge 后台生成的用户 MCP Token。Codex 建议把 tool_timeout_sec 配置为 7200，这样 wait_webgpt_target_job 等长耗时网页任务时不会被 MCP 客户端过早中断。

这个 npm 包只包含 MCP stdio proxy 客户端，不包含 bridge 后台服务、admin-ui 或浏览器扩展。后台和浏览器扩展需要由服务提供方另行部署和配置。

自己全量部署,使用自己的chatgpt账号

需要：

Node.js 20+
npm
Chrome / Chromium

安装依赖并构建：

npm install
npm run build

启动后台

前台启动：

npm start

后台启动 / 重启：

npm run gptweb-bridge:restart

后台脚本默认监听 0.0.0.0:18473，健康检查默认访问 http://127.0.0.1:18473/health。如需限制为本机访问，可以设置 WEBGPT_BRIDGE_HOST=127.0.0.1；如需换端口，可以设置 WEBGPT_BRIDGE_PORT；如需完整覆盖健康检查地址，可以设置 WEBGPT_BRIDGE_URL。gptweb-bridge:start 会等 /health 真正可访问后才返回成功，避免进程已启动但端口还没绑定时误判可用。Linux/macOS 下可用 WEBGPT_BRIDGE_START_WAIT_ATTEMPTS 和 WEBGPT_BRIDGE_START_WAIT_SLEEP_SECONDS 调整等待；PowerShell 下等待间隔使用 WEBGPT_BRIDGE_START_WAIT_SLEEP_MS。

查看状态：

npm run gptweb-bridge:status

打开后台：

http://127.0.0.1:18473/

首次启动会生成本机 bootstrap 凭据：

.webgpt/bootstrap-admin.txt

文件中包含初始 admin 登录密码、管理员 MCP Token 和管理员插件 Token。也可以在首次启动前用 WEBGPT_ADMIN_PASSWORD、WEBGPT_ADMIN_MCP_TOKEN、WEBGPT_EXTENSION_TOKEN 显式指定初始值。第一次登录后建议先修改管理员密码，并重新生成需要使用的 Token。

后台要做的事

登录后台后：

在“设置”里生成并复制当前用户自己的“插件 Token”。
在“后台管理”里创建用户，设置截止日期和可用次数。
给需要使用 MCP 的用户生成 MCP Token；新建用户也会得到自己的插件 Token。
在“项目与会话”里查看或删除项目、会话记录。
在“绑定会话”里查看或解绑浏览器会话。

如果重新生成了 MCP Token，旧 MCP Token 会失效，需要同步更新 MCP 客户端配置。插件 Token 按用户隔离：浏览器扩展只能领取和提交该 Token 所属用户的任务、会话和下载产物，不要在多个用户之间共用同一个插件 Token。

安装浏览器插件

每次 npm run build 后，插件都会构建到 extension/dist/，但浏览器加载目录仍然是仓库里的 extension/。

Chrome / Chromium 操作：

打开 chrome://extensions/
开启“开发者模式”
点击“加载已解压的扩展程序”
选择本仓库的 extension/ 目录
打开插件弹窗
Bridge 地址填：

http://127.0.0.1:18473

粘贴后台“设置”里生成的当前用户插件 Token
点击“保存插件设置”

绑定 ChatGPT 页面：

打开 ChatGPT 的项目页或对话页
点击浏览器插件图标
点击“绑定当前对话”
后台“绑定会话”里应该能看到对应 session

如果重新构建了插件：

在 chrome://extensions/ 里重新加载扩展
刷新 ChatGPT 页面
重新打开插件确认状态

配置 MCP

推荐使用已发布的 npm 包，不需要 clone 仓库：

[mcp_servers.webgpt]
command = "npx"
args = ["-y", "@wuxinhuahua/webgpt"]
env = {
  WEBGPT_BRIDGE_URL = "https://your-bridge.example.com",
  WEBGPT_BRIDGE_TOKEN = "YOUR_WEBGPT_MCP_TOKEN"
}
startup_timeout_sec = 60
tool_timeout_sec = 7200

源码开发调试时，也可以先 npm run build，再用 node dist/src/bin/webgpt-mcp.js 启动本仓库构建出的入口。

如果你在后台重新生成了用户 MCP Token，把 WEBGPT_BRIDGE_TOKEN 改成新的 Token。不要把真实 token 提交到仓库。

tool_timeout_sec = 7200 控制 Codex CLI 允许单次 MCP tool call 最长运行 2 小时；如果当前 MCP 宿主不支持这么长的 tools/call，就不要调大等待时间，改用一次短等待后手动回来取产物。startup_timeout_sec 只控制 MCP 进程启动等待时间。start_webgpt_target_job 默认只提交任务并快速返回 job id；只有显式设置 waitTimeoutMs、WEBGPT_MCP_DEFAULT_JOB_WAIT_TIMEOUT_MS 或 WEBGPT_MCP_PRO_JOB_WAIT_TIMEOUT_MS 时，启动调用才会等待。WEBGPT_MCP_WAIT_ONLY_TIMEOUT_MS、WEBGPT_MCP_PRO_WAIT_ONLY_TIMEOUT_MS、WEBGPT_MCP_WAIT_ONLY_MAX_TIMEOUT_MS 和 WEBGPT_MCP_MAX_TIMEOUT_MS 可用于覆盖 wait_webgpt_target_job 默认等待时长。wait_webgpt_target_job 遇到 awaiting-artifact 且助手已回复但没有捕获到匹配产物时，会在短 grace 窗口后返回 noArtifact: true；可用 WEBGPT_MCP_AWAITING_ARTIFACT_GRACE_TIMEOUT_MS 调整该窗口，默认 60 秒。

单项目使用时，也可以加：

WEBGPT_REPO_ROOT = "/absolute/path/to/your-project"

多项目共用同一个 MCP 配置时，不建议写死 WEBGPT_REPO_ROOT，让 AI 每次调用时传当前项目的 repoRoot。

Codex Skill（推荐）

如果让 Codex/AI 使用 WebGPT MCP，可把本仓库的 webgpt-workflow skill 安装到全局 Codex skills 目录，而不是只留在当前仓库 .codex/skills/ 下。该 skill 只应在用户明确点名完整技能名或明确要求使用本 skill 时启用，不应因为普通上下文、工具名、URL、会话 ID 或报错内容自动触发。

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R .codex/skills/webgpt-workflow "${CODEX_HOME:-$HOME/.codex}/skills/"

AI 帮用户配置时，可说明全局安装和项目内私有安装的差异；只有用户明确要求使用该 skill 时，才建议安装或启用。

使用方式

最常用流程：

启动 bridge 后台。
浏览器插件保存插件 Token。
在 ChatGPT 项目页或对话页绑定会话。
在本地 AI 里使用 WebGPT MCP。
AI 发任务给网页模型。
网页返回的 .gitdiff 或 .zip 会保存到当前项目的 .webgpt/inbox/。

如果 bridge 部署在远端，下载产物会先由 bridge 保留在 bridge 自己的 inbox；MCP 再通过 download_webgpt_file / download_webgpt_artifact 拉取文件内容并写入本地项目的 .webgpt/inbox/。这些下载工具里的 repoRoot 表示本地落盘目录，不要求远端 bridge 能访问本机路径。

常用选择：

模型：thinking 或 pro
产物：gitdiff 或 zip-output
新对话：使用项目页发送，发送后会自动记录新的会话 URL
复用对话：使用已有 conversation URL、conversationName、targetId 或 sessionId
每轮都会上传当前仓库快照 zip；复用对话只复用网页上下文，不复用网页沙盒里的旧工作目录
仓库可以保存 .webgpt/pack-constraint.json 作为稳定打包约束；默认只打包代码、文档、配置，并排除依赖、构建产物、运行数据、截图、压缩包和大体积文件

如果用户说“使用网页 pro 模型”，MCP 应传 modelMode: "pro"；如果网页找不到 Pro 或 Pro 处于禁用状态，不要自动退回 Thinking，应把模型不可用作为失败状态暴露出来。

给 AI 代安装的最小流程

如果你是 AI，帮用户安装时按这个顺序做：

确认用户使用哪个 MCP 客户端，比如 Codex CLI、Claude Code、Cursor 或 VS Code。
确认 MCP 配置写到全局还是当前项目。
在本仓库执行：

npm install
npm run build
npm run gptweb-bridge:restart

读取 .webgpt/bootstrap-admin.txt，打开 http://127.0.0.1:18473/，确认后台可登录。
使用后台里的当前用户 MCP Token 写入 MCP 配置。
让用户加载 extension/ 浏览器插件。
让用户在后台生成当前用户插件 Token，并粘贴到插件弹窗保存。
让用户打开 ChatGPT 页面并绑定会话。
如果用户明确要求使用 Codex skill，再建议把 .codex/skills/webgpt-workflow 复制到 ${CODEX_HOME:-$HOME/.codex}/skills/webgpt-workflow，作为全局 skill 使用。

AI 不要替用户猜 MCP 客户端和配置位置；不确定时先问。

更新后怎么做

代码更新或重新构建后：

npm run build
npm run gptweb-bridge:restart

然后在 chrome://extensions/ 里重新加载浏览器插件，并刷新 ChatGPT 页面。