<<<<<<< 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