notelm-mcp 1.2.1

package/docs/03_troubleshooting.md

@@ -0,0 +1,59 @@
+## Troubleshooting
+
+### Fresh start / Deep cleanup
+If you're experiencing persistent issues, corrupted data, or want to start completely fresh:
+
+**⚠️ CRITICAL: Close ALL Chrome/Chromium instances before cleanup!** Open browsers can prevent cleanup and cause issues.
+
+**Recommended workflow:**
+1. Close all Chrome/Chromium windows and instances
+2. Ask: "Run NotebookLM cleanup and preserve my library"
+3. Review the preview - you'll see exactly what will be deleted
+4. Confirm deletion
+5. Re-authenticate: "Open NotebookLM auth setup"
+
+**What gets cleaned:**
+- Browser data, cache, Chrome profiles
+- Temporary files and logs
+- Old installation data
+- **Preserved:** Your notebook library (when using preserve option)
+
+**Useful for:**
+- Authentication problems
+- Browser session conflicts
+- Corrupted browser profiles
+- Clean reinstalls
+- Switching between accounts
+
+### Browser closed / `newPage` errors
+- Symptom: `browserContext.newPage: Target page/context/browser has been closed`.
+- Fix: The server auto‑recovers (recreates context and page). Re‑run the tool.
+
+### Profile lock / `ProcessSingleton` errors
+- Cause: Another Chrome is using the base profile.
+- Fix: `NOTEBOOK_PROFILE_STRATEGY=auto` (default) falls back to isolated per‑instance profiles; or set `isolated`.
+
+### Authentication issues
+**Quick fix:** Ask the agent to repair authentication; it will run `get_health` → `setup_auth` → `get_health`.
+
+**For persistent auth failures:**
+1. Close ALL Chrome/Chromium instances
+2. Ask: "Run NotebookLM cleanup with library preservation"
+3. After cleanup completes, ask: "Open NotebookLM auth setup"
+4. This creates a completely fresh browser session while keeping your notebooks
+
+**Auto-login (optional):**
+- Set `AUTO_LOGIN_ENABLED=true` with `LOGIN_EMAIL`, `LOGIN_PASSWORD` environment variables
+- For automation workflows only
+
+### Typing speed too slow/fast
+- Adjust `TYPING_WPM_MIN`/`MAX`; or disable stealth typing by setting `STEALTH_ENABLED=false`.
+
+### Rate limit reached
+- Symptom: "NotebookLM rate limit reached (50 queries/day for free accounts)".
+- Fix: Use `re_auth` tool to switch to a different Google account, or wait until tomorrow.
+- Upgrade: Google AI Pro/Ultra gives 5x higher limits.
+
+### No notebooks found
+- Ask to add the NotebookLM link you need.
+- Ask to list the stored notebooks, then choose the one to activate.

package/docs/04_usage-guide.md

