Optimizely MCP Server - Installation Guide

🚀 Installation Methods

Both methods work reliably now that we've resolved binary compatibility issues. We recommend local installation to avoid potential NPX caching issues.

📋 Quick Installation Matrix

| Method | Reliability | Cache Issues | Setup Complexity | Team Use | Recommended For | |--------|-------------|--------------|------------------|----------|-----------------| | Local Installation | ✅ 99%+ | ✅ None | 📝 Medium | ✅ Excellent | Production, Teams, CI/CD | | NPX Direct | ✅ 95%+ | ⚠️ Possible | 📝 Simple | ⚠️ Variable | Quick Testing, Individual Use |

🥇 Method 1: Local Installation (Recommended)

✅ Best for: Production environments, team consistency, CI/CD pipelines

Step 1: Install Package

npm install @simonecoelhosfo/optimizely-mcp-server

Step 2: Copy Documentation & Setup Scripts

node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly setup-docs

✨ This automatically:

• Creates optimizely-mcp-docs/ folder with complete documentation
• Creates optly-npx-fix.cjs convenience script
• Updates your package.json with optly scripts for team use

Step 3: Essential Commands

# Core commands (note the 'node' prefix)
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly health
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly --version
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly sync status

Step 4: Configure Your AI Client

For WSL/Linux/macOS (with ./ prefix):

{
  "mcpServers": {
    "optimizely": {
      "command": "node",
      "args": ["./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly"],
      "env": {
        "NODE_ENV": "production",
        "MCP_MODE": "true",
        "OPTIMIZELY_API_TOKEN": "your-token-here",
        "OPTIMIZELY_PROJECT_IDS": "project1,project2"
      }
    }
  }
}

For Windows (without ./ prefix):

{
  "mcpServers": {
    "optimizely": {
      "command": "node",
      "args": ["node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly"],
      "env": {
        "NODE_ENV": "production",
        "MCP_MODE": "true",
        "OPTIMIZELY_API_TOKEN": "your-token-here",
        "OPTIMIZELY_PROJECT_IDS": "project1,project2"
      }
    }
  }
}

Convenience Scripts (Auto-generated)

After running setup-docs, these scripts are automatically added to your package.json:

npm run optly              # General optly command
npm run optly-health       # Health check
npm run optly-sync         # Check sync status
npm run optly-analytics    # Show analytics templates
npm run optly-entity-flags # Show flag templates

🥈 Method 2: NPX Direct

✅ Good for: Quick testing, individual development, one-off usage

⚠️ Note on NPX Caching: NPX occasionally has caching issues. If you encounter problems, clear NPX cache with npx clear-npx-cache or use local installation.

Basic Usage

npx @simonecoelhosfo/optimizely-mcp-server setup-docs
npx @simonecoelhosfo/optimizely-mcp-server health
npx @simonecoelhosfo/optimizely-mcp-server --version
npx @simonecoelhosfo/optimizely-mcp-server sync status

Configuration for Claude Desktop

{
  "mcpServers": {
    "optimizely": {
      "command": "npx",
      "args": ["-y", "@simonecoelhosfo/optimizely-mcp-server"],
      "env": {
        "NODE_ENV": "production",
        "MCP_MODE": "true",
        "OPTIMIZELY_API_TOKEN": "your-token-here",
        "OPTIMIZELY_PROJECT_IDS": "project1,project2"
      }
    }
  }
}

Configuration for Cursor

{
  "mcpServers": {
    "optimizely": {
      "command": "npx",
      "args": ["-y", "@simonecoelhosfo/optimizely-mcp-server"],
      "env": {
        "NODE_ENV": "production",
        "MCP_MODE": "true",
        "OPTIMIZELY_API_TOKEN": "your-token-here",
        "OPTIMIZELY_PROJECT_IDS": "project1,project2"
      }
    }
  }
}

If NPX Cache Issues Occur

Follow NPX's official troubleshooting guide:

# Clear NPX cache
npx clear-npx-cache

# Or use NPX with --cache flag
npx --cache ./tmp-npx-cache @simonecoelhosfo/optimizely-mcp-server health

# If persistent issues occur, switch to local installation
npm install @simonecoelhosfo/optimizely-mcp-server

🎯 Which Method Should You Choose?

✅ Choose Local Installation (Method 1) for:

• 🏢 Production environments - Maximum reliability and consistency
• 👥 Team development - Everyone uses the same setup and scripts
• 🤖 CI/CD pipelines - Avoid any caching-related build failures
• 🔒 Enterprise environments - Better control over dependencies
• 📦 Package.json scripts - Team convenience with npm run commands

✅ Choose NPX (Method 2) for:

• ⚡ Quick testing - Fast setup for trying the server
• 👤 Individual development - Personal projects or exploration
• 🔧 One-off usage - Temporary testing or evaluation
• 📦 Simple setups - Don't want to add to package.json

🔧 Node.js Compatibility

