@greenflags/mcp 0.2.0

package/dist/tools/archiveFlag.d.ts

@@ -0,0 +1,31 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            project: {
+                type: string;
+                description: string;
+            };
+            project_id: {
+                type: string;
+                description: string;
+            };
+            flag: {
+                type: string;
+                description: string;
+            };
+            flag_id: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function handler(args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/archiveFlag.js

@@ -0,0 +1,45 @@
+import { callApi } from "../api.js";
+import { requireProjectId } from "../config.js";
+import { okResult } from "../result.js";
+import { invalidateFlagCache, resolveFlag } from "../resolvers.js";
+export const toolDefinition = {
+    name: "archive_flag",
+    description: "Archive a flag (soft-delete: stops being served but kept for history).\n" +
+        "Use when: a flag is no longer needed. Prefer set_flag_value(false) if you only want to turn it off temporarily.\n" +
+        "Prerequisites: a project + an existing flag (key or id). Call list_flags to find candidates.\n" +
+        "Side effects: DESTRUCTIVE (flag stops serving). Idempotent — re-archiving returns changed:false.\n" +
+        'Example: archive_flag(flag: "legacy-banner").',
+    annotations: {
+        destructiveHint: true,
+        idempotentHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project id or slug. Optional if GREENFLAGS_PROJECT_ID is set.",
+            },
+            project_id: { type: "string", description: "Legacy alias for `project`." },
+            flag: {
+                type: "string",
+                description: "Flag key (preferred) or flag id.",
+            },
+            flag_id: { type: "string", description: "Legacy alias for `flag`." },
+        },
+    },
+};
+export async function handler(args) {
+    const projectId = requireProjectId(args["project"] ?? args["project_id"]);
+    const flagArg = (args["flag"] ?? args["flag_id"]);
+    if (typeof flagArg !== "string" || flagArg.trim() === "") {
+        throw new Error("`flag` (key or id) is required.");
+    }
+    const current = await resolveFlag(projectId, flagArg.trim());
+    const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/flags/${encodeURIComponent(current.id)}/archive`, "POST");
+    invalidateFlagCache(projectId);
+    const before = { status: current.status };
+    const after = data.flag;
+    const changed = before.status !== after.status;
+    return okResult({ flag: after, before, changed }, `Flag ${after.key} archived${changed ? "" : " (was already archived)"}.`);
+}

package/dist/tools/createFlag.d.ts

@@ -0,0 +1,41 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            project: {
+                type: string;
+                description: string;
+            };
+            project_id: {
+                type: string;
+                description: string;
+            };
+            key: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handler(args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/createFlag.js

@@ -0,0 +1,57 @@
+import { callApi } from "../api.js";
+import { requireProjectId } from "../config.js";
+import { okResult } from "../result.js";
+import { invalidateFlagCache } from "../resolvers.js";
+export const toolDefinition = {
+    name: "create_flag",
+    description: "Create a new feature flag in a project. Defaults to a boolean flag; pass `type` for string/number/json.\n" +
+        "Use when: the user wants a brand-new flag. To change an existing flag use update_flag; to set its value use set_flag_value.\n" +
+        "Prerequisites: a project. The key must be unique within the project (409 on conflict).\n" +
+        "Side effects: creates a flag (not idempotent — re-calling with the same key fails).\n" +
+        'Example: create_flag(key: "dark-mode", name: "Dark Mode").',
+    annotations: {
+        destructiveHint: false,
+        idempotentHint: false,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project id or slug. Optional if GREENFLAGS_PROJECT_ID is set.",
+            },
+            project_id: { type: "string", description: "Legacy alias for `project`." },
+            key: {
+                type: "string",
+                description: "Unique flag key (e.g. 'dark-mode').",
+            },
+            name: { type: "string", description: "Human-readable flag name." },
+            description: { type: "string", description: "Optional description." },
+            type: {
+                type: "string",
+                enum: ["boolean", "string", "number", "json"],
+                description: "Flag value type. Defaults to 'boolean'.",
+            },
+        },
+        required: ["key", "name"],
+    },
+};
+export async function handler(args) {
+    const projectId = requireProjectId(args["project"] ?? args["project_id"]);
+    const key = String(args["key"] ?? "").trim();
+    const name = String(args["name"] ?? "").trim();
+    if (!key || !name)
+        throw new Error("`key` and `name` are required.");
+    const type = typeof args["type"] === "string"
+        ? args["type"]
+        : "boolean";
+    const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/flags`, "POST", {
+        key,
+        name,
+        description: args["description"] ?? null,
+        type,
+    });
+    invalidateFlagCache(projectId);
+    const f = data.flag;
+    return okResult({ flag: f }, `Flag created: ${f.key} (id ${f.id}, type ${f.type})`);
+}

