🌉 Chat2Agent

Conjunto de herramientas de puente de código abierto que permite a la interfaz web de ChatGPT disponer de capacidades de espacio de trabajo local a través del MCP oficial

💡 Posicionamiento principal El objetivo principal de este proyecto es: permitir que la versión web de ChatGPT (incluidas las versiones gratuita y de pago) se conecte directamente al espacio de trabajo local a través del conector oficial MCP (Model Context Protocol) de OpenAI, obteniendo capacidades similares a las de Codex Agent para búsqueda de código, modificación de archivos, ejecución de pruebas y revisión.

Para conocer los límites de diseño completos, consulte 📑 ADR 0001: Web Agent Boundary y 🗺️ Hoja de ruta del producto.

🛡️ Coste cero y garantía absoluta de seguridad

1. 💰 100% gratuito, las cuentas gratuitas normales funcionan directamente

• Disponible con la versión gratuita de ChatGPT: OpenAI ya ha habilitado el Developer Mode / MCP Connector en la interfaz web. Las cuentas gratuitas normales pueden añadir conectores MCP personalizados sin necesidad de suscribirse a Plus/Team/Pro.

• Túnel público gratuito: tanto el plan gratuito de ngrok incluido como el túnel gratuito de Pinggy permiten establecer una comunicación estable entre el equipo local y la interfaz web sin ningún coste.

2. 🔒 Protocolo oficial y legítimo, riesgo de suspensión de cuenta absolutamente nulo

• Estándar abierto oficial: basado completamente en la especificación Model Context Protocol (MCP) impulsada oficialmente por OpenAI y en el flujo estándar OAuth 2.0.

• Sin ingeniería inversa ni métodos fraudulentos: nunca se inyectan cookies web, nunca se capturan interfaces privadas no públicas de la web, nunca se realiza ingeniería inversa de tokens, nunca se utilizan scripts de rastreo automatizados que infrinjan las normas. Para OpenAI, esto es simplemente un conector estándar de terceros legítimo, totalmente conforme con los Términos de Servicio (TOS) oficiales, garantizando desde la base técnica un riesgo de suspensión de cuenta nulo.

Related MCP server: codex-web-bridge

🚀 ¿Por qué elegir Chat2Agent? (Mejoras importantes respecto a la versión original)

Este proyecto es una evolución mediante refactorización profunda de la excelente idea de Embracecactus/devspace-mcp-tunnel.

La versión original del autor era principalmente un script Bash de demostración sencillo para Linux (11 archivos en total). Chat2Agent se ha ampliado a 66 archivos, con más de 6400 líneas de código nuevo y 40 pruebas unitarias automatizadas integradas, logrando una transformación a nivel industrial:

✨ Características principales e implementación técnica de alto nivel

🏗️ Principio de funcionamiento

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

• Escucha aislada: DevSpace solo escucha en la dirección de bucle local 127.0.0.1:7676, con aprobación estricta mediante OAuth (contraseña de Owner).

• Proxy inverso: la herramienta de túnel redirige el tráfico HTTPS público al puerto local 7676.

• Reglas de endpoint: la URL de conexión del cliente MCP es https://<dominio-del-túnel>/mcp, el issuer de OAuth proviene de publicBaseUrl (es decir, la raíz del dominio puro, sin /mcp).

• Cero contaminación global:

  • Lanzador de Windows: solo actualiza .mcp.json en el directorio del proyecto, sin modificar la configuración global de Codex del equipo.

  • Script de actualización de Linux: por defecto no modifica ~/.codex/config.toml, solo se sincroniza como compatibilidad heredada cuando se añade explícitamente --sync-codex.

🌐 Guía de configuración gratuita de ngrok (tutorial paso a paso)

Se recomienda usar el ngrok gratuito para proporcionar un túnel público estable (totalmente gratuito):

1. Registrar una cuenta: visite el sitio web oficial de ngrok (ngrok.com) y regístrese gratuitamente.

2. Obtener el Authtoken:

   • Tras iniciar sesión, vaya a ngrok Dashboard -> Your Authtoken.

   • Copie el Token generado.

3. (Muy recomendado) Obtener 1 dominio estático gratuito:

   • En el menú lateral, haga clic en Cloud Edge -> Domains.

   • Haga clic en Claim a domain para obtener gratuitamente un dominio estático exclusivo (como your-name.ngrok-free.app).

   • Ventaja: con un dominio fijo, no es necesario actualizar la URL en la interfaz web de ChatGPT cada vez que se reinicie el servicio.

4. Rellenar la configuración del proyecto:

   • En el directorio raíz del proyecto, copie un archivo de configuración:

     Copy-Item .env.example .env.local

   • Edite .env.local y rellene la información anterior:

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

🚀 Inicio rápido en Windows (recomendado)

1. Instalar dependencias e inicializar DevSpace

Requisitos del entorno: Node.js >=22.19 <27

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

# 2. 初始化 DevSpace 配置
devspace init

