@advertising-chat/mcp 0.2.1 → 0.17.3

package/bin/tools/translation.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.translationTools = exports.describeRule = exports.previewRuleImpact = exports.translateRuleText = exports.CARD_FIELDS = void 0;
+/**
+ * Rules in plain language: an instruction translated into a change to one
+ * rule (`translate_rule_text`), a saved rule described as its offer card
+ * (`describe_rule`), and how much recent traffic a draft would match
+ * (`preview_rule_impact`). All three are reads: translation proposes a
+ * change and saves nothing; saving is `create_rule` or `update_rule`.
+ */
+const offer_rules_1 = require("@advertising-chat/offer-rules");
+const zod_1 = require("zod");
+const tool_1 = require("../tool");
+const shared_1 = require("./shared");
+const R = offer_rules_1.RuleInput.shape;
+/** The offer card fields a translation can target (design §7.1). */
+exports.CARD_FIELDS = [
+    'offer',
+    'whoSeesIt',
+    'when',
+    'where',
+    'notShownTo',
+    'howOften',
+    'schedule',
+    'priority',
+];
+exports.translateRuleText = (0, tool_1.defineTool)({
+    name: 'translate_rule_text',
+    title: 'Translate an instruction into a rule change',
+    description: 'Turn what the user wrote in plain language into a change to one rule, checked against the agent’s catalog, moments, and the org’s offers, and read back as the offer card. Give the agent, the card field being edited (target), the instruction in the user’s words, and the rule: ruleId for a saved rule, or rule for a draft with unsaved changes. Nothing is saved. The outcome is one of: ok, with policy (fields to set), clear (fields to remove), readBack (the card after the change and which fields changed), and warnings (data the agent does not send yet, has not documented, or sends rarely): show the user the read-back and the warnings, preview_rule_impact the result, and save with update_rule (clear fields as null) or create_rule once they agree, passing instructions with the user’s words for each field the change set or cleared. clarify, with a question (message) and choices: ask the user, then translate again with the same instruction and clarifications listing every question asked so far with its answer, in order; record the instruction as the user’s words with the answers in parentheses. needs_data, when the agent does not send what the rule needs: relay the message and the note drafted for the agent’s team; add_attribute or create_moment registers what it proposes, and a rule on it matches no one until the agent sends it. unsupported, when the rule model cannot express it: say so; offer the nearest rule only if one is given, and say how it differs. If the user takes it, save it with instructions null for the fields it changed: their words describe a rule it does not quite write. Each call counts toward the workspace’s daily Assistant usage. Maps to POST /system/copilot/translate.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    capability: 'offer-manager',
+    input: {
+        application: shared_1.application,
+        target: zod_1.z
+            .enum([...exports.CARD_FIELDS, 'rule'])
+            .optional()
+            .describe('The card field the instruction is about: offer, whoSeesIt (audience), when (moments), where (channels), notShownTo (exclusions), howOften (frequency), schedule, or priority. A field’s translation changes only that field. Default rule: the whole rule.'),
+        instruction: zod_1.z
+            .string()
+            .trim()
+            .min(1)
+            .max(2000)
+            .describe('What the user wrote, in their words, e.g. "prepaid customers who hit their data limit twice in a row".'),
+        clarifications: zod_1.z
+            .array(zod_1.z.strictObject({
+            question: zod_1.z.string().trim().min(1).max(500),
+            answer: zod_1.z.string().trim().min(1).max(500),
+        }))
+            .min(1)
+            .max(5)
+            .optional()
+            .describe('After one or more clarify outcomes: each question asked (its message) and the user’s answer, a choice or their own words, in the order asked. Send the same instruction as before.'),
+        ruleId: (0, shared_1.id)('rule')
+            .optional()
+            .describe('A saved rule to change. Omit with rule, or for a new rule.'),
+        rule: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.unknown())
+            .optional()
+            .describe('The draft as it stands, unsaved changes included, with the fields of create_rule. Takes precedence over ruleId.'),
+    },
+    async run({ client }, args) {
+        const { rule, ...rest } = (0, shared_1.defined)(args);
+        let draft;
+        if (rule) {
+            const parsed = offer_rules_1.RuleDraft.safeParse({
+                ...rule,
+                application: rule.application ?? args.application,
+            });
+            if (!parsed.success) {
+                throw new shared_1.ToolInputError(`The draft is not valid:\n${(0, shared_1.issues)(parsed.error)}`);
+            }
+            if (parsed.data.application !== args.application) {
+                throw new shared_1.ToolInputError('The draft belongs to a different agent.');
+            }
+            draft = parsed.data;
+        }
+        const answer = await client.post('/copilot/translate', {
+            ...rest,
+            ...(draft !== undefined && { rule: draft }),
+        });
+        // Model, timing, and token counts are for the console; leave them out.
+        const { meta: _meta, ...outcome } = answer ?? {}; // eslint-disable-line @typescript-eslint/no-unused-vars
+        return outcome;
+    },
+});
+exports.previewRuleImpact = (0, tool_1.defineTool)({
+    name: 'preview_rule_impact',
+    title: 'Preview a rule’s reach',
+    description: 'Estimate how much recent traffic a draft rule would match, before saving it: the percentage of a sample of up to 5,000 requests per moment from the last 7 days, the estimated number of distinct customers, why the rest did not match, and flags with notes (small or empty sample, nothing or everything matched, approximations). Read the notes back to the user; "no one matched" or "everyone matched" usually means the instruction was misread or the data is missing. A sample_building flag means some moments had no sample yet and were left out while one is taken; say so, and preview again in about a minute for the full estimate. Send the draft as it stands; only the agent and moments are required. Maps to POST /system/offer-manager/preview.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    capability: 'offer-manager',
+    input: {
+        application: shared_1.application,
+        adUnits: R.adUnits.describe('The moment ids the draft applies to.'),
+        creatives: R.creatives
+            .optional()
+            .describe('The offer ids, for conditions on this offer’s history.'),
+        audience: R.audience,
+        exclusions: R.exclusions,
+        channels: R.channels,
+        schedule: R.schedule,
+        frequency: R.frequency,
+        id: (0, shared_1.id)('rule')
+            .optional()
+            .describe('The saved rule, when previewing a change to one.'),
+    },
+    async run({ client }, args) {
+        const { id: ruleId, ...draft } = (0, shared_1.defined)(args);
+        const parsed = offer_rules_1.PreviewDraft.safeParse({
+            ...draft,
+            ...(ruleId && { _id: ruleId }),
+        });
+        if (!parsed.success) {
+            throw new shared_1.ToolInputError(`The draft is not valid:\n${(0, shared_1.issues)(parsed.error)}`);
+        }
+        return client.post(`${shared_1.OM}/preview`, { rule: parsed.data });
+    },
+});
+exports.describeRule = (0, tool_1.defineTool)({
+    name: 'describe_rule',
+    title: 'Describe a rule',
+    description: 'A saved rule in plain language: its offer card, one sentence per field (agent, offer, who sees it, when, where, not shown to, how often, schedule, priority, status), written from the rule itself with its agent, moment, offer, and attribute names, plus a policy hash that changes when what the rule does changes. Maps to GET /system/offer-manager/describe/{id}.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    capability: 'offer-manager',
+    input: { id: (0, shared_1.id)('rule') },
+    async run({ client }, { id: ruleId }) {
+        return client.get(`${shared_1.OM}/describe/${(0, shared_1.enc)(ruleId)}`);
+    },
+});
+exports.translationTools = [
+    exports.translateRuleText,
+    exports.describeRule,
+    exports.previewRuleImpact,
+];
+//# sourceMappingURL=translation.js.map