package/dist/tools/getFlag.d.ts

@@ -0,0 +1,32 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            project: {
+                type: string;
+                description: string;
+            };
+            project_id: {
+                type: string;
+                description: string;
+            };
+            flag: {
+                type: string;
+                description: string;
+            };
+            flag_key: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+};
+export declare function handler(args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/getFlag.js

@@ -0,0 +1,48 @@
+import { callApi } from "../api.js";
+import { requireProjectId } from "../config.js";
+import { okResult } from "../result.js";
+import { listAllFlags } from "../resolvers.js";
+export const toolDefinition = {
+    name: "get_flag",
+    description: "Get a single flag's metadata (id, key, name, type, status, description) by key (preferred) or id.\n" +
+        "Use when: you need one flag's details. For its per-environment values use get_flag_values instead.\n" +
+        "Prerequisites: a project (call list_projects if unknown, or set GREENFLAGS_PROJECT_ID).\n" +
+        "Side effects: none (read-only).\n" +
+        'Example: get_flag(flag: "dark-mode").',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project id or slug. Optional if GREENFLAGS_PROJECT_ID is set.",
+            },
+            project_id: { type: "string", description: "Legacy alias for `project`." },
+            flag: {
+                type: "string",
+                description: "Flag key (e.g. 'dark-mode') or flag id. Key is preferred — it uses a single backend call.",
+            },
+            flag_key: { type: "string", description: "Legacy alias for `flag`." },
+        },
+        required: [],
+    },
+};
+export async function handler(args) {
+    const projectId = requireProjectId(args["project"] ?? args["project_id"]);
+    const flagArg = (args["flag"] ?? args["flag_key"]);
+    if (typeof flagArg !== "string" || flagArg.trim() === "") {
+        throw new Error("`flag` (key or id) is required.");
+    }
+    let flagKey = flagArg.trim();
+    const all = await listAllFlags(projectId);
+    const byId = all.find((f) => f.id === flagKey);
+    if (byId)
+        flagKey = byId.key;
+    const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/flags/by-key/${encodeURIComponent(flagKey)}`);
+    const f = data.flag;
+    const summary = `${f.key} (${f.type}, ${f.status}): ${f.name}${f.description ? ` — ${f.description}` : ""}`;
+    return okResult({ flag: f }, summary);
+}

package/dist/tools/getFlagValues.d.ts

@@ -0,0 +1,35 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            project: {
+                type: string;
+                description: string;
+            };
+            project_id: {
+                type: string;
+                description: string;
+            };
+            flag: {
+                type: string;
+                description: string;
+            };
+            flag_key: {
+                type: string;
+                description: string;
+            };
+            environment: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function handler(args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/getFlagValues.js

@@ -0,0 +1,77 @@
+import { callApi } from "../api.js";
+import { requireProjectId } from "../config.js";
+import { okResult } from "../result.js";
+import { listAllEnvironments, resolveEnvironmentId, resolveFlag, } from "../resolvers.js";
+export const toolDefinition = {
+    name: "get_flag_values",
+    description: "Get a flag's value across all environments, or a single environment when `environment` is given.\n" +
+        "Use when: answering \"is X enabled in prod?\" or \"what value does Y have in staging?\".\n" +
+        "Prerequisites: a project + an existing flag (key or id).\n" +
+        "Side effects: none (read-only).\n" +
+        'Example: get_flag_values(flag: "checkout-v2", environment: "prod").',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project id or slug. Optional if GREENFLAGS_PROJECT_ID is set.",
+            },
+            project_id: { type: "string", description: "Legacy alias for `project`." },
+            flag: {
+                type: "string",
+                description: "Flag key (preferred) or flag id.",
+            },
+            flag_key: { type: "string", description: "Legacy alias for `flag`." },
+            environment: {
+                type: "string",
+                description: "Optional environment slug or id. When set, returns only that env value.",
+            },
+        },
+    },
+};
+export async function handler(args) {
+    const projectId = requireProjectId(args["project"] ?? args["project_id"]);
+    const flagArg = (args["flag"] ?? args["flag_key"]);
+    if (typeof flagArg !== "string" || flagArg.trim() === "") {
+        throw new Error("`flag` (key or id) is required.");
+    }
+    const envArg = typeof args["environment"] === "string" ? args["environment"] : undefined;
+    const flag = await resolveFlag(projectId, flagArg.trim());
+    const envs = await listAllEnvironments(projectId);
+    const envById = new Map(envs.map((e) => [e.id, e]));
+    const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/flags/${encodeURIComponent(flag.id)}/values`);
+    let rows = data.values;
+    let envFilter;
+    if (envArg) {
+        const envId = await resolveEnvironmentId(projectId, envArg);
+        rows = rows.filter((r) => r.environmentId === envId);
+        const e = envById.get(envId);
+        envFilter = { id: envId, slug: e?.slug ?? envId };
+    }
+    const values = rows.map((r) => {
+        const e = envById.get(r.environmentId);
+        return {
+            environment_id: r.environmentId,
+            environment_slug: e?.slug ?? null,
+            environment_name: e?.name ?? null,
+            is_sensitive: Boolean(e?.is_sensitive),
+            type: r.type,
+            value: r.value,
+            updated_by_user_id: r.updatedByUserId,
+        };
+    });
+    const summary = values.length === 0
+        ? `Flag '${flag.key}' has no value set${envFilter ? ` in env '${envFilter.slug}'` : ""}.`
+        : `Flag '${flag.key}' values:\n${values
+            .map((v) => `- ${v.environment_slug ?? v.environment_id}: ${JSON.stringify(v.value)}`)
+            .join("\n")}`;
+    return okResult({
+        flag: { id: flag.id, key: flag.key, type: flag.type },
+        environment: envFilter ?? null,
+        values,
+    }, summary);
+}

