# Quick Installation Guide

## Prerequisites
- Python 3.8 or higher
- pip (Python package manager)

## Installation Steps

### 1. Create Virtual Environment (Recommended)
```bash
# Navigate to the MCP directory (after extracting the ZIP)
cd hands-on-mcp

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate
```

### 2. Install Python Dependencies
```bash
pip install -r requirements.txt
```

This will install:
- `mcp` - Model Context Protocol core library
- `fastmcp` - Simplified MCP server creation
- `faiss-cpu` - Vector database for similarity search
- `sentence-transformers` - Embedding models
- `numpy` - Numerical computing

### 3. Verify Installation
```bash
# Test Python packages
python3 -c "import mcp; import faiss; import sentence_transformers; print('✅ All packages installed!')"
```

## Running the Workshop

### Option 1: Standalone Scripts

**Step 1 - Generate Vector Database:**
```bash
python3 generate_vector_db.py
```

**Step 2 - Test Search:**
```bash
python3 -c "
from search_vector_db import search_in_faiss
print(search_in_faiss('collaboration principles', top_k=2))
"
```

### Option 2: MCP Server + Client

**Step 1 - Ensure vector database exists:**
```bash
python3 generate_vector_db.py
```

**Step 2 - Run MCP client (starts server automatically):**
```bash
python3 client_vector.py mcp_vector_server.py
```

## Integrating with Claude Desktop

### macOS Configuration

Edit: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vector-db": {
      "command": "python3",
      "args": ["/path/to/hands-on-mcp/mcp_vector_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/hands-on-mcp"
      }
    }
  }
}
```

**Important:** Replace `/path/to/hands-on-mcp` with the actual path where you extracted the workshop files.

Restart Claude Desktop to activate the MCP server.

## Troubleshooting

### Issue: "ModuleNotFoundError: No module named 'mcp'"
```bash
# Ensure virtual environment is activated
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Reinstall requirements
pip install -r requirements.txt
```

### Issue: "FAISS index not found"
```bash
# Generate the index first
python3 generate_vector_db.py
```

### Issue: "MCP server not responding"
**Solutions:**
1. Check if the server script path is correct
2. Ensure Python 3.8+ is being used
3. Check server logs in stderr
4. Verify all dependencies are installed

### Issue: "Dimension mismatch"
```bash
# Delete old index and regenerate
rm -rf faiss_index/
python3 generate_vector_db.py
```

## Next Steps

Refer to the [README.md](./README.md) for detailed explanations of each component and advanced usage.
