@michelabboud/visual-forge-mcp 0.6.0 → 0.7.0

package/docs/guides/provider-setup.md

@@ -0,0 +1,543 @@
+# Visual Forge MCP - Provider Setup Guide
+
+Complete guide for configuring AI image generation providers in Visual Forge MCP.
+
+---
+
+## 🎯 Overview
+
+Visual Forge MCP supports **7 AI image generation providers**. You need to configure at least one provider to generate images.
+
+**✅ Server now starts without providers configured** - you can set them up after the server is running!
+
+---
+
+## 📋 Available Providers
+
+| Provider | Cost/Image | Quality | Speed | Free Tier | Recommended For |
+|----------|-----------|---------|-------|-----------|-----------------|
+| **Google Gemini** | $0.039 | Good | Fast | Yes | General use, testing |
+| **Replicate FLUX** | $0.003 | Excellent | Medium | Pay-as-go | Cost-effective production |
+| **OpenAI DALL-E 3** | $0.04-$0.12 | Excellent | Medium | No | High-quality production |
+| **Stability AI** | $0.04 | Very Good | Fast | No | Bulk generation |
+| **xAI Grok 2** | $0.07 | Good | Fast | No | Modern architecture |
+| **Leonardo Phoenix** | $0.02 | Very Good | Medium | Credits | Design work |
+| **HuggingFace** | Free-$0.01 | Varies | Varies | Yes | Experimentation |
+
+---
+
+## 🔑 Setup Methods
+
+Visual Forge MCP supports **3 configuration methods**. Choose what works best for your scenario:
+
+### Method 1: Environment Variables (Recommended)
+
+**✅ Best for:**
+- Claude Code CLI
+- Security-conscious users
+- CI/CD pipelines
+- Multiple tools sharing keys
+
+**Pros:**
+- Most secure (not in plain text files)
+- Works across all tools
+- Easy to manage
+- Standard practice
+
+**Cons:**
+- Requires shell restart
+- Need to set for each terminal session (unless in .bashrc)
+
+**Setup:**
+
+```bash
+# Option A: Add to ~/.bashrc or ~/.zshrc (permanent)
+echo 'export GOOGLE_API_KEY="AIza..."' >> ~/.bashrc
+echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
+source ~/.bashrc
+
+# Option B: Set for current session only (temporary)
+export GOOGLE_API_KEY="AIza..."
+export OPENAI_API_KEY="sk-..."
+
+# Option C: Use .env file in project directory
+# Create .env file in /home/michel/projects/visual-forge-mcp/
+cat > .env << 'EOF'
+GOOGLE_API_KEY=AIza...
+OPENAI_API_KEY=sk-...
+STABILITY_API_KEY=sk-...
+REPLICATE_API_TOKEN=r8_...
+XAI_API_KEY=xai-...
+LEONARDO_API_KEY=...
+HUGGINGFACE_API_KEY=hf_...
+EOF
+```
+
+**Verify:**
+```bash
+echo $GOOGLE_API_KEY  # Should show your key
+```
+
+### Method 2: MCP Tool (Interactive)
+
+**✅ Best for:**
+- Claude Desktop (GUI clients)
+- Beginners
+- Quick setup
+- Testing different providers
+
+**Pros:**
+- Works immediately
+- No shell configuration needed
+- Can be done after server starts
+- Easy to change providers
+
+**Cons:**
+- Keys stored in plain text (`~/.visual-forge-mcp/config.json`)
+- Need to use MCP tool for each provider
+- Requires MCP client support
+
+**Setup:**
+
+In your MCP client (Claude Code, Claude Desktop, etc.), use these tools:
+
+```
+# Check current configuration
+Use tool: get_provider_status
+
+# Configure a provider
+Use tool: configure_provider
+  provider: gemini
+  apiKey: AIza...
+
+# Test the provider
+Use tool: test_provider_connection
+  provider: gemini
+
+# Check status again
+Use tool: get_provider_status
+```
+
+**Available MCP Tools:**
+- `configure_provider` - Add/update API key
+- `get_provider_status` - Show configured providers
+- `test_provider_connection` - Test if key works
+- `remove_provider` - Remove API key
+
+### Method 3: MCP Client Config (Automatic)
+
+**✅ Best for:**
+- Claude Code with environment variables
+- Centralized configuration
+- Team setups
+
+**Pros:**
+- Automatic passthrough of environment variables
+- Centralized in MCP client config
+- Works for all MCP servers
+
+**Cons:**
+- Requires editing MCP client settings
+- Still needs environment variables set
+
+**Setup for Claude Code:**
+
+Edit `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "visual-forge": {
+      "command": "node",
+      "args": ["/path/to/visual-forge-mcp/dist/index.js"],
+      "env": {
+        "GOOGLE_API_KEY": "${GOOGLE_API_KEY}",
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+        "STABILITY_API_KEY": "${STABILITY_API_KEY}",
+        "REPLICATE_API_TOKEN": "${REPLICATE_API_TOKEN}",
+        "XAI_API_KEY": "${XAI_API_KEY}",
+        "LEONARDO_API_KEY": "${LEONARDO_API_KEY}",
+        "HUGGINGFACE_API_KEY": "${HUGGINGFACE_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+Then set environment variables in your shell (Method 1).
+
+---
+
+## 🔐 Getting API Keys
+
+### Google Gemini (Recommended)
+1. Visit: https://ai.google.dev/
+2. Click "Get API Key"
+3. Sign in with Google account
+4. Create new project or select existing
+5. Generate API key
+6. Copy key (starts with `AIza...`)
+
+**Format:** `AIza...` (40 characters)
+
+### Replicate FLUX
+1. Visit: https://replicate.com/
+2. Sign up / Log in
+3. Go to account settings
+4. Generate API token
+5. Copy token (starts with `r8_...`)
+
+**Format:** `r8_...`
+
+### OpenAI DALL-E
+1. Visit: https://platform.openai.com/
+2. Sign up / Log in
+3. Go to API Keys section
+4. Create new secret key
+5. Copy key (starts with `sk-...`)
+
+**Format:** `sk-...` (51+ characters)
+
+### Stability AI
+1. Visit: https://platform.stability.ai/
+2. Sign up / Log in
+3. Go to API Keys
+4. Generate API key
+5. Add credits to account
+6. Copy key (starts with `sk-...`)
+
+**Format:** `sk-...`
+
+### xAI Grok
+1. Visit: https://console.x.ai/
+2. Sign up / Log in
+3. Go to API Keys
+4. Generate new key
+5. Copy key (starts with `xai-...`)
+
+**Format:** `xai-...`
+
+### Leonardo.ai
+1. Visit: https://leonardo.ai/
+2. Sign up / Log in
+3. Go to API Settings
+4. Generate API key
+5. Copy key
+
+**Format:** Varies
+
+### HuggingFace
+1. Visit: https://huggingface.co/
+2. Sign up / Log in
+3. Go to Settings → Access Tokens
+4. Create new token with "Read" permission
+5. Copy token (starts with `hf_...`)
+
+**Format:** `hf_...`
+
+---
+
+## 🎯 Complete Setup Examples
+
+### Example 1: Quick Start with Gemini (Free)
+
+**Using Environment Variables:**
+```bash
+# 1. Get Gemini API key from https://ai.google.dev/
+# 2. Add to shell config
+echo 'export GOOGLE_API_KEY="AIza..."' >> ~/.bashrc
+source ~/.bashrc
+
+# 3. Restart MCP server or Claude Code
+# 4. Test
+# In Claude: "Check provider status"
+```
+
+**Using MCP Tool:**
+```
+1. Start MCP server (it will start in setup mode)
+2. In Claude Code: "Configure Gemini provider"
+3. Tool: configure_provider
+   - provider: gemini
+   - apiKey: AIza...
+4. Tool: test_provider_connection
+   - provider: gemini
+5. Start generating images!
+```
+
+### Example 2: Production Setup (Multiple Providers)
+
+```bash
+# Add to ~/.bashrc for permanent setup
+cat >> ~/.bashrc << 'EOF'
+# Visual Forge MCP Providers
+export GOOGLE_API_KEY="AIza..."              # Primary (free)
+export REPLICATE_API_TOKEN="r8_..."          # Fallback (cheap)
+export OPENAI_API_KEY="sk-..."               # High quality
+export STABILITY_API_KEY="sk-..."            # Bulk generation
+EOF
+
+source ~/.bashrc
+
+# Verify
+echo $GOOGLE_API_KEY
+echo $REPLICATE_API_TOKEN
+
+# Restart Claude Code
+```
+
+### Example 3: Testing Setup (Temporary)
+
+```bash
+# Set for current terminal session only
+export GOOGLE_API_KEY="AIza..."
+export REPLICATE_API_TOKEN="r8_..."
+
+# Start Claude Code from this terminal
+claude
+
+# Keys will be available for this session
+# Will be gone when you close terminal
+```
+
+### Example 4: CI/CD Setup
+
+```yaml
+# GitHub Actions example
+name: Generate Documentation Images
+
+on: [push]
+
+jobs:
+  generate-images:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+
+      - name: Install Visual Forge MCP
+        run: npm install -g @michelabboud/visual-forge-mcp
+
+      - name: Generate Images
+        env:
+          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+        run: |
+          # Your image generation workflow
+          visual-forge-mcp generate docs/
+```
+
+---
+
+## 🔍 Verification & Testing
+
+### Check Configuration Status
+
+**Using MCP Tool:**
+```
+Tool: get_provider_status
+```
+
+**Output:**
+```json
+{
+  "gemini": { "configured": true, "source": "environment" },
+  "openai": { "configured": true, "source": "config_file" },
+  "stability": { "configured": false },
+  "replicate": { "configured": false },
+  "xai": { "configured": false },
+  "leonardo": { "configured": false },
+  "huggingface": { "configured": false }
+}
+```
+
+### Test Provider Connection
+
+```
+Tool: test_provider_connection
+  provider: gemini
+```
+
+**Success:**
+```json
+{
+  "success": true,
+  "provider": "gemini",
+  "message": "Google Gemini connection successful!"
+}
+```
+
+**Failure:**
+```json
+{
+  "success": false,
+  "provider": "gemini",
+  "error": "Invalid API key"
+}
+```
+
+---
+
+## ⚙️ Environment Variables Reference
+
+### Required (at least one)
+
+| Variable | Provider | Format | Example |
+|----------|----------|--------|---------|
+| `GOOGLE_API_KEY` | Google Gemini | `AIza...` | `AIza...abc123` |
+| `REPLICATE_API_TOKEN` | Replicate FLUX | `r8_...` | `r8_abc123...` |
+| `OPENAI_API_KEY` | OpenAI DALL-E | `sk-...` | `sk-proj-abc123...` |
+| `STABILITY_API_KEY` | Stability AI | `sk-...` | `sk-abc123...` |
+| `XAI_API_KEY` | xAI Grok | `xai-...` | `xai-abc123...` |
+| `LEONARDO_API_KEY` | Leonardo | Various | `abc123...` |
+| `HUGGINGFACE_API_KEY` | HuggingFace | `hf_...` | `hf_abc123...` |
+
+### Optional Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `IMAGE_GEN_OUTPUT_DIR` | `./generated-images` | Where images are saved |
+| `IMAGE_GEN_STATE_DIR` | `~/.visual-forge-mcp` | State/config storage |
+| `IMAGE_GEN_LOG_LEVEL` | `info` | Log level (debug/info/warn/error) |
+| `IMAGE_GEN_DEFAULT_PROVIDER` | `gemini` | Default provider to use |
+| `IMAGE_OPTIMIZATION_ENABLED` | `true` | Enable web optimization |
+| `IMAGE_OPTIMIZATION_QUALITY` | `85` | Optimization quality (1-100) |
+| `IMAGE_OPTIMIZATION_FORMAT` | `webp` | Format (webp/jpeg/png) |
+
+---
+
+## 🛠️ Troubleshooting
+
+### Server won't start
+
+**Error:** "No providers configured"
+
+**This should not happen anymore!** The server now starts in setup mode.
+
+If you still see this error:
+1. Update to latest version: `npm install -g @michelabboud/visual-forge-mcp@latest`
+2. Rebuild: `cd visual-forge-mcp && npm run build`
+
+### "Provider not configured" when generating
+
+**This is expected!** You need to configure at least one provider.
+
+**Solutions:**
+1. Use `configure_provider` MCP tool
+2. Set environment variables and restart server
+3. Check configuration: `get_provider_status`
+
+### API key not working
+
+```
+Tool: test_provider_connection
+  provider: gemini
+```
+
+**Common issues:**
+- Key has wrong format (check format in table above)
+- Key was copied with extra spaces
+- Key expired or was revoked
+- API key permissions insufficient
+- Account has no credits (Stability AI)
+
+### Environment variables not loading
+
+```bash
+# Check if set
+echo $GOOGLE_API_KEY
+
+# If empty, check where it's defined
+grep GOOGLE_API_KEY ~/.bashrc ~/.zshrc ~/.profile
+
+# Make sure to source the file
+source ~/.bashrc
+
+# Restart terminal or Claude Code
+```
+
+### Config file location
+
+```bash
+# Check config file
+cat ~/.visual-forge-mcp/config.json
+
+# If doesn't exist, it's normal
+# Keys are only saved here when using configure_provider tool
+```
+
+---
+
+## 🔒 Security Best Practices
+
+1. **Never commit API keys to git**
+   ```bash
+   # Add to .gitignore
+   echo ".env" >> .gitignore
+   echo ".env.*" >> .gitignore
+   ```
+
+2. **Use environment variables for production**
+   - More secure than config files
+   - Standard practice
+   - Easy to rotate
+
+3. **Restrict API key permissions**
+   - Only grant necessary permissions
+   - Use separate keys for dev/prod
+   - Rotate keys regularly
+
+4. **Monitor usage**
+   - Check provider dashboards regularly
+   - Set up billing alerts
+   - Track costs with Visual Forge cost tracking
+
+5. **Use config file only for testing**
+   - Convenient for development
+   - Keys stored in `~/.visual-forge-mcp/config.json`
+   - Make sure file permissions are restrictive: `chmod 600 ~/.visual-forge-mcp/config.json`
+
+---
+
+## 📚 Quick Reference
+
+### Setup Checklist
+
+- [ ] Choose at least one provider
+- [ ] Get API key from provider website
+- [ ] Choose setup method (env vars recommended)
+- [ ] Configure provider
+- [ ] Test connection
+- [ ] Verify with `get_provider_status`
+- [ ] Start generating images!
+
+### Common Commands
+
+```bash
+# Environment variables
+export GOOGLE_API_KEY="AIza..."
+source ~/.bashrc
+
+# MCP Tools (in Claude)
+configure_provider
+get_provider_status
+test_provider_connection
+remove_provider
+
+# Verification
+echo $GOOGLE_API_KEY
+cat ~/.visual-forge-mcp/config.json
+```
+
+### Getting Help
+
+- **Documentation**: [README.md](../../README.md)
+- **GitHub Issues**: https://github.com/michelabboud/visual-forge-mcp/issues
+- **Provider Docs**: Links in "Getting API Keys" section above
+
+---
+
+**Last Updated:** 2026-01-15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michelabboud/visual-forge-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "MCP server for AI image generation from markdown and HTML with multi-provider support and automatic web optimization",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,7 @@
     "test:watch": "jest --watch",
     "lint": "eslint src --ext .ts",
     "clean": "rm -rf dist",
-    "prepublishOnly": "npm run clean && npm run build",
+    "prepublishOnly": "npm run clean && npm run build && npm test",
     "pricing:show": "node scripts/update-pricing.js show",
     "pricing:update": "node scripts/update-pricing.js update",
     "pricing:check": "node scripts/update-pricing.js check",