optimizely-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# Optimizely MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects AI assistants to the Optimizely REST API. Manage experiments, feature flags, audiences, and more without leaving your editor.
+
+## Quick Start
+
+### 1. Get an Optimizely API Token
+
+- Log into [app.optimizely.com](https://app.optimizely.com)
+- Go to **Profile → API Access**
+- Click **Generate New Token**
+
+### 2. Add to Cursor
+
+Add this to your `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Optimizely": {
+      "command": "npx",
+      "args": ["-y", "optimizely-mcp-server"],
+      "env": {
+        "OPTIMIZELY_API_TOKEN": "<your-token-here>"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor and the Optimizely tools will be available in any chat.
+
+## Available Tools
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects in your account |
+| `get_project` | Get details for a specific project |
+
+### Experiments
+| Tool | Description |
+|------|-------------|
+| `list_experiments` | List experiments in a project |
+| `get_experiment` | Get full experiment details |
+| `create_experiment` | Create a new A/B test |
+| `update_experiment` | Update or start/pause an experiment |
+| `get_experiment_results` | Get conversion rates and statistical significance |
+
+### Feature Flags
+| Tool | Description |
+|------|-------------|
+| `list_flags` | List all feature flags in a project |
+| `get_flag` | Get flag details including variables and rules |
+| `create_flag` | Create a new feature flag |
+| `update_flag` | Update a flag's name, description, or archive it |
+| `toggle_flag` | Enable or disable a flag in a specific environment |
+| `list_flag_rules` | List rules (rollouts, A/B tests) for a flag |
+| `list_flag_variations` | List all variations for a flag |
+| `create_flag_variation` | Create a new variation with variable values |
+
+### Audiences & Targeting
+| Tool | Description |
+|------|-------------|
+| `list_audiences` | List all audiences in a project |
+| `get_audience` | Get audience targeting conditions |
+| `list_attributes` | List custom attributes used for targeting |
+
+### Campaigns & Results
+| Tool | Description |
+|------|-------------|
+| `list_campaigns` | List all campaigns in a project |
+| `get_campaign_results` | Get campaign metrics and significance |
+
+### Other
+| Tool | Description |
+|------|-------------|
+| `list_events` | List tracked events/goals |
+| `list_environments` | List environments (production, staging, etc.) |
+| `list_pages` | List pages (URL targeting) |
+| `list_changes` | View recent change history |
+| `search` | Search across all resources by keyword |
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPTIMIZELY_API_TOKEN` | Yes | Your Optimizely personal access token |
+
+## Development
+
+```bash
+git clone <repo-url>
+cd optimizely-mcp
+npm install
+npm run build
+```
+
+To test locally, update your `mcp.json` to point at the local build:
+
+```json
+{
+  "Optimizely": {
+    "command": "node",
+    "args": ["/path/to/optimizely-mcp/dist/index.js"],
+    "env": {
+      "OPTIMIZELY_API_TOKEN": "<your-token>"
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { OptimizelyClient } from "./optimizely-client.js";
+const token = process.env.OPTIMIZELY_API_TOKEN;
+if (!token) {
+    console.error("OPTIMIZELY_API_TOKEN environment variable is required");
+    process.exit(1);
+}
+const client = new OptimizelyClient(token);
+const server = new McpServer({
+    name: "Optimizely",
+    version: "1.0.0",
+});
+// ─── Projects ────────────────────────────────────────────────────────────────
+server.tool("list_projects", "List all Optimizely projects in your account. Returns project IDs, names, status, and platform.", {
+    page: z.number().optional().describe("Page number (default 1)"),
+    per_page: z
+        .number()
+        .optional()
+        .describe("Results per page (default 25, max 100)"),
+}, async ({ page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/projects",
+        params: { page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_project", "Get details for a specific Optimizely project by ID.", {
+    project_id: z.number().describe("The project ID"),
+}, async ({ project_id }) => {
+    const data = await client.request({
+        path: `/v2/projects/${project_id}`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Experiments ─────────────────────────────────────────────────────────────
+server.tool("list_experiments", "List experiments in a project. Returns experiment IDs, names, status, type, and variation details.", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional().describe("Page number"),
+    per_page: z.number().optional().describe("Results per page (max 100)"),
+}, async ({ project_id, page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/experiments",
+        params: { project_id, page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_experiment", "Get full details of a specific experiment including variations, metrics, traffic allocation, and status.", {
+    experiment_id: z.number().describe("The experiment ID"),
+}, async ({ experiment_id }) => {
+    const data = await client.request({
+        path: `/v2/experiments/${experiment_id}`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("create_experiment", "Create a new A/B test experiment in a project. Requires project_id, name, and at least one variation.", {
+    project_id: z.number().describe("The project ID to create the experiment in"),
+    name: z.string().describe("Experiment name"),
+    description: z.string().optional().describe("Experiment description"),
+    type: z
+        .enum(["a/b", "multivariate", "multiarmed_bandit"])
+        .optional()
+        .describe("Experiment type (default a/b)"),
+    variations: z
+        .array(z.object({
+        name: z.string().describe("Variation name"),
+        weight: z.number().optional().describe("Traffic weight (0-10000, representing basis points)"),
+        actions: z.array(z.any()).optional().describe("Variation actions/changes"),
+    }))
+        .describe("Array of variations for the experiment"),
+    metrics: z.array(z.any()).optional().describe("Array of metric objects"),
+    holdback: z.number().optional().describe("Holdback percentage (0-10000 basis points)"),
+}, async ({ project_id, name, description, type, variations, metrics, holdback }) => {
+    const body = {
+        project_id,
+        name,
+        variations,
+    };
+    if (description)
+        body.description = description;
+    if (type)
+        body.type = type;
+    if (metrics)
+        body.metrics = metrics;
+    if (holdback !== undefined)
+        body.holdback = holdback;
+    const data = await client.request({
+        method: "POST",
+        path: "/v2/experiments",
+        body,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("update_experiment", "Update an existing experiment. Use this to change name, description, status (start/pause/archive), traffic allocation, variations, or metrics.", {
+    experiment_id: z.number().describe("The experiment ID to update"),
+    name: z.string().optional().describe("New experiment name"),
+    description: z.string().optional().describe("New description"),
+    status: z
+        .enum(["not_started", "running", "paused", "archived"])
+        .optional()
+        .describe("Change experiment status (e.g. 'running' to start, 'paused' to pause)"),
+    variations: z.array(z.any()).optional().describe("Updated variations"),
+    metrics: z.array(z.any()).optional().describe("Updated metrics"),
+    holdback: z.number().optional().describe("Updated holdback (0-10000)"),
+}, async ({ experiment_id, ...updates }) => {
+    const body = {};
+    for (const [key, value] of Object.entries(updates)) {
+        if (value !== undefined)
+            body[key] = value;
+    }
+    const data = await client.request({
+        method: "PATCH",
+        path: `/v2/experiments/${experiment_id}`,
+        body,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_experiment_results", "Get results/statistics for an experiment, including conversion rates, statistical significance, and improvement.", {
+    experiment_id: z.number().describe("The experiment ID"),
+    start_time: z.string().optional().describe("Start time (ISO 8601 format)"),
+    end_time: z.string().optional().describe("End time (ISO 8601 format)"),
+}, async ({ experiment_id, start_time, end_time }) => {
+    const data = await client.request({
+        path: `/v2/experiments/${experiment_id}/results`,
+        params: { start_time, end_time },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Feature Flags (Flags v1 API) ───────────────────────────────────────────
+server.tool("list_flags", "List all feature flags in a project. Returns flag keys, names, descriptions, variables, and environments.", {
+    project_id: z.number().describe("The project ID"),
+    archived: z
+        .boolean()
+        .optional()
+        .describe("If true, return archived flags only"),
+    page: z.number().optional().describe("Page number"),
+    per_page: z.number().optional().describe("Results per page"),
+}, async ({ project_id, archived, page, per_page }) => {
+    const params = { page, per_page };
+    if (archived !== undefined)
+        params.archived = archived ? "true" : "false";
+    const data = await client.request({
+        path: `/flags/v1/projects/${project_id}/flags`,
+        params,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_flag", "Get details of a specific feature flag by its key, including variables, variations, environments, and rules.", {
+    project_id: z.number().describe("The project ID"),
+    flag_key: z.string().describe("The flag key"),
+}, async ({ project_id, flag_key }) => {
+    const data = await client.request({
+        path: `/flags/v1/projects/${project_id}/flags/${flag_key}`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("create_flag", "Create a new feature flag in a project.", {
+    project_id: z.number().describe("The project ID"),
+    key: z.string().describe("Unique flag key (alphanumeric, underscores, hyphens)"),
+    name: z.string().describe("Human-readable flag name"),
+    description: z.string().optional().describe("Flag description"),
+}, async ({ project_id, key, name, description }) => {
+    const body = { key, name };
+    if (description)
+        body.description = description;
+    const data = await client.request({
+        method: "POST",
+        path: `/flags/v1/projects/${project_id}/flags`,
+        body,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("update_flag", "Update an existing feature flag's name, description, or archived status.", {
+    project_id: z.number().describe("The project ID"),
+    flag_key: z.string().describe("The flag key to update"),
+    name: z.string().optional().describe("New flag name"),
+    description: z.string().optional().describe("New description"),
+    archived: z.boolean().optional().describe("Set to true to archive the flag"),
+}, async ({ project_id, flag_key, ...updates }) => {
+    const body = {};
+    for (const [key, value] of Object.entries(updates)) {
+        if (value !== undefined)
+            body[key] = value;
+    }
+    const data = await client.request({
+        method: "PATCH",
+        path: `/flags/v1/projects/${project_id}/flags/${flag_key}`,
+        body,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Flag Rules (Targeting / Rollouts / A/B tests on flags) ─────────────────
+server.tool("list_flag_rules", "List all rules (rollouts, A/B tests, targeted deliveries) for a flag in a specific environment.", {
+    project_id: z.number().describe("The project ID"),
+    flag_key: z.string().describe("The flag key"),
+    environment_key: z.string().describe("The environment key (e.g. 'production', 'development')"),
+}, async ({ project_id, flag_key, environment_key }) => {
+    const data = await client.request({
+        path: `/flags/v1/projects/${project_id}/flags/${flag_key}/environments/${environment_key}/rules`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("toggle_flag", "Enable or disable a feature flag in a specific environment. This controls whether the flag is active.", {
+    project_id: z.number().describe("The project ID"),
+    flag_key: z.string().describe("The flag key"),
+    environment_key: z.string().describe("The environment key"),
+    enabled: z.boolean().describe("true to enable, false to disable"),
+}, async ({ project_id, flag_key, environment_key, enabled }) => {
+    const data = await client.request({
+        method: "PATCH",
+        path: `/flags/v1/projects/${project_id}/flags/${flag_key}/environments/${environment_key}/ruleset`,
+        body: { enabled },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Audiences ───────────────────────────────────────────────────────────────
+server.tool("list_audiences", "List all audiences in a project. Audiences define targeting conditions for experiments.", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional(),
+    per_page: z.number().optional(),
+}, async ({ project_id, page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/audiences",
+        params: { project_id, page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_audience", "Get details of a specific audience including its targeting conditions.", {
+    audience_id: z.number().describe("The audience ID"),
+}, async ({ audience_id }) => {
+    const data = await client.request({
+        path: `/v2/audiences/${audience_id}`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Events ──────────────────────────────────────────────────────────────────
+server.tool("list_events", "List all tracked events/goals in a project. Events are used as metrics in experiments.", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional(),
+    per_page: z.number().optional(),
+}, async ({ project_id, page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/events",
+        params: { project_id, page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Environments ────────────────────────────────────────────────────────────
+server.tool("list_environments", "List all environments in a project (e.g. production, staging, development). Environments control where flags and experiments are active.", {
+    project_id: z.number().describe("The project ID"),
+}, async ({ project_id }) => {
+    const data = await client.request({
+        path: `/v2/environments/${project_id}`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Campaigns ───────────────────────────────────────────────────────────────
+server.tool("list_campaigns", "List all campaigns (personalization campaigns or multi-page experiments) in a project.", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional(),
+    per_page: z.number().optional(),
+}, async ({ project_id, page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/campaigns",
+        params: { project_id, page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("get_campaign_results", "Get results for a campaign including per-variation metrics, statistical significance, and improvement.", {
+    campaign_id: z.number().describe("The campaign ID"),
+    start_time: z.string().optional().describe("Start time (ISO 8601)"),
+    end_time: z.string().optional().describe("End time (ISO 8601)"),
+}, async ({ campaign_id, start_time, end_time }) => {
+    const data = await client.request({
+        path: `/v2/campaigns/${campaign_id}/results`,
+        params: { start_time, end_time },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Attributes ──────────────────────────────────────────────────────────────
+server.tool("list_attributes", "List all custom attributes defined in a project. Attributes are used for audience targeting.", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional(),
+    per_page: z.number().optional(),
+}, async ({ project_id, page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/attributes",
+        params: { project_id, page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Pages ───────────────────────────────────────────────────────────────────
+server.tool("list_pages", "List all pages defined in a project. Pages specify where experiments run (URL targeting).", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional(),
+    per_page: z.number().optional(),
+}, async ({ project_id, page: pg, per_page }) => {
+    const data = await client.request({
+        path: "/v2/pages",
+        params: { project_id, page: pg, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Change History ──────────────────────────────────────────────────────────
+server.tool("list_changes", "List recent changes/activity in a project. Shows who changed what and when.", {
+    project_id: z.number().describe("The project ID"),
+    page: z.number().optional(),
+    per_page: z.number().optional(),
+}, async ({ project_id, page, per_page }) => {
+    const data = await client.request({
+        path: "/v2/changes",
+        params: { project_id, page, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Search ──────────────────────────────────────────────────────────────────
+server.tool("search", "Search across all Optimizely resources (experiments, campaigns, pages, audiences, etc.) by keyword.", {
+    project_id: z.number().describe("The project ID to search in"),
+    query: z.string().describe("Search query string"),
+    per_page: z.number().optional().describe("Results per page"),
+}, async ({ project_id, query, per_page }) => {
+    const data = await client.request({
+        path: "/v2/search",
+        params: { project_id, query, per_page },
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Flag Variations ─────────────────────────────────────────────────────────
+server.tool("list_flag_variations", "List all variations for a feature flag. Variations define different configurations of flag variables.", {
+    project_id: z.number().describe("The project ID"),
+    flag_key: z.string().describe("The flag key"),
+}, async ({ project_id, flag_key }) => {
+    const data = await client.request({
+        path: `/flags/v1/projects/${project_id}/flags/${flag_key}/variations`,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+server.tool("create_flag_variation", "Create a new variation for a feature flag with specific variable values.", {
+    project_id: z.number().describe("The project ID"),
+    flag_key: z.string().describe("The flag key"),
+    key: z.string().describe("Unique variation key"),
+    name: z.string().describe("Variation name"),
+    description: z.string().optional().describe("Variation description"),
+    variables: z
+        .record(z.any())
+        .optional()
+        .describe("Map of variable key to value"),
+}, async ({ project_id, flag_key, key, name, description, variables }) => {
+    const body = { key, name };
+    if (description)
+        body.description = description;
+    if (variables)
+        body.variables = variables;
+    const data = await client.request({
+        method: "POST",
+        path: `/flags/v1/projects/${project_id}/flags/${flag_key}/variations`,
+        body,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ─── Start the server ────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/optimizely-client.d.ts

@@ -0,0 +1,11 @@
+export interface OptimizelyRequestOptions {
+    method?: string;
+    path: string;
+    params?: Record<string, string | number | undefined>;
+    body?: unknown;
+}
+export declare class OptimizelyClient {
+    private token;
+    constructor(token: string);
+    request<T = unknown>(opts: OptimizelyRequestOptions): Promise<T>;
+}

package/dist/optimizely-client.js

@@ -0,0 +1,34 @@
+const BASE_URL = "https://api.optimizely.com";
+export class OptimizelyClient {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    async request(opts) {
+        const url = new URL(opts.path, BASE_URL);
+        if (opts.params) {
+            for (const [key, value] of Object.entries(opts.params)) {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        };
+        const response = await fetch(url.toString(), {
+            method: opts.method ?? "GET",
+            headers,
+            body: opts.body ? JSON.stringify(opts.body) : undefined,
+        });
+        if (response.status === 204) {
+            return {};
+        }
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw new Error(`Optimizely API error ${response.status}: ${errorBody}`);
+        }
+        return response.json();
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "optimizely-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Optimizely REST API — manage experiments, feature flags, audiences, and more from any MCP client.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "optimizely-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "optimizely",
+    "feature-flags",
+    "experiments",
+    "a/b-testing",
+    "cursor"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "@types/node": "^22.0.0"
+  }
+}