package/dist/tools/listEnvironments.d.ts

@@ -0,0 +1,23 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            project: {
+                type: string;
+                description: string;
+            };
+            project_id: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function handler(args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/listEnvironments.js

@@ -0,0 +1,41 @@
+import { requireProjectId } from "../config.js";
+import { okResult } from "../result.js";
+import { listAllEnvironments } from "../resolvers.js";
+export const toolDefinition = {
+    name: "list_environments",
+    description: "List all environments in a project (e.g. dev, staging, prod), each with id, slug, and is_sensitive.\n" +
+        "Use when: you need environment slugs/ids, or to check which envs are sensitive before a write.\n" +
+        "Prerequisites: a project (call list_projects if unknown, or set GREENFLAGS_PROJECT_ID).\n" +
+        "Side effects: none (read-only). Writes to is_sensitive envs require confirm:true in set_flag_value.\n" +
+        'Example: "what environments exist?" before set_flag_value.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project id or slug. Optional if GREENFLAGS_PROJECT_ID is set.",
+            },
+            project_id: { type: "string", description: "Legacy alias for `project`." },
+        },
+    },
+};
+export async function handler(args) {
+    const projectId = requireProjectId(args["project"] ?? args["project_id"]);
+    const envs = await listAllEnvironments(projectId);
+    const items = envs.map((e) => ({
+        id: e.id,
+        name: e.name,
+        slug: e.slug,
+        is_sensitive: Boolean(e.is_sensitive),
+    }));
+    const summary = items.length === 0
+        ? "No environments in project."
+        : items
+            .map((e) => `- ${e.name} (slug: ${e.slug}, id: ${e.id})${e.is_sensitive ? " [sensitive]" : ""}`)
+            .join("\n");
+    return okResult({ items, total: items.length }, summary);
+}

package/dist/tools/listFlags.d.ts

