# Deep Research GPT (`/deep-research-gpt`)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform: Windows](https://img.shields.io/badge/Platform-Windows%2010%2F11-0078D6.svg)](https://microsoft.com)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://python.org)

Windows용 **ChatGPT 데스크톱(ChatGPT Classic)** 앱을 백그라운드 리서치 엔진(Lead Analyst)으로 활용하는 자동화 브리지, MCP(Model Context Protocol) 서버 및 AI 에이전트 스킬입니다.

> **면책 조항 (Disclaimer)**  
> 본 프로젝트는 개인 오픈소스 프로젝트이며, OpenAI와 제휴·보증 또는 공식적인 관련이 없습니다.  
> ChatGPT는 OpenAI의 등록 상표입니다.

---

## 🌟 주요 특징 (Key Features)

1. **결정론적 무마우스 UI 자동화 (Zero-Mouse UIA)**:
   - Windows UI Automation(`TogglePattern`, `InvokePattern`, `ValuePattern`)을 통해 마우스 커서 조작 없이 백그라운드에서 신뢰성 있게 동작합니다.
2. **Think 모드 멱등적 활성화 (Idempotent Think Mode)**:
   - Think 모드가 이미 켜져 있는 상태(`ToggleState == 1`)에서는 토글을 중복 수행하지 않아 실수로 꺼지는 현상을 원천 방지합니다.
3. **스마트 세션 재사용 (Smart Session Reuse)**:
   - 동일한 연구 주제(`topic`)로 연속 질의 시, 불필요한 새 창 생성(`Ctrl + Shift + O`)을 건너뛰고 기존 대화 컨텍스트를 유지합니다.
4. **결정론적 출력 완료 감지 & 동적 워치독 (Watchdog & Completion)**:
   - ChatGPT Classic의 `'답변 중지'`(`composer-submit-button`) 상태 전환과 유휴 복귀를 실시간 모니터링하여 조기 종료 없이 긴 응답도 온전히 수집합니다.
5. **3-Way 인터페이스**:
   - **터미널 키워드 실행기**: `python run.py <keyword>` 한 단어로 즉시 실행
   - **MCP 서버**: Antigravity, Claude Desktop, Cursor 등과 stdio MCP 연동
   - **Python API**: 파이썬 코드에서 `from chatgpt_bridge import ask_chatgpt` 직접 임포트

---

## 📁 프로젝트 구조 (Repository Structure)

```text
deep-research-gpt/
├── chatgpt_bridge/           # 핵심 브리지 패키지
│   ├── __init__.py
│   ├── core.py               # Windows UIA 드라이버 구현체
│   ├── client.py             # 파이썬 클라이언트 래퍼
│   ├── mcp_server.py         # FastMCP stdio 서버
│   ├── cli.py                # 커맨드라인 인터페이스
│   └── server.py             # 로컬 HTTP REST 브리지 서버
├── run.py                    # 초간단 키워드 실행 스크립트
├── run.bat                   # 윈도우 배치 실행기
├── SKILL.md                  # AI 에이전트(Antigravity 등) 전용 스킬 정의서
├── requirements.txt          # 파이썬 의존성 목록
├── LICENSE                   # MIT 라이선스
└── README.md
```

---

## 🚀 빠른 시작 (Quick Start)

### 1. 요구 사항
- **OS**: Windows 10 또는 Windows 11
- **Python**: 3.10 이상
- **ChatGPT**: 공식 Windows 데스크톱 앱 (로그인 완료 상태)

### 2. 설치
```bash
git clone https://github.com/wooni1017/deep-research-gpt.git
cd deep-research-gpt
pip install -r requirements.txt
```

### 3. 터미널 키워드 실행 (`run.py`)
```bash
# 기본 1+1 연동 테스트
python run.py test

# 상태 진단 (ChatGPT 창 및 Think 모드 감지)
python run.py status

# 즉석 자유 질문
python run.py ask "원하는 심층 조사 질문..."

# 등록된 키워드 목록 확인
python run.py
```

키워드 추가 및 수정은 [`run.py`](run.py)의 `TASKS` 딕셔너리에서 자유롭게 정의할 수 있습니다:
```python
TASKS = {
    "my_topic": {
        "desc": "사용자 맞춤형 심층 조사",
        "topic": "custom_topic",
        "use_template": True,
        "prompt": "해당 아키텍처의 공식 스펙과 상세 원리를 최대한 자세히 조사해라"
    }
}
```

---

## 🔌 MCP 서버 설정 (MCP Configuration)

Antigravity 또는 Claude Desktop, Cursor 등 MCP 지원 환경의 설정 파일(`mcpServers` 블록)에 아래와 같이 추가합니다:

```json
{
  "mcpServers": {
    "deep-research-gpt": {
      "command": "python",
      "args": [
        "-m",
        "chatgpt_bridge.mcp_server"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}
```

### 제공되는 MCP 도구 (Tools)
- `deep_research_gpt`: Think 모드로 심층 연구 질의 실행
  - `prompt` (string, 필수): 질문 또는 조사 대상
  - `topic` (string, 선택): 주제 식별자 (동일 주제 시 세션 유지)
  - `new_session` (boolean, 선택): 새 세션 강제 여부
  - `use_template` (boolean, 기본 `true`): `[연구 및 심층 조사 요청]` 지시문 래핑 여부
- `get_chatgpt_status`: ChatGPT Classic 윈도우 및 Think 버튼 활성화 상태 진단

---

## 🐍 Python 코드 연동 (Direct API)

```python
from chatgpt_bridge import ask_chatgpt

# 1. 심층 조사 질의 (기본 템플릿 적용)
response = ask_chatgpt("WebGPU Compute Shader 아키텍처 상세 사양", topic="webgpu")
print(response)

# 2. 템플릿 없이 순수 질문만 전송
short_answer = ask_chatgpt("1+1은 뭐야? 숫자 하나로만 답해", use_template=False)
print(short_answer)
```

---

## 📄 라이선스 (License)

본 프로젝트는 [MIT License](LICENSE)에 따라 배포됩니다.
Copyright (c) 2026 wooni1017.