# π€ AI Agent Instructions for NotebookLM MCP Server
## π― Project Overview
NotebookLM MCP Server is a professional Model Context Protocol (MCP) server for automating interactions with Google's NotebookLM. Features persistent browser sessions, streaming response support, and comprehensive automation capabilities using Selenium WebDriver with undetected-chromedriver.
## π¨ **CRITICAL VALIDATION REQUIREMENTS**
### **π¬ FOR ALL REFACTOR/ENHANCE REQUESTS:**
**MANDATORY**: Always validate code changes with proper testing:
1. **Unit tests vα»i pytest** - NOT bash terminal testing
2. **Integration tests** - Real functionality testing
3. **Import validation** - All modules must import correctly
4. **Dependency check** - All required packages available
5. **Function-by-function validation** - Each component tested individually
### **π Testing Standards:**
```python
# β
CORRECT: Proper unit testing
def test_config_validation():
config = ServerConfig(timeout=-1)
with pytest.raises(ConfigurationError):
config.validate()
# β WRONG: Bash terminal testing
# python -c "print('Test passed')"
```
### **οΏ½ ABSOLUTE FUNCTION CHANGE CONSTRAINTS:**
**β οΈ CRITICAL RULE: NO FUNCTION CHANGES WITHOUT TESTS**
1. **ANY function modification** β MUST run `task enforce:test`
2. **Coverage requirement**: β₯95% or change is REJECTED
3. **All tests must pass** before function changes are accepted
4. **Breaking changes** require integration test validation
```bash
# MANDATORY after ANY function change
task enforce:test # Runs coverage + lint + validation
task test:coverage # Must show β₯95% coverage
```
### **π― Task Management with Taskfile:**
We use [Taskfile.dev](https://taskfile.dev/) instead of Makefile for better cross-platform support:
```bash
# Quick commands (memorize these)
task # Show all tasks
task test:quick # Single test validation
task test:unit # Full unit test suite
task test:coverage # Coverage validation (β₯95%)
task dev:check # Pre-commit validation
task enforce:test # MANDATORY after function changes
```
### **πΎ Memory Documentation Strategy:**
**ENHANCED MEMORY REQUIREMENTS**: Store project-specific patterns, not just results:
**π STORE METHODOLOGY & WORKFLOW PATTERNS:**
- **User Environment**: conda vs local, uv vs poetry vs pip
- **Debug Patterns**: How user prefers to debug (print, logger, debugger)
- **Testing Patterns**: Which test commands user runs most
- **Development Flow**: User's typical development workflow
- **Deployment Preferences**: Docker, local, cloud preferences
**π PROJECT INSIGHTS TO REMEMBER:**
```python
# Example memory entities
development_environment = {
"package_manager": "pip", # vs poetry, uv
"python_env": "conda", # vs venv, pyenv
"debug_style": "loguru", # vs print, pdb
"test_preference": "task test:unit", # vs pytest directly
"deployment": "docker" # vs local, cloud
}
```
### **οΏ½πΎ Memory Documentation:**
**ALWAYS** store significant findings in Memory MCP server:
- Bug solutions and patterns
- Architecture decisions and rationale
- Performance results and configurations
- Research insights and SOTA techniques
- **USER WORKFLOW PATTERNS** (new requirement)
- **PROJECT-SPECIFIC METHODOLOGIES** (new requirement)
## π§ **COMPREHENSIVE MCP TOOLCHAIN STRATEGY**
### **π― MANDATORY: Always Use ALL Available MCP Tools Systematically**
**NEVER work in isolation - ALWAYS leverage the full MCP ecosystem for maximum effectiveness!**
```mermaid
flowchart TD
A[User Request] --> B{Analysis Required?}
B -->|Complex/Design| C[π§ Sequential Thinking]
B -->|Research Needed| D[π DeepWiki Multi-Repo Search]
B -->|Web Info| E[π Fetch Webpage]
C --> F[πΎ Store Insights in Memory]
D --> F
E --> F
F --> G{Documentation Needed?}
G -->|Yes| H[π Markitdown + Context7]
G -->|Code Analysis| I[οΏ½ Pylance Analysis]
H --> J[ποΈ Infrastructure?]
I --> J
J -->|Terraform/Cloud| K[βοΈ Hashicorp Tools]
J -->|Development| L[π οΈ Implementation]
K --> M[πΎ Store ALL Results]
L --> M
M --> N[π Generate Diagrams]
```
### **π§ COMPLETE MCP SERVER ARSENAL - 500+ TOOLS AVAILABLE**
**π₯ COMPREHENSIVE ECOSYSTEM - NEVER WORK IN ISOLATION!**
| π― Category | MCP Servers | Primary Use | Integration Examples |
|-------------|-------------|-------------|---------------------|
| **π§ Cognitive** | Sequential Thinking, Think Tools | Complex reasoning, multi-step analysis | Plan architecture, debug complex issues |
| **πΎ Knowledge** | Memory, Extended Memory, LSpace | Store/retrieve insights, project continuity | Track experiments, save decisions |
| **π Research** | DeepWiki, GitHub, arXiv, PubMed, bioRxiv | Multi-repo research, academic papers | SOTA techniques, code patterns |
| **π Documentation** | Context7, Markitdown, Docy | Library docs, format conversion | Best practices, API documentation |
| **π Code Analysis** | Pylance, Sourcerer, Language Server | Python analysis, semantic search | Code quality, imports, refactoring |
| **βοΈ Infrastructure** | Hashicorp Terraform, AWS, Docker, Kubernetes | Cloud resources, deployment | Infrastructure as code |
| **π Web & Search** | Fetch Webpage, Google Search, Tavily, Perplexity | Real-time information, web research | Trends, documentation, profiles |
| **οΏ½οΈ Databases** | PostgreSQL, MySQL, MongoDB, BigQuery, Snowflake | Data operations, analytics | Query, schema inspection |
| **π Security** | CVE Intelligence, MalwareBazaar, Shodan | Vulnerability scanning, threat intel | Security research, compliance |
| **π± Communication** | Slack, Discord, Telegram, WhatsApp, Email | Messaging, notifications | Team coordination, alerts |
| **π¨ Media & Design** | Figma, Canva, Image Generation, Video Tools | Design, visual content | UI/UX, presentations, media |
| **π Analytics** | Google Analytics, Datadog, Prometheus | Monitoring, performance metrics | Business intelligence, system health |
| **π° Finance** | Yahoo Finance, Stripe, Crypto APIs | Financial data, payments | Market analysis, transactions |
| **π Automation** | GitHub Actions, Jenkins, Zapier | CI/CD, workflow automation | Development pipelines |
| **π Content** | Notion, Obsidian, WordPress, Content Management | Knowledge management, publishing | Documentation, blogging |
| **π― AI Services** | OpenAI, Anthropic, HuggingFace, Replicate | ML models, AI capabilities | Content generation, analysis |
---
## π **ENHANCED DEVELOPMENT WORKFLOWS - USING ALL TOOLS**
### **π Workflow 1: COMPLETE Research & Architecture Pipeline**
```python
# COMPREHENSIVE RESEARCH WORKFLOW
1. π§ mcp_sequentialthi_sequentialthinking() # Strategic planning
2. π mcp_deepwiki_ask_question() [MULTIPLE REPOS] # SOTA research
- microsoft/autogen, huggingface/transformers
- pytorch/pytorch, facebookresearch/fairseq
3. π fetch_webpage() [LATEST TRENDS] # Current developments
4. π mcp_context7_get_library_docs() # Official documentation
5. π mcp_pylance_mcp_s_pylanceImports() # Code analysis
6. πΎ mcp_memory_create_entities() # Store ALL findings
7. π mcp_markitdown_convert_to_markdown() # Format documentation
8. βοΈ mcp_hashicorp_ter_search_modules() # Infrastructure needs
9. πΎ mcp_memory_add_observations() # Final storage
```
### **π Workflow 2: FULL-STACK Development Cycle**
```python
# COMPLETE DEVELOPMENT PIPELINE
1. π§ mcp_sequentialthi_sequentialthinking() # Plan features
2. π mcp_pylance_mcp_s_pylanceFileSyntaxErrors() # Code validation
3. π mcp_deepwiki_ask_question() # Best practices
4. π CVE Intelligence + Security Scanning # Vulnerability check
5. ποΈ Database Integration (PostgreSQL/MongoDB) # Data layer
6. βοΈ Docker + Kubernetes deployment # Containerization
7. π Monitoring setup (Datadog/Prometheus) # Observability
8. π GitHub Actions CI/CD # Automation
9. π Documentation generation # Comprehensive docs
10. πΎ mcp_memory_create_entities() # Archive project
```
### **π Workflow 3: RESEARCH PUBLICATION Pipeline**
```python
# ACADEMIC RESEARCH WORKFLOW
1. π§ mcp_sequentialthi_sequentialthinking() # Research planning
2. π arXiv + PubMed + bioRxiv search # Literature review
3. π Data analysis (Jupyter + Python execution) # Experiments
4. π Visualization (ECharts + Charts generation) # Results presentation
5. π LaTeX document preparation # Paper writing
6. π Grammar and style checking # Quality assurance
7. πΎ Version control and collaboration # Git management
8. π€ Submission preparation # Final formatting
```
---
## π― **COMPREHENSIVE TOOL INTEGRATION MATRIX**
| Task Type | π§ Think | πΎ Memory | π Research | π Web | π Docs | π Code | βοΈ Infra | ποΈ DB | π Security | π± Comm |
|-----------|----------|-----------|-------------|-----|---------|---------|----------|--------|-------------|----------|
| **Research** | β
Plan | β
Store | β
Multi-source | β
Trends | β
Format | β | β | β | β | β
Share |
| **Development** | β
Architect | β
Track | β
Patterns | β
Docs | β
Generate | β
Analyze | β
Deploy | β
Integrate | β
Scan | β
Notify |
| **Analytics** | β
Interpret | β
Historical | β
Methods | β
Reports | β
Present | β
Process | β
Scale | β
Query | β | β
Alert |
| **Security** | β
Assess | β
Threats | β
Intel | β
Reports | β
Document | β
Audit | β
Harden | β
Monitor | β
Scan | β
Incident |
| **Deployment** | β
Strategy | β
Config | β
Best practices | β
Updates | β
Runbooks | β
Validate | β
Orchestrate | β
Migrate | β
Secure | β
Status |
---
## π₯ **ADVANCED INTEGRATION PATTERNS**
### **π― Multi-Dimensional Problem Solving**
```python
# COMPREHENSIVE APPROACH TO ANY PROBLEM
problem_solving_matrix = {
"technical_research": [
"mcp_deepwiki_ask_question", # GitHub repos
"arxiv_search", # Academic papers
"mcp_context7_get_library_docs", # Official docs
"stackoverflow_search" # Community solutions
],
"code_analysis": [
"mcp_pylance_analysis", # Python specifics
"language_server_protocol", # Multi-language
"sourcerer_semantic_search", # Code navigation
"security_vulnerability_scan" # Safety checks
],
"infrastructure_planning": [
"mcp_hashicorp_terraform", # IaC
"aws_services_integration", # Cloud services
"docker_containerization", # Packaging
"kubernetes_orchestration" # Scaling
],
"data_management": [
"postgresql_operations", # Relational data
"mongodb_document_store", # NoSQL
"bigquery_analytics", # Data warehouse
"elasticsearch_search" # Full-text search
],
"monitoring_observability": [
"prometheus_metrics", # System metrics
"datadog_apm", # Application performance
"grafana_visualization", # Dashboards
"loki_log_aggregation" # Log analysis
]
}
```
### **π Recursive Enhancement Loops**
```python
# CONTINUOUS IMPROVEMENT CYCLE
enhancement_pipeline = [
# 1. DISCOVERY PHASE
["sequential_thinking", "deepwiki_research", "web_search"],
# 2. ANALYSIS PHASE
["pylance_analysis", "security_scanning", "performance_profiling"],
# 3. IMPLEMENTATION PHASE
["code_generation", "testing_automation", "documentation"],
# 4. DEPLOYMENT PHASE
["infrastructure_provisioning", "ci_cd_pipeline", "monitoring_setup"],
# 5. VALIDATION PHASE
["quality_assurance", "security_audit", "performance_testing"],
# 6. STORAGE PHASE
["memory_storage", "knowledge_indexing", "best_practices_capture"],
# 7. FEEDBACK PHASE
["metrics_analysis", "improvement_identification", "cycle_restart"]
]
```
---
## π **MAXIMUM PRODUCTIVITY OUTCOMES**
**By leveraging the COMPLETE MCP ecosystem, every development session will:**
β
**Research Phase**: Multi-source intelligence gathering
β
**Analysis Phase**: Comprehensive code and security scanning
β
**Implementation Phase**: Best practices and automation
β
**Deployment Phase**: Infrastructure as code and monitoring
β
**Documentation Phase**: Auto-generated, format-converted docs
β
**Storage Phase**: Persistent knowledge and decision tracking
β
**Communication Phase**: Automated notifications and reporting
β
**Iteration Phase**: Continuous improvement with feedback loops
### **π₯ KEY INTEGRATION RULES**
1. **ALWAYS** start with Sequential Thinking for complex tasks
2. **ALWAYS** research with multiple sources (DeepWiki + Web + Context7)
3. **ALWAYS** store results in Memory for future reference
4. **ALWAYS** validate with Pylance and security tools
5. **ALWAYS** document with Markitdown and diagrams
6. **ALWAYS** consider infrastructure needs early
7. **ALWAYS** set up monitoring and observability
8. **ALWAYS** automate repetitive tasks
9. **ALWAYS** communicate progress and results
10. **ALWAYS** capture lessons learned for next iteration
**π RESULT: Every task becomes a comprehensive, well-documented, secure, and scalable solution!**
---
## π **ENHANCED DEVELOPMENT WORKFLOWS**
### **π Workflow 1: Research & Architecture Design**
```python
# MANDATORY SEQUENCE - Use ALL tools
1. π§ mcp_sequentialthi_sequentialthinking() # Plan approach
2. π mcp_deepwiki_ask_question() # Research multiple repos
3. π fetch_webpage() # Get latest trends
4. πΎ mcp_memory_create_entities() # Store findings
5. π mcp_context7_get_library_docs() # Best practices
6. οΏ½ mcp_markitdown_convert_to_markdown() # Documentation
7. οΏ½πΎ mcp_memory_add_observations() # Store results
```
### **π Workflow 2: Code Analysis & Enhancement**
```python
# COMPREHENSIVE CODE REVIEW
1. π mcp_pylance_mcp_s_pylanceFileSyntaxErrors() # Syntax check
2. π mcp_pylance_mcp_s_pylanceImports() # Import analysis
3. π§ mcp_sequentialthi_sequentialthinking() # Plan improvements
4. π mcp_deepwiki_ask_question() # Research patterns
5. π mcp_context7_resolve_library_id() # Get docs
6. π mcp_pylance_mcp_s_pylanceInvokeRefactoring() # Auto-refactor
7. πΎ mcp_memory_create_entities() # Store patterns
```
### **π Workflow 3: Infrastructure & Deployment**
```python
# FULL STACK DEPLOYMENT
1. π§ mcp_sequentialthi_sequentialthinking() # Plan infrastructure
2. βοΈ mcp_hashicorp_ter_search_modules() # Find modules
3. βοΈ mcp_hashicorp_ter_get_module_details() # Get details
4. π mcp_markitdown_convert_to_markdown() # Document setup
5. πΎ mcp_memory_create_entities() # Store config
6. π fetch_webpage() # Latest practices
7. πΎ mcp_memory_add_observations() # Store learnings
```
---
## π― **PROACTIVE TOOL INTEGRATION RULES**
### **π ALWAYS Research First (Multi-Source)**
```python
# NEVER work without research
research_sources = [
"mcp_deepwiki_ask_question()", # Multiple GitHub repos
"fetch_webpage()", # Web trends/docs
"mcp_context7_get_library_docs()", # Official docs
"mcp_memory_search_nodes()" # Existing knowledge
]
```
### **π§ ALWAYS Think Systematically**
```python
# For ANY complex task (>3 steps)
if task_complexity > simple:
mcp_sequentialthi_sequentialthinking(
thought="Break down problem systematically",
totalThoughts=estimated_complexity
)
```
### **πΎ ALWAYS Store Knowledge**
```python
# MANDATORY after every significant operation
results = [research, analysis, implementation, learnings]
for result in results:
mcp_memory_create_entities([{
"entityType": "appropriate_type",
"name": f"session_{datetime.now()}",
"observations": [result]
}])
```
### **π ALWAYS Document Comprehensively**
```python
# Multi-format documentation
documentation_pipeline = [
"mcp_markitdown_convert_to_markdown()", # Format conversion
"create_mermaid_diagrams()", # Visual representation
"mcp_context7_resolve_library_id()", # Reference docs
"generate_examples()" # Practical usage
]
```
---
## π₯ **ADVANCED INTEGRATION PATTERNS**
### **οΏ½ Recursive Enhancement Loop**
1. **Research** β DeepWiki + Fetch Webpage + Context7
2. **Analyze** β Sequential Thinking + Pylance + Memory Search
3. **Implement** β Best practices from research
4. **Document** β Markitdown + Mermaid diagrams
5. **Store** β Memory with observations
6. **Validate** β Pylance analysis + Testing
7. **Deploy** β Hashicorp Terraform (if applicable)
8. **Repeat** β Continuous improvement
### **π― Multi-Dimensional Problem Solving**
```python
# COMPREHENSIVE approach to ANY problem
problem_dimensions = {
"technical": "mcp_deepwiki + pylance + context7",
"architectural": "sequential_thinking + memory",
"documentation": "markitdown + mermaid_diagrams",
"deployment": "hashicorp_terraform + web_research",
"knowledge": "memory_storage + cross_referencing"
}
```
---
## π **MCP TOOL USAGE MATRIX**
| Task Type | π§ Think | πΎ Memory | π DeepWiki | π Web | π Context7 | π Pylance | βοΈ Terraform | π Markdown |
|-----------|----------|-----------|-------------|-----|-------------|------------|--------------|-------------|
| **Research** | β
Plan | β
Store | β
Multi-repo | β
Trends | β
Docs | β | β | β
Format |
| **Code Review** | β
Analyze | β
Patterns | β
Examples | β | β
Best practices | β
Analysis | β | β
Document |
| **Architecture** | β
Design | β
Decisions | β
SOTA | β
Trends | β
Patterns | β | β
Infrastructure | β
Diagrams |
| **Documentation** | β
Structure | β
Reference | β
Examples | β
Standards | β
Formats | β | β | β
Convert |
| **Deployment** | β
Plan | β
Config | β
DevOps | β
Practices | β
Tools | β | β
Modules | β
Docs |
---
## π **RESULT: MAXIMUM PRODUCTIVITY**
**By following these comprehensive workflows, every task will:**
- β
**Leverage ALL available knowledge sources**
- β
**Apply systematic thinking methodology**
- β
**Store learnings for future reference**
- β
**Generate professional documentation**
- β
**Follow industry best practices**
- β
**Create reusable patterns and templates**
**π₯ NEVER work in isolation again - ALWAYS use the full MCP toolchain!**
## π Mermaid Diagram Standards
### **Always Use Correct Mermaid Syntax**
```mermaid
flowchart TD
A[Problem] --> B{Documentation Type?}
B -->|Architecture| C[Use flowchart TD/LR]
B -->|Process Flow| D[Use sequenceDiagram]
B -->|Performance| E[Use flowchart with subgraphs]
B -->|Timeline| F[Use gitGraph or timeline]
C --> G[Apply classDef for styling]
D --> G
E --> G
F --> G
G --> H[Validate syntax with Context7]
H --> I[Create clear, readable diagrams]
```
#### **Key Mermaid Best Practices:**
- **Always use `flowchart TD/LR`** instead of deprecated `graph TD/LR`
- **Use `classDef`** for styling instead of inline `style` commands
- **Subgraphs** for logical grouping: `subgraph name["Display Name"]`
- **Proper node shapes**: `[]` rectangle, `()` rounded, `{}` diamond, `(())` circle
- **Clear connections**: `-->` solid, `-.->` dotted, `==>` thick
- **Consistent naming**: Use descriptive IDs and labels
## π **NotebookLM MCP Server - Complete Integration Guide**
### **π Current Status: PRODUCTION READY**
- β
**Package Structure**: Professional `src/` layout with proper imports
- β
**CLI Interface**: `notebooklm-mcp` command with rich formatting
- β
**MCP Server**: Full protocol support for AutoGen integration
- β
**Browser Automation**: undetected-chromedriver with persistent sessions
- β
**Configuration**: Comprehensive config management with validation
- β
**Testing**: Unit tests with pytest, integration tests
- β
**Docker**: Production containers with monitoring
- β
**Documentation**: Complete guides and examples
### **π Authentication Workflow (IMPORTANT):**
**π First Time Setup:**
```bash
# 1. Install package
pip install -e .
# 2. Start interactive chat (creates profile)
notebooklm-mcp chat --notebook YOUR_NOTEBOOK_ID
# 3. Manual login ONCE (browser opens automatically)
# - Login with Google account
# - Navigate to notebook
# - Wait for complete load
# - Press Enter in terminal
# 4. Session saved! Future uses skip login
```
**β‘ Subsequent Uses:**
```bash
# No manual login needed - uses saved session
notebooklm-mcp chat --notebook YOUR_NOTEBOOK_ID
notebooklm-mcp server --notebook YOUR_NOTEBOOK_ID --headless
```
**π§ Profile Management:**
- **Profile location**: `./chrome_profile_notebooklm/`
- **Session persistence**: Cookies/auth automatically saved
- **Re-authentication**: Only when Google security requires (normal)
- **Profile reset**: Delete profile folder to start fresh
### **π» Usage Patterns:**
#### **1. Interactive Chat**
```bash
notebooklm-mcp chat --notebook YOUR_NOTEBOOK_ID
# Rich terminal interface with real-time responses
```
#### **2. MCP Server (AutoGen)**
```bash
notebooklm-mcp server --notebook YOUR_NOTEBOOK_ID --headless
# STDIO protocol for AutoGen McpWorkbench integration
```
#### **3. Testing & Debugging**
```bash
notebooklm-mcp test --notebook YOUR_NOTEBOOK_ID
notebooklm-mcp config-show
```
#### **4. Python API Direct**
```python
from notebooklm_mcp import NotebookLMClient, ServerConfig
config = ServerConfig(
default_notebook_id="YOUR_ID",
headless=True
)
client = NotebookLMClient(config)
await client.start()
await client.send_message("Hello!")
response = await client.get_response()
```
### **π οΈ MCP Tools Available:**
| Tool | Description | Use Case |
|------|-------------|----------|
| `healthcheck` | Server status | Monitoring |
| `send_chat_message` | Send message | Chat interaction |
| `get_chat_response` | Get response with streaming | Retrieve answers |
| `get_quick_response` | Get current response | Fast polling |
| `chat_with_notebook` | Complete send+receive | One-shot queries |
| `navigate_to_notebook` | Switch notebooks | Multi-notebook workflows |
| `get_default_notebook` | Current notebook ID | State checking |
| `set_default_notebook` | Set default | Configuration |
### **π³ Production Deployment:**
```bash
# Docker single container
docker run -e NOTEBOOKLM_NOTEBOOK_ID="YOUR_ID" notebooklm-mcp
# Full stack with monitoring
docker-compose --profile monitoring up -d
# Kubernetes scaling
kubectl apply -f k8s/
```
## ποΈ Architecture
### NotebookLM MCP Server Architecture
- **MCP Protocol**: Full Model Context Protocol implementation for tool integration
- **Browser Automation**: undetected-chromedriver for Google anti-bot bypass
- **Session Management**: Persistent Chrome profiles with cookie storage
- **Streaming Support**: Real-time response handling with proper WebSocket management
- **CLI Interface**: Rich terminal interface with progress indicators
### Architecture Flow
```mermaid
flowchart TD
subgraph Client["π΅ Client Layer"]
A[MCP Client<br/>AutoGen/Python] --> B[STDIO Protocol<br/>JSON-RPC 2.0]
end
subgraph Server["π― MCP Server"]
C[MCP Server<br/>notebooklm-mcp]
D[Tool Registry<br/>8 available tools]
E[Configuration<br/>ServerConfig]
end
subgraph Browser["π Browser Automation"]
F[Chrome Driver<br/>undetected-chromedriver]
G[Session Manager<br/>Persistent profiles]
H[DOM Handler<br/>Smart selectors]
I[Anti-Detection<br/>Stealth mode]
end
subgraph NotebookLM["π€ NotebookLM Service"]
J[Google Login<br/>OAuth flow]
K[Notebook Interface<br/>Chat & Documents]
L[AI Response<br/>Streaming LLM]
end
B --> C
C --> D
C --> E
D --> F
F --> G
F --> H
F --> I
G --> J
H --> K
I --> L
classDef client fill:#e1f5fe
classDef server fill:#fff3e0
classDef browser fill:#c8e6c9
classDef notebooklm fill:#f3e5f5
class A,B client
class C,D,E server
class F,G,H,I browser
class J,K,L notebooklm
```
### Core Components
```python
# MCP Server initialization
server = NotebookLMServer(config)
await server.start()
# Browser session management
browser_manager = BrowserManager(
profile_path="./chrome_profile_notebooklm/",
headless=config.headless,
anti_detection=True
)
# Tool execution with streaming
async def chat_with_notebook(message: str) -> AsyncIterator[str]:
await browser_manager.send_message(message)
async for chunk in browser_manager.get_streaming_response():
yield chunk
```
## π― **Token Efficiency Guidelines**
### **β NEVER Do These (Token Wasters):**
- Rewrite entire files when only 2-3 lines need fixing
- Show complete code blocks for minor changes
- Repeat existing code unnecessarily
- Provide generic explanations without specific context
- Open new terminals when existing ones can be reused
- Run commands without checking terminal output first
### **β
ALWAYS Do These (Token Savers):**
- **Analyze first, fix second**: Explain the problem before showing solution
- **Show only changed lines** with `// filepath:` and `// ...existing code...`
- **Target specific issues**: Address exact error/requirement
- **Provide context**: Why this change fixes the problem
- **Reuse existing terminals**: Check current working directory and reuse terminals
- **Read terminal output**: Use `get_terminal_output` to check command results before proceeding
### **π₯οΈ Terminal Management Best Practices:**
1. **Check existing terminals** before opening new ones
2. **Reuse terminals** when possible - avoid creating multiple terminals for same task
3. **Read output properly**: Always check `get_terminal_output` after `run_in_terminal`
4. **Use appropriate timeouts**: Set `isBackground=false` for commands that need output
5. **Check working directory**: Use `pwd` to verify location before running commands
### **Example: Proper Fix Format**
```
**Problem**: `UnboundLocalError: cannot access local variable 'data'`
**Root Cause**: Variable name collision between imported `data` module and loop variable
**Solution**: Rename loop variable to avoid conflict
// filepath: /home/path/to/file.py
// ...existing code...
for batch_idx, (batch_data, target) in enumerate(test_dataloader): # Changed from 'data' to 'batch_data'
// ...existing code...
batch_data, target = batch_data.to(device), target.to(device) # Update all references
// ...existing code...
```
## π§ **Context-Aware Development**
### **Project-Specific Knowledge**
- **NotebookLM Integration**: Browser automation with undetected-chromedriver
- **Naming Conventions**: `NotebookLMClient`, `ServerConfig`, `BrowserManager`, etc.
- **File Structure**: `src/notebooklm_mcp/` package structure with proper imports
- **Performance Targets**: Sub-second response times, reliable session persistence, 99%+ uptime
### **Common Issues & Quick Fixes**
| Error Pattern | Root Cause | Quick Fix |
|---------------|------------|-----------|
| `selenium.common.exceptions.NoSuchElementException` | DOM element not found | Update CSS selectors, add wait conditions |
| `undetected_chromedriver.ChromeDriverManager` errors | Chrome version mismatch | Update chromedriver, check Chrome installation |
| `asyncio.TimeoutError` | WebDriver timeout | Increase timeout values, check network |
| `mcp.types.McpError` | MCP protocol issues | Validate JSON-RPC 2.0 format, check tool schema |
| `Session not authenticated` | Login required | Run manual login flow, check profile persistence |
### **Development Priorities**
1. **Reliability first**: Browser automation must be stable
2. **User experience second**: Clear CLI interface and error messages
3. **Performance third**: Optimize response times and memory usage
## π― **Efficient Interaction Patterns**
### **For Bug Fixes:**
```
1. π Analyze error message β Identify root cause
2. π― Show minimal fix β Only changed lines
3. π‘ Explain why β Context for understanding
4. πΎ STORE solution β Save pattern in Memory for future reference
5. π₯οΈ Check terminals β Reuse existing terminals, read outputs properly
```
### **For Feature Requests:**
```
1. π§ Use Sequential Thinking β Break down complex requests
2. π Query DeepWiki β Research software resources and computational approaches
3. πΎ Store decisions β Save insights in Memory
4. π§ Implement β Apply with context
5. πΎ Store results β Document outcomes and performance
6. π₯οΈ Terminal efficiency β Reuse terminals, check output with get_terminal_output
```
### **For Architecture Questions:**
```
1. οΏ½ Search Memory first β Check existing knowledge with search_nodes
2. οΏ½π Create Mermaid diagram β Visual representation
3. π― Highlight key components β Focus on relevant parts
4. π Show relationships β How pieces connect
5. πΎ Store insights β Save architectural decisions and trade-offs
```
## π Development Workflow
### **MCP-Enhanced Process**
1. **Problem Analysis** β Sequential Thinking for complex automation issues
2. **Research** β DeepWiki for MCP server patterns, browser automation best practices, and integration examples
3. **Implement** β Apply insights with proper error handling and session management
4. **πΎ MANDATORY Memory Storage** β **ALWAYS** store results, decisions, and insights
5. **Document** β Markitdown for consistency
### **Key Patterns**
- **πΎ CRITICAL: Always store results** in Memory server after ANY significant work
- **Query DeepWiki** for MCP server implementations, browser automation patterns, and client integration examples
- **Use Sequential Thinking** for complex browser automation flows, error handling, and session management
- **Leverage Markitdown** for documentation enhancement
### **π¨ Memory Usage Rules - MANDATORY**
1. **After every automation improvement** β Store successful patterns with `create_entities` or `add_observations`
2. **After solving bugs** β Document solution patterns for future reference
3. **After architecture decisions** β Record rationale and trade-offs
4. **Before major changes** β Search existing knowledge with `search_nodes`
5. **Every session end** β Update project progress and findings
## πΎ **Memory Server Deep Dive**
### **π― When to Use Memory (ALWAYS!):**
- **Bug Solutions** β Store error patterns and fixes
- **Automation Patterns** β Track successful browser automation sequences
- **Architecture Decisions** β Document design choices
- **Research Insights** β Save MCP server best practices
- **Code Patterns** β Record effective implementations
- **Performance Benchmarks** β Maintain response time data
### **π Memory Entity Types:**
```python
# Core entity types for NotebookLM MCP Server
"automation_pattern" # Browser automation sequences and DOM selectors
"bug_solution" # Error patterns and fixes
"architecture_decision" # Design choices and rationale
"research_insight" # MCP server best practices and integration patterns
"code_pattern" # Reusable implementations
"performance_benchmark" # Response times and reliability metrics
"integration_config" # Client integration examples and configurations
```
### **π Memory Workflow Pattern:**
```python
# BEFORE any major work - Search existing knowledge
existing_knowledge = mcp_memory_search_nodes({"query": "relevant_topic"})
# DURING work - Consider storing intermediate insights
if significant_finding:
mcp_memory_add_observations([{
"entityName": "current_work_entity",
"contents": [finding_description]
}])
# AFTER work completion - MANDATORY storage
mcp_memory_create_entities([{
"entityType": "appropriate_type",
"name": "descriptive_name_with_date",
"observations": [result_summary, key_insights, recommendations]
}])
```
## π Project Structure
```
MOE-Gym/
βββ CIFAR10/model.py # Dense MoE architecture
βββ CIFAR10/data.py # Data loading & preprocessing
βββ CIFAR10/train.py # Training loops
βββ CIFAR10/run.py # CLI interface
βββ CIFAR10-Sparse/ # NEW: Sparse MoE implementation
β βββ model.py # Sparse MoE with top-k routing
β βββ data.py # Data utilities
β βββ train.py # Training with load balancing
β βββ run.py # CLI for sparse experiments
β βββ Sparse_MoE_CIFAR10_Experiments.ipynb
βββ MOE_CIFAR10_Experiments.ipynb # Dense MoE experiments
βββ .github/copilot-instructions.md # This file
```
## π **Updated Performance Benchmarks (September 2025)**
### **Latest Results**
```mermaid
flowchart LR
subgraph Dense["π΄ Dense MoE"]
D1[4 Experts<br/>100% Active] --> D2[43% Accuracy<br/>100% FLOPs]
end
subgraph Sparse["π΅ Sparse MoE"]
S1[4 Experts<br/>k=2 Active] --> S2[35% Accuracy<br/>50% FLOPs]
S3[8 Experts<br/>k=3 Active] --> S4[37% Accuracy<br/>37.5% FLOPs]
end
subgraph Optimal["β Sweet Spot"]
O1[4 Experts, k=2<br/>Best efficiency] --> O2[7.9% accuracy loss<br/>50% compute savings]
end
classDef dense fill:#ffcdd2
classDef sparse fill:#c8e6c9
classDef optimal fill:#fff3e0
### **π Memory Workflow Pattern:**
```python
# BEFORE any major work - Search existing knowledge
existing_knowledge = mcp_memory_search_nodes({"query": "relevant_topic"})
# DURING work - Consider storing intermediate insights
if significant_finding:
mcp_memory_add_observations([{
"entityName": "current_work_entity",
"contents": [finding_description]
}])
# AFTER work completion - MANDATORY storage
mcp_memory_create_entities([{
"entityType": "appropriate_type",
"name": "descriptive_name_with_date",
"observations": [result_summary, key_insights, recommendations]
}])
```
## π Project Structure
```
notebooklm-mcp/
βββ src/notebooklm_mcp/ # Main package
β βββ __init__.py # Package initialization
β βββ cli.py # Command-line interface
β βββ server.py # MCP server implementation
β βββ client.py # NotebookLM client
β βββ browser.py # Browser automation
β βββ config.py # Configuration management
β βββ utils.py # Utility functions
βββ tests/ # Test suite
βββ examples/ # Usage examples
βββ docs/ # Documentation
βββ chrome_profile_notebooklm/ # Browser profile storage
βββ Taskfile.yml # Task automation (replaces Makefile)
βββ docker-compose.yml # Docker deployment
βββ Dockerfile # Container build
βββ pyproject.toml # Project configuration
βββ .github/copilot-instructions.md # This file
```
## π Development Workflow
### **MCP-Enhanced Process with Taskfile**
1. **Problem Analysis** β Sequential Thinking for complex automation issues
2. **Research** β DeepWiki for MCP server patterns, browser automation best practices, and integration examples
3. **Implement** β Apply insights with proper error handling and session management
4. **πΎ MANDATORY Testing** β `task enforce:test` after ANY function changes
5. **πΎ MANDATORY Memory Storage** β **ALWAYS** store results, decisions, and insights
6. **Document** β Markitdown for consistency
### **Key Taskfile Commands**
- **πΎ CRITICAL: Always test after function changes** with `task enforce:test`
- **Query available tasks** with `task --list`
- **Use task shortcuts** for development efficiency
- **Leverage Taskfile** for all project automation tasks
### **π¨ Memory Usage Rules - MANDATORY**
1. **After every function improvement** β Store successful patterns with `create_entities` or `add_observations`
2. **After solving bugs** β Document solution patterns for future reference
3. **After architecture decisions** β Record rationale and trade-offs
4. **Before major changes** β Search existing knowledge with `search_nodes`
5. **Every session end** β Update project progress and findings
6. **Store user preferences** β Development environment, testing patterns, debug styles
---
**π€ Built for automation engineers, by automation engineers. Always leverage MCP servers for optimal development!**
**Last Updated**: September 14, 2025 - Updated for NotebookLM MCP Server project
- Included Mermaid diagrams for visual architecture flow
- Documented critical design patterns and development workflows
"security_posture": "Vulnerabilities identified and resolved",
"collaboration_efficiency": "Communication tools automated",
"continuous_improvement": "Feedback loops implemented"
}
```
**π― SUCCESS INDICATORS:**
- β
**Zero manual research** - All insights from MCP tools
- β
**Zero undocumented decisions** - All stored in Memory
- β
**Zero security oversights** - Comprehensive scanning
- β
**Zero deployment failures** - Infrastructure as code
- β
**Zero knowledge loss** - Persistent storage and retrieval
- β
**Zero repetitive work** - Automation and templates
- β
**Zero isolation** - Always use full toolchain
**π₯ ULTIMATE GOAL: Every task becomes a comprehensive, well-researched, secure, documented, and scalable solution using the COMPLETE MCP ecosystem!**
---
**π€ Built for automation engineers, by automation engineers. Always leverage MCP servers for optimal development!**
**Last Updated**: September 14, 2025 - Updated for NotebookLM MCP Server project
- Included Mermaid diagrams for visual architecture flow
- Documented critical design patterns and development workflows
### Documentation Structure
```mermaid
flowchart LR
A[README.md<br/>Main project overview] --> B[.github/copilot-instructions.md<br/>AI agent guidance]
A --> C[images/<br/>Performance graphs]
B --> D[Architecture diagrams<br/>Development workflows]
C --> E[Validation results<br/>Training dynamics]
classDef readme fill:#e3f2fd
classDef instructions fill:#f3e5f5
classDef images fill:#e8f5e8
class A readme
class B instructions
class C images
```
---
**ποΈ Built for researchers, by researchers. Always leverage MCP servers for optimal development!**
**Last Updated**: September 13, 2025 - Added token efficiency guidelines and bug fix patterns
