notelm-mcp 1.2.1

package/docs/06_integration-analysis.qmd

@@ -0,0 +1,255 @@
+---
+title: "Chrome/NotebookLM/Gemini 통합 분석 보고서"
+author: "Antigravity AI"
+date: "2026-01-02"
+format:
+  html:
+    toc: true
+    toc-depth: 3
+    number-sections: true
+---
+
+# 개요
+
+이 문서는 NotebookLM MCP 프로젝트의 Chrome 자동화, NotebookLM 연동, Gemini 통합 부분에 대한 분석 결과입니다.
+
+---
+
+# Gemini 버전 확인
+
+::: {.callout-important}
+## 결론: Gemini 2.5 사용 (Gemini 3 아님)
+NotebookLM은 현재 **Gemini 2.5**를 백엔드로 사용합니다.
+:::
+
+## 코드 내 확인 사항
+
+| 파일 | 내용 |
+|------|------|
+| `src/tools/definitions/ask-question.ts` | `"Gemini 2.5 • Session RAG"` |
+| `README.md` | `"Gemini 2.5 that provides intelligent, synthesized answers"` |
+| `CHANGELOG.md` | `"Session-based conversations with Gemini 2.5"` |
+
+## 참고
+
+- NotebookLM은 Google의 관리형 서비스
+- Gemini 모델 버전은 Google에서 제어하며 MCP에서 직접 변경 불가
+- Google이 백엔드를 업그레이드하면 자동으로 최신 버전 사용
+
+---
+
+# Chrome 자동화 분석
+
+## 사용 기술
+
+- **Patchright v1.48.2**: Playwright 포크, 봇 탐지 회피 특화
+- **영구 Chrome 프로필**: `launchPersistentContext`로 일관된 핑거프린트 유지
+
+## 핵심 구성요소
+
+| 파일 | 역할 |
+|------|------|
+| `auth-manager.ts` | Google 인증, 쿠키 관리, 상태 저장/복원 |
+| `browser-session.ts` | 개별 브라우저 세션, 질문 전송, 응답 수신 |
+| `session-manager.ts` | 다중 세션 관리, 세션 풀링, 자동 정리 |
+| `shared-context-manager.ts` | 단일 브라우저 컨텍스트 공유, 프로필 관리 |
+
+## 아키텍처 흐름
+
+```mermaid
+flowchart LR
+    A[MCP Client] --> B[Tool Handler]
+    B --> C[Session Manager]
+    C --> D[Shared Context Manager]
+    D --> E[Browser Session]
+    E --> F[NotebookLM Page]
+    F --> G[Gemini 2.5 Backend]
+```
+
+## 잘 구현된 부분
+
+::: {.callout-tip}
+### 강점
+1. **자동 복구 메커니즘**: 브라우저/컨텍스트 종료 시 자동 재연결
+2. **다국어 셀렉터**: 6개 언어 UI 대응 (영어, 독일어, 일본어, 한국어, 프랑스어, 스페인어)
+3. **스텔스 모드**: 휴먼 타이핑, 마우스 움직임, 랜덤 딜레이
+4. **세션 기반 대화**: 컨텍스트 유지를 통한 심층 연구 가능
+:::
+
+---
+
+# NotebookLM 연동 분석
+
+## 인증 흐름
+
+1. 사용자가 `setup_auth` 호출
+2. Chrome 브라우저 창 열림 (headful 모드)
+3. Google 계정 수동 로그인 (최대 10분)
+4. 쿠키 및 sessionStorage 저장
+5. 이후 세션에서 자동 인증
+
+## 질문-응답 흐름
+
+```mermaid
+sequenceDiagram
+    participant C as Claude
+    participant M as MCP Server
+    participant B as Browser Session
+    participant N as NotebookLM
+
+    C->>M: ask_question(question)
+    M->>B: getOrCreateSession()
+    B->>N: Navigate to notebook
+    B->>N: Type question (human-like)
+    B->>N: Submit (Enter)
+    N-->>B: Stream response
+    B-->>M: Parse answer
+    M-->>C: Return formatted answer
+```
+
+## Rate Limit 처리
+
+- 무료 계정: 50 쿼리/일
+- Rate limit 감지: 에러 메시지 및 입력창 disabled 체크
+- 우회: `re_auth` 도구로 다른 Google 계정 전환
+
+---
+
+# 개선 권장 사항
+
+## 우선순위: 높음
+
+### 1. ESM 호환성 문제
+
+**위치**: `src/utils/settings-manager.ts`
+
+```typescript
+// 현재 (비권장)
+const fsSync = require("fs");
+const data = fsSync.readFileSync(this.settingsPath, "utf-8");
+
+// 개선안
+import { readFileSync } from "fs";
+const data = readFileSync(this.settingsPath, "utf-8");
+```
+
+### 2. 타입 안전성 개선
+
+`@ts-expect-error` 사용 위치:
+
+- `auth-manager.ts`: sessionStorage 접근
+- `browser-session.ts`: 브라우저 컨텍스트 평가
+- `stealth-utils.ts`: 윈도우 객체 접근
+
+**개선안**: 브라우저 컨텍스트용 타입 정의 생성
+
+```typescript
+// src/types/browser-context.d.ts
+interface BrowserWindow extends Window {
+  sessionStorage: Storage;
+  localStorage: Storage;
+}
+```
+
+---
+
+## 우선순위: 중간
+
+### 3. Rate Limit 재시도 로직 (✅ 완료)
+
+`RateLimitHandler`를 사용하여 `BrowserSession.ask()` 메서드에 자동 재시도 로직을 통합했습니다.
+429 에러 또는 쿼리 제한 감지 시 지수 백오프를 통해 자동으로 재시도합니다.
+
+```typescript
+// src/session/browser-session.ts
+const handler = new RateLimitHandler();
+const askWithRetry = () => handler.executeWithRetry(askOnce);
+```
+
+### 4. 테스트 추가
+
+현재 상태:
+- `package.json`에 테스트 스크립트 없음
+- 테스트 파일 없음
+
+권장 사항:
+- Jest 또는 Vitest 설정
+- 핵심 모듈 단위 테스트
+- E2E 테스트 (Playwright 활용)
+
+### 5. 하드코딩된 타임아웃 개선
+
+```typescript
+// 현재
+await page.waitForTimeout(2000);  // 매직 넘버
+
+// 개선안
+await page.waitForTimeout(CONFIG.delays.pageStabilize);
+```
+
+---
+
+## 우선순위: 낮음
+
+### 6. 상수 추출
+
+```typescript
+// src/constants.ts
+export const SELECTORS = {
+  CHAT_INPUT: "textarea.query-box-input",
+  THINKING_MESSAGE: "div.thinking-message",
+  RESPONSE_CONTAINER: ".response-content",
+};
+
+export const URLS = {
+  NOTEBOOKLM_AUTH: "https://notebooklm.google.com/",
+  GOOGLE_ACCOUNTS: "https://accounts.google.com/",
+};
+
+export const ERROR_MESSAGES = {
+  SESSION_EXPIRED: "Session expired, re-authenticating...",
+  RATE_LIMIT: "Rate limit reached (50 queries/day)",
+};
+```
+
+### 7. 중복 코드 제거
+
+세션 초기화/복구 로직이 여러 곳에서 반복:
+
+- `BrowserSession.init()`
+- `BrowserSession.ask()` 내부 복구
+- `BrowserSession.reset()`
+
+**개선안**: 공통 복구 유틸리티 함수 추출
+
+---
+
+# 프로젝트 강점 요약
+
+::: {.callout-note}
+## 전반적 평가
+NotebookLM MCP는 **프로덕션 수준의 품질**을 갖춘 잘 설계된 프로젝트입니다.
+:::
+
+| 영역 | 평가 |
+|------|------|
+| 에러 처리 | ✅ 견고함 (try-catch + 자동 복구) |
+| 크로스 플랫폼 | ✅ Linux, macOS, Windows 지원 |
+| 문서화 | ✅ 포괄적 (설정, 도구, 트러블슈팅) |
+| MCP 표준 | ✅ 16개 도구와 리소스 제공 |
+| 보안 | ⚠️ 개선 필요 (이메일 마스킹 강화) |
+| 테스트 | ❌ 부재 (추가 필요) |
+
+---
+
+# 결론
+
+NotebookLM MCP는 Gemini 2.5 기반 NotebookLM과의 통합이 견고하게 구현되어 있으며, Patchright를 활용한 Chrome 자동화가 봇 탐지를 효과적으로 회피합니다.
+
+**즉시 개선 권장**:
+
+1. ESM 호환성 (`require()` → ESM import)
+2. 테스트 커버리지 추가
+3. Rate limit 재시도 로직
+
+이러한 개선을 적용하면 더욱 안정적이고 유지보수 가능한 프로젝트가 될 것입니다.