@wabery/cli 0.19.0 → 0.20.2

package/dist/mcp-server.js

@@ -3,7 +3,27 @@ import { z } from "zod";
 import { WaberyApiClient, WaberyApiError } from "./api-client.js";
 import { createExampleConfig } from "./config-example.js";
 import { checkWaberyConnection } from "./diagnostics.js";
+import { executeMetaManagementOperation, META_MANAGEMENT_OPERATIONS, resolveMetaManagementOperation, } from "./meta-business-agent-operations.js";
 const configSchema = z.record(z.string(), z.unknown());
+const metaSettingsShape = {
+    rollout: z.object({ enabled: z.boolean() }).optional(),
+    ai_audience: z.enum(["ALLOWLISTED_ONLY", "EVERYONE"]).optional(),
+    handoff: z
+        .object({
+        enabled: z.boolean(),
+        message: z.string().optional(),
+        message_selection: z.enum(["DEFAULT", "AGENT", "CUSTOM"]).optional(),
+    })
+        .optional(),
+    followup: z
+        .object({
+        enabled: z.boolean(),
+        followup_interval_in_seconds: z.number().int().optional(),
+        message: z.string().optional(),
+    })
+        .optional(),
+    never_say_phrases: z.array(z.string()).optional(),
+};
 const metadataSchema = z.record(z.string(), z.unknown()).optional();
 const groupIdSchema = z
     .string()
