optly-mcp-server

v2.0.4

Published

7 months ago

Enterprise-grade MCP server for Optimizely Feature and Web Experimentation platforms with AI-powered natural language interface, comprehensive security, and performance optimization

0High
0Medium
0Low

simonecoelhosfo

optimizely mcp model-context-protocol ai experimentation feature-flags ab-testing claude cursor anthropic typescript enterprise security performance

Optimizely MCP Server

Transform how you interact with Optimizely through AI-powered natural language queries

🎯 What is This?

The Optimizely MCP Server is an AI-powered interface that enables natural language interaction with your Optimizely experimentation platform. Instead of clicking through multiple UI screens, simply ask your AI assistant questions like:

"Show me all running experiments"
"Which feature flags changed this week?"
"Compare flag configurations between staging and production"
"What experiments are targeting mobile users?"

✨ Key Features

🚀 Unified Access

27 MCP tools covering 100+ API endpoints with 100% Rest API coverage
Single interface for both Feature Experimentation and Web Experimentation platforms
Automatic platform detection and routing with smart routing system
Consistent commands across all entity types
Direct integration support - Use without MCP transport for custom AI models

🧠 AI-Powered Intelligence

Natural language queries - no need to learn APIs
Context-aware responses with mandatory workflow enforcement
Revolutionary Entity Relationship Documentation Matrix preventing common AI mistakes
Intelligent relationship mapping between entities with anti-pattern detection
Template-based creation with auto-detection and rollback capabilities
Intelligent Payload Parser - Automatic fixing of malformed API payloads

📊 Comprehensive Coverage

25+ entity types: Flags, experiments, campaigns, audiences, collaborators, groups, and more
Cross-entity analysis: Connect flags to experiments to results
Real-time insights: Live data with automatic caching and change tracking
Built-in caching: SQLite-based cache with incremental sync support

🛡️ Production Considerations

Basic security: HTTPS API communication with token-based auth
Performance features: Built-in caching and incremental sync
Comprehensive documentation: Troubleshooting guides and best practices
Active development: Regular updates and community support

📊 Advanced Analytics Engine

Natural Language Queries: "Show flags with CDN settings in production"
Intelligent Query Engine: Multi-entity JOINs, aggregations, date functions
Query Result Caching: 90% performance improvement with smart invalidation
Structured Queries: Filter, group, aggregate, and transform your data
Pre-built Templates: Common analyses like variable usage, complexity detection
JSONata Transformations: Powerful data shaping and filtering
🚀 Coming Soon: Dynamic JSON Query Engine - Query ANY field from the API schema without limitations

🎯 Entity Relationship Intelligence

Comprehensive entity documentation matrix - Prevents AI agent confusion about entity independence
Mandatory workflow enforcement - Ensures proper entity calls instead of embedded data extraction
Anti-pattern detection - Blocks common mistakes like confusing variable definitions with variable values
Context-aware error messages - Guides to correct entity operations
Prescriptive error handling - Step-by-step resolution for dependency issues

🔄 Entity Migration (NEW!)

Copy entities between projects - Migrate flags, experiments, audiences, and more
Intelligent dependency resolution - Automatically handles entity relationships
Reference transformation - Updates all IDs/keys for the destination project
Progress tracking - Real-time progress bars with checkpoint/resume capability
Flexible migration options - Dry-run, selective migration, conflict resolution
Complete Migration Guide - Step-by-step instructions

🚀 Quick Start

👉 GET STARTED - Complete Setup Guide

New to the Optimizely MCP Server? Start here for a complete walkthrough from zero to working in 15 minutes.

The GET STARTED guide provides:

✅ Platform detection - Choose Cursor IDE or Claude Desktop
✅ Step-by-step setup with validation checkpoints
✅ Platform-specific configuration for your AI tool
✅ First successful queries to verify everything works
✅ Troubleshooting for common issues

Already familiar? Quick installation:

# 1. Clone and install
git clone https://github.com/anthropics/optly-mcp-server.git
cd optly-mcp-server && npm install

# 2. Configure your API token
# Configuration is handled via MCP client config (see setup guides)

# 3. Build and test
npm run build && npm start