| Node.js Version | Local Installation | NPX Method | Recommended | |----------------|-------------------|------------|-------------| | v22.x | ✅ Excellent | ✅ Excellent | Either method | | v20.x | ✅ Excellent | ✅ Very Good | Either method | | v18.x | ✅ Excellent | ✅ Good | Local preferred | | v16.x | ⚠️ Limited | ⚠️ Limited | Upgrade Node.js |

✅ Verification Steps

Test Your Installation

# Test 1: Health Check
# NPX method:
npx @simonecoelhosfo/optimizely-mcp-server health

# Local method:
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly health

# Expected output:
# ✅ Optimizely MCP Server Health Check
# 📊 Status: Healthy
# 🔄 Cache: Ready
# 🌐 API: Connected

Test Documentation Setup

# This should create optimizely-mcp-docs/ folder
npx @simonecoelhosfo/optimizely-mcp-server setup-docs
# OR
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly setup-docs

# Verify created files:
ls optimizely-mcp-docs/
# Should show: README.md, QUICK-START.md, docs/, templates/, agent-rules/

🔄 Migration Between Methods

From NPX to Local Installation

If you want to switch from NPX to local installation:

# 1. Install locally
npm install @simonecoelhosfo/optimizely-mcp-server

# 2. Update your MCP configuration from:
# "command": "npx", "args": ["-y", "@simonecoelhosfo/optimizely-mcp-server"]
# To:
# "command": "node", "args": ["./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly"]

# 3. Test the change
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly health

From Local to NPX

If you want to switch from local to NPX:

# 1. Update your MCP configuration from:
# "command": "node", "args": ["./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly"]
# To:
# "command": "npx", "args": ["-y", "@simonecoelhosfo/optimizely-mcp-server"]

# 2. Test the change
npx @simonecoelhosfo/optimizely-mcp-server health

🚀 Essential Commands Reference

Core Commands

# Health and version checks
optly health                    # System health check
optly --version                 # Show version
optly --help                    # Show all commands

# Documentation setup
optly setup-docs                # Copy docs and create convenience scripts

# Data synchronization
optly sync status               # Check sync status
optly sync refresh              # Refresh data cache

# Analytics and templates
optly analytics templates       # Show analytics query templates
optly entity templates flag     # Show flag creation templates
optly entity templates experiment # Show experiment templates

Using Different Methods

# NPX method:
npx @simonecoelhosfo/optimizely-mcp-server [command]

# Local method:
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly [command]

# NPX fix script (after setup-docs):
node optly-npx-fix.cjs optly [command]

# Package.json scripts (after setup-docs):
npm run optly-health
npm run optly-sync
npm run optly-analytics

🛠️ Troubleshooting

NPX Cache Issues

# If NPX behaves unexpectedly:
npx clear-npx-cache
npx @simonecoelhosfo/optimizely-mcp-server health

# If cache issues persist, use local installation:
npm install @simonecoelhosfo/optimizely-mcp-server

Command Not Found

# For local installation, always use 'node' prefix:
✅ node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly health
❌ ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly health

Path Issues (Windows vs Unix)

• Windows: Use node_modules/... (no ./ prefix)
• WSL/Linux/macOS: Use ./node_modules/... (with ./ prefix)

📚 After Setup: Generated Documentation

After running setup-docs, you'll have a complete documentation suite:

optimizely-mcp-docs/
├── README.md                   # Package overview
├── QUICK-START.md              # 5-minute getting started guide
├── docs/                       # Complete documentation
│   ├── cli/                   # CLI usage guides
│   ├── user-guides/           # Feature documentation
│   └── api-reference/         # Technical reference
├── templates/                  # Configuration examples
│   ├── claude-config.json     # Claude Desktop setup
│   └── cursor-config.json     # Cursor IDE setup
└── agent-rules/               # AI assistant optimization rules

Key Files to Review:

• QUICK-START.md - Start here for immediate productivity
• templates/claude-config.json - Claude Desktop configuration
• templates/cursor-config.json - Cursor IDE configuration
• docs/README.md - Comprehensive feature overview

🎉 You're Ready!

1. Choose your installation method (local recommended for teams)
2. Run setup-docs to get complete documentation
3. Configure your AI client with the appropriate method
4. Start with a health check to verify everything works
5. Explore the generated documentation for advanced features

🚀 Quick Success Pattern:

# 1. Install (choose one)
npm install @simonecoelhosfo/optimizely-mcp-server  # Recommended
# OR
npx @simonecoelhosfo/optimizely-mcp-server setup-docs  # Quick start

# 2. Setup documentation
node ./node_modules/@simonecoelhosfo/optimizely-mcp-server/bin/optly setup-docs

# 3. Test health
npm run optly-health  # OR: node optly-npx-fix.cjs optly health

# 4. Configure your AI client and start optimizing!

Happy optimizing! 🎯

Last Updated: December 2024
Binary Compatibility: ✅ Resolved - Both methods work reliably
Recommendation: Local installation for teams and production, NPX for quick testing