@rcs-campaigns/agent-toolkit 0.1.9 → 0.1.10

package/README.md

@@ -24,14 +24,18 @@ key** (Admin only). Pick the scopes the agent needs, then **copy the key — it
 shown exactly once** (`rcsk_live_…`). Treat it like a password; you can
 revoke/rotate it from the same screen.
 
-Scopes: `templates:read`, `templates:write`, `templates:submit`,
+Scopes: `campaigns:read`, `campaigns:write`, `campaigns:submit`,
 `marketplace:clone`, `messages:send`, `usage:read`, `surveys:read`,
 `surveys:write`, `surveys:submit`, `surveys:send`, `results:read`.
 
-### 2. Set the gateway URL
+### 2. Gateway URL (optional)
+
+The toolkit talks to the hosted production gateway by default, so a production
+key needs nothing else. Set `RCS_GATEWAY_URL` (or pass `--url`) only to target
+dev or a local gateway:
 
 ```bash
-RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com
+RCS_GATEWAY_URL=http://localhost:3002
 ```
 
 > The key is tied to the environment it was minted in — a key from one
@@ -67,7 +71,6 @@ pnpm --filter @rcs-campaigns/agent-toolkit build   # -> dist/mcp.js, dist/cli.js
 ### 4. Verify the key works (before wiring up a host)
 
 ```bash
-export RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com
 export RCS_AGENT_KEY=rcsk_live_…
 npx -y -p @rcs-campaigns/agent-toolkit rcs capabilities
 ```
@@ -88,7 +91,6 @@ name.
 
 ```bash
 claude mcp add rcs-campaigns \
-  --env RCS_GATEWAY_URL=https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com \
   --env RCS_AGENT_KEY=rcsk_live_… \
   -- npx -y -p @rcs-campaigns/agent-toolkit rcs-mcp
 ```
@@ -110,7 +112,6 @@ Edit `claude_desktop_config.json`
       "command": "npx",
       "args": ["-y", "-p", "@rcs-campaigns/agent-toolkit", "rcs-mcp"],
       "env": {
-        "RCS_GATEWAY_URL": "https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com",
         "RCS_AGENT_KEY": "rcsk_live_…"
       }
     }
@@ -160,7 +161,7 @@ out — pipe into `jq`, wire into CI, or call from a skill.
 | Symptom | Cause / fix |
 |---|---|
 | `No agent key configured` | `RCS_AGENT_KEY` not reaching the process — for MCP hosts it must be in the server's `env` block, not your shell. |
-| `Gateway 401` | Key wrong, revoked, or minted in a different environment than `RCS_GATEWAY_URL` points at. |
+| `Gateway 401` | Key wrong, revoked, or minted in a different environment than the gateway you're calling (production unless `RCS_GATEWAY_URL` says otherwise). |
 | `Gateway 403` (scope) | The key lacks the tool's scope — mint a new key with it (scopes are fixed at creation). |
 | Host shows no tools | Wrong path to `dist/mcp.js`, or the package wasn't built (`pnpm --filter @rcs-campaigns/agent-toolkit build`). |
 | Empty search results | The org has no published/owned templates yet — clone one from the marketplace first. |
