@greenflags/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GreenFlags
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @greenflags/mcp
+
+Connect Claude Desktop (or any MCP client) to GreenFlags to manage feature flags straight from the AI.
+
+## Requirements
+
+- Node.js ≥ 20
+- Access to a GreenFlags workspace (admin account for step 1)
+
+---
+
+## Setup
+
+### Step 1 — Register the app (workspace admin, one time only)
+
+In GreenFlags, go to **Settings → Developer Apps** and create a new app:
+
+| Field | Value |
+|-------|-------|
+| App name | `Claude Desktop MCP` |
+| Redirect URI | `http://localhost:9876/callback` |
+| Scopes | whichever you want to grant access to |
+
+Save the **Client ID** shown after creation. You'll need it in step 2.
+
+---
+
+### Step 2 — Configure Claude Desktop
+
+Edit your Claude Desktop config file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "greenflags": {
+      "command": "npx",
+      "args": ["-y", "@greenflags/mcp"],
+      "env": {
+        "GREENFLAGS_URL": "https://your-greenflags-instance.com",
+        "GREENFLAGS_CLIENT_ID": "the-client-id-from-step-1",
+        "GREENFLAGS_PROJECT_ID": "optional-default-project-id"
+      }
+    }
+  }
+}
+```
+
+`npx -y` downloads and runs the published package on demand — no local build required.
+
+`GREENFLAGS_PROJECT_ID` is optional (see **Default project**).
+
+Restart Claude Desktop.
+
+> If you don't set `GREENFLAGS_CLIENT_ID`, it defaults to `greenflags-mcp-client` (only valid if you seeded that row manually).
+
+---
+
+### Local development setup (alternative to npx)
+
+If you're working on this repo and want to run the server from source instead of the published package:
+
+```bash
+make mcp-install
+make mcp-build
+```
+
+Then point your config at the built file directly:
+```json
+{
+  "mcpServers": {
+    "greenflags": {
+      "command": "node",
+      "args": ["/absolute/path/to/repo/mcp/dist/index.js"],
+      "env": { "GREENFLAGS_URL": "...", "GREENFLAGS_CLIENT_ID": "..." }
+    }
+  }
+}
+```
+
+---
+
+## Default project
+
+If you set `GREENFLAGS_PROJECT_ID` in the `env` block, the `project` parameter becomes **optional** on every tool — the AI doesn't need to pass it on each call. If the AI passes an explicit `project`, that one wins.
+
+Without the env var, use `list_projects` first to discover available projects and pass `project` (id or slug) on every tool call.
+
+---
+
+## Identifiers
+
+Every tool accepts **key/slug or id** interchangeably:
+
+- `project` → project id or slug
+- `flag` → flag key (preferred) or id
+- `environment` → environment slug (preferred) or id
+
+The MCP resolves these to ids internally — you don't need to know the ids.
+
+---
+
+## Sensitive environments
+
+Environments flagged `is_sensitive` (typically prod) are protected. A `set_flag_value` write against a sensitive environment **is refused** unless you include `confirm: true`. Use `list_environments` to see which ones are sensitive.
+
+---
+
+## First use
+
+The first time you use a GreenFlags tool in Claude Desktop, it opens the browser to log in and approve access. Once approved, access is saved and won't be requested again (until the token expires in 1 hour).
+
+---
+
+## Re-authenticating
+
+If access expires or you want to switch accounts:
+
+```bash
+rm ~/.greenflags/tokens.json
+```
+
+The next tool call will open the browser again.
+
+---
+
+## Available tools
+
+| Tool | What it does |
+|------|----------|
+| `list_projects` | List the workspace's projects (entry point) |
+| `list_flags` | List flags with `status`/`search` filters and per-environment value |
+| `get_flag` | Get a flag by key or id |
+| `get_flag_values` | A flag's value across all environments (or one) |
+| `list_environments` | List environments, flags which ones are sensitive |
+| `create_flag` | Create a flag (typed: boolean/string/number/json) |
+| `update_flag` | Rename / change a flag's description |
+| `archive_flag` | Archive a flag (soft-delete) |
+| `set_flag_value` | Set a flag's typed value in an environment |
+
+All read tools return `structuredContent` (canonical JSON) in addition to a text summary.
+
+---
+
+## Breaking changes (0.2.0)
+
+- **`toggle_flag_value` removed.** Use **`set_flag_value`** instead. It's typed — pass exactly one of:
+  - `value_boolean: true|false`
+  - `value_string: "..."`
+  - `value_number: 123`
+  - `value_json: { ... }`
+
+  Defaults to the flag's declared `type`. For sensitive environments, add `confirm: true`.
+- New tools: `list_projects`, `get_flag_values`, `update_flag`.
+- Every tool accepts key/slug or id (see **Identifiers**) and supports `GREENFLAGS_PROJECT_ID` (see **Default project**).
+
+---
+
+## Security
+
+- Tokens are stored in plaintext at `~/.greenflags/tokens.json`. Don't use this MCP server on shared computers.
+- The token expires after 1 hour. You can delete it manually at any time.

package/dist/api.d.ts

@@ -0,0 +1 @@
+export declare function callApi<T>(path: string, method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE", data?: unknown, baseUrl?: string): Promise<T>;

package/dist/api.js

@@ -0,0 +1,46 @@
+import axios from "axios";
+import { GREENFLAGS_BASE_URL } from "./config.js";
+import { getValidToken } from "./auth.js";
+import { ApiError } from "./errors.js";
+export async function callApi(path, method = "GET", data, baseUrl = GREENFLAGS_BASE_URL) {
+    const token = await getValidToken(baseUrl);
+    try {
+        const res = await axios.request({
+            method,
+            url: `${baseUrl}${path}`,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            data,
+        });
+        return res.data.data;
+    }
+    catch (e) {
+        const err = e;
+        const status = err.response?.status ?? 0;
+        const body = err.response?.data;
+        const backendCode = body?.error;
+        const backendMsg = body?.message ?? err.message;
+        const details = body?.details;
+        if (status === 401) {
+            throw new ApiError("AUTH_EXPIRED", "Token expired or invalid. Re-authenticate (delete ~/.greenflags/tokens.json and call any tool to re-trigger OAuth).", 401);
+        }
+        if (status === 403) {
+            throw new ApiError(backendCode ?? "FORBIDDEN", backendMsg, 403, details);
+        }
+        if (status === 404) {
+            throw new ApiError(backendCode ?? "NOT_FOUND", `${backendMsg} (path: ${path})`, 404);
+        }
+        if (status === 409) {
+            throw new ApiError(backendCode ?? "CONFLICT", backendMsg, 409, details);
+        }
+        if (status === 422) {
+            throw new ApiError(backendCode ?? "VALIDATION_FAILED", backendMsg, 422, details);
+        }
+        if (status >= 500) {
+            throw new ApiError("API_ERROR", `Backend ${status}: ${backendMsg}`, status, details);
+        }
+        throw new ApiError(backendCode ?? "UNKNOWN", backendMsg, status, details);
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1 @@
+export declare function getValidToken(baseUrl?: string): Promise<string>;

package/dist/auth.js

@@ -0,0 +1,100 @@
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { URL } from "url";
+import open from "open";
+import axios from "axios";
+import { GREENFLAGS_BASE_URL, MCP_CALLBACK_PORT, MCP_CLIENT_ID, MCP_REDIRECT_URI, loadTokens, saveTokens, } from "./config.js";
+function generatePkce() {
+    const verifier = randomBytes(64)
+        .toString("base64url")
+        .slice(0, 96);
+    const challenge = createHash("sha256")
+        .update(verifier)
+        .digest("base64url");
+    return { verifier, challenge };
+}
+function generateState() {
+    return randomBytes(16).toString("hex");
+}
+async function authenticate(baseUrl) {
+    const { verifier, challenge } = generatePkce();
+    const state = generateState();
+    const port = MCP_CALLBACK_PORT;
+    const redirectUri = MCP_REDIRECT_URI;
+    // Open the browser-facing SPA consent page (not the /oauth/authorize JSON API,
+    // which requires a Bearer header a top-level navigation can't send).
+    const authorizeUrl = new URL(`${baseUrl}/authorize`);
+    authorizeUrl.searchParams.set("client_id", MCP_CLIENT_ID);
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("scope", "flags:read flags:write environments:read audit:read");
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    authorizeUrl.searchParams.set("state", state);
+    const code = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            server.close();
+            reject(new Error("OAuth timeout: no callback received within 5 minutes"));
+        }, 5 * 60 * 1000);
+        const server = createServer((req, res) => {
+            const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+            const receivedCode = reqUrl.searchParams.get("code");
+            const receivedState = reqUrl.searchParams.get("state");
+            const error = reqUrl.searchParams.get("error");
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<html><body><p>Authorization complete. You can close this tab.</p></body></html>");
+            server.close();
+            clearTimeout(timeout);
+            if (error) {
+                reject(new Error(`OAuth error: ${error}`));
+                return;
+            }
+            if (receivedState !== state) {
+                reject(new Error("OAuth state mismatch"));
+                return;
+            }
+            if (!receivedCode) {
+                reject(new Error("OAuth callback missing code"));
+                return;
+            }
+            resolve(receivedCode);
+        });
+        server.listen(port, "127.0.0.1", () => {
+            console.error(`[greenflags-mcp] Opening browser for OAuth authorization...`);
+            void open(authorizeUrl.toString());
+        });
+        server.on("error", (err) => {
+            clearTimeout(timeout);
+            if (err.code === "EADDRINUSE") {
+                reject(new Error(`[greenflags-mcp] Port ${port} is already in use.\n` +
+                    `Close the app using that port and try again.\n` +
+                    `To find it: lsof -i :${port}`));
+            }
+            else {
+                reject(err);
+            }
+        });
+    });
+    const tokenRes = await axios.post(`${baseUrl}/oauth/token`, {
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: redirectUri,
+        client_id: MCP_CLIENT_ID,
+        code_verifier: verifier,
+    }, { headers: { "content-type": "application/json" } });
+    const tokens = {
+        access_token: tokenRes.data.access_token,
+        expires_at: Date.now() + tokenRes.data.expires_in * 1000,
+    };
+    await saveTokens(tokens);
+    return tokens;
+}
+export async function getValidToken(baseUrl = GREENFLAGS_BASE_URL) {
+    const stored = await loadTokens();
+    const fiveMinutes = 5 * 60 * 1000;
+    if (stored && stored.expires_at - fiveMinutes > Date.now()) {
+        return stored.access_token;
+    }
+    const tokens = await authenticate(baseUrl);
+    return tokens.access_token;
+}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export declare const GREENFLAGS_BASE_URL: string;
+export declare const MCP_CLIENT_ID: string;
+export declare const MCP_CALLBACK_PORT = 9876;
+export declare const MCP_REDIRECT_URI = "http://localhost:9876/callback";
+export declare const TOKEN_PATH: string;
+export interface StoredTokens {
+    access_token: string;
+    expires_at: number;
+}
+export declare function saveTokens(tokens: StoredTokens): Promise<void>;
+export declare function loadTokens(): Promise<StoredTokens | null>;
+export declare function getDefaultProjectId(): string | undefined;
+export declare function requireProjectId(arg?: unknown): string;

package/dist/config.js

@@ -0,0 +1,37 @@
+import { homedir } from "os";
+import { join } from "path";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { MissingProjectIdError } from "./errors.js";
+export const GREENFLAGS_BASE_URL = process.env["GREENFLAGS_URL"] ?? "http://localhost:8787";
+// client_id of the OAuth client registered in GreenFlags (Developer Apps).
+// The admin UI generates a random UUID on registration, so this must be
+// configurable. Defaults to the seeded id for the manual-seed path.
+export const MCP_CLIENT_ID = process.env["GREENFLAGS_CLIENT_ID"] ?? "greenflags-mcp-client";
+export const MCP_CALLBACK_PORT = 9876;
+export const MCP_REDIRECT_URI = `http://localhost:${MCP_CALLBACK_PORT}/callback`;
+export const TOKEN_PATH = join(homedir(), ".greenflags", "tokens.json");
+export async function saveTokens(tokens) {
+    await mkdir(join(homedir(), ".greenflags"), { recursive: true });
+    await writeFile(TOKEN_PATH, JSON.stringify(tokens, null, 2), "utf-8");
+}
+export async function loadTokens() {
+    try {
+        const raw = await readFile(TOKEN_PATH, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function getDefaultProjectId() {
+    const raw = process.env["GREENFLAGS_PROJECT_ID"];
+    return raw && raw.trim() !== "" ? raw.trim() : undefined;
+}
+export function requireProjectId(arg) {
+    if (typeof arg === "string" && arg.trim() !== "")
+        return arg.trim();
+    const fallback = getDefaultProjectId();
+    if (fallback)
+        return fallback;
+    throw new MissingProjectIdError();
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class ApiError extends Error {
+    code: string;
+    status: number;
+    details?: unknown | undefined;
+    constructor(code: string, message: string, status: number, details?: unknown | undefined);
+}
+export declare class MissingProjectIdError extends Error {
+    constructor();
+}
+export declare class SensitiveConfirmRequiredError extends Error {
+    constructor(envSlug: string);
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+export class ApiError extends Error {
+    code;
+    status;
+    details;
+    constructor(code, message, status, details) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.details = details;
+        this.name = "ApiError";
+    }
+}
+export class MissingProjectIdError extends Error {
+    constructor() {
+        super("project_id is required. Pass project_id (or project) on the tool call, or set GREENFLAGS_PROJECT_ID in the MCP server environment.");
+        this.name = "MissingProjectIdError";
+    }
+}
+export class SensitiveConfirmRequiredError extends Error {
+    constructor(envSlug) {
+        super(`Environment '${envSlug}' is marked sensitive. Re-call this tool with confirm: true to apply.`);
+        this.name = "SensitiveConfirmRequiredError";
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { errorResult } from "./result.js";
+import * as listProjects from "./tools/listProjects.js";
+import * as listFlags from "./tools/listFlags.js";
+import * as getFlag from "./tools/getFlag.js";
+import * as createFlag from "./tools/createFlag.js";
+import * as updateFlag from "./tools/updateFlag.js";
+import * as setFlagValue from "./tools/setFlagValue.js";
+import * as archiveFlag from "./tools/archiveFlag.js";
+import * as listEnvironments from "./tools/listEnvironments.js";
+import * as getFlagValues from "./tools/getFlagValues.js";
+const tools = [
+    listProjects,
+    listFlags,
+    getFlag,
+    listEnvironments,
+    getFlagValues,
+    createFlag,
+    updateFlag,
+    setFlagValue,
+    archiveFlag,
+];
+const server = new Server({ name: "greenflags", version: "0.2.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => t.toolDefinition),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = tools.find((t) => t.toolDefinition.name === name);
+    if (!tool) {
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await tool.handler(args);
+        if (result &&
+            typeof result === "object" &&
+            "content" in result) {
+            return result;
+        }
+        return {
+            content: [{ type: "text", text: String(result) }],
+        };
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/resolvers.d.ts

@@ -0,0 +1,22 @@
+export interface FlagRecord {
+    id: string;
+    key: string;
+    name: string;
+    type: string;
+    status: string;
+    description?: string | null;
+}
+export interface EnvironmentRecord {
+    id: string;
+    name: string;
+    slug: string;
+    is_sensitive?: boolean;
+}
+export declare function resolveFlagId(projectId: string, flagOrKey: string): Promise<string>;
+export declare function resolveFlag(projectId: string, flagOrKey: string): Promise<FlagRecord>;
+export declare function resolveEnvironmentId(projectId: string, envOrSlug: string): Promise<string>;
+export declare function resolveEnvironment(projectId: string, envOrSlug: string): Promise<EnvironmentRecord>;
+export declare function listAllFlags(projectId: string): Promise<FlagRecord[]>;
+export declare function listAllEnvironments(projectId: string): Promise<EnvironmentRecord[]>;
+export declare function invalidateFlagCache(projectId: string): void;
+export declare function invalidateEnvironmentCache(projectId: string): void;

package/dist/resolvers.js

@@ -0,0 +1,92 @@
+import { callApi } from "./api.js";
+import { ApiError } from "./errors.js";
+const TTL_MS = 60_000;
+const flagCache = new Map();
+const envCache = new Map();
+function fresh(entry) {
+    if (!entry)
+        return undefined;
+    if (Date.now() - entry.at > TTL_MS)
+        return undefined;
+    return entry;
+}
+async function loadFlags(projectId) {
+    const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/flags`);
+    const byId = new Map();
+    const byAlt = new Map();
+    for (const f of data.flags) {
+        byId.set(f.id, f);
+        byAlt.set(f.key, f);
+    }
+    const entry = { at: Date.now(), byId, byAlt };
+    flagCache.set(projectId, entry);
+    return entry;
+}
+async function loadEnvironments(projectId) {
+    const data = await callApi(`/admin/projects/${encodeURIComponent(projectId)}/environments`);
+    const byId = new Map();
+    const byAlt = new Map();
+    for (const e of data.environments) {
+        const rec = {
+            id: e.id,
+            name: e.name,
+            slug: e.slug,
+            is_sensitive: Boolean(e.isSensitive),
+        };
+        byId.set(e.id, rec);
+        byAlt.set(e.slug, rec);
+    }
+    const entry = {
+        at: Date.now(),
+        byId,
+        byAlt,
+    };
+    envCache.set(projectId, entry);
+    return entry;
+}
+export async function resolveFlagId(projectId, flagOrKey) {
+    const entry = fresh(flagCache.get(projectId)) ?? (await loadFlags(projectId));
+    if (entry.byId.has(flagOrKey))
+        return flagOrKey;
+    const hit = entry.byAlt.get(flagOrKey);
+    if (hit)
+        return hit.id;
+    throw new ApiError("FLAG_NOT_FOUND", `Flag '${flagOrKey}' not found in project '${projectId}'. Use list_flags to see available flags.`, 404);
+}
+export async function resolveFlag(projectId, flagOrKey) {
+    const entry = fresh(flagCache.get(projectId)) ?? (await loadFlags(projectId));
+    const hit = entry.byId.get(flagOrKey) ?? entry.byAlt.get(flagOrKey);
+    if (hit)
+        return hit;
+    throw new ApiError("FLAG_NOT_FOUND", `Flag '${flagOrKey}' not found in project '${projectId}'.`, 404);
+}
+export async function resolveEnvironmentId(projectId, envOrSlug) {
+    const entry = fresh(envCache.get(projectId)) ?? (await loadEnvironments(projectId));
+    if (entry.byId.has(envOrSlug))
+        return envOrSlug;
+    const hit = entry.byAlt.get(envOrSlug);
+    if (hit)
+        return hit.id;
+    throw new ApiError("ENVIRONMENT_NOT_FOUND", `Environment '${envOrSlug}' not found in project '${projectId}'. Use list_environments to see available environments.`, 404);
+}
+export async function resolveEnvironment(projectId, envOrSlug) {
+    const entry = fresh(envCache.get(projectId)) ?? (await loadEnvironments(projectId));
+    const hit = entry.byId.get(envOrSlug) ?? entry.byAlt.get(envOrSlug);
+    if (hit)
+        return hit;
+    throw new ApiError("ENVIRONMENT_NOT_FOUND", `Environment '${envOrSlug}' not found in project '${projectId}'.`, 404);
+}
+export async function listAllFlags(projectId) {
+    const entry = fresh(flagCache.get(projectId)) ?? (await loadFlags(projectId));
+    return [...entry.byId.values()];
+}
+export async function listAllEnvironments(projectId) {
+    const entry = fresh(envCache.get(projectId)) ?? (await loadEnvironments(projectId));
+    return [...entry.byId.values()];
+}
+export function invalidateFlagCache(projectId) {
+    flagCache.delete(projectId);
+}
+export function invalidateEnvironmentCache(projectId) {
+    envCache.delete(projectId);
+}

package/dist/result.d.ts

@@ -0,0 +1,10 @@
+export interface McpToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export declare function okResult(structured: Record<string, unknown>, text: string): McpToolResult;
+export declare function errorResult(err: unknown): McpToolResult;

package/dist/result.js

@@ -0,0 +1,37 @@
+import { ApiError, MissingProjectIdError, SensitiveConfirmRequiredError, } from "./errors.js";
+export function okResult(structured, text) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: structured,
+    };
+}
+export function errorResult(err) {
+    if (err instanceof ApiError) {
+        return {
+            content: [{ type: "text", text: `${err.code}: ${err.message}` }],
+            structuredContent: {
+                error: {
+                    code: err.code,
+                    message: err.message,
+                    status: err.status,
+                    details: err.details ?? null,
+                },
+            },
+            isError: true,
+        };
+    }
+    if (err instanceof MissingProjectIdError ||
+        err instanceof SensitiveConfirmRequiredError) {
+        return {
+            content: [{ type: "text", text: err.message }],
+            structuredContent: { error: { code: err.name, message: err.message } },
+            isError: true,
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        structuredContent: { error: { code: "UNKNOWN", message } },
+        isError: true,
+    };
+}