@growthbook/mcp 1.6.0 → 1.7.0

package/README.md

@@ -19,22 +19,4 @@ Use the following env variables to configure the MCP server.
 | GB_APP_ORIGIN | Optional | Your GrowthBook app URL Defaults to `https://app.growthbook.io`.  |
 | GB_HTTP_HEADER_* | Optional | Custom HTTP headers to include in all GrowthBook API requests. Use the pattern `GB_HTTP_HEADER_<NAME>` where `<NAME>` is converted to proper HTTP header format (underscores become hyphens). Examples: `GB_HTTP_HEADER_X_TENANT_ID=abc123` becomes `X-Tenant-ID: abc123`, `GB_HTTP_HEADER_CF_ACCESS_TOKEN=<token>` becomes `Cf-Access-Token: <token>`. Multiple custom headers can be configured. |
 
-**Custom Headers Examples**
-
-For multi-tenant deployments or proxy configurations, you can add custom headers:
-
-```bash
-# Multi-tenant identification
-GB_HTTP_HEADER_X_TENANT_ID=tenant-123
-
-# Cloudflare Access proxy authentication
-GB_HTTP_HEADER_CF_ACCESS_TOKEN=eyJhbGciOiJSUzI1NiIs...
-```
-
-**Security Best Practices**
-- Always use HTTPS for API communication (default for GrowthBook Cloud)
-- Store API keys and sensitive headers in environment variables, never hardcode them
-- Use the Authorization header (via GB_API_KEY) for authentication
-- Custom headers are useful for multi-tenant scenarios, proxy routing, or additional context
-
 Add the MCP server to your AI tool of choice. See the [official docs](https://docs.growthbook.io/integrations/mcp) for complete a complete guide.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@growthbook/mcp",
   "mcpName": "io.github.growthbook/growthbook-mcp",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "MCP Server for interacting with GrowthBook",
   "access": "public",
   "homepage": "https://github.com/growthbook/growthbook-mcp",
@@ -20,7 +20,7 @@
     "bump:minor": "npm version minor --no-git-tag-version && npm run sync-version",
     "bump:major": "npm version major --no-git-tag-version && npm run sync-version",
     "mcpb:build": "npx -y @anthropic-ai/mcpb -- pack",
-    "generate-api-types": "npx openapi-typescript https://api.growthbook.io/api/v1/openapi.yaml -o src/api-types.ts"
+    "generate-api-types": "npx openapi-typescript https://api.growthbook.io/api/v1/openapi.yaml -o src/api-types.d.ts"
   },
   "bin": {
     "mcp": "server/index.js"

package/server/api-type-helpers.js

@@ -0,0 +1 @@
+export {};

package/server/format-responses.js

@@ -0,0 +1,540 @@
+import { formatList, generateLinkToGrowthBook } from "./utils.js";
+// Helper to resolve a metric ID to a display name using an optional lookup
+function resolveMetric(metricId, metricLookup) {
+    if (!metricLookup)
+        return `\`${metricId}\``;
+    const info = metricLookup.get(metricId);
+    if (!info)
+        return `\`${metricId}\``;
+    const inverse = info.inverse ? " (inverse)" : "";
+    return `**${info.name}** (\`${metricId}\`, ${info.type}${inverse})`;
+}
+function resolveMetricList(metrics, metricLookup) {
+    if (!metrics?.length)
+        return "none";
+    return metrics.map((g) => resolveMetric(g.metricId, metricLookup)).join(", ");
+}
+// ─── Projects ───────────────────────────────────────────────────────
+export function formatProjects(data) {
+    const projects = data.projects || [];
+    if (projects.length === 0) {
+        return "No projects found. Features and experiments will be created without a project scope.";
+    }
+    const lines = projects.map((p) => {
+        const parts = [`- **${p.name}** (id: \`${p.id}\`)`];
+        if (p.description)
+            parts.push(`  ${p.description}`);
+        return parts.join("\n");
+    });
+    return [
+        `**${projects.length} project(s):**`,
+        "",
+        ...lines,
+        "",
+        `Use the \`id\` value when creating feature flags or experiments scoped to a project.`,
+    ].join("\n");
+}
+// ─── Environments ───────────────────────────────────────────────────
+export function formatEnvironments(data) {
+    const environments = data.environments || [];
+    if (environments.length === 0) {
+        return "No environments found. At least one environment (production) should exist.";
+    }
+    const lines = environments.map((e) => {
+        const parts = [`- **${e.id}**`];
+        if (e.description)
+            parts.push(`: ${e.description}`);
+        if (e.toggleOnList)
+            parts.push(" (toggle on by default)");
+        if (e.defaultState === false)
+            parts.push(" (disabled by default)");
+        return parts.join("");
+    });
+    return [`**${environments.length} environment(s):**`, "", ...lines].join("\n");
+}
+// ─── Attributes ─────────────────────────────────────────────────────
+export function formatAttributes(data) {
+    const attributes = data.attributes || [];
+    if (attributes.length === 0) {
+        return "No targeting attributes configured. Attributes (like country, plan, userId) must be set up in GrowthBook before they can be used in targeting conditions.";
+    }
+    const lines = attributes.map((a) => {
+        return `- **${a.property}** (${a.datatype}${a.hashAttribute ? ", hash attribute" : ""})`;
+    });
+    return [
+        `**${attributes.length} attribute(s) available for targeting:**`,
+        "",
+        ...lines,
+        "",
+        `These can be used in targeting conditions (e.g. \`{"${attributes[0]?.property}": "value"}\`).`,
+    ].join("\n");
+}
+// ─── SDK Connections ────────────────────────────────────────────────
+export function formatSdkConnections(data) {
+    const connections = data.connections || [];
+    if (connections.length === 0) {
+        return "No SDK connections found. Use create_sdk_connection to create one for your app.";
+    }
+    const lines = connections.map((c) => {
+        return `**${c.name}**:
+  - Languages: ${formatList(c.languages)}
+  - Environment: ${c.environment}
+  - Client Key: \`${c.key}\`
+  - Projects: ${formatList(c.projects || [])}`;
+    });
+    return [`**${connections.length} SDK connection(s):**`, "", ...lines].join("\n");
+}
+// ─── Feature Flags ──────────────────────────────────────────────────
+export function formatFeatureFlagList(data) {
+    const features = data.features || [];
+    if (features.length === 0) {
+        return "No feature flags found. Use create_feature_flag to create one.";
+    }
+    const lines = features.map((f) => {
+        const envStatus = f.environments
+            ? Object.entries(f.environments)
+                .map(([env, config]) => `${env}: ${config.enabled ? "ON" : "OFF"}${config.rules?.length
+                ? ` (${config.rules.length} rule${config.rules.length > 1 ? "s" : ""})`
+                : ""}`)
+                .join(", ")
+            : "no environments";
+        const archived = f.archived ? " [ARCHIVED]" : "";
+        return `- **${f.id}** (${f.valueType}) — default: \`${f.defaultValue}\`${archived}\n  Environments: ${envStatus}${f.project ? `\n  Project: ${f.project}` : ""}`;
+    });
+    const pagination = data.hasMore
+        ? `\n\nShowing ${features.length} of ${data.total}. Use offset=${data.nextOffset} to see more.`
+        : "";
+    return [
+        `**${features.length} feature flag(s):**`,
+        "",
+        ...lines,
+        pagination,
+    ].join("\n");
+}
+export function formatFeatureFlagDetail(data, appOrigin) {
+    const f = data.feature;
+    if (!f)
+        return "Feature flag not found.";
+    const formatRule = (r, i) => {
+        const disabledTag = r.enabled === false ? " [DISABLED]" : "";
+        const desc = r.description ? ` — ${r.description}` : "";
+        const condition = r.condition ? `\n      Condition: ${r.condition}` : "";
+        const savedGroups = r.savedGroupTargeting?.length
+            ? `\n      Saved groups: ${r.savedGroupTargeting.map((sg) => `${sg.matchType} of [${sg.savedGroups.join(", ")}]`).join("; ")}`
+            : "";
+        const schedule = r.scheduleRules?.length
+            ? `\n      Schedule: ${r.scheduleRules.map((sr) => `${sr.enabled ? "enable" : "disable"} at ${sr.timestamp || "immediately"}`).join(", ")}`
+            : "";
+        const prerequisites = r.prerequisites?.length
+            ? `\n      Prerequisites: ${r.prerequisites.map((p) => p.id).join(", ")}`
+            : "";
+        if (r.type === "force") {
+            return `    ${i + 1}. Force rule${disabledTag}: value=\`${r.value}\`${desc}${condition}${savedGroups}${schedule}${prerequisites}`;
+        }
+        if (r.type === "rollout") {
+            return `    ${i + 1}. Rollout rule${disabledTag}: value=\`${r.value}\`, coverage=${r.coverage}, hashAttribute=${r.hashAttribute || "id"}${desc}${condition}${savedGroups}${schedule}`;
+        }
+        if (r.type === "experiment-ref") {
+            const variations = r.variations?.length
+                ? `\n      Variations: ${r.variations.map((v) => `${v.variationId}=\`${v.value}\``).join(", ")}`
+                : "";
+            return `    ${i + 1}. Experiment rule${disabledTag}: experimentId=\`${r.experimentId}\`${desc}${condition}${variations}${schedule}`;
+        }
+        if (r.type === "experiment") {
+            const trackingKey = r.trackingKey ? `, trackingKey=\`${r.trackingKey}\`` : "";
+            const coverage = r.coverage != null ? `, coverage=${r.coverage}` : "";
+            return `    ${i + 1}. Inline experiment${disabledTag}${trackingKey}${coverage}${desc}${condition}${savedGroups}${schedule}`;
+        }
+        if (r.type === "safe-rollout") {
+            return `    ${i + 1}. Safe rollout${disabledTag}: status=${r.status || "running"}, control=\`${r.controlValue}\`, variation=\`${r.variationValue}\`${condition}${savedGroups}${prerequisites}`;
+        }
+        return `    ${i + 1}. ${r.type} rule${disabledTag}${desc}`;
+    };
+    const envLines = f.environments
+        ? Object.entries(f.environments).map(([env, config]) => {
+            const status = config.enabled ? "ON" : "OFF";
+            const rules = config.rules || [];
+            const rulesSummary = rules.length > 0
+                ? rules.map(formatRule).join("\n")
+                : "    (no rules)";
+            return `  **${env}**: ${status}\n${rulesSummary}`;
+        })
+        : [];
+    const link = generateLinkToGrowthBook(appOrigin, "features", f.id);
+    const archived = f.archived
+        ? "\n**This flag is ARCHIVED.** Consider removing it from the codebase."
+        : "";
+    const tags = f.tags?.length ? `Tags: ${f.tags.join(", ")}` : "";
+    const prereqs = f.prerequisites?.length
+        ? `Prerequisites: ${f.prerequisites.join(", ")}`
+        : "";
+    return [
+        `**Feature flag: \`${f.id}\`**${archived}`,
+        `Type: ${f.valueType} | Default: \`${f.defaultValue}\` | Owner: ${f.owner || "unset"}${f.project ? ` | Project: ${f.project}` : ""}`,
+        f.description ? `Description: ${f.description}` : "",
+        tags,
+        prereqs,
+        "",
+        "**Environments:**",
+        ...envLines,
+        "",
+        `[View in GrowthBook](${link})`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+// ─── Feature Flag Creation / Update ─────────────────────────────────
+export function formatFeatureFlagCreated(data, appOrigin, sdkStub, language, docsUrl) {
+    const f = data.feature;
+    const id = f?.id || "unknown";
+    const link = generateLinkToGrowthBook(appOrigin, "features", id);
+    return [
+        `**Feature flag \`${id}\` created.**`,
+        `[View in GrowthBook](${link})`,
+        "",
+        "**SDK integration:**",
+        sdkStub,
+        "",
+        `[${language} docs](${docsUrl})`,
+    ].join("\n");
+}
+export function formatForceRuleCreated(data, appOrigin, featureId, sdkStub, language, docsUrl) {
+    const link = generateLinkToGrowthBook(appOrigin, "features", featureId);
+    return [
+        `**Targeting rule added to \`${featureId}\`.**`,
+        `[View in GrowthBook](${link})`,
+        "",
+        "**SDK integration:**",
+        sdkStub,
+        "",
+        `[${language} docs](${docsUrl})`,
+    ].join("\n");
+}
+// ─── Experiments ────────────────────────────────────────────────────
+export function formatExperimentList(data) {
+    const experiments = data.experiments || [];
+    if (experiments.length === 0) {
+        return "No experiments found. Use create_experiment to create one.";
+    }
+    const lines = experiments.map((e) => {
+        const status = e.status || "unknown";
+        const variations = e.variations
+            ? e.variations.map((v) => v.name).join(" vs ")
+            : "no variations";
+        const goalCount = e.settings?.goals?.length || 0;
+        return `- **${e.name}** (id: \`${e.id}\`, status: ${status})\n  Variations: ${variations}${goalCount > 0 ? ` | Goals: ${goalCount} metric(s)` : ""}${e.project ? ` | Project: ${e.project}` : ""}`;
+    });
+    const pagination = data.hasMore
+        ? `\n\nShowing ${experiments.length} of ${data.total}. Use offset=${data.nextOffset} to see more.`
+        : "";
+    return [
+        `**${experiments.length} experiment(s):**`,
+        "",
+        ...lines,
+        pagination,
+    ].join("\n");
+}
+export function formatExperimentDetail(data, appOrigin, metricLookup) {
+    const e = "experiment" in data && data.experiment
+        ? data.experiment
+        : data;
+    if (!e?.id)
+        return "Experiment not found.";
+    const link = generateLinkToGrowthBook(appOrigin, "experiment", e.id);
+    const variations = e.variations
+        ? e.variations
+            .map((v) => `${v.name} (key: \`${v.key}\`, variationId: \`${v.variationId}\`)`)
+            .join(", ")
+        : "none";
+    const parts = [
+        `**Experiment: ${e.name}** (id: \`${e.id}\`, status: ${e.status}, type: ${e.type || "standard"})`,
+    ];
+    if (e.archived)
+        parts.push("**This experiment is ARCHIVED.**");
+    if (e.hypothesis)
+        parts.push(`Hypothesis: ${e.hypothesis}`);
+    if (e.description)
+        parts.push(`Description: ${e.description}`);
+    parts.push(`Variations: ${variations}`);
+    parts.push(`Goal metrics: ${resolveMetricList(e.settings?.goals, metricLookup)}`);
+    const secondary = resolveMetricList(e.settings?.secondaryMetrics, metricLookup);
+    if (secondary !== "none")
+        parts.push(`Secondary metrics: ${secondary}`);
+    parts.push(`Guardrail metrics: ${resolveMetricList(e.settings?.guardrails, metricLookup)}`);
+    if (e.trackingKey)
+        parts.push(`Tracking key: \`${e.trackingKey}\``);
+    if (e.hashAttribute)
+        parts.push(`Hash attribute: \`${e.hashAttribute}\``);
+    if (e.project)
+        parts.push(`Project: ${e.project}`);
+    if (e.owner)
+        parts.push(`Owner: ${e.owner}`);
+    if (e.tags?.length)
+        parts.push(`Tags: ${e.tags.join(", ")}`);
+    // Linked features
+    if (e.linkedFeatures?.length) {
+        parts.push(`Linked features: ${e.linkedFeatures.map((f) => `\`${f}\``).join(", ")}`);
+    }
+    // Result summary (if experiment has concluded)
+    if (e.resultSummary) {
+        const rs = e.resultSummary;
+        parts.push("");
+        parts.push("**Result summary:**");
+        if (rs.status)
+            parts.push(`  Status: ${rs.status}`);
+        if (rs.winner)
+            parts.push(`  Winner: \`${rs.winner}\``);
+        if (rs.conclusions)
+            parts.push(`  Conclusions: ${rs.conclusions}`);
+        if (rs.releasedVariationId)
+            parts.push(`  Released variation: \`${rs.releasedVariationId}\``);
+    }
+    // Phases (traffic allocation history)
+    if (e.phases?.length) {
+        parts.push("");
+        parts.push(`**Phases (${e.phases.length}):**`);
+        for (const [idx, phase] of e.phases.entries()) {
+            const dateRange = `${phase.dateStarted || "?"} → ${phase.dateEnded || "ongoing"}`;
+            const traffic = phase.trafficSplit?.length
+                ? phase.trafficSplit.map((t) => `${t.variationId}: ${(t.weight * 100).toFixed(0)}%`).join(", ")
+                : "even split";
+            const coverageStr = phase.coverage != null ? `, coverage: ${(phase.coverage * 100).toFixed(0)}%` : "";
+            const targeting = phase.targetingCondition ? `\n    Targeting: ${phase.targetingCondition}` : "";
+            parts.push(`  ${idx + 1}. ${phase.name || `Phase ${idx + 1}`} (${dateRange})\n    Traffic: ${traffic}${coverageStr}${targeting}`);
+            if (phase.reasonForStopping)
+                parts.push(`    Stopped: ${phase.reasonForStopping}`);
+        }
+    }
+    // Bandit-specific settings
+    if (e.type === "multi-armed-bandit") {
+        const banditParts = [];
+        if (e.banditScheduleValue)
+            banditParts.push(`schedule: ${e.banditScheduleValue} ${e.banditScheduleUnit || "hours"}`);
+        if (e.banditBurnInValue)
+            banditParts.push(`burn-in: ${e.banditBurnInValue} ${e.banditBurnInUnit || "hours"}`);
+        if (banditParts.length)
+            parts.push(`Bandit settings: ${banditParts.join(", ")}`);
+    }
+    parts.push("");
+    parts.push(`[View in GrowthBook](${link})`);
+    return parts.join("\n");
+}
+export function formatExperimentCreated(experimentData, appOrigin, sdkStub, language, docsUrl) {
+    const e = experimentData.experiment;
+    const link = generateLinkToGrowthBook(appOrigin, "experiment", e.id);
+    const variations = e.variations
+        ? e.variations
+            .map((v) => `${v.name} (variationId: \`${v.variationId}\`)`)
+            .join(", ")
+        : "none";
+    const parts = [
+        `**Draft experiment \`${e.name}\` created.** [Review and launch in GrowthBook](${link})`,
+        "",
+        `Variations: ${variations}`,
+        `Tracking key: \`${e.trackingKey}\``,
+    ];
+    if (sdkStub) {
+        parts.push("", "**SDK integration:**", sdkStub, "", `[${language} docs](${docsUrl})`);
+    }
+    return parts.join("\n");
+}
+// ─── Metrics ────────────────────────────────────────────────────────
+export function formatMetricsList(metricsData, factMetricData) {
+    const metrics = metricsData.metrics || [];
+    const factMetrics = factMetricData.factMetrics || [];
+    if (metrics.length === 0 && factMetrics.length === 0) {
+        return "No metrics found. Metrics must be created GrowthBook before they can be used in experiments.";
+    }
+    const parts = [];
+    if (factMetrics.length > 0) {
+        parts.push(`**${factMetrics.length} fact metric(s)**:`);
+        parts.push("");
+        for (const m of factMetrics) {
+            const desc = m.description ? ` — ${m.description}` : "";
+            parts.push(`- **${m.name}** (id: \`${m.id}\`)${desc}`);
+        }
+    }
+    if (metrics.length > 0) {
+        if (parts.length > 0)
+            parts.push("");
+        parts.push(`**${metrics.length} legacy metric(s):**`);
+        parts.push("");
+        for (const m of metrics) {
+            const desc = m.description ? ` — ${m.description}` : "";
+            const type = m.type ? ` [${m.type}]` : "";
+            parts.push(`- **${m.name}** (id: \`${m.id}\`)${type}${desc}`);
+        }
+    }
+    parts.push("");
+    parts.push("Use metric `id` values when configuring experiment goals and guardrails. Fact metrics (ids starting with `fact__`) are recommended over legacy metrics.");
+    return parts.join("\n");
+}
+export function formatMetricDetail(data, appOrigin) {
+    const m = data.metric || data.factMetric;
+    if (!m)
+        return "Metric not found.";
+    const isFactMetric = !!data.factMetric;
+    const resource = isFactMetric ? "fact-metrics" : "metric";
+    const link = generateLinkToGrowthBook(appOrigin, resource, m.id);
+    const metricType = isFactMetric
+        ? "fact metric"
+        : "type" in m
+            ? m.type ?? "legacy"
+            : "legacy";
+    return [
+        `**Metric: ${m.name}** (id: \`${m.id}\`, type: ${metricType})`,
+        m.description ? `Description: ${m.description}` : "",
+        "inverse" in m && m.inverse
+            ? "**Inverse metric** — lower is better"
+            : "",
+        "",
+        `[View in GrowthBook](${link})`,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+// ─── Defaults ───────────────────────────────────────────────────────
+export function formatDefaults(defaults) {
+    const parts = [];
+    parts.push("**Experiment defaults:**");
+    parts.push("");
+    parts.push(`Datasource: \`${defaults.datasource || "not set"}\``);
+    parts.push(`Assignment query: \`${defaults.assignmentQuery || "not set"}\``);
+    parts.push(`Environments: ${defaults.environments?.length
+        ? defaults.environments.map((e) => `\`${e}\``).join(", ")
+        : "none found"}`);
+    if (defaults.name?.length > 0) {
+        const recentNames = defaults.name.slice(-5);
+        parts.push("");
+        parts.push("**Recent experiment naming examples:**");
+        for (const name of recentNames) {
+            if (name)
+                parts.push(`- ${name}`);
+        }
+    }
+    if (defaults.hypothesis?.length > 0) {
+        const recentHypotheses = defaults.hypothesis.filter(Boolean).slice(-3);
+        if (recentHypotheses.length > 0) {
+            parts.push("");
+            parts.push("**Recent hypothesis examples:**");
+            for (const h of recentHypotheses) {
+                parts.push(`- ${h}`);
+            }
+        }
+    }
+    return parts.join("\n");
+}
+// ─── Stale Features ─────────────────────────────────────────────────
+// Common SDK patterns to search for when removing a flag from the codebase
+const SDK_PATTERNS = [
+    // JS/TS/React
+    "isOn",
+    "getFeatureValue",
+    "useFeatureIsOn",
+    "useFeatureValue",
+    "evalFeature",
+    // Python
+    "is_on",
+    "get_feature_value",
+    // Go / Ruby / other
+    "IsOn",
+    "GetFeatureValue",
+    "feature_is_on",
+];
+function buildSearchPatterns(flagId) {
+    return SDK_PATTERNS.map((fn) => `${fn}("${flagId}")`).join(", ");
+}
+export function formatStaleFeatureFlags(data, requestedIds) {
+    const features = data.features || {};
+    const foundIds = Object.keys(features);
+    if (foundIds.length === 0) {
+        return "No features found for the given IDs. Check that the feature IDs are correct and your API key has access.";
+    }
+    const parts = [`**${foundIds.length} feature flag(s) checked:**`, ""];
+    let staleCount = 0;
+    for (const id of requestedIds) {
+        const f = features[id];
+        if (!f) {
+            parts.push(`- **\`${id}\`**: NOT FOUND`);
+            continue;
+        }
+        if (f.neverStale) {
+            parts.push(`- **\`${f.featureId}\`**: NOT STALE (stale detection disabled)`);
+            continue;
+        }
+        if (!f.isStale) {
+            parts.push(`- **\`${f.featureId}\`**: NOT STALE${f.staleReason ? ` (${f.staleReason})` : ""}`);
+            continue;
+        }
+        // ── Stale flag: include replacement guidance ──
+        staleCount++;
+        const envEntries = f.staleByEnv ? Object.entries(f.staleByEnv) : [];
+        const envsWithValues = envEntries.filter(([, e]) => e.evaluatesTo !== undefined);
+        let replacementValue;
+        let envNote;
+        if (envsWithValues.length === 0) {
+            replacementValue = undefined;
+            envNote =
+                "No deterministic value available — ask the user what the replacement should be.";
+        }
+        else {
+            const values = new Set(envsWithValues.map(([, e]) => e.evaluatesTo));
+            if (values.size === 1) {
+                replacementValue = envsWithValues[0][1].evaluatesTo;
+                envNote = `All environments agree.`;
+            }
+            else {
+                // Environments disagree — default to production
+                const prod = envsWithValues.find(([env]) => env === "production");
+                if (prod) {
+                    replacementValue = prod[1].evaluatesTo;
+                    const others = envsWithValues
+                        .map(([env, e]) => `${env}=\`${e.evaluatesTo}\``)
+                        .join(", ");
+                    envNote = `Environments disagree (${others}). Using production value. Confirm with the user if a different environment should be used.`;
+                }
+                else {
+                    replacementValue = envsWithValues[0][1].evaluatesTo;
+                    const others = envsWithValues
+                        .map(([env, e]) => `${env}=\`${e.evaluatesTo}\``)
+                        .join(", ");
+                    envNote = `Environments disagree (${others}). No production environment found, using ${envsWithValues[0][0]}. Confirm with the user which environment to use.`;
+                }
+            }
+        }
+        if (replacementValue !== undefined) {
+            parts.push(`- **\`${f.featureId}\`**: STALE (${f.staleReason}) — replace with: \`${replacementValue}\``);
+        }
+        else {
+            parts.push(`- **\`${f.featureId}\`**: STALE (${f.staleReason}) — needs manual review`);
+        }
+        parts.push(`  ${envNote}`);
+        parts.push(`  Search for: ${buildSearchPatterns(id)}`);
+        parts.push("");
+    }
+    // Summary
+    const notFound = requestedIds.filter((id) => !features[id]);
+    if (notFound.length > 0) {
+        parts.push(`${notFound.length} flag(s) not found: ${notFound.map((id) => `\`${id}\``).join(", ")}`);
+    }
+    if (staleCount > 0) {
+        parts.push(`**${staleCount} flag(s) ready for cleanup.** For each stale flag, find usages with the search patterns above, replace the flag check with the resolved value, and remove dead code branches. Confirm changes with the user before modifying files.`);
+    }
+    else {
+        parts.push("No stale flags found. All checked features are active.");
+    }
+    return parts.join("\n");
+}
+// ─── Helpful Errors ─────────────────────────────────────────────────
+export function formatApiError(error, context, suggestions) {
+    const message = error instanceof Error ? error.message : String(error);
+    const parts = [`Error ${context}: ${message}`];
+    if (suggestions && suggestions.length > 0) {
+        parts.push("");
+        parts.push("Suggestions:");
+        for (const s of suggestions) {
+            parts.push(`- ${s}`);
+        }
+    }
+    return parts.join("\n");
+}

package/server/tools/defaults.js

@@ -1,4 +1,5 @@
 import { handleResNotOk, fetchWithRateLimit, buildHeaders, } from "../utils.js";
+import { formatDefaults } from "../format-responses.js";
 import envPaths from "env-paths";
 import { writeFile, readFile, mkdir, unlink } from "fs/promises";
 import { join } from "path";
@@ -13,15 +14,15 @@ export async function createDefaults(apiKey, baseApiUrl) {
             headers: buildHeaders(apiKey, false),
         });
         await handleResNotOk(experimentsResponse);
-        const experimentData = await experimentsResponse.json();
-        if (experimentData.experiments.length === 0) {
+        const experimentData = (await experimentsResponse.json());
+        if (experimentData.experiments?.length === 0) {
             // No experiments: return assignment query and environments if possible
             const assignmentQueryResponse = await fetchWithRateLimit(`${baseApiUrl}/api/v1/data-sources`, {
                 headers: buildHeaders(apiKey, false),
             });
             await handleResNotOk(assignmentQueryResponse);
-            const dataSourceData = await assignmentQueryResponse.json();
-            if (dataSourceData.dataSources.length === 0) {
+            const dataSourceData = (await assignmentQueryResponse.json());
+            if (dataSourceData.dataSources?.length === 0) {
                 throw new Error("No data source or assignment query found. Experiments require a data source/assignment query. Set these up in the GrowthBook and try again.");
             }
             const assignmentQuery = dataSourceData.dataSources[0].assignmentQueries[0].id;
@@ -29,8 +30,8 @@ export async function createDefaults(apiKey, baseApiUrl) {
                 headers: buildHeaders(apiKey, false),
             });
             await handleResNotOk(environmentsResponse);
-            const environmentsData = await environmentsResponse.json();
-            const environments = environmentsData.environments.map(({ id }) => id);
+            const environmentsData = (await environmentsResponse.json());
+            const environments = (environmentsData.environments || []).map(({ id }) => id);
             return {
                 name: [],
                 hypothesis: [],
@@ -48,15 +49,15 @@ export async function createDefaults(apiKey, baseApiUrl) {
         let experiments = [];
         if (experimentData.hasMore) {
             const mostRecentExperiments = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments?offset=${experimentData.total -
-                Math.min(50, experimentData.count + experimentData.offset)}&limit=${Math.min(50, experimentData.count + experimentData.offset)}`, {
+                Math.min(50, (experimentData.count ?? 0) + (experimentData.offset ?? 0))}&limit=${Math.min(50, (experimentData.count ?? 0) + (experimentData.offset ?? 0))}`, {
                 headers: buildHeaders(apiKey),
             });
             await handleResNotOk(mostRecentExperiments);
-            const mostRecentExperimentData = await mostRecentExperiments.json();
-            experiments = mostRecentExperimentData.experiments;
+            const mostRecentExperimentData = (await mostRecentExperiments.json());
+            experiments = (mostRecentExperimentData.experiments || []);
         }
         else {
-            experiments = experimentData.experiments;
+            experiments = (experimentData.experiments || []);
         }
         // Aggregate experiment stats
         const experimentStats = experiments.reduce((acc, experiment) => {
@@ -107,8 +108,8 @@ export async function createDefaults(apiKey, baseApiUrl) {
             headers: buildHeaders(apiKey, false),
         });
         await handleResNotOk(environmentsResponse);
-        const environmentsData = await environmentsResponse.json();
-        const environments = environmentsData.environments.map(({ id }) => id);
+        const environmentsData = (await environmentsResponse.json());
+        const environments = (environmentsData.environments || []).map(({ id }) => id);
         return {
             name: experimentStats.name,
             hypothesis: experimentStats.hypothesis,
@@ -251,7 +252,7 @@ export async function registerDefaultsTools({ server, baseApiUrl, apiKey, }) {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(defaults),
+                    text: formatDefaults(defaults),
                 },
             ],
         };

package/server/tools/environments.js

@@ -1,4 +1,5 @@
 import { handleResNotOk, fetchWithRateLimit, buildHeaders, } from "../utils.js";
+import { formatEnvironments, formatApiError } from "../format-responses.js";
 import { z } from "zod";
 /**
  * Tool: get_environments
@@ -17,13 +18,15 @@ export function registerEnvironmentTools({ server, baseApiUrl, apiKey, }) {
                 headers: buildHeaders(apiKey),
             });
             await handleResNotOk(res);
-            const data = await res.json();
+            const data = (await res.json());
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text: formatEnvironments(data) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching environments: ${error}`);
+            throw new Error(formatApiError(error, "fetching environments", [
+                "Check that your GB_API_KEY has permission to read environments.",
+            ]));
         }
     });
 }