@@ -0,0 +1,245 @@
+# Advanced Usage Guide
+
+This guide covers advanced usage patterns, best practices, and detailed examples for the NotebookLM MCP server.
+
+> 📘 For installation and quick start, see the main [README](../README.md).
+
+## Research Patterns
+
+### The Iterative Research Pattern
+
+The server is designed to make your agent **ask questions automatically** with NotebookLM. Here's how to leverage this:
+
+1. **Start with broad context**
+   ```
+   "Before implementing the webhook system, research the complete webhook architecture in NotebookLM, including error handling, retry logic, and security considerations."
+   ```
+
+2. **The agent will automatically**:
+   - Ask an initial question to NotebookLM
+   - Read the reminder at the end of each response
+   - Ask follow-up questions to gather more details
+   - Continue until it has comprehensive understanding
+   - Only then provide you with a complete answer
+
+3. **Session management**
+   - The agent maintains the same `session_id` throughout the research
+   - This preserves context across multiple questions
+   - Sessions auto-cleanup after 15 minutes of inactivity
+
+### Deep Dive Example
+
+```
+User: "I need to implement OAuth2 with refresh tokens. Research the complete flow first."
+
+Agent behavior:
+1. Asks NotebookLM: "How does OAuth2 refresh token flow work?"
+2. Gets answer with reminder to ask more
+3. Asks: "What are the security best practices for storing refresh tokens?"
+4. Asks: "How to handle token expiration and renewal?"
+5. Asks: "What are common implementation pitfalls?"
+6. Synthesizes all answers into comprehensive implementation plan
+```
+
+## Notebook Management Strategies
+
+### Multi-Project Setup
+
+Organize notebooks by project or domain:
+
+```
+Production Docs Notebook → APIs, deployment, monitoring
+Development Notebook → Local setup, debugging, testing
+Architecture Notebook → System design, patterns, decisions
+Legacy Code Notebook → Old systems, migration guides
+```
+
+### Notebook Switching Patterns
+
+```
+"For this bug fix, use the Legacy Code notebook."
+"Switch to the Architecture notebook for this design discussion."
+"Use the Production Docs for deployment steps."
+```
+
+### Metadata Best Practices
+
+When adding notebooks, provide rich metadata:
+```
+"Add this notebook with description: 'Complete React 18 documentation including hooks, performance, and migration guides' and tags: react, frontend, hooks, performance"
+```
+
+## Authentication Management
+
+### Account Rotation Strategy
+
+Free tier provides 50 queries/day per account. Maximize usage:
+
+1. **Primary account** → Main development work
+2. **Secondary account** → Testing and validation
+3. **Backup account** → Emergency queries when others are exhausted
+
+```
+"Switch to secondary account" → When approaching limit
+"Check health status" → Verify which account is active
+```
+
+### Handling Auth Failures
+
+The agent can self-repair authentication:
+
+```
+"NotebookLM says I'm logged out—repair authentication"
+```
+
+This triggers: `get_health` → `setup_auth` → `get_health`
+
+## Advanced Configuration
+
+### Performance Optimization
+
+For faster interactions during development:
+```bash
+STEALTH_ENABLED=false  # Disable human-like typing
+TYPING_WPM_MAX=500     # Increase typing speed
+HEADLESS=false         # See what's happening
+```
+
+### Debugging Sessions
+
+Enable browser visibility to watch the live conversation:
+```
+"Research this issue and show me the browser"
+```
+
+Your agent automatically enables browser visibility for that research session.
+
+### Session Management
+
+Monitor active sessions:
+```
+"List all active NotebookLM sessions"
+"Close inactive sessions to free resources"
+"Reset the stuck session for notebook X"
+```
+
+## Complex Workflows
+
+### Multi-Stage Research
+
+For complex implementations requiring multiple knowledge sources:
+
+```
+Stage 1: "Research the API structure in the API notebook"
+Stage 2: "Switch to Architecture notebook and research the service patterns"
+Stage 3: "Use the Security notebook to research authentication requirements"
+Stage 4: "Synthesize all findings into implementation plan"
+```
+
+### Validation Workflow
+
+Cross-reference information across notebooks:
+
+```
+1. "In Production notebook, find the current API version"
+2. "Switch to Migration notebook, check compatibility notes"
+3. "Verify in Architecture notebook if this aligns with our patterns"
+```
+
+## Tool Integration Patterns
+
+### Direct Tool Calls
+
+For manual scripting, capture and reuse session IDs:
+
+```json
+// First call - capture session_id
+{
+  "tool": "ask_question",
+  "question": "What is the webhook structure?",
+  "notebook_id": "abc123"
+}
+
+// Follow-up - reuse session_id
+{
+  "tool": "ask_question",
+  "question": "Show me error handling examples",
+  "session_id": "captured_session_id_here"
+}
+```
+
+### Resource URIs
+
+Access library data programmatically:
+- `notebooklm://library` - Full library JSON
+- `notebooklm://library/{id}` - Specific notebook metadata
+
+## Best Practices
+
+### 1. **Context Preservation**
+- Always let the agent complete its research cycle
+- Don't interrupt between questions in a research session
+- Use descriptive notebook names for easy switching
+
+### 2. **Knowledge Base Quality**
+- Upload comprehensive documentation to NotebookLM
+- Merge related docs into single notebooks (up to 500k words)
+- Update notebooks when documentation changes
+
+### 3. **Error Recovery**
+- The server auto-recovers from browser crashes
+- Sessions rebuild automatically if context is lost
+- Profile corruption triggers automatic cleanup
+
+### 4. **Resource Management**
+- Close unused sessions to free memory
+- The server maintains max 10 concurrent sessions
+- Inactive sessions auto-close after 15 minutes
+
+### 5. **Security Considerations**
+- Use dedicated Google accounts for NotebookLM
+- Never share authentication profiles between projects
+- Backup `library.json` for important notebook collections
+
+## Troubleshooting Patterns
+
+### When NotebookLM returns incomplete answers
+```
+"The answer seems incomplete. Ask NotebookLM for more specific details about [topic]"
+```
+
+### When hitting rate limits
+```
+"We've hit the rate limit. Re-authenticate with the backup account"
+```
+
+### When browser seems stuck
+```
+"Reset all NotebookLM sessions and try again"
+```
+
+## Example Conversations
+
+### Complete Feature Implementation
+```
+User: "I need to implement a webhook system with retry logic"
+
+You: "Research webhook patterns with retry logic in NotebookLM first"
+Agent: [Researches comprehensively, asking 4-5 follow-up questions]
+Agent: "Based on my research, here's the implementation..."
+[Provides detailed code with patterns from NotebookLM]
+```
+
+### Architecture Decision
+```
+User: "Should we use microservices or monolith for this feature?"
+
+You: "Research our architecture patterns and decision criteria in the Architecture notebook"
+Agent: [Gathers context about existing patterns, scalability needs, team constraints]
+Agent: "According to our architecture guidelines..."
+[Provides recommendation based on documented patterns]
+```
+
+---
+
+Remember: The power of this integration lies in letting your agent **ask multiple questions** – gathering context and building comprehensive understanding before responding. Don't rush the research phase!

