🌉 Chat2Agent

An open-source bridge suite that gives the ChatGPT web app local workspace capabilities through the official MCP

💡 Core positioning The main goal of this project is to let the web-based ChatGPT (including both free and paid tiers) connect directly to your local workspace through OpenAI's official MCP (Model Context Protocol) developer connector, gaining code search, file modification, test execution, and review capabilities similar to Codex Agent.

For the complete design boundary, see 📑 ADR 0001: Web Agent Boundary and 🗺️ Product Roadmap.

🛡️ Zero Cost and Absolute Account Safety

1. 💰 100% Free — a Regular Free Account Is All You Need

• Works with the free ChatGPT tier: OpenAI has officially enabled Developer Mode / MCP Connector on the web app, so a regular free account can add a custom MCP connector directly — no Plus/Team/Pro subscription required!

• Free public tunnel: Whether you use the built-in ngrok free tier or the Pinggy free tunnel, you can establish stable communication between your local machine and the web app at zero cost.

2. 🔒 Official, Standards-Compliant Protocol — Absolutely Zero Ban Risk

• Official open standard: Built entirely on OpenAI's official Model Context Protocol (MCP) specification and the standard OAuth 2.0 flow.

• No reverse engineering or black-hat tactics: We never inject web cookies, never scrape non-public web APIs, never reverse-engineer tokens, and never use any unauthorized automation scripts. To OpenAI, this is simply a legitimate third-party standard connector that fully complies with the official Terms of Service (TOS) — guaranteeing zero ban risk at the technical level.

Related MCP server: codex-web-bridge

🚀 Why Choose Chat2Agent? (Major Upgrades Over the Original)

This project is a deep refactor and evolution of the excellent concept from Embracecactus/devspace-mcp-tunnel.

The original was a simple Linux Bash launcher demo (11 files total). Chat2Agent has grown to 66 files, added 6400+ lines of code, and includes 40 automated unit tests, achieving an industrial-grade transformation:

✨ Core Features & Hardcore Engineering

🏗️ How It Works

 ┌─────────────────┐       HTTPS / OAuth       ┌──────────────┐       loopback        ┌────────────────────────┐
 │  网页版 ChatGPT  │ ───────────────────────▶ │   公网隧道   │ ────────────────────▶ │  DevSpace (127.0.0.1)  │
 └─────────────────┘      (ngrok / Pinggy)     └──────────────┘     (Port: 7676)      └───────────┬────────────┘
                                                                                                  │
                                                                       ┌──────────────────────────┴───────────────┐
                                                                       ▼                                          ▼
                                                          ┌──────────────────────────┐               ┌──────────────────────────┐
                                                          │   允许的本地目录 / Shell   │               │  选定的 AGENTS.md / Skills│
                                                          └──────────────────────────┘               └──────────────────────────┘

• Isolated listening: DevSpace only listens on the local loopback address 127.0.0.1:7676, with strict authorization via OAuth (Owner password).

• Reverse proxy: The tunnel tool proxies public HTTPS traffic to the local port 7676.

• Endpoint rules: The MCP client connects to https://<tunnel-domain>/mcp, and the OAuth issuer comes from publicBaseUrl (i.e., the bare domain root, without /mcp).

• Zero global pollution:

  • Windows launcher: Only updates .mcp.json in the project directory, never modifies the machine's global Codex config.

  • Linux refresh script: Does not modify ~/.codex/config.toml by default; only syncs as a legacy compatibility step when explicitly invoked with --sync-codex.

🌐 Free ngrok Setup Guide (Step-by-Step, Zero Cost)

We recommend the free ngrok for stable public tunnel support (completely free):

1. Create an account: Visit ngrok's official site (ngrok.com) and register for free.

2. Get your Authtoken:

   • After logging in, go to ngrok Dashboard -> Your Authtoken.

   • Copy the generated token.

3. (Highly recommended) Claim 1 free static domain:

   • In the left menu, click Cloud Edge -> Domains.

   • Click Claim a domain to claim a free dedicated static domain (e.g., your-name.ngrok-free.app).

   • Benefit: With a fixed domain, you never need to update the URL in the ChatGPT web app after restarting the service!