@@ -0,0 +1,36 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {
+            project: {
+                type: string;
+                description: string;
+            };
+            project_id: {
+                type: string;
+                description: string;
+            };
+            environment: {
+                type: string;
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            search: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare function handler(args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/listFlags.js

@@ -0,0 +1,94 @@
+import { callApi } from "../api.js";
+import { requireProjectId } from "../config.js";
+import { okResult } from "../result.js";
+import { listAllFlags, resolveEnvironment, } from "../resolvers.js";
+export const toolDefinition = {
+    name: "list_flags",
+    description: "List flags in a project, optionally filtered by status/search and showing each flag's value in one environment.\n" +
+        "Use when: browsing flags, or answering questions like \"which flags are off in prod?\" (pass environment + status).\n" +
+        "Prerequisites: a project (call list_projects if unknown, or set GREENFLAGS_PROJECT_ID).\n" +
+        "Side effects: none (read-only).\n" +
+        'Example: list_flags(environment: "prod", status: "active", search: "checkout").',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project id or slug. Optional if GREENFLAGS_PROJECT_ID is set in the MCP server environment.",
+            },
+            project_id: {
+                type: "string",
+                description: "Legacy alias for `project`.",
+            },
+            environment: {
+                type: "string",
+                description: "Optional environment slug or id. When set, each flag entry includes `value_in_env`.",
+            },
+            status: {
+                type: "string",
+                enum: ["active", "archived"],
+                description: "Optional filter by status.",
+            },
+            search: {
+                type: "string",
+                description: "Optional case-insensitive substring filter applied to `key` and `name`.",
+            },
+        },
+    },
+};
+export async function handler(args) {
+    const projectId = requireProjectId(args["project"] ?? args["project_id"]);
+    const status = typeof args["status"] === "string" ? args["status"] : undefined;
+    const search = typeof args["search"] === "string" && args["search"].trim() !== ""
+        ? args["search"].toLowerCase().trim()
+        : undefined;
+    const envArg = typeof args["environment"] === "string" ? args["environment"] : undefined;
+    const flags = await listAllFlags(projectId);
+    let env;
+    if (envArg) {
+        const e = await resolveEnvironment(projectId, envArg);
+        env = { id: e.id, slug: e.slug, is_sensitive: Boolean(e.is_sensitive) };
+    }
+    let filtered = flags;
+    if (status)
+        filtered = filtered.filter((f) => f.status === status);
+    if (search)
+        filtered = filtered.filter((f) => f.key.toLowerCase().includes(search) ||
+            f.name.toLowerCase().includes(search));
+    const items = await Promise.all(filtered.map(async (f) => {
+        let value_in_env = undefined;
+        if (env) {
+            const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/flags/${encodeURIComponent(f.id)}/values`);
+            const v = data.values.find((row) => row.environmentId === env.id);
+            value_in_env = v ? v.value : null;
+        }
+        return {
+            id: f.id,
+            key: f.key,
+            name: f.name,
+            type: f.type,
+            status: f.status,
+            description: f.description ?? null,
+            ...(env ? { value_in_env } : {}),
+        };
+    }));
+    const head = items
+        .slice(0, 5)
+        .map((i) => env
+        ? `- ${i.key} (${i.status}) = ${JSON.stringify(i.value_in_env)}`
+        : `- ${i.key} (${i.status}): ${i.name}`)
+        .join("\n");
+    const summary = items.length === 0
+        ? "No flags match."
+        : `Found ${items.length} flag(s)${env ? ` in env ${env.slug}` : ""}${status ? ` with status=${status}` : ""}${search ? ` matching "${search}"` : ""}.\n${head}${items.length > 5 ? "\n..." : ""}`;
+    return okResult({
+        items,
+        total: items.length,
+        filtered: Boolean(status || search || env),
+        environment: env ?? null,
+    }, summary);
+}

package/dist/tools/listProjects.d.ts

@@ -0,0 +1,14 @@
+import { type McpToolResult } from "../result.js";
+export declare const toolDefinition: {
+    name: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputSchema: {
+        type: "object";
+        properties: {};
+    };
+};
+export declare function handler(_args: Record<string, unknown>): Promise<McpToolResult>;

package/dist/tools/listProjects.js

@@ -0,0 +1,34 @@
+import { callApi } from "../api.js";
+import { okResult } from "../result.js";
+export const toolDefinition = {
+    name: "list_projects",
+    description: "List all projects in the authenticated workspace, returning each project's id, name, and slug.\n" +
+        "Use when: you don't yet know which project to operate on — every other tool needs a project.\n" +
+        "Prerequisites: none. This is the typical entry point.\n" +
+        "Side effects: none (read-only).\n" +
+        'Example: "what projects do I have?" or as the first step before listing flags.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+export async function handler(_args) {
+    const data = await callApi("/admin/projects");
+    const items = data.projects.map((p) => ({
+        id: p.id,
+        name: p.name,
+        slug: p.slug,
+        description: p.description ?? null,
+    }));
+    const summary = items.length === 0
+        ? "No projects in workspace."
+        : `Found ${items.length} project(s): ${items
+            .slice(0, 5)
+            .map((p) => p.slug)
+            .join(", ")}${items.length > 5 ? ", ..." : ""}`;
+    return okResult({ items, total: items.length }, summary);
+}