slidev-builder-mcp-v2-protected

Version:
Professional Slidev presentation builder with Git Guardian protection, component library, and AI-powered features. Never lose your presentation work again!
github.com/adolfosalasgomez3011/slidev-builder-mcp
adolfosalasgomez3011/slidev-builder-mcp
721 lines (558 loc) • 15.7 kB
Markdown
View Raw
<<<<<<< HEAD
# Slidev Builder MCP - Installation & Setup Guide
=======
# Slidev Builder MCP - Installation Guide
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872

## 📋 Prerequisites

### System Requirements
- **Node.js**: Version 18.0.0 or higher
<<<<<<< HEAD
- **npm**: Version 8.0.0 or higher (comes with Node.js)
- **Python**: Version 3.8+ (for chart generation features)
- **Git**: For version control and cloning repositories

### Verify Prerequisites
```bash
node --version    # Should show v18.0.0+
npm --version     # Should show 8.0.0+
python --version  # Should show 3.8+
git --version     # Any recent version
```

---

=======
- **NPM**: Version 8.0.0 or higher
- **TypeScript**: Version 5.0.0 or higher (for development)
- **Git**: For version control and collaboration

### Optional Dependencies
- **Python**: Version 3.8+ (for chart generation)
- **Chromium**: For PDF export (installed automatically with Slidev)
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872

## 🚀 Installation Methods

### Method 1: Global NPM Installation (Recommended)

```bash
<<<<<<< HEAD
# Install globally for system-wide access
=======
# Install globally
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872
npm install -g @hatch/slidev-builder-mcp

# Verify installation
slidev-builder-mcp --version
<<<<<<< HEAD

# Test basic functionality
slidev-builder-mcp --help
```

### Method 2: Local Project Installation

```bash
# Create new project directory
mkdir my-presentations
cd my-presentations

# Install locally
npm init -y
npm install @hatch/slidev-builder-mcp

# Use via npx
npx slidev-builder-mcp --help
```

### Method 3: Development Installation

```bash
# Clone the repository
git clone https://github.com/hatch-ltd/slidev-builder-mcp.git
=======
```

### Method 2: Local Development Setup

```bash
# Clone the repository
git clone https://github.com/adolfosalasgomez3011/slidev-builder-mcp.git
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872
cd slidev-builder-mcp

# Install dependencies
npm install

# Build the project
npm run build

<<<<<<< HEAD
# Link for global development use
npm link

# Test the development version
slidev-builder-mcp --version
```

---


## ⚙️ MCP Client Configuration

### Claude Desktop Integration

1. **Locate Configuration File**
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. **Add MCP Server Configuration**
```json
{
  "mcpServers": {
    "slidev-builder": {
      "command": "slidev-builder-mcp",
      "args": []
    }
  }
}
```

