INSTALLATION.md•9.6 kB
# Installation Guide
Comprehensive installation instructions for SCS-MCP and Voice Assistant.
## Table of Contents
1. [System Requirements](#system-requirements)
2. [Quick Start](#quick-start)
3. [Detailed Installation](#detailed-installation)
4. [Voice Assistant Setup](#voice-assistant-setup)
5. [Claude Desktop Configuration](#claude-desktop-configuration)
6. [VS Code Extension](#vs-code-extension)
7. [Troubleshooting](#troubleshooting)
8. [Verification](#verification)
---
## System Requirements
### Minimum Requirements
- **OS**: Windows 10/11 (with WSL2), macOS 10.15+, Linux (Ubuntu 20.04+)
- **Python**: 3.8 or higher
- **Node.js**: 16.0 or higher (for Voice Assistant)
- **RAM**: 4GB minimum, 8GB recommended
- **Storage**: 2GB free space
- **Claude Desktop**: Latest version
### Optional Requirements
- **VS Code**: For extension integration
- **Git**: For cloning repository
- **FFmpeg**: For video recording features
- **Chrome/Edge**: For voice recognition
---
## Quick Start
### 1. Clone and Install
```bash
# Clone repository
git clone https://github.com/yourusername/scs-mcp.git
cd scs-mcp
# Run installer
chmod +x scripts/install.sh
./scripts/install.sh
```
### 2. Configure Claude Desktop
Add to `claude_desktop_config.json`:
**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
"mcpServers": {
"scs-mcp": {
"command": "wsl",
"args": [
"bash",
"-c",
"cd /path/to/scs-mcp && python3 -m src.server"
]
}
}
}
```
**macOS/Linux** (`~/.config/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"scs-mcp": {
"command": "python3",
"args": ["-m", "src.server"],
"cwd": "/path/to/scs-mcp"
}
}
}
```
### 3. Restart Claude Desktop
---
## Detailed Installation
### Step 1: Install Python Dependencies
```bash
# Create virtual environment (recommended)
python3 -m venv venv
# Activate virtual environment
# On Windows (WSL/Git Bash):
source venv/Scripts/activate
# On macOS/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Download sentence transformer model
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2')"
```
### Step 2: Initialize Database
```bash
# Create index for your project
python scripts/init_index.py --project-root /path/to/your/project
# Verify index
python scripts/verify_index.py
```
### Step 3: Configure Environment
Create `.env` file in project root:
```bash
# Project Settings
PROJECT_ROOT=/path/to/your/code/project
PROJECT_NAME=MyProject
# Model Settings
EMBEDDING_MODEL=all-MiniLM-L6-v2
EMBEDDING_CACHE_SIZE=1000
# Performance
MAX_WORKERS=4
BATCH_SIZE=32
CACHE_TTL=300
# Features
ENABLE_GIT_HISTORY=true
ENABLE_METRICS=true
ENABLE_ORCHESTRATION=true
```
### Step 4: Test Installation
```bash
# Run test suite
python -m pytest tests/
# Test MCP connection
python scripts/test_mcp.py
```
---
## Voice Assistant Setup
### Step 1: Install Node.js Dependencies
```bash
cd voice-assistant
npm install
# Setup media directories and database
npm run setup
```
### Step 2: Configure Voice Assistant
Create `voice-assistant/.env`:
```bash
# Server Configuration
PORT=3000
WS_PORT=3001
# Optional: ElevenLabs for TTS
ELEVENLABS_API_KEY=your_api_key_here
# Optional: OpenAI for enhanced processing
OPENAI_API_KEY=your_api_key_here
# Media Storage
MAX_STORAGE_GB=5
CLEANUP_DAYS=30
```
### Step 3: Install VS Code Extension
```bash
cd voice-assistant/vscode-extension
npm install
npm run compile
# Open VS Code
code .
# Press F5 to run extension in debug mode
```
### Step 4: Start Voice Assistant Server
```bash
cd voice-assistant
npm start
# Or for development with auto-reload
npm run dev
```
### Step 5: Access Web UI
Open browser to: [http://localhost:3000/media-ui.html](http://localhost:3000/media-ui.html)
---
## Claude Desktop Configuration
### Windows with WSL2
1. **Install WSL2**:
```powershell
wsl --install
wsl --set-default-version 2
```
2. **Setup in WSL**:
```bash
# In WSL terminal
cd /mnt/c/Users/YourName/Documents/
git clone https://github.com/yourusername/scs-mcp.git
cd scs-mcp
./scripts/install.sh
```
3. **Configure Claude Desktop**:
```json
{
"mcpServers": {
"scs-mcp": {
"command": "wsl",
"args": [
"bash",
"-c",
"cd /mnt/c/Users/YourName/Documents/scs-mcp && python3 -m src.server"
],
"env": {
"PROJECT_ROOT": "/mnt/c/Users/YourName/YourProject"
}
}
}
}
```
### macOS
1. **Install Homebrew** (if not installed):
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
2. **Install Python**:
```bash
brew install python@3.11
```
3. **Configure Claude Desktop**:
```json
{
"mcpServers": {
"scs-mcp": {
"command": "/opt/homebrew/bin/python3",
"args": ["-m", "src.server"],
"cwd": "/Users/YourName/Documents/scs-mcp",
"env": {
"PROJECT_ROOT": "/Users/YourName/YourProject"
}
}
}
}
```
### Linux
1. **Install dependencies**:
```bash
sudo apt update
sudo apt install python3-pip python3-venv git
```
2. **Configure Claude Desktop**:
```json
{
"mcpServers": {
"scs-mcp": {
"command": "python3",
"args": ["-m", "src.server"],
"cwd": "/home/username/scs-mcp",
"env": {
"PROJECT_ROOT": "/home/username/your-project"
}
}
}
}
```
---
## VS Code Extension
### Installation
1. **From VSIX file**:
```bash
cd voice-assistant/vscode-extension
npm run package
# Creates voice-assistant-1.0.0.vsix
# Install in VS Code
code --install-extension voice-assistant-1.0.0.vsix
```
2. **Development mode**:
- Open `voice-assistant/vscode-extension` in VS Code
- Press `F5` to launch new VS Code window with extension
- Extension will auto-connect to voice server
### Configuration
VS Code settings.json:
```json
{
"voiceAssistant.serverUrl": "ws://localhost:3001",
"voiceAssistant.autoConnect": true,
"voiceAssistant.voiceMode": "push",
"voiceAssistant.notifications": "important"
}
```
### Keyboard Shortcuts
- `Ctrl+Shift+V` / `Cmd+Shift+V`: Toggle voice assistant
- `Ctrl+Shift+A` / `Cmd+Shift+A`: Ask question
- `Ctrl+Shift+S` / `Cmd+Shift+S`: Take screenshot
- `Ctrl+Shift+H` / `Cmd+Shift+H`: Show media history
---
## Troubleshooting
### Common Issues
#### 1. "MCP Server not found" in Claude Desktop
**Solution**: Verify path in config file and restart Claude Desktop
```bash
# Test server directly
python3 -m src.server
# Check for errors
```
#### 2. "Database locked" error
**Solution**: Close other instances and clear lock
```bash
# Find and kill python processes
ps aux | grep python
kill -9 [PID]
# Remove lock file if exists
rm .claude-symbols/*.db-shm
rm .claude-symbols/*.db-wal
```
#### 3. Voice recognition not working
**Solution**:
- Use Chrome or Edge browser
- Check microphone permissions
- Ensure HTTPS or localhost connection
#### 4. Import errors for sentence-transformers
**Solution**:
```bash
pip uninstall sentence-transformers torch
pip install --no-cache-dir sentence-transformers torch
```
#### 5. WSL performance issues
**Solution**: Move project to WSL filesystem
```bash
# Move from Windows to WSL
cp -r /mnt/c/path/to/project ~/projects/
cd ~/projects/project
```
### Debug Mode
Enable debug logging:
```bash
# Set environment variable
export SCS_DEBUG=true
# Or in .env file
SCS_DEBUG=true
# Run with verbose output
python3 -m src.server --debug
```
### Log Files
Check logs for errors:
- Server logs: `logs/server.log`
- Voice assistant: `voice-assistant/logs/`
- VS Code extension: Help → Toggle Developer Tools
---
## Verification
### Test Complete Installation
```bash
# 1. Test Python environment
python3 scripts/test_install.py
# 2. Test database
python3 scripts/verify_index.py
# 3. Test MCP tools
python3 scripts/test_tools.py
# 4. Test voice assistant
cd voice-assistant
npm test
# 5. Full system test
python3 scripts/integration_test.py
```
### Expected Output
```
✅ Python version: 3.11.0
✅ All dependencies installed
✅ Database initialized
✅ Embedding model loaded
✅ MCP server responding
✅ Voice assistant connected
✅ VS Code extension active
✅ All systems operational
```
---
## Updating
### Update to Latest Version
```bash
# Pull latest changes
git pull origin main
# Update Python dependencies
pip install -r requirements.txt --upgrade
# Update Node dependencies
cd voice-assistant
npm update
# Rebuild VS Code extension
cd vscode-extension
npm run compile
# Re-index if needed
python scripts/reindex.py
```
---
## Uninstallation
### Complete Removal
```bash
# 1. Remove from Claude Desktop config
# Edit claude_desktop_config.json and remove scs-mcp entry
# 2. Uninstall VS Code extension
code --uninstall-extension voice-assistant
# 3. Remove project directory
rm -rf /path/to/scs-mcp
# 4. Remove virtual environment
rm -rf venv/
# 5. Clear cache
rm -rf ~/.cache/scs-mcp
```
---
## Support
### Getting Help
- **Documentation**: [/docs](./docs/)
- **GitHub Issues**: [Report bugs](https://github.com/yourusername/scs-mcp/issues)
- **Discord**: [Join community](https://discord.gg/scs-mcp)
### Diagnostic Information
When reporting issues, include:
```bash
# Generate diagnostic report
python scripts/diagnostic.py > diagnostic.txt
```
Include:
1. Operating system and version
2. Python version
3. Node.js version (if using voice assistant)
4. Claude Desktop version
5. Error messages from logs
6. Output of diagnostic script