package/bin/tools/translation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation.js","sourceRoot":"","sources":["../../src/tools/translation.ts"],"names":[],"mappings":"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"}

package/bin/version.d.ts

@@ -0,0 +1,2 @@
+/** The package version, reported to MCP hosts. Kept in step with package.json (tested). */
+export declare const VERSION = "0.17.3";

package/bin/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** The package version, reported to MCP hosts. Kept in step with package.json (tested). */
+exports.VERSION = '0.17.3';
+//# sourceMappingURL=version.js.map

package/bin/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":";;;AAAA,2FAA2F;AAC9E,QAAA,OAAO,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@advertising-chat/mcp",
-  "version": "0.2.1",
-  "description": "MCP server for Advertising.chat — give any agent the ability to serve ads (fetch_ad, record_event)",
+  "version": "0.17.3",
+  "description": "MCP server for Advertising.chat: manage Offer Manager (agents, moments, rules, offers, decisions) with your own login, or serve in-chat ads with an API key",
   "license": "MIT",
   "author": "Advertising.chat",
   "homepage": "https://docs.advertising.chat/",
@@ -14,9 +14,9 @@
     "mcp",
     "model-context-protocol",
     "advertising",
+    "offer-manager",
     "ads",
-    "llm",
-    "monetization"
+    "llm"
   ],
   "main": "bin/index.js",
   "types": "bin/index.d.ts",
@@ -37,8 +37,11 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@advertising-chat/sdk": "^0.2.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^4.0.0"
+    "@advertising-chat/offer-rules": "^2.6.0",
+    "@advertising-chat/sdk": "^0.17.3",
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "zod": "^4.6.7"
   }
 }