package/docs/05_project-analysis.qmd

@@ -0,0 +1,309 @@
+---
+title: "NotebookLM MCP 프로젝트 분석 보고서"
+author: "Antigravity AI"
+date: "2026-01-02"
+format:
+  html:
+    toc: true
+    toc-depth: 3
+    number-sections: true
+---
+
+# 프로젝트 개요
+
+NotebookLM MCP는 Google NotebookLM을 MCP(Model Context Protocol) 서버로 통합하여 Claude와 같은 AI 에이전트가 NotebookLM의 RAG(Retrieval-Augmented Generation) 기능을 활용할 수 있게 해주는 TypeScript 기반 프로젝트입니다.
+
+## 핵심 기능
+
+- **브라우저 자동화**: Patchright(Playwright 포크)를 사용한 헤드리스 브라우저 제어
+- **세션 관리**: 다중 동시 세션 지원, 자동 정리 및 복구
+- **노트북 라이브러리**: 다중 NotebookLM 노트북 관리
+- **MCP 통합**: 표준 MCP 프로토콜을 통한 도구 및 리소스 노출
+- **스텔스 기능**: 봇 탐지 회피를 위한 휴먼 타이핑 시뮬레이션
+
+---
+
+# 프로젝트 강점
+
+## 아키텍처 설계
+
+::: {.callout-tip}
+### 잘 설계된 모듈 구조
+프로젝트는 관심사 분리(Separation of Concerns)를 잘 따르고 있습니다.
+:::
+
+| 모듈 | 책임 |
+|------|------|
+| `auth/` | 인증 관리 (로그인, 쿠키, 상태 저장) |
+| `library/` | 노트북 라이브러리 CRUD |
+| `session/` | 브라우저 세션 생명주기 |
+| `tools/` | MCP 도구 정의 및 핸들러 |
+| `resources/` | MCP 리소스 핸들러 |
+| `utils/` | 재사용 유틸리티 |
+
+## 코드 품질
+
+1. **TypeScript 전면 도입**: 타입 안전성 확보
+2. **포괄적인 에러 처리**: try-catch 블록과 사용자 친화적 메시지
+3. **자동 복구 로직**: 브라우저/세션 충돌 시 자동 재연결
+4. **상세한 로깅**: 디버깅을 위한 색상 구분 로그
+
+## 사용자 경험
+
+- **설정 불필요**: 환경 변수나 도구 파라미터로 런타임 구성
+- **크로스 플랫폼**: Linux, macOS, Windows 지원 (`env-paths` 활용)
+- **포괄적인 문서화**: 설정, 도구, 트러블슈팅, 사용 가이드 제공
+
+---
+
+# 발견된 문제점
+
+## 심각도: 높음 (Critical)
+
+### 1. 하드코딩된 독일어 셀렉터
+
+::: {.callout-warning}
+### 국제화 문제
+일부 셀렉터가 독일어로 하드코딩되어 다른 언어 사용자에게 작동하지 않습니다.
+:::
+
+**위치**: `src/session/browser-session.ts:2504`, `src/auth/auth-manager.ts:1130-1134`
+
+```typescript
+// 문제점: 독일어 aria-label 하드코딩
+await this.page.waitForSelector('textarea[aria-label="Feld für Anfragen"]', {
+  timeout: 5000,
+  state: "visible",
+});
+```
+
+**개선안**: 다국어 셀렉터 배열 또는 언어 독립적 셀렉터 사용
+
+```typescript
+const localizedLabels = [
+  "Enter your question",  // 영어
+  "Feld für Anfragen",    // 독일어
+  "質問を入力", // 일본어
+  // ...
+];
+```
+
+### 2. 동기적 `require()` 사용
+
+**위치**: `src/utils/settings-manager.ts:7101-7102`
+
+```typescript
+// 문제점: ESM 프로젝트에서 require() 사용
+const fsSync = require("fs");
+const data = fsSync.readFileSync(this.settingsPath, "utf-8");
+```
+
+**개선안**: ESM 호환 동기 import 또는 비동기 초기화 패턴 사용
+
+```typescript
+import { readFileSync } from "fs";
+```
+
+### 3. `@ts-expect-error` 남용
+
+여러 파일에서 타입 억제를 과도하게 사용하고 있습니다:
+
+- `src/auth/auth-manager.ts`: sessionStorage 접근
+- `src/session/browser-session.ts`: 브라우저 컨텍스트 평가
+- `src/utils/stealth-utils.ts`: 윈도우 객체 접근
+
+**개선안**: 브라우저 컨텍스트를 위한 적절한 타입 정의 생성
+
+---
+
+## 심각도: 중간 (Medium)
+
+### 4. 멀티 인스턴스 복구 전략 미흡
+
+`SharedContextManager`에서 프로필 잠금 충돌 시 isolated 프로필로 대체하지만, 인증 상태가 불완전하게 복제될 수 있습니다.
+
+### 5. 하드코딩된 타임아웃 값
+
+**위치**: 다수의 파일
+
+```typescript
+await page.waitForTimeout(2000);  // 매직 넘버
+timeout: 10000,  // 설정에서 가져오지 않음
+```
+
+**개선안**: `CONFIG` 객체에서 일관되게 타임아웃 로드
+
+### 6. 불완전한 Rate Limit 처리
+
+Rate limit 감지는 존재하지만, 재시도 로직이나 백오프 전략이 없습니다.
+
+**개선안**:
+
+```typescript
+class RateLimitHandler {
+  private retryCount = 0;
+  private maxRetries = 3;
+  
+  async executeWithRetry<T>(fn: () => Promise<T>): Promise<T> {
+    try {
+      return await fn();
+    } catch (e) {
+      if (e instanceof RateLimitError && this.retryCount < this.maxRetries) {
+        await this.exponentialBackoff();
+        return this.executeWithRetry(fn);
+      }
+      throw e;
+    }
+  }
+}
+```
+
+### 7. 테스트 부재
+
+프로젝트에 테스트 파일이 없습니다. `package.json`에 테스트 스크립트가 정의되어 있지 않습니다.
+
+---
+
+## 심각도: 낮음 (Low)
+
+### 8. 중복 코드
+
+세션 초기화와 복구 로직이 여러 곳에서 반복됩니다:
+
+- `BrowserSession.init()`
+- `BrowserSession.ask()` 내부의 복구 로직
+- `BrowserSession.reset()`
+
+**개선안**: 공통 복구 유틸리티 함수 추출
+
+### 9. 마법 문자열 (Magic Strings)
+
+셀렉터, URL, 에러 메시지 등이 코드 전반에 분산되어 있습니다.
+
+**개선안**: 상수 파일로 집중화
+
+```typescript
+// src/constants.ts
+export const SELECTORS = {
+  CHAT_INPUT: "textarea.query-box-input",
+  THINKING_MESSAGE: "div.thinking-message",
+  // ...
+};
+```
+
+### 10. 불필요한 `void` 연산자
+
+**위치**: `src/session/browser-session.ts:2527`
+
+```typescript
+void this.page.url();  // 불필요한 void
+```
+
+---
+
+# 보안 고려사항
+
+## 주의 필요
+
+::: {.callout-caution}
+### 자격 증명 로깅
+비밀번호는 마스킹되어 있지만, 이메일 주소가 부분적으로 로그에 노출됩니다.
+:::
+
+```typescript
+// 현재 구현
+private maskEmail(email: string): string {
+  return `${name[0]}${"*".repeat(name.length - 2)}${name[name.length - 1]}@${domain}`;
+}
+// 결과: j***k@gmail.com (도메인 노출)
+```
+
+## 권장 사항
+
+1. **민감 정보 로깅 검토**: 프로덕션에서 이메일 도메인도 마스킹
+2. **브라우저 프로필 암호화**: 저장된 쿠키/세션 데이터 암호화 고려
+3. **환경 변수 검증**: 민감한 환경 변수 형식 검증 강화
+
+---
+
+# 개선 권장사항
+
+## 우선순위 1: 즉시 개선
+
+| 항목 | 설명 | 예상 공수 |
+|------|------|----------|
+| 다국어 셀렉터 | 언어 독립적 UI 셀렉터 적용 | 2-3시간 |
+| ESM 호환성 | `require()` 제거 | 1시간 |
+| 상수 추출 | 매직 넘버/문자열 중앙화 | 3-4시간 |
+
+## 우선순위 2: 단기 개선
+
+| 항목 | 설명 | 예상 공수 |
+|------|------|----------|
+| 단위 테스트 추가 | Jest/Vitest 설정 및 핵심 모듈 테스트 | 1-2일 |
+| Rate Limit 백오프 | 지수 백오프 재시도 로직 | 3-4시간 |
+| 타입 정의 개선 | `@ts-expect-error` 제거 | 2-3시간 |
+
+## 우선순위 3: 장기 개선
+
+| 항목 | 설명 |
+|------|------|
+| E2E 테스트 | Playwright를 활용한 통합 테스트 |
+| 메트릭 수집 | 사용량 통계 및 성능 모니터링 |
+| 플러그인 아키텍처 | 다른 서비스 확장 가능 구조 |
+
+---
+
+# 코드 품질 메트릭
+
+## 파일 구조 분석
+
+```
+src/
+├── auth/           # 1 파일, ~1,100 줄
+├── library/        # 2 파일, ~400 줄
+├── resources/      # 1 파일, ~250 줄
+├── session/        # 3 파일, ~1,200 줄
+├── tools/          # 5 파일, ~1,500 줄
+├── utils/          # 6 파일, ~1,600 줄
+├── config.ts       # ~200 줄
+├── errors.ts       # 에러 정의
+├── index.ts        # 진입점
+└── types.ts        # 공통 타입
+```
+
+## 복잡도 영역
+
+| 파일 | 복잡도 | 비고 |
+|------|--------|------|
+| `browser-session.ts` | 높음 | 다중 상태 관리, 복구 로직 |
+| `auth-manager.ts` | 높음 | 다양한 인증 시나리오 처리 |
+| `cleanup-manager.ts` | 중간 | 플랫폼별 경로 처리 |
+| `handlers.ts` | 중간 | 다수의 도구 핸들러 |
+
+---
+
+# 결론
+
+NotebookLM MCP는 전반적으로 **잘 설계되고 구현된 프로젝트**입니다. 모듈화된 아키텍처, 포괄적인 에러 처리, 자동 복구 메커니즘 등 프로덕션 수준의 품질을 갖추고 있습니다.
+
+그러나 몇 가지 개선이 필요합니다:
+
+1. **국제화**: 독일어 하드코딩 제거
+2. **테스트**: 테스트 커버리지 추가
+3. **코드 품질**: 타입 억제 제거, 상수 추출
+
+이러한 개선을 통해 더욱 안정적이고 유지보수 가능한 프로젝트가 될 것입니다.
+
+---
+
+# 부록: 파일별 주요 이슈 요약
+
+| 파일 | 이슈 | 심각도 |
+|------|------|--------|
+| `browser-session.ts` | 독일어 셀렉터, void 연산자 | 높음/낮음 |
+| `auth-manager.ts` | 독일어 버튼 텍스트 | 높음 |
+| `settings-manager.ts` | require() 사용 | 높음 |
+| `handlers.ts` | any 타입 사용 | 중간 |
+| `cleanup-manager.ts` | 플랫폼 특정 로직 중복 | 낮음 |
+| 전체 | 테스트 부재 | 중간 |