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
478
BULLETPROOF_QUICKSTART.md
Normal file
478
BULLETPROOF_QUICKSTART.md
Normal file
@@ -0,0 +1,478 @@
|
||||
# Bulletproof Quick Start Guide
|
||||
|
||||
**Target Audience:** Complete beginners | Never used Python/git before? Start here!
|
||||
|
||||
**Time:** 15-30 minutes total (including all installations)
|
||||
|
||||
**Result:** Working Skill Seeker installation + your first Claude skill created
|
||||
|
||||
---
|
||||
|
||||
## 📋 What You'll Need
|
||||
|
||||
Before starting, you need:
|
||||
- A computer (macOS, Linux, or Windows with WSL)
|
||||
- Internet connection
|
||||
- 30 minutes of time
|
||||
|
||||
That's it! We'll install everything else together.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Install Python (5 minutes)
|
||||
|
||||
### Check if You Already Have Python
|
||||
|
||||
Open Terminal (macOS/Linux) or Command Prompt (Windows) and type:
|
||||
|
||||
```bash
|
||||
python3 --version
|
||||
```
|
||||
|
||||
**✅ If you see:** `Python 3.10.x` or `Python 3.11.x` or higher → **Skip to Step 2!**
|
||||
|
||||
**❌ If you see:** `command not found` or version less than 3.10 → **Continue below**
|
||||
|
||||
### Install Python
|
||||
|
||||
#### macOS:
|
||||
```bash
|
||||
# Install Homebrew (if not installed)
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
|
||||
# Install Python
|
||||
brew install python3
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
python3 --version
|
||||
# Should show: Python 3.11.x or similar
|
||||
```
|
||||
|
||||
#### Linux (Ubuntu/Debian):
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install python3 python3-pip
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
python3 --version
|
||||
pip3 --version
|
||||
```
|
||||
|
||||
#### Windows:
|
||||
1. Download Python from: https://www.python.org/downloads/
|
||||
2. Run installer
|
||||
3. **IMPORTANT:** Check "Add Python to PATH" during installation
|
||||
4. Open Command Prompt and verify:
|
||||
```bash
|
||||
python --version
|
||||
```
|
||||
|
||||
**✅ Success looks like:**
|
||||
```
|
||||
Python 3.11.5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Install Git (3 minutes)
|
||||
|
||||
### Check if You Have Git
|
||||
|
||||
```bash
|
||||
git --version
|
||||
```
|
||||
|
||||
**✅ If you see:** `git version 2.x.x` → **Skip to Step 3!**
|
||||
|
||||
**❌ If not installed:**
|
||||
|
||||
#### macOS:
|
||||
```bash
|
||||
brew install git
|
||||
```
|
||||
|
||||
#### Linux:
|
||||
```bash
|
||||
sudo apt install git
|
||||
```
|
||||
|
||||
#### Windows:
|
||||
Download from: https://git-scm.com/download/win
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
git --version
|
||||
# Should show: git version 2.x.x
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Get Skill Seeker (2 minutes)
|
||||
|
||||
### Choose Where to Put It
|
||||
|
||||
Pick a location for the project. Good choices:
|
||||
- macOS/Linux: `~/Projects/` or `~/Documents/`
|
||||
- Windows: `C:\Users\YourName\Projects\`
|
||||
|
||||
### Clone the Repository
|
||||
|
||||
```bash
|
||||
# Create Projects directory (if it doesn't exist)
|
||||
mkdir -p ~/Projects
|
||||
cd ~/Projects
|
||||
|
||||
# Clone Skill Seeker
|
||||
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
|
||||
|
||||
# Enter the directory
|
||||
cd Skill_Seekers
|
||||
```
|
||||
|
||||
**✅ Success looks like:**
|
||||
```
|
||||
Cloning into 'Skill_Seekers'...
|
||||
remote: Enumerating objects: 245, done.
|
||||
remote: Counting objects: 100% (245/245), done.
|
||||
```
|
||||
|
||||
**Verify you're in the right place:**
|
||||
```bash
|
||||
pwd
|
||||
# Should show: /Users/yourname/Projects/Skill_Seekers (or similar)
|
||||
|
||||
ls
|
||||
# Should show: README.md, cli/, mcp/, configs/, etc.
|
||||
```
|
||||
|
||||
**❌ If `git clone` fails:**
|
||||
```bash
|
||||
# Check internet connection
|
||||
ping google.com
|
||||
|
||||
# Or download ZIP manually:
|
||||
# https://github.com/yusufkaraaslan/Skill_Seekers/archive/refs/heads/main.zip
|
||||
# Then unzip and cd into it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Install Dependencies (2 minutes)
|
||||
|
||||
```bash
|
||||
# Make sure you're in the Skill_Seekers directory
|
||||
cd ~/Projects/Skill_Seekers # Adjust path if you chose different location
|
||||
|
||||
# Install required packages
|
||||
pip3 install requests beautifulsoup4
|
||||
```
|
||||
|
||||
**✅ Success looks like:**
|
||||
```
|
||||
Successfully installed requests-2.31.0 beautifulsoup4-4.12.3
|
||||
```
|
||||
|
||||
**❌ If pip3 not found:**
|
||||
```bash
|
||||
# Try without the 3
|
||||
pip install requests beautifulsoup4
|
||||
```
|
||||
|
||||
**❌ If permission denied:**
|
||||
```bash
|
||||
# Add --user flag
|
||||
pip3 install --user requests beautifulsoup4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Test Your Installation (1 minute)
|
||||
|
||||
Let's make sure everything works:
|
||||
|
||||
```bash
|
||||
# Test the main script can run
|
||||
python3 cli/doc_scraper.py --help
|
||||
```
|
||||
|
||||
**✅ Success looks like:**
|
||||
```
|
||||
usage: doc_scraper.py [-h] [--config CONFIG] [--interactive] ...
|
||||
```
|
||||
|
||||
**❌ If you see "No such file or directory":**
|
||||
```bash
|
||||
# Check you're in the right directory
|
||||
pwd
|
||||
# Should show path ending in /Skill_Seekers
|
||||
|
||||
# List files
|
||||
ls cli/
|
||||
# Should show: doc_scraper.py, estimate_pages.py, etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Create Your First Skill! (5-10 minutes)
|
||||
|
||||
Let's create a simple skill using a preset configuration.
|
||||
|
||||
### Option A: Small Test (Recommended First Time)
|
||||
|
||||
```bash
|
||||
# Create a config for a small site first
|
||||
cat > configs/test.json << 'EOF'
|
||||
{
|
||||
"name": "test-skill",
|
||||
"description": "Test skill creation",
|
||||
"base_url": "https://tailwindcss.com/docs/installation",
|
||||
"max_pages": 5,
|
||||
"rate_limit": 0.5
|
||||
}
|
||||
EOF
|
||||
|
||||
# Run the scraper
|
||||
python3 cli/doc_scraper.py --config configs/test.json
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Scrapes 5 pages from Tailwind CSS docs
|
||||
2. Creates `output/test-skill/` directory
|
||||
3. Generates SKILL.md and reference files
|
||||
|
||||
**⏱️ Time:** ~30 seconds
|
||||
|
||||
**✅ Success looks like:**
|
||||
```
|
||||
Scraping: https://tailwindcss.com/docs/installation
|
||||
Page 1/5: Installation
|
||||
Page 2/5: Editor Setup
|
||||
...
|
||||
✅ Skill created at: output/test-skill/
|
||||
```
|
||||
|
||||
### Option B: Full Example (React Docs)
|
||||
|
||||
```bash
|
||||
# Use the React preset
|
||||
python3 cli/doc_scraper.py --config configs/react.json --max-pages 50
|
||||
```
|
||||
|
||||
**⏱️ Time:** ~5 minutes
|
||||
|
||||
**What you get:**
|
||||
- `output/react/SKILL.md` - Main skill file
|
||||
- `output/react/references/` - Organized documentation
|
||||
|
||||
### Verify It Worked
|
||||
|
||||
```bash
|
||||
# Check the output
|
||||
ls output/test-skill/
|
||||
# Should show: SKILL.md, references/, scripts/, assets/
|
||||
|
||||
# Look at the generated skill
|
||||
head output/test-skill/SKILL.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Package for Claude (30 seconds)
|
||||
|
||||
```bash
|
||||
# Package the skill
|
||||
python3 cli/package_skill.py output/test-skill/
|
||||
```
|
||||
|
||||
**✅ Success looks like:**
|
||||
```
|
||||
✅ Skill packaged successfully!
|
||||
📦 Created: output/test-skill.zip
|
||||
📏 Size: 45.2 KB
|
||||
|
||||
Ready to upload to Claude AI!
|
||||
```
|
||||
|
||||
**Now you have:** `output/test-skill.zip` ready to upload to Claude!
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Upload to Claude (2 minutes)
|
||||
|
||||
1. Go to https://claude.ai
|
||||
2. Click your profile → Settings
|
||||
3. Click "Knowledge" or "Skills"
|
||||
4. Click "Upload Skill"
|
||||
5. Select `output/test-skill.zip`
|
||||
6. Done! Claude can now use this skill
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Success! What's Next?
|
||||
|
||||
You now have a working Skill Seeker installation! Here's what you can do:
|
||||
|
||||
### Try Other Presets
|
||||
|
||||
```bash
|
||||
# See all available presets
|
||||
ls configs/
|
||||
|
||||
# Try Vue.js
|
||||
python3 cli/doc_scraper.py --config configs/vue.json --max-pages 50
|
||||
|
||||
# Try Django
|
||||
python3 cli/doc_scraper.py --config configs/django.json --max-pages 50
|
||||
```
|
||||
|
||||
### Create Custom Skills
|
||||
|
||||
```bash
|
||||
# Interactive mode - answer questions
|
||||
python3 cli/doc_scraper.py --interactive
|
||||
|
||||
# Or create config for any website
|
||||
python3 cli/doc_scraper.py \
|
||||
--name myframework \
|
||||
--url https://docs.myframework.com/ \
|
||||
--description "My favorite framework"
|
||||
```
|
||||
|
||||
### Use with Claude Code (Advanced)
|
||||
|
||||
If you have Claude Code installed:
|
||||
|
||||
```bash
|
||||
# One-time setup
|
||||
./setup_mcp.sh
|
||||
|
||||
# Then use natural language in Claude Code:
|
||||
# "Generate a skill for Svelte docs"
|
||||
# "Package the skill at output/svelte/"
|
||||
```
|
||||
|
||||
**See:** [docs/MCP_SETUP.md](docs/MCP_SETUP.md) for full MCP setup
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### "Command not found" errors
|
||||
|
||||
**Problem:** `python3: command not found`
|
||||
|
||||
**Solution:** Python not installed or not in PATH
|
||||
- macOS/Linux: Reinstall Python with brew/apt
|
||||
- Windows: Reinstall Python, check "Add to PATH"
|
||||
- Try `python` instead of `python3`
|
||||
|
||||
### "Permission denied" errors
|
||||
|
||||
**Problem:** Can't install packages or run scripts
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use --user flag
|
||||
pip3 install --user requests beautifulsoup4
|
||||
|
||||
# Or make script executable
|
||||
chmod +x cli/doc_scraper.py
|
||||
```
|
||||
|
||||
### "No such file or directory"
|
||||
|
||||
**Problem:** Can't find cli/doc_scraper.py
|
||||
|
||||
**Solution:** You're not in the right directory
|
||||
```bash
|
||||
# Go to the Skill_Seekers directory
|
||||
cd ~/Projects/Skill_Seekers # Adjust your path
|
||||
|
||||
# Verify
|
||||
ls cli/
|
||||
# Should show doc_scraper.py
|
||||
```
|
||||
|
||||
### "ModuleNotFoundError"
|
||||
|
||||
**Problem:** Missing Python packages
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Install dependencies again
|
||||
pip3 install requests beautifulsoup4
|
||||
|
||||
# If that fails, try:
|
||||
pip3 install --user requests beautifulsoup4
|
||||
```
|
||||
|
||||
### Scraping is slow or fails
|
||||
|
||||
**Problem:** Takes forever or gets errors
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use smaller max_pages for testing
|
||||
python3 cli/doc_scraper.py --config configs/react.json --max-pages 10
|
||||
|
||||
# Check internet connection
|
||||
ping google.com
|
||||
|
||||
# Check the website is accessible
|
||||
curl -I https://docs.yoursite.com
|
||||
```
|
||||
|
||||
### Still stuck?
|
||||
|
||||
1. **Check our detailed troubleshooting guide:** [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
2. **Open an issue:** https://github.com/yusufkaraaslan/Skill_Seekers/issues
|
||||
3. **Include this info:**
|
||||
- Operating system (macOS 13, Ubuntu 22.04, Windows 11, etc.)
|
||||
- Python version (`python3 --version`)
|
||||
- Full error message
|
||||
- What command you ran
|
||||
|
||||
---
|
||||
|
||||
## 📚 Next Steps
|
||||
|
||||
- **Read the full README:** [README.md](README.md)
|
||||
- **Learn about presets:** [configs/](configs/)
|
||||
- **Try MCP integration:** [docs/MCP_SETUP.md](docs/MCP_SETUP.md)
|
||||
- **Advanced usage:** [docs/](docs/)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Quick Reference
|
||||
|
||||
```bash
|
||||
# Your typical workflow:
|
||||
|
||||
# 1. Create/use a config
|
||||
python3 cli/doc_scraper.py --config configs/react.json --max-pages 50
|
||||
|
||||
# 2. Package it
|
||||
python3 cli/package_skill.py output/react/
|
||||
|
||||
# 3. Upload output/react.zip to Claude
|
||||
|
||||
# Done! 🎉
|
||||
```
|
||||
|
||||
**Common locations:**
|
||||
- **Configs:** `configs/*.json`
|
||||
- **Output:** `output/skill-name/`
|
||||
- **Packaged skills:** `output/skill-name.zip`
|
||||
|
||||
**Time estimates:**
|
||||
- Small skill (5-10 pages): 30 seconds
|
||||
- Medium skill (50-100 pages): 3-5 minutes
|
||||
- Large skill (500+ pages): 15-30 minutes
|
||||
|
||||
---
|
||||
|
||||
**Still confused?** That's okay! Open an issue and we'll help you get started: https://github.com/yusufkaraaslan/Skill_Seekers/issues/new
|
||||
27
README.md
27
README.md
@@ -95,6 +95,20 @@ graph LR
|
||||
3. **Enhance**: AI analyzes docs and creates comprehensive SKILL.md with examples
|
||||
4. **Package**: Bundles everything into a Claude-ready `.zip` file
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
**Before you start, make sure you have:**
|
||||
|
||||
1. **Python 3.10 or higher** - [Download](https://www.python.org/downloads/) | Check: `python3 --version`
|
||||
2. **Git** - [Download](https://git-scm.com/) | Check: `git --version`
|
||||
3. **15-30 minutes** for first-time setup
|
||||
|
||||
**First time user?** → **[Start Here: Bulletproof Quick Start Guide](BULLETPROOF_QUICKSTART.md)** 🎯
|
||||
|
||||
This guide walks you through EVERYTHING step-by-step (Python install, git clone, first skill creation).
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Method 1: MCP Server for Claude Code (Easiest)
|
||||
@@ -102,6 +116,10 @@ graph LR
|
||||
Use Skill Seeker directly from Claude Code with natural language!
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
|
||||
cd Skill_Seekers
|
||||
|
||||
# One-time setup (5 minutes)
|
||||
./setup_mcp.sh
|
||||
|
||||
@@ -737,11 +755,18 @@ python3 doc_scraper.py --config configs/godot.json
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **[QUICKSTART.md](QUICKSTART.md)** - Get started in 3 steps
|
||||
### Getting Started
|
||||
- **[BULLETPROOF_QUICKSTART.md](BULLETPROOF_QUICKSTART.md)** - 🎯 **START HERE** if you're new!
|
||||
- **[QUICKSTART.md](QUICKSTART.md)** - Quick start for experienced users
|
||||
- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
|
||||
|
||||
### Guides
|
||||
- **[docs/LARGE_DOCUMENTATION.md](docs/LARGE_DOCUMENTATION.md)** - Handle 10K-40K+ page docs
|
||||
- **[docs/ENHANCEMENT.md](docs/ENHANCEMENT.md)** - AI enhancement guide
|
||||
- **[docs/UPLOAD_GUIDE.md](docs/UPLOAD_GUIDE.md)** - How to upload skills to Claude
|
||||
- **[docs/MCP_SETUP.md](docs/MCP_SETUP.md)** - MCP integration setup
|
||||
|
||||
### Technical
|
||||
- **[docs/CLAUDE.md](docs/CLAUDE.md)** - Technical architecture
|
||||
- **[STRUCTURE.md](STRUCTURE.md)** - Repository structure
|
||||
|
||||
|
||||
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
|
||||
63
setup_mcp.sh
63
setup_mcp.sh
@@ -103,7 +103,7 @@ echo "You need to add this configuration to Claude Code:"
|
||||
echo ""
|
||||
echo -e "${YELLOW}Configuration file:${NC} ~/.config/claude-code/mcp.json"
|
||||
echo ""
|
||||
echo "Add this JSON configuration:"
|
||||
echo "Add this JSON configuration (paths are auto-detected for YOUR system):"
|
||||
echo ""
|
||||
echo -e "${GREEN}{"
|
||||
echo " \"mcpServers\": {"
|
||||
@@ -117,27 +117,7 @@ echo " }"
|
||||
echo " }"
|
||||
echo -e "}${NC}"
|
||||
echo ""
|
||||
echo "To configure automatically, run:"
|
||||
echo ""
|
||||
echo -e "${YELLOW} mkdir -p ~/.config/claude-code${NC}"
|
||||
echo ""
|
||||
echo "Then edit ~/.config/claude-code/mcp.json and add the configuration above"
|
||||
echo ""
|
||||
echo "Or use this one-liner (BE CAREFUL - this may overwrite existing config):"
|
||||
echo ""
|
||||
echo -e "${RED}cat > ~/.config/claude-code/mcp.json << 'EOF'
|
||||
{
|
||||
\"mcpServers\": {
|
||||
\"skill-seeker\": {
|
||||
\"command\": \"python3\",
|
||||
\"args\": [
|
||||
\"$REPO_PATH/mcp/server.py\"
|
||||
],
|
||||
\"cwd\": \"$REPO_PATH\"
|
||||
}
|
||||
}
|
||||
}
|
||||
EOF${NC}"
|
||||
echo -e "${YELLOW}Note:${NC} The paths above are YOUR actual paths (not placeholders!)"
|
||||
echo ""
|
||||
|
||||
# Ask if user wants auto-configure
|
||||
@@ -164,7 +144,7 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
|
||||
# Create config directory
|
||||
mkdir -p ~/.config/claude-code
|
||||
|
||||
# Write configuration
|
||||
# Write configuration with actual expanded path
|
||||
cat > ~/.config/claude-code/mcp.json << EOF
|
||||
{
|
||||
"mcpServers": {
|
||||
@@ -180,13 +160,46 @@ if [[ $REPLY =~ ^[Yy]$ ]]; then
|
||||
EOF
|
||||
|
||||
echo -e "${GREEN}✓${NC} Configuration written to ~/.config/claude-code/mcp.json"
|
||||
echo ""
|
||||
echo "Configuration contents:"
|
||||
cat ~/.config/claude-code/mcp.json
|
||||
echo ""
|
||||
|
||||
# Verify the path exists
|
||||
if [ -f "$REPO_PATH/mcp/server.py" ]; then
|
||||
echo -e "${GREEN}✓${NC} Verified: MCP server file exists at $REPO_PATH/mcp/server.py"
|
||||
else
|
||||
echo -e "${RED}❌ Warning: MCP server not found at $REPO_PATH/mcp/server.py${NC}"
|
||||
echo "Please check the path!"
|
||||
fi
|
||||
else
|
||||
echo "Skipping auto-configuration"
|
||||
echo "Please manually configure Claude Code using the JSON above"
|
||||
echo ""
|
||||
echo "IMPORTANT: Replace \$REPO_PATH with the actual path: $REPO_PATH"
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Step 7: Final instructions
|
||||
# Step 7: Test the configuration
|
||||
if [ -f ~/.config/claude-code/mcp.json ]; then
|
||||
echo "Step 7: Testing MCP configuration..."
|
||||
echo "Checking if paths are correct..."
|
||||
|
||||
# Extract the configured path
|
||||
if command -v jq &> /dev/null; then
|
||||
CONFIGURED_PATH=$(jq -r '.mcpServers["skill-seeker"].args[0]' ~/.config/claude-code/mcp.json 2>/dev/null || echo "")
|
||||
if [ -n "$CONFIGURED_PATH" ] && [ -f "$CONFIGURED_PATH" ]; then
|
||||
echo -e "${GREEN}✓${NC} MCP server path is valid: $CONFIGURED_PATH"
|
||||
elif [ -n "$CONFIGURED_PATH" ]; then
|
||||
echo -e "${YELLOW}⚠${NC} Warning: Configured path doesn't exist: $CONFIGURED_PATH"
|
||||
fi
|
||||
else
|
||||
echo "Install 'jq' for config validation: brew install jq (macOS) or apt install jq (Linux)"
|
||||
fi
|
||||
fi
|
||||
echo ""
|
||||
|
||||
# Step 8: Final instructions
|
||||
echo "=================================================="
|
||||
echo "Setup Complete!"
|
||||
echo "=================================================="
|
||||
@@ -195,7 +208,7 @@ echo "Next steps:"
|
||||
echo ""
|
||||
echo " 1. ${YELLOW}Restart Claude Code${NC} (quit and reopen, don't just close window)"
|
||||
echo " 2. In Claude Code, test with: ${GREEN}\"List all available configs\"${NC}"
|
||||
echo " 3. You should see 6 Skill Seeker tools available"
|
||||
echo " 3. You should see 9 Skill Seeker tools available"
|
||||
echo ""
|
||||
echo "Available MCP Tools:"
|
||||
echo " • generate_config - Create new config files"
|
||||
|
||||
Reference in New Issue
Block a user