Next: Configure your AI client using the GET STARTED guide

🛠️ Complete Tools Reference

👉 GET SUPPORTED TOOLS - Complete Reference

Discover what you can accomplish with the Optimizely MCP Server! The complete reference covers:

✅ 27 MCP tools with natural language examples
✅ Common workflows from discovery to analysis
✅ Tool descriptions showing what each tool returns
✅ Use case examples for real-world scenarios

Perfect for understanding the full capabilities before starting.

🔄 Schema Generation & Modern Defaults

The server includes an intelligent schema generation system that solves the jQuery 1.11.3 problem by providing modern defaults for entity creation.

Problem Solved

When creating projects through Optimizely's API, the default settings include jQuery 1.11.3 and other legacy configurations. Our schema system:

✅ Extracts live schemas from Optimizely's API specification
✅ Provides modern defaults that override legacy settings
✅ Allows user customization via configuration files or chat
✅ Maintains up-to-date schemas as Optimizely evolves their API

Key Commands

# Generate schema from live API (discovers 25+ entity types)
npm run generate-fields

# Update everything (Swagger + schema + build)
npm run build:clean

# Test the jQuery problem solution
npm run test-defaults

# Direct execution (for debugging)
npx tsx scripts/gen-fields.ts

Generated Files

| File | Purpose | Auto-Generated | |------|---------|----------------| | scripts/gen-fields.ts | Generator script | ❌ Manual | | src/generated/fields.generated.ts | Schema output | ✅ Auto | | docs/schema-generation-guide.md | Full documentation | ❌ Manual |

Maintenance Schedule

Update weekly with npm run generate-fields
Before releases run npm run build:clean
Commit changes to src/generated/fields.generated.ts

Modern vs Legacy Defaults

// ❌ Optimizely's Legacy Default (causes jQuery 1.11.3)
{ platform: "web" }

// ✅ Our Modern Default (Feature Experimentation)
{ 
  platform: "feature",
  settings: {
    web: {
      snippet: {
        include_jquery: false,
        library: "none"
      }
    }
  }
}

📖 Complete Schema Generation Guide

🔧 Direct Integration Options

REST API Server (Available Now! 🚀)

We provide a full REST API server that exposes all MCP functionality via HTTP endpoints. Perfect for Python, Ruby, or any language that can make HTTP requests.

📍 Location: ../optimizely-rest-api

Quick Start:

# 1. Build the main MCP server first
cd optly-mcp-server && npm run build

# 2. Start the REST API server
cd ../optimizely-rest-api
npm install
npm start

# Server runs on http://localhost:3000

Example Usage (Python):

import requests

# List all flags in a project
response = requests.get("http://localhost:3000/api/v1/projects/12345/flags")
flags = response.json()

# Create a new entity
response = requests.post("http://localhost:3000/api/v1/entities/flag", 
    json={"key": "new_feature", "name": "New Feature Flag"})

📖 REST API Documentation

Future: Direct NPM Package

Status: PLANNED - We plan to extract the business logic into a standalone NPM package that can be used programmatically without the MCP layer.

📖 Current Implementation Guide

🖥️ Command Line Interface (CLI)

The Optimizely MCP Server includes a comprehensive CLI for direct interaction with your Optimizely data:

Installation

# Build the project
npm run build

# Run the CLI directly from the project
node bin/optly --help

# Or use npm scripts (recommended)
npm run optly -- --help

# For development (without building)
npm run optly:dev -- --help

Usage Examples

# First, ensure the project is built
npm run build

# Sync data with filtering
node bin/optly sync --project 12345 --entities flags,audiences --environments production

# Query with SQL
node bin/optly query --sql "SELECT * FROM flags WHERE enabled = 1"

# Search across entities
node bin/optly search "checkout" --type flag

# Export/Import data
node bin/optly export flags --format yaml --output flags.yaml
node bin/optly import flags.yaml --dry-run

# Or use npm scripts (recommended)
npm run optly -- sync --project 12345
npm run optly -- query --sql "SELECT * FROM flags WHERE enabled = 1"

CLI Features:

