mcp-meta-ads-incrementality 0.2.3 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -2
- package/dist/index.js +6 -597
- package/dist/index.js.map +1 -1
- package/dist/lib/graph.d.ts +2 -2
- package/dist/lib/graph.js +1 -1
- package/dist/lib/naming-standards.d.ts +12 -6
- package/dist/lib/naming-standards.d.ts.map +1 -1
- package/dist/lib/naming-standards.js +12 -6
- package/dist/lib/naming-standards.js.map +1 -1
- package/dist/toolDefinitions.d.ts +784 -0
- package/dist/toolDefinitions.d.ts.map +1 -0
- package/dist/toolDefinitions.js +611 -0
- package/dist/toolDefinitions.js.map +1 -0
- package/dist/tools/campaign-build.d.ts +12 -0
- package/dist/tools/campaign-build.d.ts.map +1 -1
- package/dist/tools/campaign-build.js +43 -16
- package/dist/tools/campaign-build.js.map +1 -1
- package/dist/writeGate.d.ts +25 -0
- package/dist/writeGate.d.ts.map +1 -0
- package/dist/writeGate.js +60 -0
- package/dist/writeGate.js.map +1 -0
- package/package.json +5 -3
|
@@ -7,6 +7,14 @@ export interface CreateCampaignInput {
|
|
|
7
7
|
buying_type?: 'AUCTION' | 'RESERVED';
|
|
8
8
|
daily_budget?: number;
|
|
9
9
|
lifetime_budget?: number;
|
|
10
|
+
/**
|
|
11
|
+
* Whether ad sets in this campaign can share up to 20% of each other's budget.
|
|
12
|
+
* Meta requires this to be explicitly true/false whenever the campaign itself
|
|
13
|
+
* has no daily_budget/lifetime_budget (ABO) — omitting it 400s with subcode
|
|
14
|
+
* 4834011. Defaults to false (no sharing) for ABO campaigns when not passed;
|
|
15
|
+
* omitted entirely for CBO campaigns unless explicitly set.
|
|
16
|
+
*/
|
|
17
|
+
is_adset_budget_sharing_enabled?: boolean;
|
|
10
18
|
}
|
|
11
19
|
export interface CreateCampaignResult {
|
|
12
20
|
campaign_id: string;
|
|
@@ -57,6 +65,10 @@ export interface CreateAdCreativeInput {
|
|
|
57
65
|
name: string;
|
|
58
66
|
page_id: string;
|
|
59
67
|
image_hash?: string;
|
|
68
|
+
/** Ad-account video library id (from meta_ads_upload_video or Ads Manager). Routes the creative through object_story_spec.video_data instead of link_data. */
|
|
69
|
+
video_id?: string;
|
|
70
|
+
/** Optional thumbnail override for a video creative; Meta auto-generates one if omitted. */
|
|
71
|
+
thumbnail_url?: string;
|
|
60
72
|
link: string;
|
|
61
73
|
/** Single primary text. Mutually exclusive with `messages`. */
|
|
62
74
|
message?: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"campaign-build.d.ts","sourceRoot":"","sources":["../../src/tools/campaign-build.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC7B,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,WAAW,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"campaign-build.d.ts","sourceRoot":"","sources":["../../src/tools/campaign-build.ts"],"names":[],"mappings":"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"}
|
|
@@ -27,6 +27,13 @@ export async function createCampaign(input, accessToken) {
|
|
|
27
27
|
body.daily_budget = String(input.daily_budget);
|
|
28
28
|
if (input.lifetime_budget !== undefined)
|
|
29
29
|
body.lifetime_budget = String(input.lifetime_budget);
|
|
30
|
+
const isCbo = input.daily_budget !== undefined || input.lifetime_budget !== undefined;
|
|
31
|
+
if (input.is_adset_budget_sharing_enabled !== undefined) {
|
|
32
|
+
body.is_adset_budget_sharing_enabled = String(input.is_adset_budget_sharing_enabled);
|
|
33
|
+
}
|
|
34
|
+
else if (!isCbo) {
|
|
35
|
+
body.is_adset_budget_sharing_enabled = 'false';
|
|
36
|
+
}
|
|
30
37
|
const res = await graphPost(`${account}/campaigns`, accessToken, body);
|
|
31
38
|
return { campaign_id: res.id, account_id: account, name: input.name, status };
|
|
32
39
|
}
|
|
@@ -136,24 +143,44 @@ export async function createAdCreative(input, accessToken) {
|
|
|
136
143
|
body.asset_feed_spec = JSON.stringify(assetFeedSpec);
|
|
137
144
|
}
|
|
138
145
|
else {
|
|
139
|
-
const
|
|
140
|
-
link: input.link,
|
|
141
|
-
message: messages[0],
|
|
142
|
-
};
|
|
143
|
-
if (input.image_hash)
|
|
144
|
-
linkData.image_hash = input.image_hash;
|
|
145
|
-
if (headlines.length)
|
|
146
|
-
linkData.name = headlines[0];
|
|
147
|
-
if (descriptions.length)
|
|
148
|
-
linkData.description = descriptions[0];
|
|
149
|
-
if (callToAction)
|
|
150
|
-
linkData.call_to_action = callToAction;
|
|
151
|
-
const objectStorySpec = {
|
|
152
|
-
page_id: input.page_id,
|
|
153
|
-
link_data: linkData,
|
|
154
|
-
};
|
|
146
|
+
const objectStorySpec = { page_id: input.page_id };
|
|
155
147
|
if (input.instagram_actor_id)
|
|
156
148
|
objectStorySpec.instagram_actor_id = input.instagram_actor_id;
|
|
149
|
+
if (input.video_id) {
|
|
150
|
+
// Plain object_story_spec.video_data — deliberately never routed through
|
|
151
|
+
// asset_feed_spec. Combining video_id with a `description` field there
|
|
152
|
+
// forces Meta to classify the creative as Dynamic Creative, which requires
|
|
153
|
+
// is_dynamic_creative on the ad set (immutable after creation) and then
|
|
154
|
+
// caps that ad set at one active ad. So: message + title only, no
|
|
155
|
+
// description, for every video creative. See NeonOne switcher campaign
|
|
156
|
+
// card (clients/neon-one/tasks/neonone-switcher-campaign.md) for the
|
|
157
|
+
// incident this was learned from.
|
|
158
|
+
const videoData = {
|
|
159
|
+
video_id: input.video_id,
|
|
160
|
+
message: messages[0],
|
|
161
|
+
};
|
|
162
|
+
if (headlines.length)
|
|
163
|
+
videoData.title = headlines[0];
|
|
164
|
+
if (input.thumbnail_url)
|
|
165
|
+
videoData.image_url = input.thumbnail_url;
|
|
166
|
+
videoData.call_to_action = callToAction ?? { type: 'LEARN_MORE', value: { link: input.link } };
|
|
167
|
+
objectStorySpec.video_data = videoData;
|
|
168
|
+
}
|
|
169
|
+
else {
|
|
170
|
+
const linkData = {
|
|
171
|
+
link: input.link,
|
|
172
|
+
message: messages[0],
|
|
173
|
+
};
|
|
174
|
+
if (input.image_hash)
|
|
175
|
+
linkData.image_hash = input.image_hash;
|
|
176
|
+
if (headlines.length)
|
|
177
|
+
linkData.name = headlines[0];
|
|
178
|
+
if (descriptions.length)
|
|
179
|
+
linkData.description = descriptions[0];
|
|
180
|
+
if (callToAction)
|
|
181
|
+
linkData.call_to_action = callToAction;
|
|
182
|
+
objectStorySpec.link_data = linkData;
|
|
183
|
+
}
|
|
157
184
|
body.object_story_spec = JSON.stringify(objectStorySpec);
|
|
158
185
|
}
|
|
159
186
|
const res = await graphPost(`${account}/adcreatives`, accessToken, body);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"campaign-build.js","sourceRoot":"","sources":["../../src/tools/campaign-build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,SAAS,kBAAkB,CAAC,SAAiB;IAC3C,OAAO,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,SAAS,EAAE,CAAC;AACvE,CAAC;
|
|
1
|
+
{"version":3,"file":"campaign-build.js","sourceRoot":"","sources":["../../src/tools/campaign-build.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tools that mutate Meta Ads state. These are hidden from the tool list and
|
|
3
|
+
* refused at call time unless META_ADS_MCP_WRITE=true.
|
|
4
|
+
*
|
|
5
|
+
* The env prefix is deliberately META_ADS — shared with the Python meta-ads
|
|
6
|
+
* MCP server — so one flag means "Meta writes allowed this session" across
|
|
7
|
+
* both servers.
|
|
8
|
+
*
|
|
9
|
+
* Adding a new tool? Put it in this set if it creates, updates, deletes,
|
|
10
|
+
* uploads, swaps, rebinds, edits, or renames anything. The shape test in
|
|
11
|
+
* writeGate.test.ts enforces this by name pattern.
|
|
12
|
+
*/
|
|
13
|
+
export declare const WRITE_TOOLS: ReadonlySet<string>;
|
|
14
|
+
export declare function isWriteTool(name: string): boolean;
|
|
15
|
+
export declare function isWriteEnabled(env?: NodeJS.ProcessEnv): boolean;
|
|
16
|
+
export declare function filterTools<T extends {
|
|
17
|
+
name: string;
|
|
18
|
+
}>(allTools: readonly T[], env?: NodeJS.ProcessEnv): T[];
|
|
19
|
+
export declare const WRITE_DISABLED_MESSAGE: string;
|
|
20
|
+
/**
|
|
21
|
+
* Assert that a tool call is allowed under the current write-mode setting.
|
|
22
|
+
* Throws a clear Error if the tool mutates state and writes are disabled.
|
|
23
|
+
*/
|
|
24
|
+
export declare function assertWriteAllowed(toolName: string, env?: NodeJS.ProcessEnv): void;
|
|
25
|
+
//# sourceMappingURL=writeGate.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"writeGate.d.ts","sourceRoot":"","sources":["../src/writeGate.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAkB1C,CAAC;AAOH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD;AAED,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE5E;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,EACpD,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,CAAC,EAAE,CAEL;AAED,eAAO,MAAM,sBAAsB,QAEgD,CAAC;AAEpF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,IAAI,CAQN"}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import { createWriteGate } from 'mcp-write-gate';
|
|
2
|
+
/**
|
|
3
|
+
* Tools that mutate Meta Ads state. These are hidden from the tool list and
|
|
4
|
+
* refused at call time unless META_ADS_MCP_WRITE=true.
|
|
5
|
+
*
|
|
6
|
+
* The env prefix is deliberately META_ADS — shared with the Python meta-ads
|
|
7
|
+
* MCP server — so one flag means "Meta writes allowed this session" across
|
|
8
|
+
* both servers.
|
|
9
|
+
*
|
|
10
|
+
* Adding a new tool? Put it in this set if it creates, updates, deletes,
|
|
11
|
+
* uploads, swaps, rebinds, edits, or renames anything. The shape test in
|
|
12
|
+
* writeGate.test.ts enforces this by name pattern.
|
|
13
|
+
*/
|
|
14
|
+
export const WRITE_TOOLS = new Set([
|
|
15
|
+
'meta_ads_update_ad_url_tags',
|
|
16
|
+
'meta_ads_rename_ad',
|
|
17
|
+
'meta_ads_swap_ad_lead_form',
|
|
18
|
+
'meta_ads_rebind_ad_creative',
|
|
19
|
+
'meta_ads_edit_creative_text',
|
|
20
|
+
'meta_ads_create_campaign',
|
|
21
|
+
'meta_ads_create_adset',
|
|
22
|
+
'meta_ads_create_ad_creative',
|
|
23
|
+
'meta_ads_create_ad',
|
|
24
|
+
'meta_ads_upload_image',
|
|
25
|
+
'meta_ads_create_leadgen_form',
|
|
26
|
+
'meta_ads_create_custom_audience',
|
|
27
|
+
'meta_ads_upload_users_to_audience',
|
|
28
|
+
'meta_ads_create_lookalike_audience',
|
|
29
|
+
'meta_ads_update_object_status',
|
|
30
|
+
'meta_ads_update_budget',
|
|
31
|
+
'meta_ads_delete_object',
|
|
32
|
+
]);
|
|
33
|
+
const gate = createWriteGate({
|
|
34
|
+
writeTools: WRITE_TOOLS,
|
|
35
|
+
envPrefix: 'META_ADS',
|
|
36
|
+
});
|
|
37
|
+
export function isWriteTool(name) {
|
|
38
|
+
return gate.isWriteTool(name);
|
|
39
|
+
}
|
|
40
|
+
export function isWriteEnabled(env = process.env) {
|
|
41
|
+
return gate.isWriteEnabled(env);
|
|
42
|
+
}
|
|
43
|
+
export function filterTools(allTools, env = process.env) {
|
|
44
|
+
return gate.filterTools(allTools, env);
|
|
45
|
+
}
|
|
46
|
+
export const WRITE_DISABLED_MESSAGE = 'Write operations are disabled. Set META_ADS_MCP_WRITE=true in the MCP server environment ' +
|
|
47
|
+
'to enable mutating tools (create/update/delete/upload/swap/rebind/edit/rename).';
|
|
48
|
+
/**
|
|
49
|
+
* Assert that a tool call is allowed under the current write-mode setting.
|
|
50
|
+
* Throws a clear Error if the tool mutates state and writes are disabled.
|
|
51
|
+
*/
|
|
52
|
+
export function assertWriteAllowed(toolName, env = process.env) {
|
|
53
|
+
try {
|
|
54
|
+
gate.assertWriteAllowed(toolName, env);
|
|
55
|
+
}
|
|
56
|
+
catch {
|
|
57
|
+
throw new Error(`Tool "${toolName}" is a write operation. ${WRITE_DISABLED_MESSAGE}`);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
//# sourceMappingURL=writeGate.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"writeGate.js","sourceRoot":"","sources":["../src/writeGate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IACtD,6BAA6B;IAC7B,oBAAoB;IACpB,4BAA4B;IAC5B,6BAA6B;IAC7B,6BAA6B;IAC7B,0BAA0B;IAC1B,uBAAuB;IACvB,6BAA6B;IAC7B,oBAAoB;IACpB,uBAAuB;IACvB,8BAA8B;IAC9B,iCAAiC;IACjC,mCAAmC;IACnC,oCAAoC;IACpC,+BAA+B;IAC/B,wBAAwB;IACxB,wBAAwB;CACzB,CAAC,CAAC;AAEH,MAAM,IAAI,GAAG,eAAe,CAAC;IAC3B,UAAU,EAAE,WAAW;IACvB,SAAS,EAAE,UAAU;CACtB,CAAC,CAAC;AAEH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAyB,OAAO,CAAC,GAAG;IACjE,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,QAAsB,EACtB,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GACjC,2FAA2F;IAC3F,iFAAiF,CAAC;AAEpF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,CAAC;QACH,IAAI,CAAC,kBAAkB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,SAAS,QAAQ,2BAA2B,sBAAsB,EAAE,CACrE,CAAC;IACJ,CAAC;AACH,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mcp-meta-ads-incrementality",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "MCP server for Meta Marketing API focused on incrementality reporting. Surfaces Meta's incremental conversion attribution alongside default 7d-click/1d-view and dda windows so agencies can see the gap between reported and incremental performance.",
|
|
5
5
|
"main": "dist/index.js",
|
|
6
6
|
"bin": {
|
|
@@ -17,8 +17,9 @@
|
|
|
17
17
|
"build": "tsc",
|
|
18
18
|
"start": "node dist/index.js",
|
|
19
19
|
"dev": "tsx src/index.ts",
|
|
20
|
-
"test": "vitest run",
|
|
20
|
+
"test": "vitest run && npm run test:shell",
|
|
21
21
|
"test:watch": "vitest",
|
|
22
|
+
"test:shell": "bash tests/run-mcp-keychain.test.sh",
|
|
22
23
|
"smoke": "scripts/healthcheck.sh"
|
|
23
24
|
},
|
|
24
25
|
"keywords": [
|
|
@@ -41,11 +42,12 @@
|
|
|
41
42
|
"@modelcontextprotocol/sdk": "^0.5.0",
|
|
42
43
|
"env-paths": "^3.0.0",
|
|
43
44
|
"facebook-nodejs-business-sdk": "^24.0.1",
|
|
45
|
+
"mcp-write-gate": "^1.0.0",
|
|
44
46
|
"open": "^10.0.0",
|
|
45
47
|
"zod": "^3.22.4"
|
|
46
48
|
},
|
|
47
49
|
"devDependencies": {
|
|
48
|
-
"@drak-marketing/mcp-test-harness": "^0.
|
|
50
|
+
"@drak-marketing/mcp-test-harness": "^0.2.3",
|
|
49
51
|
"@types/facebook-nodejs-business-sdk": "^23.0.0",
|
|
50
52
|
"@types/node": "^20.10.0",
|
|
51
53
|
"tsx": "^4.7.0",
|