3. **For Local Installation**
=======
# Test the installation
npm test
```

### Method 3: NPX (No Installation)

```bash
# Run directly with NPX
npx @hatch/slidev-builder-mcp
```

## 🔧 MCP Client Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872
```json
{
  "mcpServers": {
    "slidev-builder": {
      "command": "npx",
      "args": ["@hatch/slidev-builder-mcp"]
    }
  }
}
```

<<<<<<< HEAD
4. **Restart Claude Desktop**
   - Close Claude Desktop completely
   - Restart the application
   - Verify the MCP server appears in tools

### VS Code MCP Extension Integration

1. **Install MCP Extension**
```bash
code --install-extension modelcontextprotocol.mcp
```

2. **Configure in VS Code Settings**
```json
{
  "mcp.servers": {
=======
### VS Code with MCP Extension

Add to your MCP configuration:

```json
{
  "mcpServers": {
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872
    "slidev-builder": {
      "command": "slidev-builder-mcp",
      "args": []
    }
  }
}
```

<<<<<<< HEAD
### Generic MCP Client Configuration

For other MCP clients, use this standard configuration:

```json
{
  "name": "slidev-builder",
  "command": "slidev-builder-mcp",
  "args": [],
  "capabilities": {
    "tools": true,
    "resources": true
  }
}
```

---


## 🐍 Python Setup (Optional but Recommended)

### Install Python Dependencies

The MCP can automatically set up Python environments, but manual setup ensures reliability:

```bash
# Create virtual environment (recommended)
python -m venv slidev-env

# Activate virtual environment
# Windows:
slidev-env\Scripts\activate
# macOS/Linux:
source slidev-env/bin/activate

# Install required packages
pip install matplotlib plotly pandas numpy seaborn jupyter

# Verify installation
python -c "import matplotlib; print('✓ matplotlib')"
python -c "import plotly; print('✓ plotly')"
python -c "import pandas; print('✓ pandas')"
=======
### Custom MCP Client

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'slidev-builder-mcp',
  args: []
});

const client = new Client({
  name: 'slidev-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);
```

## 🐍 Python Integration Setup (Optional)

### Install Python Dependencies

```bash
# Create virtual environment
python -m venv slidev-env
source slidev-env/bin/activate  # On Windows: slidev-env\Scripts\activate

# Install required packages
pip install matplotlib plotly pandas numpy seaborn
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872
```

### Configure Python Path

<<<<<<< HEAD
If using a virtual environment, configure the MCP to use it:

```json
{
  "mcpServers": {
    "slidev-builder": {
      "command": "slidev-builder-mcp",
      "args": [],
      "env": {
        "PYTHON_PATH": "/path/to/slidev-env/bin/python"
      }
    }
  }
}
```

---


## 🎨 Theme Setup

### Install Additional Themes

```bash
# Install official Hatch themes
npm install -g @hatch/slidev-theme-corporate
npm install -g @hatch/slidev-theme-executive
npm install -g @hatch/slidev-theme-technical

# Install community themes
npm install -g @slidev/theme-default
npm install -g @slidev/theme-seriph
```

### Verify Theme Installation

```bash
# List available themes
slidev-builder-mcp list-themes

# Test theme application
slidev-builder-mcp test-theme hatch-corporate
```

---


## 🔧 Development Environment Setup

### IDE Configuration

#### VS Code (Recommended)
1. **Install Extensions**
```bash
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension bradlc.vscode-tailwindcss
code --install-extension vue.volar
code --install-extension ms-python.python
```

2. **Configure Workspace Settings**
```json
{
  "typescript.preferences.useAliasesForRenames": false,
  "typescript.suggest.autoImports": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "files.associations": {
    "*.md": "markdown"
  }
}
```

#### IntelliJ/WebStorm
1. Enable TypeScript support
2. Install Vue.js plugin
3. Configure ESLint and Prettier
4. Set up Markdown preview

### Git Configuration

```bash
# Configure Git for development
git config --global user.name "Your Name"
git config --global user.email "your.email@hatch.com"

# Set up Git hooks (if contributing)
cd slidev-builder-mcp
npm run prepare
```

---


## 🧪 Testing Installation

### Basic Functionality Test

```bash
# Create test directory
mkdir slidev-test
cd slidev-test

# Test basic MCP functionality (if using development setup)
node -e "
const { SlidevBuilderMCP } = require('@hatch/slidev-builder-mcp');
const mcp = new SlidevBuilderMCP();
console.log('✓ MCP loaded successfully');
"
```

### Full Integration Test

Create a test script to verify all features:

```javascript
// test-installation.js
async function testInstallation() {
  try {
    // Test 1: Create a simple deck
    console.log('🧪 Testing deck creation...');
    await mcp.callTool('create_deck', {
      title: 'Installation Test',
      outputPath: './test-deck',
      theme: 'hatch-corporate'
    });
    console.log('✓ Deck creation successful');

    // Test 2: Add a slide
    console.log('🧪 Testing slide addition...');
    await mcp.callTool('create_slide', {
      deckPath: './test-deck',
      slideType: 'content',
      content: {
        title: 'Test Slide',
        body: '- Test point 1\n- Test point 2'
      }
    });
    console.log('✓ Slide addition successful');

    // Test 3: Generate a simple chart
    console.log('🧪 Testing chart generation...');
    await mcp.callTool('generate_chart', {
      chartType: 'bar',
      data: {
        labels: ['A', 'B', 'C'],
        values: [1, 2, 3]
      },
      outputPath: './test-deck',
      styling: { title: 'Test Chart' }
    });
    console.log('✓ Chart generation successful');

    // Test 4: Export to PDF
    console.log('🧪 Testing PDF export...');
    await mcp.callTool('export_deck', {
      deckPath: './test-deck',
      format: 'pdf',
      outputPath: './test-deck.pdf'
    });
    console.log('✓ PDF export successful');

    console.log('\n🎉 All tests passed! Installation is complete.');
    
  } catch (error) {
    console.error('❌ Test failed:', error.message);
    console.log('\n📋 Troubleshooting steps:');
    console.log('1. Verify all prerequisites are installed');
    console.log('2. Check MCP client configuration');
    console.log('3. Ensure Python dependencies are available');
    console.log('4. Review error logs for specific issues');
  }
}

// Run tests
testInstallation();
```

---


## 🔍 Troubleshooting

### Common Installation Issues

#### 1. Node.js Version Incompatibility
```bash
# Error: Unsupported Node.js version
# Solution: Update Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or use Node Version Manager
nvm install 18
nvm use 18
```

#### 2. NPM Permission Issues (Linux/macOS)
```bash
# Error: EACCES permission denied
# Solution: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

#### 3. Python Module Not Found
```bash
# Error: ModuleNotFoundError: No module named 'matplotlib'
# Solution: Install in correct environment
which python  # Verify Python path
pip install matplotlib plotly pandas numpy

# Or use conda
conda install matplotlib plotly pandas numpy
```

#### 4. MCP Server Not Found
```json
// Error: MCP server 'slidev-builder' not found
// Solution: Check Claude config path and syntax
{
  "mcpServers": {
    "slidev-builder": {
      "command": "slidev-builder-mcp",
      "args": []
    }
  }
}
```

#### 5. Port Already in Use
```bash
# Error: Port 3030 already in use
# Solution: Use different port
SLIDEV_PORT=3031 slidev-builder-mcp

# Or kill existing process
lsof -ti:3030 | xargs kill -9
```

### Debug Mode

Enable verbose logging for troubleshooting:

```bash
# Set debug environment variables
export DEBUG=slidev-builder:*
export SLIDEV_DEBUG=true

# Run with debug output
slidev-builder-mcp --verbose

# Check logs
tail -f ~/.slidev-builder/logs/debug.log
```

### Getting Help

1. **Check Documentation**
   - [README.md](./README.md) - Overview and basic usage
   - [API-DOCUMENTATION.md](./API-DOCUMENTATION.md) - Complete API reference
   - [QUICKSTART.md](./QUICKSTART.md) - 5-minute getting started

2. **Community Support**
   - GitHub Issues: Bug reports and feature requests
   - Discussions: Questions and community help
   - Wiki: Community-maintained guides

3. **Hatch Internal Support**
   - Slack: #digital-innovation channel
   - Email: digital-innovation@hatch.com
   - Teams: Weekly office hours

---


## 🔄 Keeping Updated

### Automatic Updates

```bash
# Check for updates
npm outdated -g @hatch/slidev-builder-mcp

# Update to latest version
npm update -g @hatch/slidev-builder-mcp

# Verify update
slidev-builder-mcp --version
```

### Manual Updates

```bash
# Uninstall old version
npm uninstall -g @hatch/slidev-builder-mcp

# Install latest version
npm install -g @hatch/slidev-builder-mcp@latest

# Clear cache if needed
npm cache clean --force
```

### Development Updates

```bash
# Pull latest changes
git pull origin main

# Update dependencies
npm install

# Rebuild
npm run build

# Test changes
npm test
```

---


## 📊 Performance Optimization

### System Optimization

```bash
# Increase Node.js memory limit for large presentations
export NODE_OPTIONS="--max-old-space-size=4096"

# Optimize npm registry
npm config set registry https://registry.npmjs.org/

# Clear npm cache
npm cache clean --force
```

### MCP Configuration Optimization

```json
{
  "mcpServers": {
    "slidev-builder": {
      "command": "slidev-builder-mcp",
      "args": ["--memory-limit", "2048", "--timeout", "30000"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

---


## ✅ Installation Checklist

- [ ] Node.js 18+ installed and verified
- [ ] NPM working correctly
- [ ] Python 3.8+ available (optional)
- [ ] Slidev Builder MCP installed globally
- [ ] MCP client configured (Claude Desktop, VS Code, etc.)
- [ ] Python dependencies installed (if using charts)
- [ ] Basic functionality tested
- [ ] Themes accessible
- [ ] Export functionality working
- [ ] Debug mode accessible if needed

---


**🎉 Congratulations! Your Slidev Builder MCP is now ready for creating professional presentations.**

For next steps, see the [Quick Start Guide](./QUICKSTART.md) or dive into the [Complete API Documentation](./API-DOCUMENTATION.md).
=======
```bash
# Set environment variable
export SLIDEV_PYTHON_PATH="/path/to/your/python"

# Or in Windows
set SLIDEV_PYTHON_PATH="C:\\path\\to\\your\\python.exe"
```

## ✅ Verification

### Test Basic Functionality

```bash
# Create a test presentation
mkdir test-presentation
cd test-presentation

# Initialize with MCP (if using Claude Desktop)
# Or use the API directly
```

### Test with MCP Client

```javascript
// Test the create_deck tool
const result = await mcp.callTool('create_deck', {
  title: 'Test Presentation',
  outputPath: './test-deck',
  theme: 'default'
});

console.log(result);
```

## 🔧 Troubleshooting

### Common Issues

#### Node.js Version Error
```bash
# Check Node.js version
node --version

# Update Node.js if needed
npm install -g n
n latest
```

#### Permission Errors
```bash
# Fix NPM permissions (Linux/Mac)
sudo chown -R $(whoami) ~/.npm

# Or use NPM prefix
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```

#### Python Path Issues
```bash
# Find Python path
which python3
# or
where python

# Set in environment
export SLIDEV_PYTHON_PATH="$(which python3)"
```

### Support

For installation issues:
1. Check the [Troubleshooting Guide](./TROUBLESHOOTING.md)
2. Open an issue on [GitHub](https://github.com/adolfosalasgomez3011/slidev-builder-mcp/issues)
3. Contact the development team

---


🎉 **Installation Complete!** You're ready to create professional presentations with Slidev Builder MCP.
>>>>>>> 4b901da2b8e4bbb10dd10e20f9875a7c2344f872