Entity & Environment Filtering - Sync only what you need
SQL Queries - Full SQLite with JSON support
Multiple Output Formats - JSON, CSV, YAML
Watch Mode - Monitor changes in real-time
Interactive REPL - Advanced operations
Automation Ready - Scriptable with webhooks

📖 Complete CLI User Guide | 🤖 AI Agent CLI Reference

📖 Documentation

🚨 CRITICAL: Start Here for Success

Protocol vs Template Guide - 🔥 THE #1 CONCEPT - Understanding this prevents 90% of frustration
AI Agent Engineering - 📚 Complete 5-phase learning framework for mastering AI agents
Self-Tuning Templates - How to refine templates based on agent feedback

🚀 For Immediate Use

GET STARTED - ⚡ Complete setup guide - zero to working in 15 minutes
User Guide - Comprehensive guide to using the server
CLI User Guide - ✅ NEW: Complete command-line interface guide with SQL queries and automation
Quick Reference - ✅ NEW: All 27 tools with examples
Setup Validation Guide - ✅ NEW: 5-phase validation process

🤖 For AI Agents & Tools

AI Agent Engineering - 🎓 NEW: 5-phase learning framework for AI agent mastery
AI Agent Protocols - 📚 NEW: Centralized research documents and specifications
Entity Relationship Matrix - ✅ NEW: Prevents common AI mistakes
Agent Operational Rules - ✅ UPDATED: All 27 tools documented
Display Formatting Guide - Response formatting standards

🔧 For Developers & Architects

Developer Reference Guide - ✅ NEW: Direct integration without MCP transport
Intelligent Payload Parser - 🧠 CRITICAL: Auto-fixes malformed payloads with fuzzy matching
Technical Design - ✅ UPDATED: Complete architecture with security fixes
EntityOrchestrator Workflows - ✅ NEW: Multi-step operation workflows
Parametric Tool Architecture - Technical architecture overview
Database Schema - ✅ UPDATED: Version 9 schema with 21 tables
Performance Optimization - ✅ NEW: Multi-level cache architecture
API Reference - Complete Optimizely API documentation
Contributing Guide - How to contribute

🛡️ For Operations & Security

Security Considerations - ✅ NEW: Comprehensive security guide
Common Issues - ✅ NEW: Troubleshooting with diagnostics
Migration Guide - ✅ NEW: Version and platform migrations
Test Strategy - ✅ NEW: Comprehensive testing approach

📤 Response Standards & AI Agent Engineering

AI Agent Engineering - 🎓 NEW: Complete 5-phase learning framework for mastery
AI Agent Protocols - 📚 NEW: Centralized research documents and specifications
Response Standards Complete - ✅ MOVED: All 7 response types with hierarchy
Hard Stop Implementation - ✅ MOVED: Error handling patterns
Neural Patterns Discovery - 🧠 BREAKTHROUGH: Neural-first design discovery
Template Generation Guide - 🤖 AI AGENTS: Response generation patterns
Quick Reference - ✅ ACTIVE: One-page implementation guide

📚 Complete Documentation Index

Documentation Index - Complete navigation guide to all documentation

💬 Example Interactions

Discovery

You: "Show me all my Optimizely projects"
AI: Here are your projects:
    - Project 12345 (Web Experimentation)
    - Project 20224828075 (Feature Experimentation) 
    - Project 67890 (Web Experimentation)

Feature Flags

You: "What feature flags are in project 20224828075?"
AI: Found 15 feature flags:
    - checkout-redesign (85% rollout in production)
    - new-pricing-engine (testing in staging)
    - mobile-navigation (100% rolled out)
    ...

Experiments

You: "Show running experiments targeting mobile users"
AI: Found 3 experiments targeting mobile users:
    1. Mobile Checkout Flow (running for 7 days, 2,341 visitors)
    2. App Onboarding Test (running for 3 days, 892 visitors)
    3. Mobile Navigation (reached significance! +12% conversion)

Analysis

You: "Compare the checkout-redesign flag between staging and production"
AI: Differences found:
    - Rollout: Staging 100% vs Production 85%
    - Targeting: Staging includes internal users, Production excludes
    - Variables: Button color differs (blue vs green)

🏗️ Architecture

The server uses a parametric tool architecture with sophisticated routing and caching:

