Fix Issue #8: Add bulletproof setup and prerequisites
Addresses community feedback about missing setup steps. New Documentation: + BULLETPROOF_QUICKSTART.md - Complete beginner guide - Step-by-step Python/Git installation - Every step with expected output - Troubleshooting for each step - Test example (5-page scrape) - 15-30 minute complete setup + TROUBLESHOOTING.md - Comprehensive troubleshooting - Installation issues (Python, pip, permissions) - Runtime issues (file not found, configs) - MCP setup issues (placeholder paths!) - Scraping issues (slow, empty content) - Platform-specific (macOS/Linux/Windows) - Verification commands Setup Script Improvements: ✅ Fixed setup_mcp.sh path expansion - Now shows ACTUAL paths (not $REPO_PATH placeholder) - Verifies paths exist after writing config - Shows config contents for verification - Tests MCP server path validity - Clear warning about placeholders README Updates: ✅ Added Prerequisites section - Python 3.10+ requirement clear - Git requirement clear - Links to bulletproof guide ✅ Added git clone step to Quick Start ✅ Reorganized Documentation section - Getting Started (new, beginner, troubleshooting) - Guides (advanced topics) - Technical (architecture) Fixes: - Issue #8 - Prereqs to Getting Started - Issue #114 on project board (H1.1) - Placeholder path problem in MCP setup - Missing beginner-friendly docs Impact: New users can now get started without confusion!
This commit is contained in:
yusyus
446
TROUBLESHOOTING.md
Normal file
446
TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,446 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
Common issues and solutions when using Skill Seeker.
|
||||
|
||||
---
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### Python Not Found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
python3: command not found
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check if Python is installed:**
|
||||
```bash
|
||||
which python3
|
||||
python --version # Try without the 3
|
||||
```
|
||||
|
||||
2. **Install Python:**
|
||||
- **macOS:** `brew install python3`
|
||||
- **Linux:** `sudo apt install python3 python3-pip`
|
||||
- **Windows:** Download from python.org, check "Add to PATH"
|
||||
|
||||
3. **Use python instead of python3:**
|
||||
```bash
|
||||
python cli/doc_scraper.py --help
|
||||
```
|
||||
|
||||
### Module Not Found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
ModuleNotFoundError: No module named 'requests'
|
||||
ModuleNotFoundError: No module named 'bs4'
|
||||
ModuleNotFoundError: No module named 'mcp'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Install dependencies:**
|
||||
```bash
|
||||
pip3 install requests beautifulsoup4
|
||||
pip3 install -r mcp/requirements.txt # For MCP
|
||||
```
|
||||
|
||||
2. **Use --user flag if permission denied:**
|
||||
```bash
|
||||
pip3 install --user requests beautifulsoup4
|
||||
```
|
||||
|
||||
3. **Check pip is working:**
|
||||
```bash
|
||||
pip3 --version
|
||||
```
|
||||
|
||||
### Permission Denied
|
||||
|
||||
**Error:**
|
||||
```
|
||||
Permission denied: '/usr/local/lib/python3.x/...'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Use --user flag:**
|
||||
```bash
|
||||
pip3 install --user requests beautifulsoup4
|
||||
```
|
||||
|
||||
2. **Use sudo (not recommended):**
|
||||
```bash
|
||||
sudo pip3 install requests beautifulsoup4
|
||||
```
|
||||
|
||||
3. **Use virtual environment (best practice):**
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install requests beautifulsoup4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Runtime Issues
|
||||
|
||||
### File Not Found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
FileNotFoundError: [Errno 2] No such file or directory: 'cli/doc_scraper.py'
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check you're in the Skill_Seekers directory:**
|
||||
```bash
|
||||
pwd
|
||||
# Should show: .../Skill_Seekers
|
||||
|
||||
ls
|
||||
# Should show: README.md, cli/, mcp/, configs/
|
||||
```
|
||||
|
||||
2. **Change to the correct directory:**
|
||||
```bash
|
||||
cd ~/Projects/Skill_Seekers # Adjust path
|
||||
```
|
||||
|
||||
### Config File Not Found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
FileNotFoundError: configs/react.json
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
1. **Check config exists:**
|
||||
```bash
|
||||
ls configs/
|
||||
# Should show: godot.json, react.json, vue.json, etc.
|
||||
```
|
||||
|
||||
2. **Use full path:**
|
||||
```bash
|
||||
python3 cli/doc_scraper.py --config $(pwd)/configs/react.json
|
||||
```
|
||||
|
||||
3. **Create missing config:**
|
||||
```bash
|
||||
python3 cli/doc_scraper.py --interactive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP Setup Issues
|
||||
|
||||
### MCP Server Not Loading
|
||||
|
||||
**Symptoms:**
|
||||
- Tools don't appear in Claude Code
|
||||
- "List all available configs" doesn't work
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check configuration file:**
|
||||
```bash
|
||||
cat ~/.config/claude-code/mcp.json
|
||||
```
|
||||
|
||||
2. **Verify paths are ABSOLUTE (not placeholders):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"skill-seeker": {
|
||||
"args": [
|
||||
"/Users/yourname/Projects/Skill_Seekers/mcp/server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
❌ **Bad:** `$REPO_PATH` or `/path/to/Skill_Seekers`
|
||||
✅ **Good:** `/Users/john/Projects/Skill_Seekers`
|
||||
|
||||
3. **Test server manually:**
|
||||
```bash
|
||||
cd ~/Projects/Skill_Seekers
|
||||
python3 mcp/server.py
|
||||
# Should start without errors (Ctrl+C to stop)
|
||||
```
|
||||
|
||||
4. **Re-run setup script:**
|
||||
```bash
|
||||
./setup_mcp.sh
|
||||
# Select "y" for auto-configure
|
||||
```
|
||||
|
||||
5. **RESTART Claude Code completely:**
|
||||
- Quit (don't just close window)
|
||||
- Reopen
|
||||
|
||||
### Placeholder Paths in Config
|
||||
|
||||
**Problem:** Config has `$REPO_PATH` or `/Users/username/` instead of real paths
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Get your actual path
|
||||
cd ~/Projects/Skill_Seekers
|
||||
pwd
|
||||
# Copy this path
|
||||
|
||||
# Edit config
|
||||
nano ~/.config/claude-code/mcp.json
|
||||
|
||||
# Replace ALL instances of placeholders with your actual path
|
||||
# Save (Ctrl+O, Enter, Ctrl+X)
|
||||
|
||||
# Restart Claude Code
|
||||
```
|
||||
|
||||
### Tools Appear But Don't Work
|
||||
|
||||
**Symptoms:**
|
||||
- Tools listed but commands fail
|
||||
- "Error executing tool" messages
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check working directory:**
|
||||
```json
|
||||
{
|
||||
"cwd": "/FULL/PATH/TO/Skill_Seekers"
|
||||
}
|
||||
```
|
||||
|
||||
2. **Verify files exist:**
|
||||
```bash
|
||||
ls cli/doc_scraper.py
|
||||
ls mcp/server.py
|
||||
```
|
||||
|
||||
3. **Test CLI tools directly:**
|
||||
```bash
|
||||
python3 cli/doc_scraper.py --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scraping Issues
|
||||
|
||||
### Slow or Hanging
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check network connection:**
|
||||
```bash
|
||||
ping google.com
|
||||
curl -I https://docs.yoursite.com
|
||||
```
|
||||
|
||||
2. **Use smaller max_pages for testing:**
|
||||
```bash
|
||||
python3 cli/doc_scraper.py --config configs/test.json --max-pages 5
|
||||
```
|
||||
|
||||
3. **Increase rate_limit in config:**
|
||||
```json
|
||||
{
|
||||
"rate_limit": 1.0 // Increase from 0.5
|
||||
}
|
||||
```
|
||||
|
||||
### No Content Extracted
|
||||
|
||||
**Problem:** Pages scraped but content is empty
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Check selector in config:**
|
||||
```bash
|
||||
# Test with browser dev tools
|
||||
# Look for: article, main, div[role="main"], div.content
|
||||
```
|
||||
|
||||
2. **Verify website is accessible:**
|
||||
```bash
|
||||
curl https://docs.example.com
|
||||
```
|
||||
|
||||
3. **Try different selectors:**
|
||||
```json
|
||||
{
|
||||
"selectors": {
|
||||
"main_content": "article" // Try: main, div.content, etc.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rate Limiting / 429 Errors
|
||||
|
||||
**Error:**
|
||||
```
|
||||
HTTP Error 429: Too Many Requests
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Increase rate_limit:**
|
||||
```json
|
||||
{
|
||||
"rate_limit": 2.0 // Wait 2 seconds between requests
|
||||
}
|
||||
```
|
||||
|
||||
2. **Reduce max_pages:**
|
||||
```json
|
||||
{
|
||||
"max_pages": 50 // Scrape fewer pages
|
||||
}
|
||||
```
|
||||
|
||||
3. **Try again later:**
|
||||
```bash
|
||||
# Wait an hour and retry
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Issues
|
||||
|
||||
### macOS
|
||||
|
||||
**Issue:** Can't run `./setup_mcp.sh`
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
chmod +x setup_mcp.sh
|
||||
./setup_mcp.sh
|
||||
```
|
||||
|
||||
**Issue:** Homebrew not installed
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
**Issue:** pip3 not found
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install python3-pip
|
||||
```
|
||||
|
||||
**Issue:** Permission errors
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use --user flag
|
||||
pip3 install --user requests beautifulsoup4
|
||||
```
|
||||
|
||||
### Windows (WSL)
|
||||
|
||||
**Issue:** Python not in PATH
|
||||
|
||||
**Solution:**
|
||||
1. Reinstall Python
|
||||
2. Check "Add Python to PATH"
|
||||
3. Or add manually to PATH
|
||||
|
||||
**Issue:** Line ending errors
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
dos2unix setup_mcp.sh
|
||||
./setup_mcp.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Commands
|
||||
|
||||
Use these to check your setup:
|
||||
|
||||
```bash
|
||||
# 1. Check Python
|
||||
python3 --version # Should be 3.10+
|
||||
|
||||
# 2. Check dependencies
|
||||
pip3 list | grep requests
|
||||
pip3 list | grep beautifulsoup4
|
||||
pip3 list | grep mcp
|
||||
|
||||
# 3. Check files exist
|
||||
ls cli/doc_scraper.py
|
||||
ls mcp/server.py
|
||||
ls configs/
|
||||
|
||||
# 4. Check MCP config
|
||||
cat ~/.config/claude-code/mcp.json
|
||||
|
||||
# 5. Test scraper
|
||||
python3 cli/doc_scraper.py --help
|
||||
|
||||
# 6. Test MCP server
|
||||
timeout 3 python3 mcp/server.py || echo "Server OK"
|
||||
|
||||
# 7. Check git repo
|
||||
git status
|
||||
git log --oneline -5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If none of these solutions work:
|
||||
|
||||
1. **Check existing issues:**
|
||||
https://github.com/yusufkaraaslan/Skill_Seekers/issues
|
||||
|
||||
2. **Open a new issue with:**
|
||||
- Your OS (macOS 13, Ubuntu 22.04, etc.)
|
||||
- Python version (`python3 --version`)
|
||||
- Full error message
|
||||
- What command you ran
|
||||
- Output of verification commands above
|
||||
|
||||
3. **Include this debug info:**
|
||||
```bash
|
||||
# System info
|
||||
uname -a
|
||||
python3 --version
|
||||
pip3 --version
|
||||
|
||||
# Skill Seeker info
|
||||
cd ~/Projects/Skill_Seekers # Your path
|
||||
pwd
|
||||
git log --oneline -1
|
||||
ls -la cli/ mcp/ configs/
|
||||
|
||||
# MCP config (if using MCP)
|
||||
cat ~/.config/claude-code/mcp.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Fixes Checklist
|
||||
|
||||
- [ ] In the Skill_Seekers directory? (`pwd`)
|
||||
- [ ] Python 3.10+ installed? (`python3 --version`)
|
||||
- [ ] Dependencies installed? (`pip3 list | grep requests`)
|
||||
- [ ] Config file exists? (`ls configs/yourconfig.json`)
|
||||
- [ ] Internet connection working? (`ping google.com`)
|
||||
- [ ] For MCP: Config uses absolute paths? (not `$REPO_PATH`)
|
||||
- [ ] For MCP: Claude Code restarted? (quit and reopen)
|
||||
|
||||
---
|
||||
|
||||
**Still stuck?** Open an issue: https://github.com/yusufkaraaslan/Skill_Seekers/issues/new
|
||||
Reference in New Issue
Block a user