@@ -216,7 +236,10 @@ const WRITE_NOTE = {
     enabled: "Write tools are enabled for this session. Your OAuth scopes decide what you may change, so attempt the write and let the server reject it if a scope is missing.",
 };
 function serverInstructions(writePolicy) {
-    return `${SERVER_INSTRUCTIONS}\n${WRITE_NOTE[writePolicy]}`;
+    const instructions = process.env.WABERY_META_BUSINESS_AGENTS_OPERATE_ENABLED === "true"
+        ? SERVER_INSTRUCTIONS
+        : SERVER_INSTRUCTIONS.replace(", and Business Agent configuration", "").replace("Use routing and thread-control tools for human handoff. ", "Use routing tools for human handoff. ");
+    return `${instructions}\n${WRITE_NOTE[writePolicy]}`;
 }
 const MCP_SENSITIVE_OUTPUT_KEY_SUFFIXES = [
     "accesstoken",
@@ -320,6 +343,10 @@ export function createWaberyMcpServer(client = new WaberyApiClient(), options =
         version: options.serverVersion ?? "0.1.0",
     }, { instructions: serverInstructions(writePolicy) });
     const registerTool = (name, config, callback) => {
+        if (name.includes("business_agent") &&
+            process.env.WABERY_META_BUSINESS_AGENTS_OPERATE_ENABLED !== "true") {
+            return undefined;
+        }
         options.onToolRegistered?.({
             name,
             title: config.title,
@@ -518,7 +545,7 @@ OpenAPI: https://api.wabery.com/v1/openapi.json
 CLI: npm i -g @wabery/cli (https://www.npmjs.com/package/@wabery/cli)
 MCP: https://mcp.wabery.com
 Sandbox: shared WhatsApp test number, no Meta setup
-Free plan: $0, one Live project, 500 messages, no credit card
+Free plan: $0, one Live project, 1,000 messages, no credit card
 API keys: create them yourself at https://app.wabery.com/access?tab=api-keys
 `,
         },
@@ -572,7 +599,7 @@ REST version is currently scheduled for sunset.
 
 Canonical URL: https://wabery.com/pricing.md
 
-Free: $0, 1 Live project, 500 messages, Sandbox, no credit card.
+Free: $0, 1 Live project, 1,000 messages, Sandbox, no credit card.
 Pro: $15/month for two Live projects and 50K messages.
 Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
 `,
@@ -711,6 +738,94 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             throw error;
         }
     });
+    registerTool("wabery_list_business_agent_operations", {
+        title: "Discover Meta management operations",
+        description: "Use this when you need to discover documented Meta management operations supported by this client. This is management access for a creator, never customer-facing agent tools. Server authorization and feature availability still apply; local contract coverage is not live verification.",
+        inputSchema: {},
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => jsonResult({
+        operations: META_MANAGEMENT_OPERATIONS,
+        live_verified: false,
+    }));
+    const metaOperationNames = (read) => META_MANAGEMENT_OPERATIONS.filter((item) => (item.method === "GET") === read).map((item) => item.name);
+    registerTool("wabery_read_business_agent_operation", {
+        title: "Read Meta management data",
+        description: "Use this when you need to read a named operation from wabery_list_business_agent_operations. Supply path identifiers in parameters (business_agent_id, connector_id, tool_id, remote_id) and documented filters in query. Connector/tool IDs are Wabery binding IDs; other resource IDs are Meta IDs. This cannot invoke a write or run a tool.",
+        inputSchema: {
+            operation: z.enum(metaOperationNames(true)),
+            parameters: z.record(z.string()).optional(),
+            query: z.record(z.union([z.string(), z.number()])).optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async ({ operation, ...input }) => {
+        if (resolveMetaManagementOperation(operation).method !== "GET")
+            throw new Error("Read operation required");
+        return jsonResult(await executeMetaManagementOperation(client, operation, input));
+    });
+    registerTool("wabery_write_business_agent_operation", {
+        title: "Change Meta management configuration",
+        description: "Use this when you need one named management write after explicit creator approval. Parameters contain scoped IDs; body contains the documented Wabery API request. Test/eval/tool-run may cause real backend writes: isolate connectors first. No automatic retries after uncertain writes. For files.upload provide body.file_name and body.file_base64 (up to 1 MiB decoded); use CLI/SDK for larger files. Never provide this management tool to a customer-facing agent.",
+        inputSchema: {
+            operation: z.enum(metaOperationNames(false)),
+            parameters: z.record(z.string()).optional(),
+            query: z.record(z.union([z.string(), z.number()])).optional(),
+            body: z.record(z.unknown()).optional(),
+            operation_id: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("Required caller-owned ID for onboard, settings, and connector mutations."),
+            confirmation_token: z
+                .string()
+                .optional()
+                .describe("Required confirmation: meta_management_write"),
+        },
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ operation, confirmation_token, operation_id, ...input }) => {
+        const blocked = await requireWrite("wabery_write_business_agent_operation", confirmation_token, "meta_management_write");
+        if (blocked)
+            return blocked;
+        if (resolveMetaManagementOperation(operation).method === "GET")
+            throw new Error("Write operation required");
+        let body = input.body;
+        if (operation === "files.upload") {
+            const name = input.body?.file_name;
+            const encoded = input.body?.file_base64;
+            if (typeof name !== "string" ||
+                typeof encoded !== "string" ||
+                encoded.length > 1_398_104 ||
+                !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded))
+                throw new Error("Provide file_name and valid base64 for a file of at most 1 MiB");
+            const bytes = Buffer.from(encoded, "base64");
+            if (bytes.length > 1_048_576)
+                throw new Error("MCP file limit is 1 MiB; use CLI or SDK");
+            const form = new FormData();
+            form.set("file_name", name);
+            form.set("file", new Blob([new Uint8Array(bytes)]), name);
+            body = form;
+        }
+        return jsonResult(await executeMetaManagementOperation(client, operation, {
+            ...input,
+            body,
+            operationId: operation_id,
+        }));
+    });
     registerTool("wabery_list_business_agents", {
         title: "List Meta Business Agents",
         description: "Use this when you need the selected project's Meta Business Agent records and business_agent_id values. Do not use it for live settings; use wabery_get_business_agent_settings.",
@@ -746,11 +861,8 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
         description: "Use this when you need to provision or overwrite Meta Business Agent settings for a channel_id from wabery_list_channels. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
         inputSchema: {
             channel_id: z.string().min(1),
-            enabled: z.boolean().optional(),
-            persona: z.string().min(1).max(4096).optional(),
-            language: z.string().min(2).max(16).optional(),
-            handoff: z.record(z.string(), z.unknown()).optional(),
-            knowledge: z.record(z.string(), z.unknown()).optional(),
+            operation_id: z.string().min(1).max(200),
+            ...metaSettingsShape,
             confirmation_token: z
                 .string()
                 .optional()
@@ -763,11 +875,11 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             openWorldHint: true,
         },
     }, async (input) => {
-        const { confirmation_token, ...body } = input;
+        const { confirmation_token, operation_id, ...body } = input;
         const blocked = await requireWrite("wabery_apply_business_agent", confirmation_token, "apply_business_agent");
         if (blocked)
             return blocked;
-        return jsonResult(await client.put("/business-agents", body));
+        return jsonResult(await client.put("/business-agents", body, operation_id));
     });
     registerTool("wabery_get_business_agent_settings", {
         title: "Get Meta Business Agent settings",
@@ -787,11 +899,8 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
         description: "Use this when you need to overwrite live Meta settings for a business_agent_id from wabery_list_business_agents. Prefer wabery_apply_business_agent when provisioning by channel.",
         inputSchema: {
             business_agent_id: z.string().min(1),
-            enabled: z.boolean().optional(),
-            persona: z.string().min(1).max(4096).optional(),
-            language: z.string().min(2).max(16).optional(),
-            handoff: z.record(z.string(), z.unknown()).optional(),
-            knowledge: z.record(z.string(), z.unknown()).optional(),
+            operation_id: z.string().min(1).max(200),
+            ...metaSettingsShape,
             confirmation_token: z
                 .string()
                 .optional()
@@ -804,11 +913,11 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             openWorldHint: true,
         },
     }, async (input) => {
-        const { business_agent_id, confirmation_token, ...body } = input;
+        const { business_agent_id, confirmation_token, operation_id, ...body } = input;
         const blocked = await requireWrite("wabery_update_business_agent_settings", confirmation_token, "update_business_agent_settings");
         if (blocked)
             return blocked;
-        return jsonResult(await client.put(`/business-agents/${encodeURIComponent(business_agent_id)}/settings`, body));
+        return jsonResult(await client.put(`/business-agents/${encodeURIComponent(business_agent_id)}/settings`, body, operation_id));
     });
     registerTool("wabery_list_business_agent_connectors", {
         title: "List Meta Business Agent connectors",
@@ -830,6 +939,7 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
         description: "Use this when you need to create a connector in Meta for a provisioned business_agent_id from wabery_list_business_agents. Prefer wabery_apply_config for reviewed project-wide declarative changes.",
         inputSchema: {
             business_agent_id: z.string().min(1),
+            operation_id: z.string().min(1).max(200),
             name: z.string().min(1).max(120),
             type: z.string().min(1).max(80),
             config: z.record(z.string(), z.unknown()).optional(),
@@ -846,11 +956,11 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             openWorldHint: true,
         },
     }, async (input) => {
-        const { confirmation_token, ...body } = input;
+        const { confirmation_token, operation_id, ...body } = input;
         const blocked = await requireWrite("wabery_create_business_agent_connector", confirmation_token, "create_business_agent_connector");
         if (blocked)
             return blocked;
-        return jsonResult(await client.post("/business-agents/connectors", body));
+        return jsonResult(await client.post("/business-agents/connectors", body, operation_id));
     });
     registerTool("wabery_create_business_agent_connector_tool", {
         title: "Create Meta Business Agent connector tool",
@@ -972,7 +1082,7 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
     });
     registerTool("wabery_get_business_agent_thread_control", {
         title: "Get Meta Business Agent thread control",
-        description: "Use this when you need to inspect current WhatsApp thread ownership for a channel_id from wabery_list_channels and contact_id from wabery_list_contacts. Use the set tool for handoff.",
+        description: "Use this when you need Wabery's last observed thread-control state, which may be unknown or stale. Meta does not document an owner GET endpoint. Use channel_id and contact_id from this project; use the set tool for an explicit transition.",
         inputSchema: {
             channel_id: z.string().min(1),
             contact_id: z.string().min(1),
@@ -980,26 +1090,27 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             thread_id: z.string().min(1).optional(),
         },
         annotations: {
-            readOnlyHint: false,
+            readOnlyHint: true,
             destructiveHint: false,
-            idempotentHint: false,
+            idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => jsonResult(await client.post("/business-agents/thread-control", {
+    }, async (input) => jsonResult(await client.get("/business-agents/thread-control", {
         ...input,
-        action: "get",
     })));
     registerTool("wabery_set_business_agent_thread_control", {
         title: "Set Meta Business Agent thread control",
         description: "Use this when you need to take or pass WhatsApp thread control for a channel_id and contact_id, changing automation or human ownership. Inspect first with wabery_get_business_agent_thread_control.",
         inputSchema: {
-            action: z.enum(["take", "pass"]),
+            operation_id: z.string().min(1).max(200),
+            action: z.enum(["take", "release", "pass"]),
             channel_id: z.string().min(1),
             contact_id: z.string().min(1),
             business_agent_id: z.string().min(1).optional(),
-            thread_id: z.string().min(1).optional(),
+            to: z.string().min(1),
+            pass_to_meta: z.boolean().optional(),
             reason: z.string().max(512).optional(),
-            payload: z.record(z.string(), z.unknown()).optional(),
+            metadata: z.string().max(2000).optional(),
             confirmation_token: z
                 .string()
                 .optional()
@@ -1012,19 +1123,21 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             openWorldHint: true,
         },
     }, async (input) => {
-        const { confirmation_token, ...body } = input;
+        const { confirmation_token, operation_id, ...body } = input;
         const blocked = await requireWrite("wabery_set_business_agent_thread_control", confirmation_token, "thread_control");
         if (blocked)
             return blocked;
-        return jsonResult(await client.post("/business-agents/thread-control", body));
+        return jsonResult(await client.post("/business-agents/thread-control", body, operation_id));
     });
     registerTool("wabery_test_business_agent", {
         title: "Test Meta Business Agent",
         description: "Use this when you need to submit a controlled test scenario to Meta for a business_agent_id from wabery_list_business_agents. This is a remote provider operation, not a read or a real-recipient message send.",
         inputSchema: {
+            operation_id: z.string().min(1).max(200),
             business_agent_id: z.string().min(1),
-            input: z.string().min(1).optional(),
-            scenario: z.record(z.string(), z.unknown()).optional(),
+            user_msg: z.string().min(1),
+            conversation_id: z.string().min(1).optional(),
+            isolated_connectors: z.literal(true),
             confirmation_token: z
                 .string()
                 .optional()
@@ -1036,17 +1149,23 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ confirmation_token, ...body }) => {
+    }, async ({ confirmation_token, operation_id, ...body }) => {
         const blocked = await requireWrite("wabery_test_business_agent", confirmation_token, "test_business_agent");
         if (blocked)
             return blocked;
-        return jsonResult(await client.post("/business-agents/test", body));
+        return jsonResult(await client.post("/business-agents/test", body, operation_id));
     });
     registerTool("wabery_get_business_agent_eval", {
-        title: "Get Meta Business Agent eval summary",
-        description: "Use this when you need the live Meta evaluation summary for a business_agent_id from wabery_list_business_agents. Do not use it to run a test scenario.",
+        title: "Read Meta Business Agent evaluation",
+        description: "Use this when you need cases, a job, evaluation details, or summaries. Supply job_id for run, comma-separated eval_id for details, or comma-separated summary_id for summary. This does not start evaluation or invoke tools.",
         inputSchema: {
             business_agent_id: z.string().min(1),
+            operation: z
+                .enum(["cases", "run", "details", "summary"])
+                .default("cases"),
+            job_id: z.string().optional(),
+            eval_id: z.string().optional(),
+            summary_id: z.string().optional(),
         },
         annotations: {
             readOnlyHint: true,
@@ -1054,12 +1173,16 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async ({ business_agent_id }) => jsonResult(await client.get("/business-agents/eval", {
+    }, async ({ business_agent_id, operation, job_id, eval_id, summary_id }) => jsonResult(await client.get("/business-agents/eval", {
         business_agent_id,
+        operation,
+        job_id,
+        eval_id,
+        summary_id,
     })));
     registerTool("wabery_list_business_agent_skills", {
         title: "List Meta Business Agent skills",
-        description: "Use this when you need the current Meta skill list for a business_agent_id from wabery_list_business_agents. Use the set tool only to replace the full list.",
+        description: "Use this when you need individual Meta skills and review states. There is no bulk replacement API. Use skills.create/update/delete through the management operation tool.",
         inputSchema: {
             business_agent_id: z.string().min(1),
         },
@@ -1072,28 +1195,31 @@ Create API keys yourself at https://app.wabery.com/access?tab=api-keys.
     }, async ({ business_agent_id }) => jsonResult(await client.get("/business-agents/skills", {
         business_agent_id,
     })));
-    registerTool("wabery_set_business_agent_skills", {
-        title: "Set Meta Business Agent skills",
-        description: "Use this when you need to replace the entire Meta skill list for a business_agent_id from wabery_list_business_agents. Do not use it to append one skill without first preserving existing entries.",
+    registerTool("wabery_create_business_agent_skill", {
+        title: "Create one Meta Business Agent skill",
+        description: "Use this when you need to create one skill without replacing existing skills. Its Meta review status must become active before relying on it.",
         inputSchema: {
+            operation_id: z.string().min(1).max(200),
             business_agent_id: z.string().min(1),
-            skills: z.array(z.unknown()),
+            title: z.string().max(64).optional(),
+            description: z.string().max(1024).optional(),
+            skill: z.string().max(20000).optional(),
             confirmation_token: z
                 .string()
                 .optional()
-                .describe("Required when write mode is enabled: set_business_agent_skills"),
+                .describe("Required when write mode is enabled: create_business_agent_skill"),
         },
         annotations: {
             readOnlyHint: false,
-            destructiveHint: true,
-            idempotentHint: true,
+            destructiveHint: false,
+            idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ confirmation_token, ...body }) => {
-        const blocked = await requireWrite("wabery_set_business_agent_skills", confirmation_token, "set_business_agent_skills");
+    }, async ({ confirmation_token, operation_id, ...body }) => {
+        const blocked = await requireWrite("wabery_create_business_agent_skill", confirmation_token, "create_business_agent_skill");
         if (blocked)
             return blocked;
-        return jsonResult(await client.put("/business-agents/skills", body));
+        return jsonResult(await client.post("/business-agents/skills", body, operation_id));
     });
     registerTool("wabery_list_projects", {
         title: "List Wabery projects",