┌─────────────────────────────────────────────────────────┐
│                    AI Assistant (Claude, etc.)           │
├─────────────────────────────────────────────────────────┤
│                    MCP Protocol Layer                    │
├─────────────────────────────────────────────────────────┤
│              27 Parametric Tools                        │
│   list_entities • get_entity_details • manage_lifecycle │
├─────────────────────────────────────────────────────────┤
│                Smart Routing System                      │
│         Platform detection • Error handling              │
├─────────────────────────────────────────────────────────┤
│              Multi-Level Cache Architecture              │
│        L1 Memory • L2 SQLite • L3 API                   │
├─────────────────────────────────────────────────────────┤
│   Feature Experimentation  │  Web Experimentation       │
│   🚩 Flags API            │  🌐 Experiments API       │
└─────────────────────────────────────────────────────────┘

Key Architecture Components

EntityRouter: 2,409 lines of sophisticated routing logic
IncrementalSyncManager: 1,027 lines of fully implemented sync
ChangeHistoryTracker: 447 lines of production-ready tracking
Multi-level caching: Memory, SQLite, and API layers
Smart routing: Automatic platform detection and error handling

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Current Priorities

✅ Entity Relationship Documentation Matrix - Completed comprehensive entity documentation
✅ Security Hardening - Comprehensive security implementation completed
✅ Performance Optimization - Multi-level cache architecture implemented
✅ Testing Strategy - Comprehensive testing approach documented
Additional entity type support (Variable Definitions endpoints)
Enhanced analytics capabilities

📊 Supported Entities

Feature Experimentation (100% Complete!)

✅ Flags (full CRUD)
✅ Environments
✅ Rulesets (full management)
✅ Rules
✅ Variations (full CRUD)
✅ Variable Definitions (full CRUD)
✅ Experiments

Web Experimentation (100% Complete!)

✅ Campaigns (full CRUD)
✅ Experiments (full CRUD)
✅ Pages (full CRUD)
✅ Audiences (full CRUD)
✅ Attributes (full CRUD)
✅ Events (full CRUD)
✅ Experiment Results
✅ Collaborators (full management)
✅ Extensions (full CRUD)
✅ Environments (full CRUD)
✅ Webhooks (full CRUD)
✅ List Attributes (full CRUD)

Cross-Platform (100% Complete!)

✅ Projects
✅ Groups (full CRUD)
✅ Change History
✅ Analytics - Advanced Query Engine with natural language support
✅ Diagnostics
✅ User Management

🚀 Roadmap

See our Expansion Roadmap for the vision of transforming from a configuration tool to a complete experimentation intelligence platform.

Completed Major Milestones

✅ Technical Design Audit - 23/28 tasks completed (82%)
✅ Security Hardening - Comprehensive threat model and protection
✅ Performance Optimization - Multi-level cache architecture
✅ Documentation Overhaul - Complete documentation matrix
✅ Testing Strategy - Comprehensive testing approach
✅ Operational Readiness - Troubleshooting and migration guides

🚀 Universal Data Democratization Platform

Separate Project: The architecture/ folder contains comprehensive technical documentation for a Universal Data Democratization Platform - a vision for transforming how small businesses interact with their data through collaborative intelligence.

Key Documents:

Architecture Index - Complete navigation to all platform documentation
Technical Design v3 - Production-ready architecture
Data Model Guide - 4-layer data architecture
Database Scalability - Evolution from 1 to 1M customers

This represents a separate initiative from the MCP server, focused on universal data access across any API.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on the Model Context Protocol by Anthropic
Powered by Optimizely APIs
TypeScript, Node.js, and the amazing open source community

📞 Support

Documentation: Start with the User Guide or Documentation Index
Setup Issues: See Setup Validation Guide
Troubleshooting: Check Common Issues
Security: Review Security Considerations
Performance: See Performance Optimization
Issues: Please file issues on GitHub
Discussions: Join our discussions for questions and ideas

Built with ❤️ for the experimentation community #� �T�e�s�t� �c�o�m�m�e�n�t� �f�o�r� �h�o�o�k� �v�e�r�i�f�i�c�a�t�i�o�n� � �