@@ -172,7 +173,7 @@ out — pipe into `jq`, wire into CI, or call from a skill.
 ```ts
 import { GatewayClient, TOOLS } from '@rcs-campaigns/agent-toolkit';
 
-const client = GatewayClient.fromEnv(); // reads RCS_GATEWAY_URL + RCS_AGENT_KEY
+const client = GatewayClient.fromEnv(); // reads RCS_AGENT_KEY (+ optional RCS_GATEWAY_URL)
 const { items } = await client.call({
   method: 'GET',
   path: '/templates',

package/dist/cli.js

@@ -12,7 +12,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * org's own brand) and reads RCS_*. Either prefix is accepted under either bin.
  *
  * Config (flags override env):
- *   --url <gateway base url>   | WA_GATEWAY_URL / RCS_GATEWAY_URL
+ *   --url <gateway base url>   | WA_GATEWAY_URL / RCS_GATEWAY_URL (optional;
+ *                                defaults to the hosted production gateway)
  *   --key <rcsk_…>             | WA_AGENT_KEY   / RCS_AGENT_KEY
  *   --channel RCS|WHATSAPP     | WA_DEFAULT_CHANNEL / RCS_DEFAULT_CHANNEL
  *
@@ -29,30 +30,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
  */
 const node_fs_1 = require("node:fs");
 const client_1 = require("./client");
-/** Minimal argv parser: --flag value, --bool, and repeatable --to/--var. */
-function parseArgs(argv) {
-    const out = { _: [], flags: {}, multi: { to: [], var: [], audience: [] } };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a.startsWith('--')) {
-            const key = a.slice(2);
-            const next = argv[i + 1];
-            const takesValue = next !== undefined && !next.startsWith('--');
-            const value = takesValue ? argv[++i] : true;
-            if (key === 'to' || key === 'var' || key === 'audience') {
-                if (typeof value === 'string')
-                    out.multi[key].push(value);
-            }
-            else {
-                out.flags[key] = value;
-            }
-        }
-        else {
-            out._.push(a);
-        }
-    }
-    return out;
-}
+const tools_1 = require("./tools");
+const cliDispatch_1 = require("./cliDispatch");
 /**
  * Read a JSON body from a file, letting the skin's default channel apply when
  * the document doesn't name one. An explicit `channel` in the file always wins,
@@ -83,11 +62,28 @@ function kvPairs(pairs) {
 function print(data) {
     process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
 }
+// Catalog dispatch: everything without a curated command below is reached
+// through the tool catalog, so a new gateway capability is callable from the
+// CLI as soon as it has a `tools.ts` entry. The parsing lives in
+// ./cliDispatch so it can be tested without running this entry point.
+async function dispatchCatalog(words, argv, client, defaultChannel) {
+    const match = (0, cliDispatch_1.resolveTool)(words);
+    if (!match) {
+        fail(`Unknown command: ${words.join(' ') || '(none)'}\n\n${USAGE}`);
+    }
+    const { tool, used } = match;
+    const args = (0, cliDispatch_1.argsFromArgv)(tool, words.slice(used), argv);
+    return print(await client.call(tool.toRequest((0, tools_1.withDefaultChannel)(tool, args, defaultChannel))));
+}
 const SKIN = (0, client_1.detectSkin)();
-const BIN = SKIN === 'wa' ? 'wa' : 'rcs';
+const BRAND = (0, client_1.detectBrand)();
+/** The bin name as the user typed it; the surveys packages ship their own. */
+const BIN = BRAND === 'wa-surveys' || BRAND === 'rcs-surveys' ? BRAND : SKIN === 'wa' ? 'wa' : 'rcs';
+/** Env var prefix: WA_* or RCS_*, never the bin name (wa-surveys → WA_*). */
+const ENV_PREFIX = SKIN === 'wa' ? 'WA' : 'RCS';
 /** Show the channel this skin actually defaults to in its own help text. */
 const CHANNEL_EG = SKIN === 'wa' ? 'WHATSAPP' : 'RCS';
-const USAGE = `${BIN} — ${(0, client_1.skinLabels)(SKIN).product} agent CLI v${(0, client_1.readVersion)()}
+const USAGE = `${BIN} — ${(0, client_1.skinLabels)(BRAND).product} agent CLI v${(0, client_1.readVersion)()}
 
 Usage:
   ${BIN} capabilities
@@ -113,9 +109,18 @@ Surveys:
   ${BIN} survey sends <id>
   ${BIN} survey results <id>
 
-Config: --url/${BIN.toUpperCase()}_GATEWAY_URL, --key/${BIN.toUpperCase()}_AGENT_KEY`;
+Everything else, straight from the tool catalog (scope shown after each):
+${(0, cliDispatch_1.catalogUsage)(BIN)}
+
+  Any catalog tool name also works as typed (${BIN} list_conversations, or
+  ${BIN} list-conversations). Structured arguments come from --file <doc.json>:
+  an object merges at the top level, a bare array fills the tool's list argument.
+  Repeat a flag or comma-separate it for lists (--event a --event b).
+
+Config: --key/${ENV_PREFIX}_AGENT_KEY (required),
+        --url/${ENV_PREFIX}_GATEWAY_URL (optional; defaults to the hosted gateway)`;
 async function run() {
-    const argv = parseArgs(process.argv.slice(2));
+    const argv = (0, cliDispatch_1.parseArgs)(process.argv.slice(2));
     const cmd = argv._[0];
     if (!cmd || cmd === 'help' || argv.flags.help) {
         process.stdout.write(`${USAGE}\n`);
@@ -340,12 +345,12 @@ async function run() {
                         path: `/surveys/${enc(id)}/results`
                     }));
                 default:
-                    fail(`Unknown survey subcommand: ${sub ?? '(none)'}\n\n${USAGE}`);
+                    // `survey render|clone|delete` and anything the catalog grows later.
+                    return dispatchCatalog(argv._, argv, client, config.defaultChannel);
             }
-            return;
         }
         default:
-            fail(`Unknown command: ${cmd}\n\n${USAGE}`);
+            return dispatchCatalog(argv._, argv, client, config.defaultChannel);
     }
 }
 function str(v) {
@@ -363,6 +368,10 @@ function fail(message) {
     process.exit(2);
 }
 run().catch((err) => {
+    if (err instanceof cliDispatch_1.UsageError) {
+        // Bad arguments, not a failed call — same exit 2 the curated commands use.
+        fail(err.message);
+    }
     if (err instanceof client_1.GatewayError) {
         process.stderr.write(`Gateway ${err.status}: ${err.message}\n`);
         if (err.details)

package/dist/cliDispatch.d.ts

@@ -0,0 +1,65 @@
+import { type ToolDef } from './tools';
+export interface ParsedArgs {
+    _: string[];
+    flags: Record<string, string | boolean>;
+    multi: Record<string, string[]>;
+    /**
+     * EVERY flag's values in order, including the ones `multi` claims and the
+     * ones `flags` collapses to their last occurrence. Catalog dispatch needs
+     * this: an array-typed argument (`--event a --event b`) cannot be expressed
+     * by either of the other two, and hardcoding another name into `multi` would
+     * put us back to editing this file whenever the gateway grows an argument.
+     */
+    repeats: Record<string, string[]>;
+}
+/**
+ * A caller error — bad or missing arguments, unknown command.
+ *
+ * Thrown rather than exiting so these functions stay testable; `cli.ts` turns
+ * it into the same stderr + exit 2 every usage error has always produced.
+ */
+export declare class UsageError extends Error {
+}
+/** Minimal argv parser: --flag value, --bool, and repeatable --to/--var. */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/**
+ * Catalog tools that already have a curated command, listed only so generated
+ * help does not print a second, uglier spelling of a command that has a good
+ * one. Being in this set does not disable catalog dispatch for the tool.
+ */
+export declare const CURATED: Set<string>;
+/**
+ * Friendlier spellings for generically-dispatched tools: `wa audience get`
+ * rather than `wa get_audience`. The catalog name always works too, in snake or
+ * kebab case, so a tool added tomorrow is callable before anyone writes it an
+ * alias here.
+ */
+export declare const ALIASES: Record<string, string>;
+/** The `:param` names in a tool's route, in the order the route names them. */
+export declare function pathParams(tool: ToolDef): string[];
+/** The friendly spelling of a tool, for help text and error messages. */
+export declare function cliName(tool: ToolDef): string;
+/**
+ * Resolve argv's leading words to a catalog tool. Two words are tried first so
+ * `audience get` wins over a tool literally named `audience`; the number of
+ * words consumed comes back so the caller knows where positionals start.
+ */
+export declare function resolveTool(words: string[]): {
+    tool: ToolDef;
+    used: number;
+} | undefined;
+/** Coerce raw flag strings to the JSON-Schema type the tool declares. */
+export declare function coerce(schema: any, values: string[]): unknown;
+/**
+ * Build a tool's arguments from argv: positionals fill the route's `:params`,
+ * flags fill everything else, and `--file` supplies the structured ones — an
+ * object merges at the top level, a bare array fills the tool's single
+ * array-typed argument, so `--file contacts.json` works whether the file holds
+ * `[…]` or `{"contacts":[…]}`.
+ */
+export declare function argsFromArgv(tool: ToolDef, positionals: string[], argv: ParsedArgs, readFile?: (path: string) => string): Record<string, any>;
+/** One tool's usage line, derived from its schema rather than written by hand. */
+export declare function toolUsage(tool: ToolDef, bin?: string): string;
+/** The generated half of the help: every catalog tool without a curated command. */
+export declare function catalogUsage(bin?: string): string;
+//# sourceMappingURL=cliDispatch.d.ts.map

package/dist/cliDispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliDispatch.d.ts","sourceRoot":"","sources":["../src/cliDispatch.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,EAAE,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,KAAK;CAAG;AAExC,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAyBpD;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO,aAyBlB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAwB1C,CAAC;AAEF,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAElD;AAED,yEAAyE;AACzE,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAG7C;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,MAAM,EAAE,GACd;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAa7C;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CA4B7D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,MAAM,EAAE,EACrB,IAAI,EAAE,UAAU,EAChB,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAuC,GAClE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAiDrB;AAED,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,SAAQ,GAAG,MAAM,CAc5D;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,GAAG,SAAQ,GAAG,MAAM,CAIhD"}

package/dist/cliDispatch.js

@@ -0,0 +1,260 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALIASES = exports.CURATED = exports.UsageError = void 0;
+exports.parseArgs = parseArgs;
+exports.pathParams = pathParams;
+exports.cliName = cliName;
+exports.resolveTool = resolveTool;
+exports.coerce = coerce;
+exports.argsFromArgv = argsFromArgv;
+exports.toolUsage = toolUsage;
+exports.catalogUsage = catalogUsage;
+/**
+ * Argument parsing and catalog dispatch for the `rcs` / `wa` CLI.
+ *
+ * Split out of `cli.ts` because that file is an entry point: it calls `run()`
+ * at module scope, so importing it to test anything would run the CLI. These
+ * are the pure parts — argv in, tool arguments out — and they are where the
+ * behaviour worth testing lives.
+ *
+ * WHY CATALOG DISPATCH EXISTS: `tools.ts` already declares every gateway
+ * capability (route, schema, scope) and a CI test fails when a route has no
+ * entry. The CLI used to hand-write its own routes anyway, so it drifted to
+ * ~20 of the catalog's 48 tools while the MCP server had all of them. Now the
+ * curated commands stay hand-written — they earn it, folding several flags into
+ * one endpoint — and everything else is reached through the catalog, so a new
+ * capability is callable from the CLI the moment it has a catalog entry.
+ */
+const node_fs_1 = require("node:fs");
+const tools_1 = require("./tools");
+/**
+ * A caller error — bad or missing arguments, unknown command.
+ *
+ * Thrown rather than exiting so these functions stay testable; `cli.ts` turns
+ * it into the same stderr + exit 2 every usage error has always produced.
+ */
+class UsageError extends Error {
+}
+exports.UsageError = UsageError;
+/** Minimal argv parser: --flag value, --bool, and repeatable --to/--var. */
+function parseArgs(argv) {
+    const out = {
+        _: [],
+        flags: {},
+        multi: { to: [], var: [], audience: [] },
+        repeats: {}
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            const takesValue = next !== undefined && !next.startsWith('--');
+            const value = takesValue ? argv[++i] : true;
+            if (typeof value === 'string')
+                (out.repeats[key] ??= []).push(value);
+            if (key === 'to' || key === 'var' || key === 'audience') {
+                if (typeof value === 'string')
+                    out.multi[key].push(value);
+            }
+            else {
+                out.flags[key] = value;
+            }
+        }
+        else {
+            out._.push(a);
+        }
+    }
+    return out;
+}
+/**
+ * Catalog tools that already have a curated command, listed only so generated
+ * help does not print a second, uglier spelling of a command that has a good
+ * one. Being in this set does not disable catalog dispatch for the tool.
+ */
+exports.CURATED = new Set([
+    'capabilities',
+    'search_templates',
+    'get_template',
+    'render_template',
+    'create_template',
+    'clone_template',
+    'submit_template',
+    'send_message',
+    'upload_media',
+    'get_knowledge',
+    'set_knowledge',
+    'delete_knowledge',
+    'enable_knowledge',
+    'disable_knowledge',
+    'get_usage',
+    'search_surveys',
+    'get_survey',
+    'create_survey',
+    'update_survey',
+    'submit_survey',
+    'send_survey',
+    'send_survey_test',
+    'list_survey_sends',
+    'get_results'
+]);
+/**
+ * Friendlier spellings for generically-dispatched tools: `wa audience get`
+ * rather than `wa get_audience`. The catalog name always works too, in snake or
+ * kebab case, so a tool added tomorrow is callable before anyone writes it an
+ * alias here.
+ */
+exports.ALIASES = {
+    audiences: 'search_audiences',
+    'audience get': 'get_audience',
+    'audience contacts': 'list_audience_contacts',
+    'audience create': 'create_audience',
+    'audience import': 'import_contacts',
+    'audience delete': 'delete_audience',
+    contacts: 'list_contacts',
+    'contact get': 'get_contact',
+    'contact update': 'update_contact',
+    conversations: 'list_conversations',
+    'conversation get': 'get_conversation',
+    'conversation assign': 'assign_conversation',
+    webhooks: 'list_webhooks',
+    'webhook create': 'create_webhook',
+    'webhook update': 'update_webhook',
+    'webhook delete': 'delete_webhook',
+    'webhook test': 'test_webhook',
+    'template update': 'update_template',
+    'template duplicate': 'duplicate_template',
+    'template delete': 'delete_template',
+    'survey render': 'render_survey',
+    'survey clone': 'clone_survey',
+    'survey delete': 'delete_survey'
+};
+/** The `:param` names in a tool's route, in the order the route names them. */
+function pathParams(tool) {
+    return (tool.path.match(/:([A-Za-z0-9_]+)/g) ?? []).map((s) => s.slice(1));
+}
+/** The friendly spelling of a tool, for help text and error messages. */
+function cliName(tool) {
+    const alias = Object.entries(exports.ALIASES).find(([, name]) => name === tool.name);
+    return alias ? alias[0] : tool.name;
+}
+/**
+ * Resolve argv's leading words to a catalog tool. Two words are tried first so
+ * `audience get` wins over a tool literally named `audience`; the number of
+ * words consumed comes back so the caller knows where positionals start.
+ */
+function resolveTool(words) {
+    const two = words.slice(0, 2).join(' ');
+    if (words.length >= 2 && exports.ALIASES[two]) {
+        const tool = (0, tools_1.findTool)(exports.ALIASES[two]);
+        if (tool)
+            return { tool, used: 2 };
+    }
+    const one = words[0];
+    if (!one)
+        return undefined;
+    const direct = (exports.ALIASES[one] ? (0, tools_1.findTool)(exports.ALIASES[one]) : undefined) ??
+        (0, tools_1.findTool)(one) ??
+        (0, tools_1.findTool)(one.replace(/-/g, '_'));
+    return direct ? { tool: direct, used: 1 } : undefined;
+}
+/** Coerce raw flag strings to the JSON-Schema type the tool declares. */
+function coerce(schema, values) {
+    const raw = schema?.type;
+    const type = Array.isArray(raw) ? raw.find((t) => t !== 'null') : raw;
+    if (type === 'array') {
+        // Repeat the flag, or comma-separate it — both read naturally in a shell.
+        const items = values.length > 1 ? values : values[0].split(',');
+        const itemType = schema.items?.type;
+        return items.map((v) => itemType === 'number' || itemType === 'integer'
+            ? Number(v)
+            : itemType === 'boolean'
+                ? v !== 'false'
+                : v);
+    }
+    const last = values[values.length - 1];
+    if (type === 'number' || type === 'integer')
+        return Number(last);
+    if (type === 'boolean')
+        return last !== 'false';
+    if (type === 'object') {
+        try {
+            return JSON.parse(last);
+        }
+        catch {
+            throw new UsageError('an object argument must be JSON on the command line, or come from --file');
+        }
+    }
+    return last;
+}
+/**
+ * Build a tool's arguments from argv: positionals fill the route's `:params`,
+ * flags fill everything else, and `--file` supplies the structured ones — an
+ * object merges at the top level, a bare array fills the tool's single
+ * array-typed argument, so `--file contacts.json` works whether the file holds
+ * `[…]` or `{"contacts":[…]}`.
+ */
+function argsFromArgv(tool, positionals, argv, readFile = (p) => (0, node_fs_1.readFileSync)(p, 'utf8')) {
+    const props = (tool.inputSchema.properties ?? {});
+    const args = {};
+    const file = typeof argv.flags.file === 'string' ? argv.flags.file : undefined;
+    if (file) {
+        const doc = JSON.parse(readFile(file));
+        if (Array.isArray(doc)) {
+            const arrayProp = Object.keys(props).find((k) => props[k]?.type === 'array');
+            if (!arrayProp) {
+                throw new UsageError(`${cliName(tool)} takes no list argument — --file must hold a JSON object`);
+            }
+            args[arrayProp] = doc;
+        }
+        else if (doc && typeof doc === 'object') {
+            Object.assign(args, doc);
+        }
+        else {
+            throw new UsageError('--file must hold a JSON object or array');
+        }
+    }
+    for (const [key, schema] of Object.entries(props)) {
+        if (key === 'file')
+            continue;
+        const values = argv.repeats[key];
+        if (values?.length) {
+            args[key] = coerce(schema, values);
+        }
+        else if (schema?.type === 'boolean' && argv.flags[key] === true) {
+            args[key] = true;
+        }
+    }
+    pathParams(tool).forEach((param, i) => {
+        if (args[param] === undefined && positionals[i] !== undefined) {
+            args[param] = positionals[i];
+        }
+    });
+    const missing = (tool.inputSchema.required ?? []).filter((k) => args[k] === undefined);
+    if (missing.length) {
+        throw new UsageError(`${cliName(tool)} is missing: ${missing.join(', ')}\n\n${toolUsage(tool)}`);
+    }
+    return args;
+}
+/** One tool's usage line, derived from its schema rather than written by hand. */
+function toolUsage(tool, bin = 'rcs') {
+    const props = (tool.inputSchema.properties ?? {});
+    const required = new Set(tool.inputSchema.required ?? []);
+    const params = pathParams(tool);
+    const flags = Object.keys(props)
+        .filter((k) => !params.includes(k))
+        .map((k) => {
+        // A nullable argument declares `["string","null"]`; read it as string|null.
+        const raw = props[k]?.type;
+        const type = Array.isArray(raw) ? raw.join('|') : (raw ?? 'value');
+        const one = type === 'boolean' ? `--${k}` : `--${k} <${type}>`;
+        return required.has(k) ? one : `[${one}]`;
+    });
+    return `  ${bin} ${[cliName(tool), ...params.map((p) => `<${p}>`), ...flags].join(' ')}`;
+}
+/** The generated half of the help: every catalog tool without a curated command. */
+function catalogUsage(bin = 'rcs') {
+    return tools_1.TOOLS.filter((t) => !exports.CURATED.has(t.name))
+        .map((t) => `${toolUsage(t, bin)}   # ${t.scope}`)
+        .join('\n');
+}

