@growthbook/mcp 0.1.2 → 1.0.0

package/README.md

@@ -14,7 +14,7 @@ Use the following env variables to configure the MCP server.
 | Variable Name | Status   | Description                                                       |
 | ------------- | -------- | ----------------------------------------------------------------- |
 | GB_API_KEY    | Required | A GrowthBook API key.                                             |
-| GB_USER       | Required | Your name. Used when creating a feature flag.                     |
+| GB_EMAIL      | Required | Your email address used with GrowthBook. Used when creating feature flags and experiments.|
 | GB_API_URL    | Optional | Your GrowthBook API URL. Defaults to `https://api.growthbook.io`. |
 | GB_APP_ORIGIN | Optional | Your GrowthBook app URL Defaults to `https://app.growthbook.io`.  |
 
@@ -36,7 +36,7 @@ Find instructions below to add the MCP server to a client. Any client that suppo
         "GB_API_KEY": "YOUR_API_KEY",
         "GB_API_URL": "YOUR_API_URL",
         "GB_APP_ORIGIN": "YOUR_APP_ORIGIN",
-        "GB_USER": "YOUR_NAME"
+        "GB_EMAIL": "YOUR_EMAIL"
       }
     }
   }
@@ -64,7 +64,7 @@ You should now see a green active status after the server successfully connects!
           "GB_API_KEY": "YOUR_API_KEY",
           "GB_API_URL": "YOUR_API_URL",
           "GB_APP_ORIGIN": "YOUR_APP_ORIGIN",
-          "GB_USER": "YOUR_NAME"
+          "GB_EMAIL": "YOUR_EMAIL"
         }
       }
     }
@@ -92,7 +92,7 @@ GrowthBook MCP is now ready to use in VS Code.
         "GB_API_KEY": "YOUR_API_KEY",
         "GB_API_URL": "YOUR_API_URL",
         "GB_APP_ORIGIN": "YOUR_APP_ORIGIN",
-        "GB_USER": "YOUR_NAME"
+        "GB_EMAIL": "YOUR_EMAIL"
       }
     }
   }
@@ -122,6 +122,9 @@ A hammer icon should appear in the chat window, indicating that your GrowthBook
   - `get_experiment`: Fetch details for a specific experiment by ID.
   - `get_attributes`: List all user attributes tracked in GrowthBook (useful for targeting).
   - `create_experiment`: Creates a feature-flag based experiment.
+  - `get_defaults`: Get default values for experiments including hypothesis, description, datasource, and assignment query. (Runs automatically when the create experiment tool is called.)
+  - `create_defaults`: Set custom default values for experiments that will be used when creating new experiments.
+  - `clear_user_defaults`: Clear user-defined defaults and revert to automatic defaults.
 
 - **Environments**
 

package/build/index.js

@@ -12,7 +12,7 @@ import { registerDefaultsTools } from "./tools/defaults.js";
 export const baseApiUrl = getApiUrl();
 export const apiKey = getApiKey();
 export const appOrigin = getAppOrigin();
