🌉 Chat2Agent

ChatGPT 웹 인터페이스가 공식 MCP를 통해 로컬 워크스페이스 기능을 갖추게 하는 오픈소스 브리지 스위트

💡 핵심 포지셔닝 이 프로젝트의 주요 목표는 웹 버전 ChatGPT(무료 버전 및 유료 버전 포함) 가 OpenAI 공식 MCP(Model Context Protocol) 개발자 커넥터를 통해 로컬 워크스페이스에 직접 연결되어 Codex Agent와 같은 코드 검색, 파일 수정, 테스트 실행 및 리뷰 기능을 얻을 수 있게 하는 것입니다.

전체 설계 경계는 📑 ADR 0001: Web Agent Boundary 및 🗺️ 제품 로드맵을 참조하세요.

🛡️ 제로 비용과 절대적 안전 보장

1. 💰 100% 무료, 일반 무료 계정으로 바로 사용 가능

• ChatGPT 무료 버전 사용 가능: OpenAI는 공식적으로 웹 인터페이스에 Developer Mode / MCP Connector를 공개했으며, 일반 무료 계정도 Plus/Team/Pro 구독 없이 바로 커스텀 MCP 커넥터를 추가할 수 있습니다!

• 무료 공용 터널: 기본 제공되는 ngrok 무료 요금제든 Pinggy 무료 터널이든, 전 과정에서 비용 없이 로컬과 웹 간 통신을 안정적으로 연결할 수 있습니다.

2. 🔒 공식 표준 프로토콜, 절대 0 계정 정지 위험

• 공식 개방형 표준: OpenAI가 공식적으로 도입한 Model Context Protocol(MCP) 규격과 표준 OAuth 2.0 프로세스에 완전히 기반합니다.

• 리버스 엔지니어링 및 불법 수단 배제: 웹 Cookie 주입 절대 없음, 웹 비공개 인터페이스 크롤링 절대 없음, Token 리버스 절대 없음, 위반 자동화 크롤러 스크립트 절대 사용하지 않음. OpenAI 입장에서 이는 정식 타사 표준 커넥터일 뿐이며, 공식 이용약관(TOS)을 완전히 준수하므로 기술적 기반에서 0 계정 정지 위험을 보장합니다.

Related MCP server: codex-web-bridge

🚀 왜 Chat2Agent인가? (원작자 버전 대비 주요 업그레이드)

이 프로젝트는 Embracecactus/devspace-mcp-tunnel의 훌륭한 아이디어를 기반으로 심층 리팩토링하여 진화한 것입니다.

원작자 버전은 주로 Linux용 간단한 Bash 시작 스크립트 데모(총 11개 파일)였습니다. Chat2Agent는 66개 파일, 6400+줄의 신규 코드, 40개의 자동화 단위 테스트로 확장되어 산업급 변신을 이루었습니다:

✨ 핵심 기능 및 하드코어 엔지니어링 구현

🏗️ 작동 원리

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

• 격리 리슨: DevSpace는 로컬 루프백 주소 127.0.0.1:7676만 리슨하며, OAuth(Owner 비밀번호)를 통한 엄격한 승인 절차를 거칩니다.

• 리버스 프록시: 터널 도구가 공용 HTTPS 트래픽을 로컬 7676 포트로 프록시합니다.

• 엔드포인트 규칙: MCP 클라이언트 연결 URL은 https://<터널 도메인>/mcp이며, OAuth issuer는 publicBaseUrl(즉, 순수 도메인 루트, /mcp 제외)에서 파생됩니다.

• 전역 오염 제로:

  • Windows 런처: 프로젝트 디렉토리의 .mcp.json만 업데이트, 본机 전역 Codex 설정을 변경하지 않습니다.

  • Linux 새로고침 스크립트: 기본적으로 ~/.codex/config.toml을 수정하지 않으며, 명시적으로 --sync-codex를 추가한 경우에만 레거시 호환 동기화로 수행합니다.

🌐 무료 ngrok 설정 가이드 (단계별 무료 사용)

무료 ngrok을 사용하여 안정적인 공용 터널 지원을 권장합니다(완전 무료):

1. 계정 등록: ngrok 공식 사이트 (ngrok.com)에서 무료 계정을 등록하세요.

2. Authtoken 획득:

   • 로그인 후 ngrok Dashboard -> Your Authtoken으로 이동합니다.

   • 생성된 Token 문자열을 복사하세요.

3. (강력 추천) 무료 정적 도메인 1개 받기:

   • 왼쪽 메뉴에서 Cloud Edge -> Domains를 클릭하세요.

   • Claim a domain을 클릭하여 전용 정적 도메인(예: your-name.ngrok-free.app)을 무료로 받으세요.

   • 장점: 도메인이 고정되면 서비스를 재시작할 때마다 ChatGPT 웹에서 URL을 다시 업데이트할 필요가 없습니다!

4. 프로젝트 설정 입력:

   • 프로젝트 루트 디렉토리에 설정 파일을 복사하세요:

     Copy-Item .env.example .env.local

   • .env.local을 편집하여 방금 얻은 정보를 입력하세요:

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

🚀 Windows 빠른 시작 (권장)

1. 의존성 설치 및 DevSpace 초기화

요구 환경: Node.js >=22.19 <27

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

# 2. 初始化 DevSpace 配置
devspace init

