# ChatGPT Web MCP

### Codex 额度不够用了？通过 ChatGPT 网页版 + MCP 继续部分开发工作

**当 Codex 额度暂时用尽，你仍然可以在 ChatGPT 网页版里完成一部分常见开发操作。**

如果你平时使用 Codex 查看项目、修改代码、运行命令、执行测试或管理远程服务器，可以尝试用 **ChatGPT 网页版 + MCP** 完成其中的一部分：

- **查看与修改代码**：读取文件、理解项目、调整实现
- **运行命令与测试**：执行脚本、排查问题、检查测试结果
- **管理开发任务**：查看日志与进程、检查 Git 状态、追踪实验
- **操作授权服务器**：直接在聊天中执行常见远程操作

ChatGPT 负责理解需求与调用工具，MCP 负责将工具能力接入对话。本项目当前通过 **SSH / SFTP** 连接已授权的 Linux 主机；这些是底层实现，不需要用户在 ChatGPT 对话中手动输入 SSH 命令。

**这是 Codex 之外的一种工作方式，不会增加或恢复 Codex 额度，也无法完整替代 Codex 的全部能力。** 可用功能受当前 ChatGPT 工具权限、使用限制以及服务器配置影响。

### Codex usage exhausted? Continue selected development tasks with ChatGPT Web + MCP

**If you've hit your Codex usage limit, you can still handle some common development workflows in ChatGPT on the web.**

Use **ChatGPT Web + MCP** to inspect and edit project files, run commands and tests, check logs, manage Git repositories, and operate authorized remote servers—all through chat. ChatGPT handles the conversation and tool calls; the MCP service supplies remote tools. Under the hood, this implementation uses SSH/SFTP to access Linux hosts.

**This is an alternative workflow, not extra Codex quota or a full replacement for Codex.** Availability depends on your ChatGPT tool access, usage limits, and server configuration.

---