devspace init le guiará para introducir los directorios permitidos, el puerto (rellene 7676) y la URL base pública (puede rellenar https://placeholder.invalid inicialmente; el lanzador la reescribirá automáticamente).

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

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

2. Inicio con un clic, consulta de estado y parada

# 运行启动前预检
npm run preflight

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

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

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

🐧 Inicio rápido en Linux / WSL

1. Instalación e inicialización

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

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

2. Inicio del túnel y sincronización automática

# 方式 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"

📱 Configuración del cliente y autorización

Configuración en la versión web de ChatGPT (compatible con cuentas gratuitas)

1. Abra la interfaz web de ChatGPT, haga clic en el avatar de la esquina inferior izquierda y vaya a Settings → Apps & Connectors → Advanced → Developer Mode.

2. Haga clic en Create connector e introduzca su dirección MCP pública: https://<su-dominio-del-túnel>/mcp.

3. En la ventana OAuth que aparece, introduzca la contraseña de Owner de DevSpace (guardada en ~/.devspace/auth.json) para completar la autorización.

4. Inicie una nueva conversación, haga clic en el icono del conector en la barra de herramientas y ChatGPT podrá leer, escribir y ejecutar su código local.

🛠️ Caja de herramientas de diagnóstico y comandos de línea de comandos

Este repositorio incluye un conjunto completo de comandos de diagnóstico y operación:

# 🔍 综合诊断与能力探针
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 # 全局吊销所有授权令牌

📂 Estructura del proyecto y descripción de archivos

├── 🪟 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 决策记录、路线图与验收报告

💡 Registro de problemas y soluciones (Troubleshooting)

• Síntoma del error: el cliente muestra expected .../ , received .../mcp.

• Análisis de la causa: publicBaseUrl en config.json se ha rellenado con una dirección que incluye /mcp. DevSpace utiliza publicBaseUrl para derivar el issuer de OAuth y luego concatena /mcp como endpoint MCP.

• Solución: asegúrese de que publicBaseUrl sea la raíz del dominio puro (sin sufijo), y solo incluya /mcp en la URL de conexión que rellena el cliente. Los scripts de este proyecto ya realizan la corrección automática.

• Síntoma del error: el comando no se encuentra en entornos no interactivos, o el enlace simbólico de npm no tiene permisos de ejecución.

• Solución: el script de inicio de este proyecto completa automáticamente la variable de entorno PATH e incluye lógica de autocuración chmod +x. Si necesita repararlo manualmente, ejecute:

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

• Análisis de la causa: el patrón tradicional pkill -f coincide con los argumentos de línea de comandos del propio script actual, causando daños accidentales.

• Solución: este proyecto cambia a registrar el PID y combina el identificador de inicio de Linux /proc/la cadena de propiedad de procesos de Windows para una terminación precisa.

• Análisis de la causa: setsid no puede invocar directamente el comando integrado de Shell eval.

• Solución: se encapsula uniformemente como llamada setsid bash -c "$CMD".

• Análisis de la causa: el DevSpace ascendente monta por defecto la aplicación MCP completa al invocar herramientas como open_workspace, lo que provoca la creación frecuente de iframes; además, el componente original depende de cargar recursos desde ngrok, que son bloqueados por la página de interceptación de seguridad del túnel gratuito.

• Solución: este proyecto realiza una adaptación de compatibilidad del módulo en memoria:

  1. Solo se montan recursos de UI para el show_changes final;

  2. Se utiliza un componente Diff en línea completamente autocontenido y versionado (ui://devspace/diff-card-inline-v3.html);

  3. Tras la modificación, haga clic en Refresh en la configuración del conector de ChatGPT e inicie una nueva conversación para probar.

• Nota: si no configura un dominio fijo, el dominio del túnel gratuito puede cambiar en cada reinicio. Se recomienda obtener gratuitamente 1 dominio estático en el panel de ngrok, para no tener que actualizar repetidamente el endpoint de ChatGPT.

🛡️ Normas de seguridad y exención de responsabilidad

1. Aislamiento de credenciales: está estrictamente prohibido enviar .env.local, ~/.devspace/auth.json, registros de ejecución o archivos .mcp.json reales a cualquier repositorio de código público.

2. Riesgo controlable: el túnel público es accesible; actívelo solo cuando sea necesario. Si sospecha que las credenciales se han filtrado, ejecute inmediatamente node oauth-admin.mjs revoke-all --yes y rote los tokens.

3. Aviso de cuota: You've hit your usage limit es un límite de cuota de invocación de modelos en el lado de OpenAI/ChatGPT, no está relacionado con el túnel local ni con este proyecto.

4. Para el modelo de amenazas detallado y las directrices de respuesta de seguridad, consulte 🔒 SECURITY.md.

🤝 Agradecimientos y licencia de código abierto (Credits & License)

Este proyecto continúa la refactorización y evolución sobre la excelente idea de Embracecactus/devspace-mcp-tunnel.

• Repositorio del autor original: Embracecactus/devspace-mcp-tunnel (gracias al autor original por sentar las bases del prototipo de script automatizado de Linux y las ideas prácticas)

• Soporte de la base subyacente: DevSpace (@waishnav/devspace)

• Licencia de código abierto: este proyecto está completamente abierto bajo la licencia MIT License. De acuerdo con las normas de la licencia MIT, el proyecto conserva íntegramente la declaración de derechos de autor del autor original (Copyright (c) 2026 Embracecactus). Puede estudiar, modificar y redistribuir libremente dentro del marco legal y reglamentario.