devspace init은 허용 디렉토리, 포트(7676 입력) 및 공용 base URL(임시로 https://placeholder.invalid 입력 가능, 런처가 자동으로 재작성)을 안내합니다.

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

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

2. 원클릭 시작, 상태 확인 및 중지

# 运行启动前预检
npm run preflight

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

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

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

🐧 Linux / WSL 빠른 시작

1. 설치 및 초기화

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

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

2. 터널 시작 및 자동 동기화

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

📱 클라이언트 설정 및 인증

웹 버전 ChatGPT 설정 (무료 계정 지원)

1. ChatGPT 웹을 열고 왼쪽 하단 아바타를 클릭하여 Settings → Apps & Connectors → Advanced → Developer Mode로 이동합니다.

2. Create connector를 클릭하고 공용 MCP 주소를 입력하세요: https://<터널 도메인>/mcp.

3. 페이지에 표시되는 OAuth 창에서 DevSpace의 Owner 비밀번호(~/.devspace/auth.json에 저장)를 입력하여 인증을 완료하세요.

4. 새 대화를 시작하고 도구 모음의 커넥터 아이콘을 클릭하면 ChatGPT가 로컬 코드를 읽고, 작성하고, 실행할 수 있습니다!

🛠️ 진단 툴박스 및 CLI 명령어

본 저장소에는 완벽한 진단 및 운영 명령어 세트가 내장되어 있습니다:

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

📂 프로젝트 구조 및 파일 설명

├── 🪟 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)

• 오류 증상: 클라이언트가 expected .../ , received .../mcp를 표시합니다.

• 원인 분석: config.json의 publicBaseUrl에 /mcp가 포함된 주소가 입력되었습니다. DevSpace는 publicBaseUrl로 OAuth issuer를 파생한 후 /mcp를 연결하여 MCP 엔드포인트로 사용합니다.

• 해결 방법: publicBaseUrl이 순수 도메인 루트(접미사 없음)인지 확인하고, 클라이언트에 입력하는 연결 URL에만 /mcp를 포함하세요. 본 프로젝트 스크립트는 자동 수정을 수행합니다.

• 오류 증상: 비대화형 환경에서 명령어를 찾을 수 없거나, npm 심볼릭 링크에 실행 권한이 없습니다.

• 해결 방법: 본 프로젝트 시작 스크립트는 PATH 환경변수를 자동으로 보완하고 chmod +x 자가 치유 로직을 내장합니다. 수동 수정이 필요하면 다음을 실행하세요:

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

• 원인 분석: 기존 pkill -f 방식은 현재 스크립트 자체의 명령줄 인자와 매칭되어 오살이 발생합니다.

• 해결 방법: 본 프로젝트는 PID 기록과 Linux /proc 시작 식별자/Windows 프로세스 소유 체인을 결합하여 정밀 종료를 수행합니다.

• 원인 분석: setsid는 Shell 내장 명령어 eval을 직접 호출할 수 없습니다.

• 해결 방법: setsid bash -c "$CMD" 호출로 통일하여 래핑합니다.

• 원인 분석: 상위 DevSpace는 기본적으로 open_workspace 등 도구 호출 시 전체 MCP App을 마운트하여 iframe이 빈번하게 생성됩니다. 또한 원래 컴포넌트는 ngrok에서 리소스를 로드하므로 무료 터널의 보안 차단 페이지에 의해 차단됩니다.

• 해결 방법: 본 프로젝트는 메모리에서 모듈 호환성 어댑테이션을 수행합니다:

  1. 최종 show_changes에만 UI 리소스를 마운트합니다;

  2. 완전히 자체 포함된 버전 관리 인라인 Diff 컴포넌트(ui://devspace/diff-card-inline-v3.html)를 사용합니다;

  3. 수정 후 ChatGPT Connector 설정에서 Refresh를 클릭하고 새 대화를 열어 테스트하세요.

• 설명: 고정 도메인을 설정하지 않으면 무료 터널은 재시작할 때마다 도메인이 변경될 수 있습니다. ngrok Dashboard에서 무료 정적 도메인 1개를 받으면 ChatGPT 엔드포인트를 반복적으로 업데이트할 필요 없이 한 번에 해결됩니다.

🛡️ 보안 규정 및 면책 조항

1. 자격 증명 격리: .env.local, ~/.devspace/auth.json, 실행 로그 또는 실제 .mcp.json을 공개 코드 저장소에 커밋하는 것을 엄격히 금지합니다.

2. 위험 통제 가능: 공용 터널은 접근 가능성을 가지므로 필요할 때만 활성화하세요. 자격 증명 유출이 의심되면 즉시 node oauth-admin.mjs revoke-all --yes를 실행하고 Token을 교체하세요.

3. 할당량 안내: You've hit your usage limit는 OpenAI / ChatGPT 측의 모델 호출 할당량 제한이며, 로컬 터널 및 본 프로젝트와 무관합니다.

4. 상세한 위협 모델 및 보안 대응 지침은 🔒 SECURITY.md를 참조하세요.

🤝 감사 및 오픈소스 라이선스 (Credits & License)

본 프로젝트는 Embracecactus/devspace-mcp-tunnel의 훌륭한 아이디어를 기반으로 지속적인 리팩토링과 진화를 통해 개발되었습니다.

• 원작자 저장소: Embracecactus/devspace-mcp-tunnel (원작자가 마련한 Linux 자동화 스크립트 초기 형태와 실천 아이디어에 감사드립니다)

• 기반 인프라 지원: DevSpace (@waishnav/devspace)

• 오픈소스 라이선스: 본 프로젝트는 MIT License 라이선스로 완전히 오픈소스입니다. MIT 라이선스 규정에 따라 원작자의 저작권 표시(Copyright (c) 2026 Embracecactus)를 완전히 보존하며, 법적 범위 내에서 자유롭게 학습, 수정 및 2차 배포할 수 있습니다.