package/dist/client.d.ts

@@ -41,6 +41,14 @@ export interface GatewayConfig {
  * argv, a bundler-rewritten path, or a direct import all fall through to 'rcs'.
  */
 export declare function detectSkin(argv?: readonly string[]): 'wa' | 'rcs';
+/**
+ * The product a bin is branded as. The surveys packages (@wa-surveys/…,
+ * @rcs-surveys/…) are aliases like @wa-campaigns/…: same gateway, same catalog.
+ * The brand only changes the words the host and the model read; the channel
+ * default and env prefix still come from {@link detectSkin}.
+ */
+export type Brand = 'rcs-campaigns' | 'wa-campaigns' | 'rcs-surveys' | 'wa-surveys';
+export declare function detectBrand(argv?: readonly string[]): Brand;
 /**
  * The version of the package the user actually installed, read at runtime rather
  * than restated in a constant. A hardcoded copy silently goes stale the first
@@ -61,12 +69,22 @@ export declare function detectSkin(argv?: readonly string[]): 'wa' | 'rcs';
  * and `dist/mcp.js` alike.
  */
 export declare function readVersion(argv?: readonly string[]): string;
-/** Human-readable product + channel names for the running skin. */
-export declare function skinLabels(skin?: 'wa' | 'rcs'): {
+/**
+ * Human-readable product + channel names for the running bin. Accepts a skin
+ * ('wa' | 'rcs', meaning the campaigns brand) or a full brand.
+ */
+export declare function skinLabels(skinOrBrand?: 'wa' | 'rcs' | Brand): {
     product: string;
     channel: string;
-    slug: string;
+    slug: Brand;
 };
+/**
+ * The hosted production gateway. Both skins (wa and rcs) talk to this one
+ * deployment, so a customer only has to supply an agent key. Set
+ * WA_GATEWAY_URL / RCS_GATEWAY_URL (or --url) to point at dev or a local
+ * gateway instead.
+ */
+export declare const DEFAULT_GATEWAY_URL = "https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com";
 /**
  * Normalize a channel from configuration or a tool argument. Accepts the channel
  * enum itself (any case) AND a brand id — canonical or legacy — resolving it to

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,UAAU,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,IAAI,GAAG,KAAK,CAG/E;AAmCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,MAAM,CAO1E;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,IAAI,GAAE,IAAI,GAAG,KAAoB;;;;EAI3D;AA6BD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAMpE;AAOD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;gBACN,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CA4B7E;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAElD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa;IAI/D,+EAA+E;IACzE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAmCvD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,UAAU,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,IAAI,GAAG,KAAK,CAE/E;AAED;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,YAAY,CAAC;AAEpF,wBAAgB,WAAW,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,KAAK,CAczE;AA8CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,SAAS,MAAM,EAAiB,GAAG,MAAM,CAO1E;AASD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,WAAW,GAAE,IAAI,GAAG,KAAK,GAAG,KAAqB;aAX/B,MAAM;aAAW,MAAM;UAAQ,KAAK;EAehF;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,iEACgC,CAAC;AA6BjE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAMpE;AAOD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;gBACN,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CA4B7E;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,aAAa;IAElD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa;IAI/D,+EAA+E;IACzE,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;CAmCvD"}

package/dist/client.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GatewayClient = exports.GatewayError = void 0;
+exports.GatewayClient = exports.GatewayError = exports.DEFAULT_GATEWAY_URL = void 0;
 exports.detectSkin = detectSkin;
+exports.detectBrand = detectBrand;
 exports.readVersion = readVersion;
 exports.skinLabels = skinLabels;
 exports.normalizeChannel = normalizeChannel;
@@ -18,8 +19,22 @@ const node_path_1 = require("node:path");
  * argv, a bundler-rewritten path, or a direct import all fall through to 'rcs'.
  */
 function detectSkin(argv = process.argv) {
-    const name = invokedBinName(argv);
-    return name === 'wa' || name === 'wa-mcp' ? 'wa' : 'rcs';
+    return detectBrand(argv).startsWith('wa-') ? 'wa' : 'rcs';
+}
+function detectBrand(argv = process.argv) {
+    switch (invokedBinName(argv)) {
+        case 'wa':
+        case 'wa-mcp':
+            return 'wa-campaigns';
+        case 'wa-surveys':
+        case 'wa-surveys-mcp':
+            return 'wa-surveys';
+        case 'rcs-surveys':
+        case 'rcs-surveys-mcp':
+            return 'rcs-surveys';
+        default:
+            return 'rcs-campaigns';
+    }
 }
 /**
  * The bin basename this process was launched as — "wa-mcp", "mcp", "cli" — or
@@ -42,7 +57,18 @@ function invokedBinName(argv) {
  * — hence "mcp" and "cli" rather than "rcs-mcp" and "rcs". Anything not in this
  * set is not one of ours, and is never trusted to locate a package.
  */
-const OWN_BINS = new Set(['wa', 'wa-mcp', 'rcs', 'rcs-mcp', 'mcp', 'cli']);
+const OWN_BINS = new Set([
+    'wa',
+    'wa-mcp',
+    'rcs',
+    'rcs-mcp',
+    'mcp',
+    'cli',
+    'wa-surveys',
+    'wa-surveys-mcp',
+    'rcs-surveys',
+    'rcs-surveys-mcp'
+]);
 /** The `version` of the package.json in `dir`, or undefined if unreadable. */
 function packageVersionAt(dir) {
     try {
@@ -81,12 +107,27 @@ function readVersion(argv = process.argv) {
     }
     return packageVersionAt((0, node_path_1.join)(__dirname, '..')) ?? '0.0.0';
 }
-/** Human-readable product + channel names for the running skin. */
-function skinLabels(skin = detectSkin()) {
-    return skin === 'wa'
-        ? { product: 'WhatsApp Campaigns', channel: 'WhatsApp', slug: 'wa-campaigns' }
-        : { product: 'RCS Campaigns', channel: 'RCS', slug: 'rcs-campaigns' };
+const BRAND_LABELS = {
+    'wa-campaigns': { product: 'WhatsApp Campaigns', channel: 'WhatsApp', slug: 'wa-campaigns' },
+    'rcs-campaigns': { product: 'RCS Campaigns', channel: 'RCS', slug: 'rcs-campaigns' },
+    'wa-surveys': { product: 'WhatsApp Surveys', channel: 'WhatsApp', slug: 'wa-surveys' },
+    'rcs-surveys': { product: 'RCS Surveys', channel: 'RCS', slug: 'rcs-surveys' }
+};
+/**
+ * Human-readable product + channel names for the running bin. Accepts a skin
+ * ('wa' | 'rcs', meaning the campaigns brand) or a full brand.
+ */
+function skinLabels(skinOrBrand = detectBrand()) {
+    const brand = skinOrBrand === 'wa' ? 'wa-campaigns' : skinOrBrand === 'rcs' ? 'rcs-campaigns' : skinOrBrand;
+    return { ...BRAND_LABELS[brand] };
 }
+/**
+ * The hosted production gateway. Both skins (wa and rcs) talk to this one
+ * deployment, so a customer only has to supply an agent key. Set
+ * WA_GATEWAY_URL / RCS_GATEWAY_URL (or --url) to point at dev or a local
+ * gateway instead.
+ */
+exports.DEFAULT_GATEWAY_URL = 'https://rcs-templates-api-dot-msg2ai-server.ue.r.appspot.com';
 /** First environment variable that is set and non-empty, under either prefix. */
 function fromEnv(...names) {
     for (const name of names) {
@@ -159,7 +200,7 @@ function resolveConfig(partial) {
     const [keyFirst, keySecond] = skin === 'wa'
         ? ['WA_AGENT_KEY', 'RCS_AGENT_KEY']
         : ['RCS_AGENT_KEY', 'WA_AGENT_KEY'];
-    const baseUrl = partial?.baseUrl ?? fromEnv(urlFirst, urlSecond) ?? 'http://localhost:3002';
+    const baseUrl = partial?.baseUrl ?? fromEnv(urlFirst, urlSecond) ?? exports.DEFAULT_GATEWAY_URL;
     const apiKey = partial?.apiKey ?? fromEnv(keyFirst, keySecond) ?? '';
     if (!apiKey) {
         throw new Error(`No agent key configured. Set ${keyFirst} or pass apiKey explicitly.`);

package/dist/mcp.js

@@ -11,13 +11,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * runtime dependencies — nothing to install, nothing to drift, and it slots into
  * the workspace without touching the lockfile's external graph.
  *
- * Credentials: the agent key + gateway URL come from the environment
- * (RCS_AGENT_KEY / RCS_GATEWAY_URL). This process holds the key only to forward
+ * Credentials: the agent key comes from the environment (RCS_AGENT_KEY); the
+ * gateway URL defaults to the hosted production gateway and can be overridden
+ * with RCS_GATEWAY_URL. This process holds the key only to forward
  * it as a Bearer token to the gateway — all business logic stays server-side.
  *
  * Wire it up (e.g. Claude Code):
  *   claude mcp add rcs-campaigns -- npx -y -p @rcs-campaigns/agent-toolkit rcs-mcp
- *   (with RCS_AGENT_KEY + RCS_GATEWAY_URL set in the environment)
+ *   (with RCS_AGENT_KEY set in the environment)
  */
 const node_readline_1 = require("node:readline");
 const client_1 = require("./client");
@@ -31,7 +32,7 @@ const PROTOCOL_VERSION = '2024-11-05';
  * Same catalog, same gateway — only the words the model reads differ.
  */
 const SKIN = (0, client_1.detectSkin)();
-const { product: PRODUCT, channel: CHANNEL, slug: SLUG } = (0, client_1.skinLabels)(SKIN);
+const { product: PRODUCT, channel: CHANNEL, slug: SLUG } = (0, client_1.skinLabels)((0, client_1.detectBrand)());
 const SERVER_INFO = { name: SLUG, version: (0, client_1.readVersion)() };
 /**
  * Surfaced to MCP hosts as the initialize result's `instructions` string — hosts

package/dist/tools.js

@@ -102,7 +102,7 @@ exports.TOOLS = [
     {
         name: 'search_templates',
         description: 'Search the published RCS template marketplace. Returns normalized listings (id, name, rating, cloneCount, categoryKeys).',
-        scope: 'templates:read',
+        scope: 'campaigns:read',
         method: 'GET',
         path: '/templates',
         inputSchema: {
@@ -139,7 +139,7 @@ exports.TOOLS = [
     {
         name: 'get_template',
         description: 'Fetch one template by id (a published marketplace listing or one your org owns).',
-        scope: 'templates:read',
+        scope: 'campaigns:read',
         method: 'GET',
         path: '/templates/:id',
         inputSchema: {
@@ -156,7 +156,7 @@ exports.TOOLS = [
     {
         name: 'render_template',
         description: 'Validate a template and return the rendered RCS payload + variable-bound SMS/MMS fallback, without sending. Use to inspect before cloning/sending.',
-        scope: 'templates:read',
+        scope: 'campaigns:read',
         method: 'POST',
         path: '/templates/:id/render',
         inputSchema: {
@@ -181,7 +181,7 @@ exports.TOOLS = [
     {
         name: 'create_template',
         description: 'Create a template draft in your org. Compose a TemplateContent (text/card/carousel) with a REQUIRED non-empty smsFallback; the shared RCS validator gates it. Submit it (submit_template) and await provider approval before send_message for rich RCS; an unsubmitted template delivers as SMS fallback.',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'POST',
         path: '/templates',
         successStatus: 201,
@@ -220,7 +220,7 @@ exports.TOOLS = [
     {
         name: 'update_template',
         description: 'Partially update a template your org owns: name, description, category, tags, knowledgeDoc, and content (re-validated by the shared RCS validator — a non-empty smsFallback is still required). Only the fields you pass change. Editing the CONTENT of an already-approved template invalidates that approval: submit_template it again and await approval, or it delivers as SMS fallback until then. Use get_template first to edit incrementally rather than overwriting blind.',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'PUT',
         path: '/templates/:id',
         inputSchema: {
@@ -265,7 +265,7 @@ exports.TOOLS = [
     {
         name: 'duplicate_template',
         description: 'Duplicate a template your org OWNS into a fresh private draft (e.g. to iterate a variant without touching the original). The copy keeps the content, channel, category, tags and knowledge base, but starts unsubmitted — it has no provider approval of its own until you submit_template it. For copying someone else\'s PUBLISHED marketplace listing, use clone_template instead.',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'POST',
         path: '/templates/:id/duplicate',
         successStatus: 201,
@@ -283,7 +283,7 @@ exports.TOOLS = [
     {
         name: 'delete_template',
         description: 'Delete a template your org owns. IRREVERSIBLE, and it also removes the template from the provider (Twilio), so an approved template loses its approval and can no longer be sent. Broadcasts that already went out are unaffected. Prefer this only for drafts and abandoned iterations; ask the user before deleting anything they have submitted or sent.',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'DELETE',
         path: '/templates/:id',
         inputSchema: {
@@ -318,7 +318,7 @@ exports.TOOLS = [
     {
         name: 'submit_template',
         description: 'Submit an org-owned template to the provider (Twilio) for approval. Returns the contentSid + approval status.',
-        scope: 'templates:submit',
+        scope: 'campaigns:submit',
         method: 'POST',
         path: '/templates/:id/submit',
         inputSchema: {
@@ -685,7 +685,7 @@ exports.TOOLS = [
     {
         name: 'get_knowledge',
         description: "Read a template's knowledge base: the grounding document text plus whether answering is enabled. Use before set_knowledge to edit a doc incrementally instead of overwriting it blind.",
-        scope: 'templates:read',
+        scope: 'campaigns:read',
         method: 'GET',
         path: '/templates/:id/knowledge',
         inputSchema: {
@@ -702,7 +702,7 @@ exports.TOOLS = [
     {
         name: 'set_knowledge',
         description: 'Set/replace a template\'s knowledge base: the grounding document AI answers are generated from when recipients reply. Include operating instructions in the doc itself — e.g. "Any question not answered by this document must be answered exactly: …". Setting a doc re-enables answering.',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'PUT',
         path: '/templates/:id/knowledge',
         inputSchema: {
@@ -726,7 +726,7 @@ exports.TOOLS = [
     {
         name: 'delete_knowledge',
         description: 'Delete a template\'s knowledge base document.',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'DELETE',
         path: '/templates/:id/knowledge',
         inputSchema: {
@@ -743,7 +743,7 @@ exports.TOOLS = [
     {
         name: 'enable_knowledge',
         description: 'Enable knowledge answering on a template (the doc is used again).',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'POST',
         path: '/templates/:id/knowledge/enable',
         inputSchema: {
@@ -760,7 +760,7 @@ exports.TOOLS = [
     {
         name: 'disable_knowledge',
         description: 'Disable knowledge answering on a template WITHOUT deleting the doc (pause).',
-        scope: 'templates:write',
+        scope: 'campaigns:write',
         method: 'POST',
         path: '/templates/:id/knowledge/disable',
         inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcs-campaigns/agent-toolkit",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "mcpName": "com.rcs-campaigns/campaigns",
   "description": "Agent skins for the RCS Campaigns gateway: an MCP server (rcs-mcp / wa-mcp) and a CLI (rcs / wa) over one shared client.",
   "license": "UNLICENSED",