# Installation Guide - Project Mind MCP

Complete installation guide for all platforms.

---

## System Requirements

### Minimum Requirements
- **Node.js:** 18.0.0 or higher
- **Memory:** 2GB RAM minimum
- **Disk Space:** 500MB for MCP server + database
- **Operating System:** Windows 10+, macOS 11+, or Linux (Ubuntu 20.04+)

### Recommended Requirements
- **Node.js:** 20.0.0 or higher (LTS)
- **Memory:** 4GB RAM
- **Disk Space:** 2GB (for large project indexing)
- **SSD recommended** for database performance

---

## Installation Methods

### Method 1: NPM Package (Recommended)

```bash
npm install -g project-mind-mcp
project-mind-mcp setup
```

### Method 2: From Source

```bash
git clone https://github.com/yourusername/project-mind-mcp.git
cd project-mind-mcp
npm install
npm run build
npm run install:claude
```

### Method 3: Docker (Coming Soon)

```bash
docker pull project-mind/mcp-server
docker run -v ~/.claude:/config project-mind/mcp-server
```

---

## Platform-Specific Instructions

### Windows

**1. Install Node.js**
```powershell
# Using winget
winget install OpenJS.NodeJS.LTS

# Or download from nodejs.org
```

**2. Install Project Mind**
```powershell
cd "D:\Project Mind"
git clone <repository>
cd project-mind-mcp
npm install
npm run build
```

**3. Configure Claude Desktop**
```powershell
npm run install:claude
# Or manually edit: %APPDATA%\Claude\claude_desktop_config.json
```

**4. Verify Installation**
```powershell
npm run validate
```

### macOS

**1. Install Node.js**
```bash
# Using Homebrew
brew install node@20

# Or download from nodejs.org
```

**2. Install Project Mind**
```bash
cd ~/Projects
git clone <repository>
cd project-mind-mcp
npm install
npm run build
```

**3. Configure Claude Desktop**
```bash
npm run install:claude
# Or manually edit: ~/Library/Application Support/Claude/claude_desktop_config.json
```

**4. Verify Installation**
```bash
npm run validate
```

### Linux (Ubuntu/Debian)

**1. Install Node.js**
```bash
# Using NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify
node --version
npm --version
```

**2. Install Project Mind**
```bash
cd ~/projects
git clone <repository>
cd project-mind-mcp
npm install
npm run build
```

**3. Configure Claude Desktop**
```bash
npm run install:claude
# Or manually edit: ~/.config/Claude/claude_desktop_config.json
```

**4. Verify Installation**
```bash
npm run validate
```

---

## Post-Installation Setup

### 1. Database Initialization

The database is automatically created on first run at:
- Windows: `D:\Project Mind\project-mind-mcp\data\project-mind.db`
- macOS/Linux: `~/project-mind-mcp/data/project-mind.db`

**Manual initialization:**
```bash
mkdir -p data
# Database will be created on first MCP connection
```

### 2. Environment Variables (Optional)

Create `.env` file:
```env
PROJECT_MIND_DB_PATH=./data/project-mind.db
PROJECT_MIND_LOG_LEVEL=info
PROJECT_MIND_PROFILE=false
PROJECT_MIND_MAX_FILE_SIZE=10
```

### 3. Test Connection

Restart Claude Desktop and type:
```
Use Project Mind to list all registered projects
```

---

## Upgrading

### From NPM
```bash
npm update -g project-mind-mcp
```

### From Source
```bash
cd project-mind-mcp
git pull
npm install
npm run build
```

**Database Migration:**
Database migrations are automatic. Backup first:
```bash
cp data/project-mind.db data/project-mind-backup.db
```

---

## Uninstallation

### Remove MCP Server
```bash
# If installed via NPM
npm uninstall -g project-mind-mcp

# If installed from source
rm -rf project-mind-mcp
```

### Remove Configuration
```bash
# Windows
del %APPDATA%\Claude\claude_desktop_config.json

# macOS/Linux
rm ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

### Remove Database (Optional)
```bash
rm -rf project-mind-mcp/data
```

---

## Troubleshooting Installation

### Problem: Node.js version mismatch

**Error:** "Requires Node.js >=18.0.0"

**Solution:**
```bash
# Check version
node --version

# Upgrade Node.js
# Windows: winget upgrade OpenJS.NodeJS.LTS
# macOS: brew upgrade node
# Linux: See NodeSource instructions
```

### Problem: npm install fails

**Error:** "EACCES: permission denied"

**Solution:**
```bash
# Don't use sudo with npm
# Configure npm prefix
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

# Or use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
```

### Problem: Build fails

**Error:** "Cannot find module 'typescript'"

**Solution:**
```bash
npm install --save-dev typescript
npm run build
```

### Problem: Claude Desktop doesn't see MCP

**Error:** No tools available

**Solution:**
1. Check config file syntax: `cat <config-file> | jq .`
2. Verify path: `node <path-to-dist/index.js>`
3. Check logs: `cat %APPDATA%\Claude\logs\mcp.log`
4. Completely restart Claude Desktop

---

## Advanced Installation

### Custom Installation Path

```bash
cd /custom/path
git clone <repository>
cd project-mind-mcp
npm install
npm run build

# Update config manually with custom path
```

### Development Installation

```bash
git clone <repository>
cd project-mind-mcp
npm install

# Watch mode for development
npm run dev

# In separate terminal
npm test:watch
```

### Multi-User Installation (Linux)

```bash
# Install globally
sudo npm install -g project-mind-mcp

# Configure per-user
project-mind-mcp setup --user
```

---

## Verification Checklist

After installation, verify:

- ✅ Node.js version >=18: `node --version`
- ✅ npm installed: `npm --version`
- ✅ MCP server built: `ls dist/index.js`
- ✅ Database directory: `ls data/`
- ✅ Config file updated: `cat <config-file>`
- ✅ Claude Desktop restarted
- ✅ Tools available in Claude

**Run automated verification:**
```bash
npm run validate
```

---

**Next:** [Quick Start Guide](QUICK_START.md) | [Integration Guide](INTEGRATION.md)