4. Fill in the project config:

   • In the project root, copy the config file:

     Copy-Item .env.example .env.local

   • Edit .env.local and fill in the information:

     NGROK_AUTHTOKEN=你的ngrok_authtoken
     NGROK_DOMAIN=your-name.ngrok-free.app # 如果没有申请固定域名则留空

🚀 Windows Quick Start (Recommended)

1. Install Dependencies and Initialize DevSpace

Requirements: Node.js >=22.19 <27

# 1. 全局安装 DevSpace CLI 并安装项目依赖
npm install --global @waishnav/devspace
npm ci

# 2. 初始化 DevSpace 配置
devspace init

devspace init will guide you through entering the allowed directories, port (enter 7676), and public base URL (you can enter https://placeholder.invalid for now; the launcher will rewrite it automatically).

# 目录授权示例（按需开放）：
D:/AI/project-one,D:/AI/project-two

# 明确接受风险后，也可以全盘开放：
C:/,D:/

2. One-Click Start, Check Status, and Stop

# 运行启动前预检
npm run preflight

# 启动后台受管服务（通过 /healthz 门控后返回成功）
./start.bat

# 查看运行状态与诊断
npm run status

# 精准停止受管进程树
./stop.bat

🐧 Linux / WSL Quick Start

1. Install and Initialize

git clone https://github.com/xiaoxiao341/Chat2Agent.git
cd Chat2Agent
chmod +x setup.sh refresh-devspace-mcp.sh

# 国内网络建议追加 --mirror 加速 npm 安装
./setup.sh --mirror

2. Start the Tunnel and Auto-Sync

# 方式 A：使用 Pinggy 隧道（默认无需配置任何账号）
./refresh-devspace-mcp.sh --tunnel-cmd "ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p 443 -R0:localhost:7676 a.pinggy.io"

# 方式 B：使用 ngrok
./refresh-devspace-mcp.sh --tunnel-cmd "ngrok http 7676" --url-regex 'https://[a-z0-9-]+\.ngrok-free\.app'

# 方式 C：使用已有的公网隧道地址
./refresh-devspace-mcp.sh --known-url "https://abc-123.ngrok-free.app/mcp"

📱 Client Configuration & Authorization

Web-based ChatGPT Configuration (Supports Free Accounts)

1. Open the ChatGPT web app, click the avatar in the bottom-left corner, and go to Settings → Apps & Connectors → Advanced → Developer Mode.

2. Click Create connector and enter your public MCP address: https://<your-tunnel-domain>/mcp.

3. In the OAuth window that appears, enter the DevSpace Owner password (stored in ~/.devspace/auth.json) to complete authorization.

4. Start a new conversation, click the connector icon in the toolbar, and ChatGPT can read, write, and run your local code!

🛠️ Diagnostic Toolbox & CLI Commands

This repository includes a complete set of diagnostic and operational commands:

# 🔍 综合诊断与能力探针
npm run probe                         # 完整 OAuth + tools/list 诊断
node mcp-probe.mjs --workspace D:/AI/x --json  # 输出 Skills、Subagents 与指令清单
node mcp-probe.mjs --test-delete --test-dir D:/AI/tmp # 安全沙箱删除测试
npm run probe:accept                  # 隔离式编辑、测试、长进程与 diff 自动验收
npm run doctor:web                    # ChatGPT 网页 Connector 专用深度排错

# 📦 资源与 Hook 审计
npm run resources                     # 查看已发现/显式选择的 Codex Skills
npm run hooks                         # 检查网页兼容 Hook（明确标注不支持 before_tool）

# 🔐 OAuth 审计与令牌管控
npm run oauth:list                    # 列出所有已注册的客户端
node oauth-admin.mjs prune            # 清理过期的访问令牌
node oauth-admin.mjs revoke-client <client-id> --yes # 撤销指定客户端
node oauth-admin.mjs revoke-all --yes # 全局吊销所有授权令牌

📂 Project Structure & File Descriptions

├── 🪟 Windows 受管核心
│   ├── start.bat / stop.bat          # Windows 快捷启停入口
│   ├── start-ngrok.mjs               # ngrok 隧道守护与 DevSpace 进程生命周期管理
│   ├── stop-service.mjs              # 基于 PID 树与进程签名的精准安全停止
│   └── service-status.mjs            # 进程状态诊断与健康探测
├── 🐧 Linux / WSL 工具
│   ├── setup.sh                      # 依赖安装与交互初始化
│   ├── refresh-devspace-mcp.sh       # 隧道刷新与配置原子重载
│   └── linux-process-utils.sh        # Linux /proc 标识安全验证与进程管理
├── 🔍 诊断与验收体系
│   ├── web-doctor.mjs                # 网页 Connector 诊断套件
│   ├── mcp-probe.mjs                 # MCP 协议与能力边界探针
│   ├── execution-evidence.mjs        # 隐私最小化执行证据收录
│   └── web-acceptance.mjs            # 真实 ChatGPT 网页交互验收工具
├── 🔐 权限与资源配置
│   ├── oauth-admin.mjs / oauth-db.mjs # OAuth 数据库管理与 Token 撤销
│   ├── resource-admin.mjs            # Codex Skills 与 AGENTS.md 资源镜像
│   └── hook-admin.mjs                # after_tool / tool_failure Hook 适配器
└── 📄 模板与规范
    ├── .env.example                  # 环境变量模板
    ├── .mcp.json.example             # MCP 客户端配置示例
    ├── review.sh / templates/        # 静态审查脚手架与报告模板
    └── docs/                         # ADR 决策记录、路线图与验收报告

💡 Troubleshooting

• Error: The client reports expected .../ , received .../mcp.

• Root cause: The publicBaseUrl in config.json was set to a URL with /mcp. DevSpace derives the OAuth issuer from publicBaseUrl and then appends /mcp as the MCP endpoint.

• Solution: Make sure publicBaseUrl is the bare domain root (no suffix), and only include /mcp in the connection URL you enter in the client. This project's scripts already handle this automatically.

• Error message: The command is not found in a non-interactive environment, or the npm symlink lacks execute permission.

• Solution: This project's launcher scripts automatically complete the PATH environment variable and include a built-in chmod +x self-healing logic. To fix manually, run:

  chmod +x $(readlink -f $(which devspace))

• Root cause: The traditional pkill -f pattern matches the current script's own command-line arguments, causing collateral damage.

• Solution: This project records the PID and combines Linux /proc startup markers / Windows process ownership chains for precise termination.

• Root cause: setsid cannot directly invoke the shell built-in command eval.

• Solution: Unified wrapper as setsid bash -c "$CMD".

• Root cause: The upstream DevSpace mounts the full MCP App on tool calls like open_workspace, creating frequent iframes; and the original component loads resources from ngrok, which the free tunnel's security interception page blocks.

• Solution: This project adapts the module in memory for compatibility:

  1. Only mounts the UI resource on the final show_changes;

  2. Uses a fully self-contained, versioned inline Diff component (ui://devspace/diff-card-inline-v3.html);

  3. After the change, click Refresh in the ChatGPT Connector settings and start a new conversation to test.

• Note: If you don't configure a fixed domain, the free tunnel's domain may change on every restart. We recommend claiming 1 free static domain in the ngrok Dashboard to avoid having to update the ChatGPT endpoint repeatedly.

🛡️ Security Policy & Disclaimer

1. Credential isolation: Never commit .env.local, ~/.devspace/auth.json, runtime logs, or real .mcp.json to any public repository.

2. Risk control: The public tunnel is accessible; only enable it when needed. If you suspect credential leakage, immediately run node oauth-admin.mjs revoke-all --yes and rotate your tokens.

3. Usage limit notice: You've hit your usage limit is a model usage limit on the OpenAI / ChatGPT side and is unrelated to the local tunnel or this project.

4. For a detailed threat model and security response guidance, see 🔒 SECURITY.md.

🤝 Credits & License

This project is a continued refactor and evolution of the excellent concept from Embracecactus/devspace-mcp-tunnel.

• Original author's repository: Embracecactus/devspace-mcp-tunnel (thanks to the original author for the Linux automation script foundation and practical approach)

• Underlying foundation: DevSpace (@waishnav/devspace)

• License: This project is fully open source under the MIT License. In accordance with the MIT License, the project retains the original author's copyright notice (Copyright (c) 2026 Embracecactus). You are free to learn from, modify, and redistribute it within legal and compliant boundaries.