这是一个面向 ChatGPT 网页版的 **远程开发 MCP 接入项目**：包含 MCP 远程工具、GitHub OAuth 网关、Cloudflare HTTPS Tunnel、插件配置及必要测试。SSH / SFTP 仅用于底层远程执行与文件传输。核心实现基于 [blackaxgit/ssh-mcp](https://github.com/blackaxgit/ssh-mcp)，许可证见 [LICENSE](LICENSE)。GitHub 更新不会自动部署到正在运行的服务器。

## 在 ChatGPT 中使用

1. 在 ChatGPT 的 **设置 → Plugins** 中连接或启用本项目的 MCP 连接器（现有连接器显示名为 **Remote SSH**）。
2. 如需重新建立自定义 MCP 连接，地址为 `https://<你的 HTTPS 公网域名>/mcp`，选择 OAuth 并通过 GitHub 登录。
3. 在会话中选择现有连接器 **@Remote SSH**，直接提出请求，例如：
   - “列出可用 SSH 服务器。”
   - “在 `gpu-local` 执行 `hostname`、`whoami` 和 `uptime`。”
   - “只读检查 `/home/test/Double` 下项目的 Git 状态和运行进程。”
   - “修改指定文件，运行测试通过后再提交。”

已接入的工具：`list_servers`、`list_groups`、`execute`、`execute_on_group`、`upload_file`、`download_file`。请只连接有权管理的服务器，避免在未经确认的情况下执行有破坏性的操作。

## 运行架构

ChatGPT 网页版通过 HTTPS MCP 调用远程工具。**实线表示工具请求，虚线表示 GitHub OAuth 登录授权**；SSH / SFTP 是服务器侧的底层执行方式。

```mermaid
flowchart TB
    subgraph EXTERNAL["用户与身份验证"]
        direction LR
        CHAT["ChatGPT 网页版<br/>MCP 工具调用"]
        GH["GitHub OAuth<br/>身份验证"]
    end

    CF["Cloudflare Tunnel<br/>公网 HTTPS 入口"]

    subgraph SERVER["Linux / GPU 服务器"]
        direction TB
        GW["8200 · OAuth 网关<br/>授权与请求转发"]
        MCP["8000 · MCP 服务<br/>6 个远程工具"]
        SSH["gpu-local · 目标主机<br/>命令执行与文件传输"]
        GW -->|"Bearer 认证"| MCP
        MCP -->|"SSH / SFTP"| SSH
    end

    CHAT -->|"HTTPS / MCP"| CF
    CF --> GW
    GW -. "GitHub 登录" .-> GH
    GH -. "授权回调" .-> GW

    classDef main fill:#EAF4FD,stroke:#A6CEE3,color:#164D72,stroke-width:1px;
    classDef oauth fill:#F0F5FA,stroke:#A6BCCD,color:#274A63,stroke-width:1px;
    class CHAT,CF,GW,MCP,SSH main;
    class GH oauth;
    style SERVER fill:#F8FAFC,stroke:#CDD7E1,stroke-width:1px
    style EXTERNAL fill:transparent,stroke:transparent
```

**各组件负责什么？**

| 组件 | 主要职责 |
| --- | --- |
| **ChatGPT 网页版 + MCP** | 理解指令、发起 MCP 工具调用、展示结果 |
| **Cloudflare Tunnel** | 提供公网 HTTPS 通道，将请求安全转发到本地 8200 端口 |
| **GitHub OAuth** | 确认允许登录的 GitHub 用户身份；不负责运行 SSH 命令 |
| **8200 OAuth 网关** | 处理授权码与 Token、校验访问权限，把 MCP 请求转给内部服务 |
| **8000 SSH MCP** | 提供 `execute`、文件传输、服务器列表等 6 个工具 |
| **gpu-local** | 通过 SSH 执行命令或使用 SFTP 传输文件的目标主机 |

调用顺序可以记作：**ChatGPT → Cloudflare → 8200 网关 → 8000 MCP → SSH 主机**。首次连接或令牌失效时，才需要额外进行 GitHub OAuth 授权。

仓库主要内容：

- `src/ssh_mcp/`：SSH / SFTP / MCP 核心源码
- `gateway/app.py`：GitHub OAuth、ChatGPT 授权及 MCP 代理
- `cloudflared/cloudflared`：Cloudflared Linux x86_64 v2026.10.1 二进制
- `cloudflared/run-oauth-tunnel.sh`：把 HTTPS Tunnel 指向 8200 网关
- `deploy/`：启动、安装和诊断脚本；`config/`：服务器清单示例
- `plugin/`：插件清单、MCP 配置和 `skills/remote-ssh/SKILL.md`
- `scripts/build_plugin.py`：生成插件 ZIP
- `tests/`、`integration/tests/`：功能与打包回归测试
- `pyproject.toml`、`uv.lock`、`LICENSE`：构建与许可

实际配置和密钥**不提交 Git**：`~/.config/ssh-mcp/servers.toml`、SSH 私钥、Bearer Token、GitHub OAuth Secret、网关运行日志均位于私有运行环境。

## 首次部署到 Linux（Conda）

需要已安装并初始化的 **Conda**、SSH 可用、GitHub OAuth App 以及公网 HTTPS 通道。本项目正式部署使用 **`chatgpt-ssh-mcp` Conda 环境**，不需要创建 Python venv。请在目标 Linux 主机上运行。**仓库目录名与现有 Conda 环境名相互独立**；旧环境 `chatgpt-ssh-mcp` 保持不变：

```bash
git clone https://github.com/Double-wk/chatgpt-web-mcp.git
cd chatgpt-web-mcp

# 默认创建/复用名为 chatgpt-ssh-mcp 的 Conda 环境；
# 自动安装项目、生成缺失的内部 Token，已有 Token 不会被覆盖。
export SSH_MCP_PROJECT_DIR="$PWD"
bash deploy/setup-conda.sh

# 获取环境的实际路径，覆盖启动脚本预置的原服务器绝对路径。
export SSH_MCP_CONDA_PREFIX="$(conda run -n chatgpt-ssh-mcp python -c 'import sys; print(sys.prefix)' | tail -n 1)"

# Gateway 使用同一个 Conda 环境（不安装到系统 Python）。
"$SSH_MCP_CONDA_PREFIX/bin/python" -m pip install uvicorn httpx starlette python-multipart
```

`deploy/setup-conda.sh` 在私有目录 `~/.config/ssh-mcp/` 创建或保留 `servers.toml` 和 `http-token`。修改 `servers.toml`，并在 `~/.ssh/config` 配置可访问的 SSH 主机，先验证 SSH 连通。`gateway-token` 也是必需的私有文件，仅在不存在时创建：

```bash
install -d -m 700 "$HOME/.config/ssh-mcp"
if [ ! -f "$HOME/.config/ssh-mcp/gateway-token" ]; then
  umask 077
  "$SSH_MCP_CONDA_PREFIX/bin/python" -c 'import secrets; print(secrets.token_urlsafe(48))' > "$HOME/.config/ssh-mcp/gateway-token"
fi
chmod 600 "$HOME/.config/ssh-mcp/http-token" "$HOME/.config/ssh-mcp/gateway-token"

# 启动内部 MCP（127.0.0.1:8000）
bash deploy/run-http.sh
```

已有部署的服务器请**保留原有 Token 和配置**，不要重新生成或覆盖。现有实例的 Conda 环境路径为 `/mnt/tcm_agent_data/Double/envs/chatgpt-ssh-mcp`，仓库目录为 `/home/test/Double/chatgpt-web-mcp`；`deploy/run-http.sh` 与 `deploy/chatgpt-ssh-mcp.service` 使用该运行环境。迁移到新机器时请设置 `SSH_MCP_PROJECT_DIR` 和 `SSH_MCP_CONDA_PREFIX`。

## OAuth 和 HTTPS 网关

在 GitHub Developer Settings 创建 OAuth App，授权回调 URI 为 `https://<公网域名>/oauth/github/callback`。在服务器**私有环境**中设置 `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`、`GITHUB_ALLOWED_IDS`（允许登录的 GitHub 数字用户 ID，逗号分隔）和 `GATEWAY_PUBLIC_BASE`（公网 HTTPS 根地址，不含 `/mcp`）。**GITHUB_ALLOWED_IDS 必须非空**：精简版网关在白名单缺失时会拒绝授权，不会放行所有 GitHub 用户。

通过环境变量 `CHATGPT_OAUTH_CLIENT_ID` 和 `CHATGPT_OAUTH_REDIRECT_URI` 设置 ChatGPT 连接器的客户端 ID 与**完整回调 URI**。默认客户端 ID 是 `chatgpt-remote-ssh`，默认回调 URI 仅对应先前创建的连接器；创建新连接后必须使用页面显示的实际值，不应复制旧值。内部 MCP 应已在 8000 运行，然后在另一个终端启动：

```bash
PYTHONPATH="$PWD" "$SSH_MCP_CONDA_PREFIX/bin/python" -m uvicorn gateway.app:app --host 127.0.0.1 --port 8200
```

再开启 Cloudflare Tunnel：

```bash
./cloudflared/run-oauth-tunnel.sh
```

仓库保留 Linux x86_64 的 `cloudflared` v2026.10.1（约 39 MB），这是实际部署依赖。其他系统或架构使用相应官方版本并设置 `CLOUDFLARED_BIN`。Quick Tunnel 域名可能变化，届时须同步更新网关公开基地址、GitHub OAuth 回调 URI、ChatGPT MCP URL。长期部署建议固定 HTTPS 域名。

## Gateway 连接堆积修复与安全升级

**故障特征**：8000 端口接近 256 条已建立连接、出现 `Exceeded concurrency limit`、初始化和工具请求返回 HTTP 503。原 Gateway 的 `httpx.AsyncClient(timeout=None).request()` 会等待整个 SSE 响应结束；新的代理使用 `send(..., stream=True)` + `StreamingResponse` 实时转发，并在正常结束、下游断开或任务取消时关闭上游响应和 HTTP 客户端。保留 OAuth、MCP Session ID、原有 6 个工具。新的实现降低了连接堆积风险，但不等于已证明所有生产网络故障都能自动恢复。

**不要直接在运行目录 `git pull`**：本仓库曾重写为单个根提交，旧目录与 GitHub `main` 的历史可能不兼容。请在新目录检出并测试，旧的 MCP 8000、Gateway 8200、私有 Token、Conda 环境和正在运行的实验保持不变。

```bash
cd /home/test/Double
git clone https://github.com/Double-wk/chatgpt-web-mcp.git chatgpt-web-mcp
cd chatgpt-web-mcp

PY=/mnt/tcm_agent_data/Double/envs/chatgpt-ssh-mcp/bin/python
"$PY" -m unittest discover -s integration/tests -p 'test*.py' -v

# 仅在确认 8202 未被使用后，在单独终端启动测试网关：
ss -ltnp | grep ':8202' || true
PYTHONPATH="$PWD" "$PY" -m uvicorn gateway.app:app --host 127.0.0.1 --port 8202
```

从另一个终端测试独立网关的真实 MCP 初始化和只读工具调用（**不打印 Token**）：

```bash
cd /home/test/Double/chatgpt-web-mcp
PY=/mnt/tcm_agent_data/Double/envs/chatgpt-ssh-mcp/bin/python
SSH_MCP_HTTP_PORT=8202 \
SSH_MCP_HTTP_TOKEN_FILE="$HOME/.config/ssh-mcp/gateway-token" \
"$PY" deploy/doctor-mcp.py --probe-execute

# 多次测试后核对连接是否回落，不应持续攀升至 256：
ss -Htn state established '( sport = :8000 )' | wc -l
```

此诊断探针只会执行固定的 `hostname` 命令，且当前版本仅检查本机配置的 `gpu-local`。还应在测试环境验证 SSE 被客户端取消、异常退出时连接被释放；CI 回归测试覆盖这些模拟场景。

**切换生产 8200 之前**：确认现有 Gateway 是如何注入 `GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`、`GITHUB_ALLOWED_IDS`、`GATEWAY_PUBLIC_BASE` 及 ChatGPT OAuth 回调配置；在新服务中保留完全相同的私有设置。先确认 8202 探针通过，再在维护窗口仅替换 8200 Gateway 进程，切勿重启 8000 MCP 或修改训练数据。切换后重跑探针、检查公网 OAuth，并持续观察连接数与 503；发生异常则回滚到原目录启动的 Gateway。切勿把密钥内容、实际 OAuth 回调 code/state 粘贴到聊天或 Git。

## 自检和插件打包

```bash
# 先检查本机端口与网关
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8200/healthz
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8200/.well-known/oauth-authorization-server
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8200/mcp

# 检查工具发现及只读远程 hostname（默认 gpu-local）
"$SSH_MCP_CONDA_PREFIX/bin/python" deploy/doctor-mcp.py --probe-execute

# 测试插件打包，并为已部署的 HTTPS MCP 生成 ZIP
"$SSH_MCP_CONDA_PREFIX/bin/python" -m unittest discover -s integration/tests -p 'test*.py' -v
"$SSH_MCP_CONDA_PREFIX/bin/python" scripts/build_plugin.py --web-url "https://<你的域名>/mcp" --output /tmp/remote-ssh.zip
```

正常结果：前两个接口返回 `200`；未认证的 `/mcp` 返回 `401`；doctor 显示 `MCP initialize OK`、6 个工具和 `MCP execute OK`。该诊断脚本会检查当前示例的 `gpu-local` 别名和固定主机名；迁移到别的服务器后，要相应更新诊断目标。

OAuth 正常链路为 `/oauth/authorize`（302）→ `/oauth/github/callback`（302）→ `POST /oauth/token`（200）→ `POST /mcp`（200/202）。如果出现“缺少回调数据”，分别检查 GitHub 和 ChatGPT 回调是否携带 `code/state`，不要将这些实际参数打印到公开日志。

## 开源致谢与许可证

本仓库并非从零实现所有组件。项目在开源软件基础上做了 **ChatGPT 接入、GitHub OAuth 网关与部署集成**，应保留原作者署名并明确修改范围：

- **[blackaxgit/ssh-mcp](https://github.com/blackaxgit/ssh-mcp)**：SSH MCP 核心实现、SSH/SFTP 工具、配置及相关测试的重要上游来源。感谢原项目贡献者。本仓库保留其源码，遵循 **Mozilla Public License 2.0（MPL-2.0）**，见根目录 [LICENSE](LICENSE)。本项目的 OAuth 网关、ChatGPT 插件配置与部署集成为额外工作，不代表原作者为这些修改背书。
- **[Cloudflare/cloudflared](https://github.com/cloudflare/cloudflared)**：提供 Cloudflare Tunnel 可执行程序，负责 HTTPS 访问通道。感谢 Cloudflare 维护开源项目。其开源许可证为 **Apache License 2.0**，参见 [Cloudflare 项目的许可证](https://github.com/cloudflare/cloudflared/blob/master/LICENSE) 和仓库随附的 `cloudflared/LICENSE`。仓库保留 Linux x86_64 版本的二进制文件，方便恢复部署。
- **[Model Context Protocol](https://modelcontextprotocol.io/)**：本项目遵循 MCP 协议与工具交互规范。

开源代码的许可证与本项目自定义部署配置不是同一回事：服务器私钥、GitHub OAuth Secret、Bearer Token 和访问日志不属于公开仓库内容，也不应提交到 Git。

## Git 管理与安全

仓库目标是保留**最小可部署的完整项目**，旧的 Docker/Compose 模板、无认证测试通道、冗余文档已剔除，核心源码与 cloudflared 仍保留。OAuth 临时状态和令牌目前保存在网关进程内存中，因此重启可能需要重新授权。不要把私钥、Token、GitHub Secret 或日志提交 Git，也不要对在线部署目录进行未经验证的文件覆盖。

Git `main` 已整理为**一个根提交**；旧提交在其他克隆或缓存中可能仍然存在。**特别注意**：本机已将工作目录迁移为 `/home/test/Double/chatgpt-web-mcp`；Conda 环境仍使用 `chatgpt-ssh-mcp`。既有 systemd 服务文件已同步到新工作目录，迁移部署时请按目标机器设置对应路径，避免直接覆盖运行中的工作树。