-export const user = getUser();
+export const user = await getUser(baseApiUrl, apiKey);
 // Create an MCP server
 const server = new McpServer({
     name: "GrowthBook MCP",

package/build/tools/defaults.js

@@ -1,10 +1,12 @@
 import { handleResNotOk } from "../utils.js";
 import envPaths from "env-paths";
-import { writeFile, readFile } from "fs/promises";
+import { writeFile, readFile, mkdir, unlink } from "fs/promises";
 import { join } from "path";
+import { z } from "zod";
 const paths = envPaths("growthbook-mcp"); // Use your app name
 const experimentDefaultsDir = paths.config; // This is the recommended config directory
 const experimentDefaultsFile = join(experimentDefaultsDir, "experiment-defaults.json");
+const userDefaultsFile = join(experimentDefaultsDir, "user-defaults.json");
 export async function createDefaults(apiKey, baseApiUrl) {
     try {
         const experimentsResponse = await fetch(`${baseApiUrl}/api/v1/experiments`, {
@@ -42,6 +44,10 @@ export async function createDefaults(apiKey, baseApiUrl) {
                 datasource: "",
                 assignmentQuery,
                 environments,
+                filePaths: {
+                    experimentDefaultsFile,
+                    userDefaultsFile,
+                },
                 timestamp: new Date().toISOString(),
             };
         }
@@ -121,6 +127,10 @@ export async function createDefaults(apiKey, baseApiUrl) {
             datasource: mostFrequentDS.ds,
             assignmentQuery: mostFrequentDS.aq,
             environments,
+            filePaths: {
+                experimentDefaultsFile,
+                userDefaultsFile,
+            },
             timestamp: new Date().toISOString(),
         };
     }
@@ -128,16 +138,94 @@ export async function createDefaults(apiKey, baseApiUrl) {
         throw error;
     }
 }
+async function getUserDefaults() {
+    try {
+        const userDefaultsData = await readFile(userDefaultsFile, "utf8");
+        return JSON.parse(userDefaultsData);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
 export async function getDefaults(apiKey, baseApiUrl) {
+    // First check for user-defined defaults
+    const userDefaults = await getUserDefaults();
+    if (userDefaults) {
+        // User has set defaults, use them for datasource/assignment/environments
+        // But still get the automatic defaults for names/hypotheses/descriptions
+        let autoDefaults = {
+            name: [],
+            hypothesis: [],
+            description: [],
+        };
+        try {
+            // Try to get existing auto-generated defaults for name/hypothesis/description
+            const experimentDefaultsData = await readFile(experimentDefaultsFile, "utf8");
+            const parsedExperimentDefaults = JSON.parse(experimentDefaultsData);
+            if (parsedExperimentDefaults &&
+                new Date(parsedExperimentDefaults.timestamp).getTime() >
+                    new Date().getTime() - 1000 * 60 * 60 * 24 * 30 // 30 days
+            ) {
+                autoDefaults = {
+                    name: parsedExperimentDefaults.name || [],
+                    hypothesis: parsedExperimentDefaults.hypothesis || [],
+                    description: parsedExperimentDefaults.description || [],
+                };
+            }
+            else {
+                // Re-generate auto defaults if expired
+                const generatedDefaults = await createDefaults(apiKey, baseApiUrl);
+                await mkdir(experimentDefaultsDir, { recursive: true });
+                await writeFile(experimentDefaultsFile, JSON.stringify(generatedDefaults, null, 2));
+                autoDefaults = {
+                    name: generatedDefaults.name,
+                    hypothesis: generatedDefaults.hypothesis,
+                    description: generatedDefaults.description,
+                };
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                // Generate new auto defaults
+                const generatedDefaults = await createDefaults(apiKey, baseApiUrl);
+                await mkdir(experimentDefaultsDir, { recursive: true });
+                await writeFile(experimentDefaultsFile, JSON.stringify(generatedDefaults, null, 2));
+                autoDefaults = {
+                    name: generatedDefaults.name,
+                    hypothesis: generatedDefaults.hypothesis,
+                    description: generatedDefaults.description,
+                };
+            }
+        }
+        // Combine user defaults with auto defaults
+        return {
+            name: autoDefaults.name || [],
+            hypothesis: autoDefaults.hypothesis || [],
+            description: autoDefaults.description || [],
+            datasource: userDefaults.datasourceId,
+            assignmentQuery: userDefaults.assignmentQueryId,
+            environments: userDefaults.environments,
+            filePaths: {
+                experimentDefaultsFile,
+                userDefaultsFile,
+            },
+            timestamp: new Date().toISOString(),
+        };
+    }
+    // No user defaults, use fully automatic defaults
     let experimentDefaults;
     try {
         const experimentDefaultsData = await readFile(experimentDefaultsFile, "utf8");
         let parsedExperimentDefaults = JSON.parse(experimentDefaultsData);
         if (!parsedExperimentDefaults ||
-            parsedExperimentDefaults.timestamp <
+            new Date(parsedExperimentDefaults.timestamp).getTime() <
                 new Date().getTime() - 1000 * 60 * 60 * 24 * 30 // 30 days
         ) {
             const generatedExperimentDefaults = await createDefaults(apiKey, baseApiUrl);
+            await mkdir(experimentDefaultsDir, { recursive: true });
             await writeFile(experimentDefaultsFile, JSON.stringify(generatedExperimentDefaults, null, 2));
             parsedExperimentDefaults = generatedExperimentDefaults;
         }
@@ -147,6 +235,7 @@ export async function getDefaults(apiKey, baseApiUrl) {
         if (error.code === "ENOENT") {
             // experimentDefaultsFile does not exist, generate new defaults
             const generatedExperimentDefaults = await createDefaults(apiKey, baseApiUrl);
+            await mkdir(experimentDefaultsDir, { recursive: true });
             await writeFile(experimentDefaultsFile, JSON.stringify(generatedExperimentDefaults, null, 2));
             experimentDefaults = generatedExperimentDefaults;
         }
@@ -163,7 +252,70 @@ export async function registerDefaultsTools({ server, baseApiUrl, apiKey, }) {
     server.tool("get_defaults", "Get the default values for experiments, including hypothesis, description, datasource, assignment query, and environments.", {}, async () => {
         const defaults = await getDefaults(apiKey, baseApiUrl);
         return {
-            content: [{ type: "text", text: JSON.stringify(defaults, null, 2) }],
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(defaults, null, 2),
+                },
+            ],
         };
     });
+    server.tool("set_user_defaults", "Set user-defined defaults for datasource, assignment query, and environments. These will override the automatic defaults for these fields.", {
+        datasourceId: z.string().describe("The data source ID to use as default"),
+        assignmentQueryId: z
+            .string()
+            .describe("The assignment query ID to use as default"),
+        environments: z
+            .array(z.string())
+            .describe("List of environment IDs to use as defaults"),
+    }, async ({ datasourceId, assignmentQueryId, environments }) => {
+        try {
+            const userDefaults = {
+                datasourceId,
+                assignmentQueryId,
+                environments,
+                timestamp: new Date().toISOString(),
+            };
+            await mkdir(experimentDefaultsDir, { recursive: true });
+            await writeFile(userDefaultsFile, JSON.stringify(userDefaults, null, 2));
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `User defaults have been saved:\n\n${JSON.stringify(userDefaults, null, 2)} to ${userDefaultsFile}\n\nThese will be used when creating new experiments.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            throw new Error(`Error setting user defaults: ${error}`);
+        }
+    });
+    server.tool("clear_user_defaults", "Clear user-defined defaults and revert to automatic defaults.", {}, async () => {
+        try {
+            await readFile(userDefaultsFile, "utf8");
+            await unlink(userDefaultsFile);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "User defaults have been cleared. The system will now use automatic defaults.",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No user defaults were set.",
+                        },
+                    ],
+                };
+            }
+            throw new Error(`Error clearing user defaults: ${error}`);
+        }
+    });
 }

package/build/tools/experiments.js

@@ -57,7 +57,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 // Loop through the environments and create a rule for each one keyed by environment name
                 environments: defaultEnvironments.reduce((acc, env) => {
                     acc[env] = {
-                        enabled: true,
+                        enabled: false,
                         rules: [
                             {
                                 type: "force",
@@ -176,7 +176,12 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 .string()
                 .describe("Variation name. Base name off the examples from get_defaults. If none are available, use a short, descriptive name that captures the essence of the variation."),
             value: z
-                .union([z.string(), z.number(), z.boolean(), z.record(z.any())])
+                .union([
+                z.string(),
+                z.number(),
+                z.boolean(),
+                z.record(z.string(), z.any()),
+            ])
                 .describe("The value of the control and each of the variations. The value should be a string, number, boolean, or object. If it's an object, it should be a valid JSON object."),
         }))
             .describe("Experiment variations. The key should be the variation name and the value should be the variation value. Look to variations included in preview experiments for guidance on generation. The default or control variation should always be first."),
@@ -203,6 +208,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
             name,
             description,
             hypothesis,
+            owner: user.email,
             trackingKey: name.toLowerCase().replace(/[^a-z0-9]/g, "-"),
             tags: ["mcp"],
             assignmentQueryId: experimentDefaults?.assignmentQuery,
@@ -226,7 +232,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
             const flagId = `flag_${name.toLowerCase().replace(/[^a-z0-9]/g, "_")}`;
             const flagPayload = {
                 id: flagId,
-                owner: user,
+                owner: user.name,
                 defaultValue: variations[0].value,
                 valueType: typeof variations[0].value === "string"
                     ? "string"
@@ -237,7 +243,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 environments: {
                     ...experimentDefaults.environments.reduce((acc, env) => {
                         acc[env] = {
-                            enabled: true,
+                            enabled: false,
                             rules: [
                                 {
                                     type: "experiment-ref",
@@ -261,8 +267,8 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 },
                 body: JSON.stringify(flagPayload),
             });
-            const flagData = await flagRes.json();
             await handleResNotOk(flagRes);
+            const flagData = await flagRes.json();
             const experimentLink = generateLinkToGrowthBook(appOrigin, "experiment", experimentData.experiment.id);
             const flagLink = generateLinkToGrowthBook(appOrigin, "features", flagData.feature.id);
             const { stub, docs, language } = getDocsMetadata(fileExtension);

package/build/tools/features.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { getDocsMetadata, handleResNotOk, generateLinkToGrowthBook, SUPPORTED_FILE_EXTENSIONS, } from "../utils.js";
 import { exec } from "child_process";
+import { getDefaults } from "./defaults.js";
 export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, user, }) {
     /**
      * Tool: create_feature_flag
@@ -14,7 +15,7 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
             .string()
             .optional()
             .default("")
-            .describe("A briefdescription of the feature flag"),
+            .describe("A brief description of the feature flag"),
         valueType: z
             .enum(["string", "number", "boolean", "json"])
             .describe("The value type the feature flag will return"),
@@ -25,13 +26,37 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
             .enum(SUPPORTED_FILE_EXTENSIONS)
             .describe("The extension of the current file. If it's unclear, ask the user."),
     }, async ({ id, description, valueType, defaultValue, fileExtension }) => {
+        // get environments
+        let environments = [];
+        const defaults = await getDefaults(apiKey, baseApiUrl);
+        if (defaults.environments) {
+            environments = defaults.environments;
+        }
+        else {
+            const envRes = await fetch(`${baseApiUrl}/api/v1/features/environments`, {
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+            });
+            await handleResNotOk(envRes);
+            const envData = await envRes.json();
+            environments = envData.environments.map((env) => env.id);
+        }
         const payload = {
             id,
             description,
-            owner: user,
+            owner: user.name,
             valueType,
             defaultValue,
             tags: ["mcp"],
+            environments: environments.reduce((acc, env) => {
+                acc[env] = {
+                    enabled: false,
+                    rules: [],
+                };
+                return acc;
+            }, {}),
         };
         try {
             const res = await fetch(`${baseApiUrl}/api/v1/features`, {

package/build/utils.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { getFeatureFlagDocs } from "./docs.js";
 // Shared file extension enum for all MCP tools
 export const SUPPORTED_FILE_EXTENSIONS = [
@@ -52,12 +53,39 @@ export function getAppOrigin() {
     const userAppOrigin = process.env.GB_APP_ORIGIN;
     return `${userAppOrigin || defaultAppOrigin}`;
 }
-export function getUser() {
-    const user = process.env.GB_USER;
+export async function getUser(baseApiUrl, apiKey) {
+    const user = process.env.GB_EMAIL || process.env.GB_USER;
     if (!user) {
-        throw new Error("GB_USER environment variable is required");
+        throw new Error("GB_EMAIL environment variable is required");
+    }
+    // Show deprecation warning if using the old variable
+    if (process.env.GB_USER && !process.env.GB_EMAIL) {
+        console.error("⚠️  GB_USER is deprecated. Use GB_EMAIL instead.");
+    }
+    const emailSchema = z.string().email();
+    if (!emailSchema.safeParse(user).success) {
+        throw new Error("GB_EMAIL is not a valid email");
+    }
+    try {
+        const users = await fetch(`${baseApiUrl}/api/v1/members?userEmail=${user}`, {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+        });
+        await handleResNotOk(users);
+        const usersData = await users.json();
+        if (usersData.members.length === 0) {
+            throw new Error(`Email not found in GrowthBook. Update GB_EMAIL environment variable to your email address in GrowthBook.`);
+        }
+        const userFromGrowthBook = {
+            email: usersData.members[0].email,
+            name: usersData.members[0].name,
+        };
+        return userFromGrowthBook;
+    }
+    catch (error) {
+        throw new Error(`Error fetching user from GrowthBook. Please check your GB_EMAIL and GB_API_KEY environment variables.`);
     }
-    return user;
 }
 export function getDocsMetadata(extension) {
     switch (extension) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growthbook/mcp",
-  "version": "0.1.2",
+  "version": "1.0.0",
   "description": "",
   "access": "public",
   "homepage": "https://github.com/growthbook/growthbook-mcp",
@@ -22,13 +22,13 @@
   "license": "MIT",
   "packageManager": "pnpm@10.6.1",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.13.1",
+    "@modelcontextprotocol/sdk": "^1.17.2",
     "env-paths": "^3.0.0",
     "zod": "^3.25.67"
   },
   "devDependencies": {
-    "@types/node": "^24.0.4",
-    "typescript": "^5.8.3"
+    "@types/node": "^24.2.1",
+    "typescript": "^5.9.2"
   },
   "type": "module"
 }