package/server/tools/experiments/experiment-summary.js

@@ -14,7 +14,7 @@ async function processBatch(items, concurrency, processor) {
     }
     return results;
 }
-async function getMetricLookup(baseApiUrl, apiKey, metricIds) {
+export async function getMetricLookup(baseApiUrl, apiKey, metricIds) {
     const metricLookup = new Map();
     if (metricIds.size === 0) {
         return metricLookup;

package/server/tools/experiments/experiments.js

@@ -1,7 +1,8 @@
 import { z } from "zod";
-import { generateLinkToGrowthBook, getDocsMetadata, handleResNotOk, SUPPORTED_FILE_EXTENSIONS, paginationSchema, fetchWithRateLimit, fetchWithPagination, featureFlagSchema, fetchFeatureFlag, mergeRuleIntoFeatureFlag, buildHeaders, } from "../../utils.js";
+import { getDocsMetadata, handleResNotOk, SUPPORTED_FILE_EXTENSIONS, paginationSchema, fetchWithRateLimit, fetchWithPagination, featureFlagSchema, fetchFeatureFlag, mergeRuleIntoFeatureFlag, buildHeaders, } from "../../utils.js";
+import { formatExperimentList, formatExperimentDetail, formatExperimentCreated, formatAttributes, formatApiError, } from "../../format-responses.js";
 import { getDefaults } from "../defaults.js";
-import { handleSummaryMode } from "./experiment-summary.js";
+import { handleSummaryMode, getMetricLookup } from "./experiment-summary.js";
 export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin, user, }) {
     /**
      * Tool: get_experiments
@@ -34,36 +35,56 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                     headers: buildHeaders(apiKey),
                 });
                 await handleResNotOk(res);
-                const data = await res.json();
-                // Fetch results
+                const data = (await res.json());
+                const dataWithResult = data;
                 if (mode === "full") {
-                    if (data.status === "draft") {
-                        data.result = null;
+                    // Fetch results
+                    if (data.experiment.status === "draft") {
+                        dataWithResult.result = null;
                     }
-                    try {
-                        const resultsRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments/${experimentId}/results`, {
-                            headers: buildHeaders(apiKey, false),
-                        });
-                        await handleResNotOk(resultsRes);
-                        const resultsData = await resultsRes.json();
-                        data.result = resultsData.result;
+                    else {
+                        try {
+                            const resultsRes = await fetchWithRateLimit(`${baseApiUrl}/api/v1/experiments/${experimentId}/results`, {
+                                headers: buildHeaders(apiKey, false),
+                            });
+                            await handleResNotOk(resultsRes);
+                            const resultsData = await resultsRes.json();
+                            dataWithResult.result = resultsData.result;
+                        }
+                        catch (error) {
+                            console.error(`Error fetching results for experiment ${experimentId}`, error);
+                        }
                     }
-                    catch (error) {
-                        console.error(`Error fetching results for experiment ${experimentId}`, error);
+                    // Resolve metric IDs to names
+                    const metricIds = new Set();
+                    for (const g of data.experiment.settings?.goals || [])
+                        metricIds.add(g.metricId);
+                    for (const g of data.experiment.settings?.guardrails || [])
+                        metricIds.add(g.metricId);
+                    for (const g of data.experiment.settings?.secondaryMetrics || [])
+                        metricIds.add(g.metricId);
+                    const metricLookup = await getMetricLookup(baseApiUrl, apiKey, metricIds);
+                    // Multi-block response: curated summary first, raw results second
+                    const content = [
+                        { type: "text", text: formatExperimentDetail(dataWithResult, appOrigin, metricLookup) },
+                    ];
+                    if (dataWithResult.result) {
+                        content.push({
+                            type: "text",
+                            text: `**Full results data (raw):**\n\`\`\`json\n${JSON.stringify(dataWithResult.result, null, 2)}\n\`\`\``,
+                        });
                     }
+                    return { content };
                 }
-                const linkToGrowthBook = generateLinkToGrowthBook(appOrigin, "experiment", experimentId);
-                const text = `
-      ${JSON.stringify(data)}
-      
-      [View the experiment in GrowthBook](${linkToGrowthBook})
-      `;
                 return {
-                    content: [{ type: "text", text }],
+                    content: [{ type: "text", text: formatExperimentDetail(dataWithResult, appOrigin) }],
                 };
             }
             catch (error) {
-                throw new Error(`Error getting experiment: ${error}`);
+                throw new Error(formatApiError(error, `fetching experiment '${experimentId}'`, [
+                    "Check the experiment ID is correct.",
+                    "Use get_experiments without an experimentId to list all available experiments.",
+                ]));
             }
         }
         const progressToken = extra._meta?.progressToken;
@@ -83,7 +104,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
         };
         await reportProgress(1, "Fetching experiments...");
         try {
-            const data = await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/experiments", limit, offset, mostRecent, project ? { projectId: project } : undefined);
+            const data = (await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/experiments", limit, offset, mostRecent, project ? { projectId: project } : undefined));
             let experiments = data.experiments || [];
             // Reverse experiments array for mostRecent to show newest-first
             if (mostRecent && offset === 0 && Array.isArray(experiments)) {
@@ -130,12 +151,20 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 };
             }
             await reportProgress(2, "Processing results...");
+            // Full mode: return raw JSON since users expect complete results data
+            if (mode === "full") {
+                return {
+                    content: [{ type: "text", text: JSON.stringify(data) }],
+                };
+            }
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text: formatExperimentList(data) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching experiments: ${error}`);
+            throw new Error(formatApiError(error, "fetching experiments", [
+                "Check that your GB_API_KEY has permission to read experiments.",
+            ]));
         }
     });
     /**
@@ -156,13 +185,15 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 headers: buildHeaders(apiKey),
             });
             await handleResNotOk(res);
-            const data = await res.json();
+            const data = (await res.json());
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text: formatAttributes(data) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching attributes: ${error}`);
+            throw new Error(formatApiError(error, "fetching attributes", [
+                "Check that your GB_API_KEY has permission to read attributes.",
+            ]));
         }
     });
     /**
@@ -252,7 +283,7 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 body: JSON.stringify(experimentPayload),
             });
             await handleResNotOk(experimentRes);
-            const experimentData = await experimentRes.json();
+            const experimentData = (await experimentRes.json());
             let flagData = null;
             if (featureId) {
                 // Fetch the existing feature flag first to preserve existing rules
@@ -275,23 +306,18 @@ export function registerExperimentTools({ server, baseApiUrl, apiKey, appOrigin,
                 });
                 await handleResNotOk(flagRes);
                 flagData = await flagRes.json();
-            }
-            const experimentLink = generateLinkToGrowthBook(appOrigin, "experiment", experimentData.experiment.id);
+            } // flagData is UpdateFeatureResponse when featureId was set
             const { stub, docs, language } = getDocsMetadata(fileExtension);
-            const flagText = featureId &&
-                `**How to implement the feature flag experiment in your code:**
----
-${stub}
----
-**Learn more about implementing experiments in your codebase:**
-See the [GrowthBook ${language} docs](${docs}).`;
-            const text = `**✅ Your draft experiment \`${name}\` is ready!.** [View the experiment in GrowthBook](${experimentLink}) to review and launch.\n\n${flagText}`;
             return {
-                content: [{ type: "text", text }],
+                content: [{ type: "text", text: formatExperimentCreated(experimentData, appOrigin, featureId ? stub : undefined, language, docs) }],
             };
         }
         catch (error) {
-            throw new Error(`Error creating experiment: ${error}`);
+            throw new Error(formatApiError(error, `creating experiment '${name}'`, [
+                "Call get_defaults first and use the returned datasource/assignment query IDs.",
+                "If linking to a feature flag, verify the flag exists with get_feature_flags.",
+                "Check that variation values match the specified valueType.",
+            ]));
         }
     });
 }

package/server/tools/features.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { getDocsMetadata, handleResNotOk, generateLinkToGrowthBook, paginationSchema, featureFlagSchema, fetchWithRateLimit, fetchWithPagination, fetchFeatureFlag, mergeRuleIntoFeatureFlag, buildHeaders, } from "../utils.js";
+import { getDocsMetadata, handleResNotOk, paginationSchema, featureFlagSchema, fetchWithRateLimit, fetchWithPagination, fetchFeatureFlag, mergeRuleIntoFeatureFlag, buildHeaders, } from "../utils.js";
+import { formatFeatureFlagList, formatFeatureFlagDetail, formatFeatureFlagCreated, formatForceRuleCreated, formatStaleFeatureFlags, formatApiError, } from "../format-responses.js";
 import { exec } from "child_process";
 import { getDefaults } from "./defaults.js";
 export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, user, }) {
@@ -54,28 +55,21 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
             await handleResNotOk(res);
             const data = await res.json();
             const { docs, language, stub } = getDocsMetadata(fileExtension);
-            const linkToGrowthBook = generateLinkToGrowthBook(appOrigin, "features", id);
-            const text = `This is the API response: ${JSON.stringify(data)}
-
-        Additionally, here is a template of what to show to the user:
-
-        **✅ Your feature flag \`my-flag-name\` is ready!**
-        [View it in GrowthBook](${linkToGrowthBook})
-
-        **How to use it in your code:**
-        (To the LLM agent. Use the text below to properly add the feature flag to the codebase. Also, surface the relevant docs/implemenation to the user)
-
-        ${stub}
-
-        **Want to learn more?**
-        See the [GrowthBook ${language} docs](${docs})
-      `;
             return {
-                content: [{ type: "text", text }],
+                content: [
+                    {
+                        type: "text",
+                        text: formatFeatureFlagCreated(data, appOrigin, stub, language, docs),
+                    },
+                ],
             };
         }
         catch (error) {
-            throw new Error(`Error creating feature flag: ${error}`);
+            throw new Error(formatApiError(error, `creating feature flag '${id}'`, [
+                "Check the id is valid (letters, numbers, _, -, ., :, | only).",
+                "A flag with this id may already exist — use get_feature_flags to check.",
+                "If scoping to a project, verify the project id with get_projects.",
+            ]));
         }
     });
     /**
@@ -122,29 +116,22 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
             });
             await handleResNotOk(res);
             const data = await res.json();
-            const linkToGrowthBook = generateLinkToGrowthBook(appOrigin, "features", featureId);
             const { docs, language, stub } = getDocsMetadata(fileExtension);
-            const text = `This is the API response: ${JSON.stringify(data)}
-
-        Additionally, here is a template of what to show to the user:
-
-        **✅ Your feature flag \`my-flag-name\` is ready!.**
-        [View it in GrowthBook](${linkToGrowthBook})
-    
-        **How to use it in your code:**
-        (To the LLM agent. Use the text below to properly add the feature flag to the codebase. Also, surface the relevant docs/implemenation to the user)
-
-        ${stub}
-
-        **Want to learn more?**
-        See the [GrowthBook ${language} docs](${docs})
-      `;
             return {
-                content: [{ type: "text", text }],
+                content: [
+                    {
+                        type: "text",
+                        text: formatForceRuleCreated(data, appOrigin, featureId, stub, language, docs),
+                    },
+                ],
             };
         }
         catch (error) {
-            throw new Error(`Error creating force rule: ${error}`);
+            throw new Error(formatApiError(error, `adding rule to '${featureId}'`, [
+                `Check that feature flag '${featureId}' exists — use get_feature_flags to verify.`,
+                'Ensure the value matches the flag\'s valueType (e.g. "true" for boolean flags).',
+                'For condition syntax, use MongoDB-style JSON: {"country": "US"}',
+            ]));
         }
     });
     /**
@@ -170,20 +157,17 @@ export function registerFeatureTools({ server, baseApiUrl, apiKey, appOrigin, us
                 });
                 await handleResNotOk(res);
                 const data = await res.json();
-                const linkToGrowthBook = generateLinkToGrowthBook(appOrigin, "features", featureFlagId);
-                const text = `This is the API response: ${JSON.stringify(data)}
-  
-Share information about the feature flag with the user. In particular, give details about the enabled environments,
-rules for each environment, and the default value. If the feature flag is archived or doesn't exist, inform the user and
-ask if they want to remove references to the feature flag from the codebase.
-  
-[View it in GrowthBook](${linkToGrowthBook})`;
                 return {
-                    content: [{ type: "text", text }],
+                    content: [
+                        { type: "text", text: formatFeatureFlagDetail(data, appOrigin) },
+                    ],
                 };
             }
             catch (error) {
-                throw new Error(`Error fetching flags: ${error}`);
+                throw new Error(formatApiError(error, `fetching feature flag '${featureFlagId}'`, [
+                    "Check the feature flag id is correct.",
+                    "Use get_feature_flags without a featureFlagId to list all available flags.",
+                ]));
             }
         }
         // Fetch multiple feature flags
@@ -194,66 +178,68 @@ ask if they want to remove references to the feature flag from the codebase.
                 data.features = data.features.reverse();
             }
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text: formatFeatureFlagList(data) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching flags: ${error}`);
+            throw new Error(formatApiError(error, "fetching feature flags", [
+                "Check that your GB_API_KEY has permission to read features.",
+            ]));
         }
     });
     /**
-     * Tool: get_stale_safe_rollouts
+     * Tool: get_stale_feature_flags
      */
-    server.registerTool("get_stale_safe_rollouts", {
-        title: "Get Stale Safe Rollouts",
-        description: "Finds feature flags with completed safe rollout rules that can be cleaned up from your codebase. Safe rollouts gradually increase traffic while monitoring for regressions. Completed rollouts (released or rolled-back) indicate flag code can be simplified: released means the new value won, rolled-back means revert to control value. Use for technical debt cleanup.",
+    server.registerTool("get_stale_feature_flags", {
+        title: "Get Stale Feature Flags",
+        description: "Given a list of feature flag IDs, checks whether each one is stale and returns cleanup guidance including replacement values and SDK search patterns. You MUST provide featureIds — gather them first from the user, from the current file context, or by grepping the codebase for SDK patterns (isOn, getFeatureValue, useFeatureIsOn, useFeatureValue, evalFeature).",
         inputSchema: z.object({
-            limit: z.number().optional().default(100),
-            offset: z.number().optional().default(0),
+            featureIds: z
+                .array(z.string())
+                .optional()
+                .describe("REQUIRED. One or more feature flag IDs to check (e.g. [\"my-feature\", \"dark-mode\"]). Gather IDs first from the user, from code context, or by grepping for SDK usage patterns."),
         }),
         annotations: {
             readOnlyHint: true,
         },
-    }, async ({ limit, offset }) => {
+    }, async ({ featureIds }) => {
         try {
-            const queryParams = new URLSearchParams({
-                limit: limit?.toString(),
-                offset: offset?.toString(),
-            });
-            const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/features?${queryParams.toString()}`, {
+            if (!featureIds?.length) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "**featureIds is required.** This tool checks specific flags — it does not list all stale flags.",
+                                "",
+                                "To gather feature flag IDs, try one of these approaches:",
+                                "1. **Ask the user** which flags they want to check",
+                                "2. **Extract from current file context** — look for flag IDs in the open file",
+                                "3. **Grep the codebase** for GrowthBook SDK patterns:",
+                                '   `grep -rn "isOn\\|getFeatureValue\\|useFeatureIsOn\\|useFeatureValue\\|evalFeature" --include="*.{ts,tsx,js,jsx,py,go,rb}"`',
+                                "",
+                                "Then call this tool again with the discovered flag IDs.",
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            const ids = featureIds.join(",");
+            const res = await fetchWithRateLimit(`${baseApiUrl}/api/v1/stale-features?ids=${encodeURIComponent(ids)}`, {
                 headers: buildHeaders(apiKey),
             });
             await handleResNotOk(res);
-            const data = await res.json();
-            const filteredSafeRollouts = data.features.filter((feature) => {
-                const envs = feature.environments;
-                if (!envs)
-                    return false;
-                return Object.values(envs).some((env) => {
-                    const rules = env.rules;
-                    if (!rules)
-                        return false;
-                    return rules.some((rule) => {
-                        return (rule.type === "safe-rollout" &&
-                            (rule.status === "rolled-back" || rule.status === "released"));
-                    });
-                });
-            });
-            const text = `
-        ${JSON.stringify(filteredSafeRollouts)}
-
-        Share information about the rolled-back or released safe rollout rules with the user. Safe Rollout rules are stored under
-        environmentSettings, keyed by environment and are within the rules array with a type of "safe-rollout". Ask the user if they
-        would like to remove references to the feature associated with the rolled-back or released safe rollout rules and if they do,
-        remove the references and associated GrowthBook code and replace the values with controlValue if the safe rollout rule is rolled-back or with the
-        variationValue if the safe rollout is released. In addition to the current file, you may need to update other files in the codebase.
-        `;
+            const data = (await res.json());
+            const text = formatStaleFeatureFlags(data, featureIds);
             return {
                 content: [{ type: "text", text }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching stale safe rollouts: ${error}`);
+            throw new Error(formatApiError(error, "checking stale features", [
+                "Check that the feature IDs are correct.",
+                "Check that your GB_API_KEY has permission to read features.",
+            ]));
         }
     });
     /**

package/server/tools/metrics.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { generateLinkToGrowthBook, handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, buildHeaders, } from "../utils.js";
+import { handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, buildHeaders, } from "../utils.js";
+import { formatMetricsList, formatMetricDetail, formatApiError } from "../format-responses.js";
 export function registerMetricsTools({ server, baseApiUrl, apiKey, appOrigin, }) {
     /**
      * Tool: get_metrics
@@ -36,27 +37,29 @@ export function registerMetricsTools({ server, baseApiUrl, apiKey, appOrigin, })
                     });
                 }
                 await handleResNotOk(res);
-                const data = await res.json();
-                const linkToGrowthBook = generateLinkToGrowthBook(appOrigin, data.factMetric ? "fact-metrics" : "metric", metricId);
+                const data = metricId.startsWith("fact__")
+                    ? (await res.json())
+                    : (await res.json());
                 return {
                     content: [
                         {
                             type: "text",
-                            text: JSON.stringify(data) +
-                                `\n**Critical** Show the user the link to the metric in GrowthBook: [View the metric in GrowthBook](${linkToGrowthBook})
-      `,
+                            text: formatMetricDetail(data, appOrigin),
                         },
                     ],
                 };
             }
             catch (error) {
-                throw new Error(`Error fetching metric: ${error}`);
+                throw new Error(formatApiError(error, `fetching metric '${metricId}'`, [
+                    "Check the metric ID is correct. Fact metric IDs start with 'fact__'.",
+                    "Use get_metrics without a metricId to list all available metrics.",
+                ]));
             }
         }
         try {
             const additionalParams = project ? { projectId: project } : undefined;
-            const metricsData = await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/metrics", limit, offset, mostRecent, additionalParams);
-            const factMetricData = await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/fact-metrics", limit, offset, mostRecent, additionalParams);
+            const metricsData = (await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/metrics", limit, offset, mostRecent, additionalParams));
+            const factMetricData = (await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/fact-metrics", limit, offset, mostRecent, additionalParams));
             // Reverse arrays for mostRecent to show newest-first
             if (mostRecent && offset === 0) {
                 if (Array.isArray(metricsData.metrics)) {
@@ -66,16 +69,14 @@ export function registerMetricsTools({ server, baseApiUrl, apiKey, appOrigin, })
                     factMetricData.factMetrics = factMetricData.factMetrics.reverse();
                 }
             }
-            const metricData = {
-                metrics: metricsData,
-                factMetrics: factMetricData,
-            };
             return {
-                content: [{ type: "text", text: JSON.stringify(metricData) }],
+                content: [{ type: "text", text: formatMetricsList(metricsData, factMetricData) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching metrics: ${error}`);
+            throw new Error(formatApiError(error, "fetching metrics", [
+                "Check that your GB_API_KEY has permission to read metrics.",
+            ]));
         }
     });
 }

package/server/tools/projects.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { paginationSchema, fetchWithPagination, } from "../utils.js";
+import { formatProjects, formatApiError } from "../format-responses.js";
 /**
  * Tool: get_projects
  */
@@ -15,17 +16,18 @@ export function registerProjectTools({ server, baseApiUrl, apiKey, }) {
         },
     }, async ({ limit, offset, mostRecent }) => {
         try {
-            const data = await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/projects", limit, offset, mostRecent);
-            // Reverse projects array for mostRecent to show newest-first
+            const data = (await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/projects", limit, offset, mostRecent));
             if (mostRecent && offset === 0 && Array.isArray(data.projects)) {
                 data.projects = data.projects.reverse();
             }
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text: formatProjects(data) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching projects: ${error}`);
+            throw new Error(formatApiError(error, "fetching projects", [
+                "Check that your GB_API_KEY has permission to read projects.",
+            ]));
         }
     });
 }

package/server/tools/sdk-connections.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { handleResNotOk, paginationSchema, fetchWithRateLimit, fetchWithPagination, buildHeaders, } from "../utils.js";
+import { formatSdkConnections, formatEnvironments, formatApiError } from "../format-responses.js";
 export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
     /**
      * Tool: get_sdk_connections
@@ -19,17 +20,19 @@ export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
         },
     }, async ({ limit, offset, mostRecent, project }) => {
         try {
-            const data = await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/sdk-connections", limit, offset, mostRecent, project ? { projectId: project } : undefined);
+            const data = (await fetchWithPagination(baseApiUrl, apiKey, "/api/v1/sdk-connections", limit, offset, mostRecent, project ? { projectId: project } : undefined));
             // Reverse connections array for mostRecent to show newest-first
             if (mostRecent && offset === 0 && Array.isArray(data.connections)) {
                 data.connections = data.connections.reverse();
             }
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text: formatSdkConnections(data) }],
             };
         }
         catch (error) {
-            throw new Error(`Error fetching sdk connections: ${error}`);
+            throw new Error(formatApiError(error, "fetching SDK connections", [
+                "Check that your GB_API_KEY has permission to read SDK connections.",
+            ]));
         }
     });
     /**
@@ -89,12 +92,14 @@ export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
                 });
                 await handleResNotOk(res);
                 const data = await res.json();
-                const text = `${JSON.stringify(data)}
-    
-        Here is the list of environments. Ask the user to select one and use the key in the create_sdk_connection tool.
-        `;
                 return {
-                    content: [{ type: "text", text }],
+                    content: [
+                        {
+                            type: "text",
+                            text: formatEnvironments(data) +
+                                "\n\nAsk the user to select an environment, then call create_sdk_connection with the chosen environment id.",
+                        },
+                    ],
                 };
             }
             catch (error) {
@@ -116,13 +121,20 @@ export function registerSdkConnectionTools({ server, baseApiUrl, apiKey, }) {
                 body: JSON.stringify(payload),
             });
             await handleResNotOk(res);
-            const data = await res.json();
+            const data = (await res.json());
+            const conn = data.sdkConnection;
+            const text = conn
+                ? `**SDK connection \`${conn.name}\` created.**\nClient key: \`${conn.key}\`\nEnvironment: ${conn.environment}\nLanguage(s): ${conn.languages.join(", ")}`
+                : `SDK connection created.\n${JSON.stringify(data)}`;
             return {
-                content: [{ type: "text", text: JSON.stringify(data) }],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
-            throw new Error(`Error creating sdk connection: ${error}`);
+            throw new Error(formatApiError(error, "creating SDK connection", [
+                "Ensure the environment exists — use get_environments to check available environments.",
+                "Check that the language parameter is a valid SDK language.",
+            ]));
         }
     });
 }

package/server/utils.js

@@ -516,3 +516,9 @@ export async function fetchWithPagination(baseApiUrl, apiKey, endpoint, limit, o
     await handleResNotOk(mostRecentRes);
     return await mostRecentRes.json();
 }
+export function formatList(items) {
+    return new Intl.ListFormat("en", {
+        style: "long",
+        type: "conjunction",
+    }).format(items);
+}