@cesteral/msads-mcp 1.0.0 → 1.2.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.
Files changed (58) hide show
  1. package/dist/cesteral-manifest.json +22 -0
  2. package/dist/mcp-server/prompts/definitions/troubleshoot-entity.prompt.js +1 -1
  3. package/dist/mcp-server/prompts/definitions/troubleshoot-entity.prompt.js.map +1 -1
  4. package/dist/mcp-server/tools/definitions/download-report.tool.d.ts +16 -16
  5. package/dist/mcp-server/tools/definitions/get-entity.tool.d.ts +92 -74
  6. package/dist/mcp-server/tools/definitions/get-entity.tool.d.ts.map +1 -1
  7. package/dist/mcp-server/tools/definitions/get-entity.tool.js +48 -25
  8. package/dist/mcp-server/tools/definitions/get-entity.tool.js.map +1 -1
  9. package/dist/mcp-server/tools/definitions/manage-criterions.tool.d.ts +4 -4
  10. package/dist/mcp-server/tools/definitions/update-entity.tool.d.ts +1929 -17
  11. package/dist/mcp-server/tools/definitions/update-entity.tool.d.ts.map +1 -1
  12. package/dist/mcp-server/tools/definitions/update-entity.tool.js +173 -11
  13. package/dist/mcp-server/tools/definitions/update-entity.tool.js.map +1 -1
  14. package/dist/mcp-server/tools/utils/capture-snapshot.d.ts +11 -0
  15. package/dist/mcp-server/tools/utils/capture-snapshot.d.ts.map +1 -0
  16. package/dist/mcp-server/tools/utils/capture-snapshot.js +113 -0
  17. package/dist/mcp-server/tools/utils/capture-snapshot.js.map +1 -0
  18. package/dist/mcp-server/tools/utils/dry-run.d.ts +13 -0
  19. package/dist/mcp-server/tools/utils/dry-run.d.ts.map +1 -0
  20. package/dist/mcp-server/tools/utils/dry-run.js +98 -0
  21. package/dist/mcp-server/tools/utils/dry-run.js.map +1 -0
  22. package/dist/testkit/fixtures/index.d.ts +11 -0
  23. package/dist/testkit/fixtures/index.d.ts.map +1 -0
  24. package/dist/testkit/fixtures/index.js +254 -0
  25. package/dist/testkit/fixtures/index.js.map +1 -0
  26. package/dist/testkit/index.d.ts +6 -0
  27. package/dist/testkit/index.d.ts.map +1 -0
  28. package/dist/testkit/index.js +26 -0
  29. package/dist/testkit/index.js.map +1 -0
  30. package/dist/testkit/types.d.ts +18 -0
  31. package/dist/testkit/types.d.ts.map +1 -0
  32. package/dist/testkit/types.js +2 -0
  33. package/dist/testkit/types.js.map +1 -0
  34. package/package.json +12 -2
  35. package/dist/mcp-server/tools/definitions/get-ad-preview.tool.d.ts +0 -68
  36. package/dist/mcp-server/tools/definitions/get-ad-preview.tool.d.ts.map +0 -1
  37. package/dist/mcp-server/tools/definitions/get-ad-preview.tool.js +0 -90
  38. package/dist/mcp-server/tools/definitions/get-ad-preview.tool.js.map +0 -1
  39. package/dist/types-global/mcp.d.ts +0 -2
  40. package/dist/types-global/mcp.d.ts.map +0 -1
  41. package/dist/types-global/mcp.js +0 -2
  42. package/dist/types-global/mcp.js.map +0 -1
  43. package/dist/utils/errors/index.d.ts +0 -2
  44. package/dist/utils/errors/index.d.ts.map +0 -1
  45. package/dist/utils/errors/index.js +0 -2
  46. package/dist/utils/errors/index.js.map +0 -1
  47. package/dist/utils/security/rate-limiter.d.ts +0 -3
  48. package/dist/utils/security/rate-limiter.d.ts.map +0 -1
  49. package/dist/utils/security/rate-limiter.js +0 -5
  50. package/dist/utils/security/rate-limiter.js.map +0 -1
  51. package/dist/utils/telemetry/index.d.ts +0 -2
  52. package/dist/utils/telemetry/index.d.ts.map +0 -1
  53. package/dist/utils/telemetry/index.js +0 -2
  54. package/dist/utils/telemetry/index.js.map +0 -1
  55. package/dist/utils/telemetry/tracing.d.ts +0 -3
  56. package/dist/utils/telemetry/tracing.d.ts.map +0 -1
  57. package/dist/utils/telemetry/tracing.js +0 -4
  58. package/dist/utils/telemetry/tracing.js.map +0 -1
@@ -0,0 +1,22 @@
1
+ {
2
+ "manifestVersion": 1,
3
+ "packageName": "@cesteral/msads-mcp",
4
+ "packageVersion": "1.2.0",
5
+ "generatedAt": "2026-06-01T18:49:33.439Z",
6
+ "tools": [
7
+ {
8
+ "toolName": "msads_get_entity",
9
+ "contractPlatformSlug": "msads",
10
+ "contractToolSlug": "get_entity",
11
+ "schemaVersion": "1",
12
+ "definitionHash": "d33960e312ffd4b7074c60ebf22ab650580fbc53c8e974620aa451a4ba5832f0"
13
+ },
14
+ {
15
+ "toolName": "msads_update_entity",
16
+ "contractPlatformSlug": "msads",
17
+ "contractToolSlug": "update_entity",
18
+ "schemaVersion": "1",
19
+ "definitionHash": "e45479e3141a76d2ae7ab0be1ecdcfe1932d5d6457bafe1521aea7249f78bf7d"
20
+ }
21
+ ]
22
+ }
@@ -17,7 +17,7 @@ export function getMsAdsTroubleshootEntityMessage(args) {
17
17
 
18
18
  ## Step 1: Fetch Entity Details
19
19
  \`\`\`json
20
- msads_get_entity({ "entityType": "${entityType}", "entityIds": ["${entityId}"] })
20
+ msads_get_entity({ "entityType": "${entityType}", "entityId": "${entityId}" })
21
21
  \`\`\`
22
22
 
23
23
  ## Step 2: Check Status
@@ -1 +1 @@
1
- {"version":3,"file":"troubleshoot-entity.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/troubleshoot-entity.prompt.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,6BAA6B,GAAW;IACnD,IAAI,EAAE,2BAA2B;IACjC,WAAW,EAAE,yDAAyD;IACtE,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,8CAA8C;YAC3D,QAAQ,EAAE,IAAI;SACf;QACD,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,2BAA2B,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC/E;CACF,CAAC;AAEF,MAAM,UAAU,iCAAiC,CAAC,IAA6B;IAC7E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,YAAY,CAAC;IAEhD,OAAO;;;;oCAI2B,UAAU,qBAAqB,QAAQ;;;;;;;;;;;;mBAYxD,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,kCAAkC,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,4BAA4B;;;;;;;;;;;;;CAa7O,CAAC;AACF,CAAC"}
1
+ {"version":3,"file":"troubleshoot-entity.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/troubleshoot-entity.prompt.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,6BAA6B,GAAW;IACnD,IAAI,EAAE,2BAA2B;IACjC,WAAW,EAAE,yDAAyD;IACtE,SAAS,EAAE;QACT;YACE,IAAI,EAAE,YAAY;YAClB,WAAW,EAAE,8CAA8C;YAC3D,QAAQ,EAAE,IAAI;SACf;QACD,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,2BAA2B,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC/E;CACF,CAAC;AAEF,MAAM,UAAU,iCAAiC,CAAC,IAA6B;IAC7E,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,cAAc,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,YAAY,CAAC;IAEhD,OAAO;;;;oCAI2B,UAAU,mBAAmB,QAAQ;;;;;;;;;;;;mBAYtD,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,kCAAkC,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC,CAAC,4BAA4B;;;;;;;;;;;;;CAa7O,CAAC;AACF,CAAC"}
@@ -45,20 +45,20 @@ export declare const DownloadReportOutputSchema: z.ZodObject<{
45
45
  expiresAt: z.ZodString;
46
46
  mimeType: z.ZodString;
47
47
  }, "strip", z.ZodTypeAny, {
48
+ mimeType: string;
49
+ signedUrl: string;
48
50
  bucket: string;
49
51
  objectName: string;
50
52
  bytes: number;
51
- signedUrl: string;
52
53
  expiresAt: string;
53
- mimeType: string;
54
54
  rowCount?: number | undefined;
55
55
  }, {
56
+ mimeType: string;
57
+ signedUrl: string;
56
58
  bucket: string;
57
59
  objectName: string;
58
60
  bytes: number;
59
- signedUrl: string;
60
61
  expiresAt: string;
61
- mimeType: string;
62
62
  rowCount?: number | undefined;
63
63
  }>, z.ZodObject<{
64
64
  error: z.ZodString;
@@ -93,12 +93,12 @@ export declare const DownloadReportOutputSchema: z.ZodObject<{
93
93
  rawCsvResourceUri?: string | undefined;
94
94
  rawCsvByteLength?: number | undefined;
95
95
  spill?: {
96
+ mimeType: string;
97
+ signedUrl: string;
96
98
  bucket: string;
97
99
  objectName: string;
98
100
  bytes: number;
99
- signedUrl: string;
100
101
  expiresAt: string;
101
- mimeType: string;
102
102
  rowCount?: number | undefined;
103
103
  } | {
104
104
  error: string;
@@ -118,12 +118,12 @@ export declare const DownloadReportOutputSchema: z.ZodObject<{
118
118
  rawCsvResourceUri?: string | undefined;
119
119
  rawCsvByteLength?: number | undefined;
120
120
  spill?: {
121
+ mimeType: string;
122
+ signedUrl: string;
121
123
  bucket: string;
122
124
  objectName: string;
123
125
  bytes: number;
124
- signedUrl: string;
125
126
  expiresAt: string;
126
- mimeType: string;
127
127
  rowCount?: number | undefined;
128
128
  } | {
129
129
  error: string;
@@ -182,20 +182,20 @@ export declare const downloadReportTool: {
182
182
  expiresAt: z.ZodString;
183
183
  mimeType: z.ZodString;
184
184
  }, "strip", z.ZodTypeAny, {
185
+ mimeType: string;
186
+ signedUrl: string;
185
187
  bucket: string;
186
188
  objectName: string;
187
189
  bytes: number;
188
- signedUrl: string;
189
190
  expiresAt: string;
190
- mimeType: string;
191
191
  rowCount?: number | undefined;
192
192
  }, {
193
+ mimeType: string;
194
+ signedUrl: string;
193
195
  bucket: string;
194
196
  objectName: string;
195
197
  bytes: number;
196
- signedUrl: string;
197
198
  expiresAt: string;
198
- mimeType: string;
199
199
  rowCount?: number | undefined;
200
200
  }>, z.ZodObject<{
201
201
  error: z.ZodString;
@@ -230,12 +230,12 @@ export declare const downloadReportTool: {
230
230
  rawCsvResourceUri?: string | undefined;
231
231
  rawCsvByteLength?: number | undefined;
232
232
  spill?: {
233
+ mimeType: string;
234
+ signedUrl: string;
233
235
  bucket: string;
234
236
  objectName: string;
235
237
  bytes: number;
236
- signedUrl: string;
237
238
  expiresAt: string;
238
- mimeType: string;
239
239
  rowCount?: number | undefined;
240
240
  } | {
241
241
  error: string;
@@ -255,12 +255,12 @@ export declare const downloadReportTool: {
255
255
  rawCsvResourceUri?: string | undefined;
256
256
  rawCsvByteLength?: number | undefined;
257
257
  spill?: {
258
+ mimeType: string;
259
+ signedUrl: string;
258
260
  bucket: string;
259
261
  objectName: string;
260
262
  bytes: number;
261
- signedUrl: string;
262
263
  expiresAt: string;
263
- mimeType: string;
264
264
  rowCount?: number | undefined;
265
265
  } | {
266
266
  error: string;
@@ -1,132 +1,133 @@
1
1
  import { z } from "zod";
2
- import type { RequestContext, McpTextContent, SdkContext } from "@cesteral/shared";
2
+ import type { RequestContext, McpTextContent } from "@cesteral/shared";
3
+ import type { SdkContext } from "@cesteral/shared";
3
4
  export declare const GetEntityInputSchema: z.ZodDiscriminatedUnion<"entityType", [z.ZodObject<{
4
- entityIds: z.ZodArray<z.ZodString, "many">;
5
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
6
5
  entityType: z.ZodLiteral<"campaign">;
6
+ entityId: z.ZodString;
7
7
  accountId: z.ZodString;
8
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
8
9
  }, "strip", z.ZodTypeAny, {
9
10
  entityType: "campaign";
10
11
  accountId: string;
11
- entityIds: string[];
12
+ entityId: string;
12
13
  additionalParams?: Record<string, unknown> | undefined;
13
14
  }, {
14
15
  entityType: "campaign";
15
16
  accountId: string;
16
- entityIds: string[];
17
+ entityId: string;
17
18
  additionalParams?: Record<string, unknown> | undefined;
18
19
  }>, z.ZodObject<{
19
- entityIds: z.ZodArray<z.ZodString, "many">;
20
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
21
20
  entityType: z.ZodLiteral<"adGroup">;
21
+ entityId: z.ZodString;
22
22
  campaignId: z.ZodString;
23
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
23
24
  }, "strip", z.ZodTypeAny, {
24
25
  entityType: "adGroup";
25
- entityIds: string[];
26
+ entityId: string;
26
27
  campaignId: string;
27
28
  additionalParams?: Record<string, unknown> | undefined;
28
29
  }, {
29
30
  entityType: "adGroup";
30
- entityIds: string[];
31
+ entityId: string;
31
32
  campaignId: string;
32
33
  additionalParams?: Record<string, unknown> | undefined;
33
34
  }>, z.ZodObject<{
34
- entityIds: z.ZodArray<z.ZodString, "many">;
35
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
36
35
  entityType: z.ZodLiteral<"ad">;
36
+ entityId: z.ZodString;
37
37
  adGroupId: z.ZodString;
38
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
38
39
  }, "strip", z.ZodTypeAny, {
39
40
  entityType: "ad";
40
- entityIds: string[];
41
+ entityId: string;
41
42
  adGroupId: string;
42
43
  additionalParams?: Record<string, unknown> | undefined;
43
44
  }, {
44
45
  entityType: "ad";
45
- entityIds: string[];
46
+ entityId: string;
46
47
  adGroupId: string;
47
48
  additionalParams?: Record<string, unknown> | undefined;
48
49
  }>, z.ZodObject<{
49
- entityIds: z.ZodArray<z.ZodString, "many">;
50
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
51
50
  entityType: z.ZodLiteral<"keyword">;
51
+ entityId: z.ZodString;
52
52
  adGroupId: z.ZodString;
53
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
53
54
  }, "strip", z.ZodTypeAny, {
54
55
  entityType: "keyword";
55
- entityIds: string[];
56
+ entityId: string;
56
57
  adGroupId: string;
57
58
  additionalParams?: Record<string, unknown> | undefined;
58
59
  }, {
59
60
  entityType: "keyword";
60
- entityIds: string[];
61
+ entityId: string;
61
62
  adGroupId: string;
62
63
  additionalParams?: Record<string, unknown> | undefined;
63
64
  }>, z.ZodObject<{
64
- entityIds: z.ZodArray<z.ZodString, "many">;
65
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
66
65
  entityType: z.ZodLiteral<"adExtension">;
66
+ entityId: z.ZodString;
67
67
  accountId: z.ZodString;
68
68
  adExtensionType: z.ZodString;
69
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
69
70
  }, "strip", z.ZodTypeAny, {
70
71
  entityType: "adExtension";
71
72
  accountId: string;
72
- entityIds: string[];
73
+ entityId: string;
73
74
  adExtensionType: string;
74
75
  additionalParams?: Record<string, unknown> | undefined;
75
76
  }, {
76
77
  entityType: "adExtension";
77
78
  accountId: string;
78
- entityIds: string[];
79
+ entityId: string;
79
80
  adExtensionType: string;
80
81
  additionalParams?: Record<string, unknown> | undefined;
81
82
  }>, z.ZodObject<{
82
- entityIds: z.ZodArray<z.ZodString, "many">;
83
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
84
83
  entityType: z.ZodLiteral<"budget">;
84
+ entityId: z.ZodString;
85
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
85
86
  }, "strip", z.ZodTypeAny, {
86
87
  entityType: "budget";
87
- entityIds: string[];
88
+ entityId: string;
88
89
  additionalParams?: Record<string, unknown> | undefined;
89
90
  }, {
90
91
  entityType: "budget";
91
- entityIds: string[];
92
+ entityId: string;
92
93
  additionalParams?: Record<string, unknown> | undefined;
93
94
  }>, z.ZodObject<{
94
- entityIds: z.ZodArray<z.ZodString, "many">;
95
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
96
95
  entityType: z.ZodLiteral<"audience">;
96
+ entityId: z.ZodString;
97
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
97
98
  }, "strip", z.ZodTypeAny, {
98
99
  entityType: "audience";
99
- entityIds: string[];
100
+ entityId: string;
100
101
  additionalParams?: Record<string, unknown> | undefined;
101
102
  }, {
102
103
  entityType: "audience";
103
- entityIds: string[];
104
+ entityId: string;
104
105
  additionalParams?: Record<string, unknown> | undefined;
105
106
  }>, z.ZodObject<{
106
- entityIds: z.ZodArray<z.ZodString, "many">;
107
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
108
107
  entityType: z.ZodLiteral<"label">;
108
+ entityId: z.ZodString;
109
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
109
110
  }, "strip", z.ZodTypeAny, {
110
111
  entityType: "label";
111
- entityIds: string[];
112
+ entityId: string;
112
113
  additionalParams?: Record<string, unknown> | undefined;
113
114
  }, {
114
115
  entityType: "label";
115
- entityIds: string[];
116
+ entityId: string;
116
117
  additionalParams?: Record<string, unknown> | undefined;
117
118
  }>]>;
118
119
  export declare const GetEntityOutputSchema: z.ZodObject<{
119
- entities: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">;
120
+ entity: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>;
120
121
  entityType: z.ZodString;
121
122
  timestamp: z.ZodString;
122
123
  }, "strip", z.ZodTypeAny, {
123
124
  entityType: string;
124
- entities: Record<string, any>[];
125
125
  timestamp: string;
126
+ entity: Record<string, any> | null;
126
127
  }, {
127
128
  entityType: string;
128
- entities: Record<string, any>[];
129
129
  timestamp: string;
130
+ entity: Record<string, any> | null;
130
131
  }>;
131
132
  type GetEntityInput = z.infer<typeof GetEntityInputSchema>;
132
133
  type GetEntityOutput = z.infer<typeof GetEntityOutputSchema>;
@@ -137,147 +138,164 @@ export declare const getEntityTool: {
137
138
  title: string;
138
139
  description: string;
139
140
  inputSchema: z.ZodDiscriminatedUnion<"entityType", [z.ZodObject<{
140
- entityIds: z.ZodArray<z.ZodString, "many">;
141
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
142
141
  entityType: z.ZodLiteral<"campaign">;
142
+ entityId: z.ZodString;
143
143
  accountId: z.ZodString;
144
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
144
145
  }, "strip", z.ZodTypeAny, {
145
146
  entityType: "campaign";
146
147
  accountId: string;
147
- entityIds: string[];
148
+ entityId: string;
148
149
  additionalParams?: Record<string, unknown> | undefined;
149
150
  }, {
150
151
  entityType: "campaign";
151
152
  accountId: string;
152
- entityIds: string[];
153
+ entityId: string;
153
154
  additionalParams?: Record<string, unknown> | undefined;
154
155
  }>, z.ZodObject<{
155
- entityIds: z.ZodArray<z.ZodString, "many">;
156
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
157
156
  entityType: z.ZodLiteral<"adGroup">;
157
+ entityId: z.ZodString;
158
158
  campaignId: z.ZodString;
159
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
159
160
  }, "strip", z.ZodTypeAny, {
160
161
  entityType: "adGroup";
161
- entityIds: string[];
162
+ entityId: string;
162
163
  campaignId: string;
163
164
  additionalParams?: Record<string, unknown> | undefined;
164
165
  }, {
165
166
  entityType: "adGroup";
166
- entityIds: string[];
167
+ entityId: string;
167
168
  campaignId: string;
168
169
  additionalParams?: Record<string, unknown> | undefined;
169
170
  }>, z.ZodObject<{
170
- entityIds: z.ZodArray<z.ZodString, "many">;
171
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
172
171
  entityType: z.ZodLiteral<"ad">;
172
+ entityId: z.ZodString;
173
173
  adGroupId: z.ZodString;
174
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
174
175
  }, "strip", z.ZodTypeAny, {
175
176
  entityType: "ad";
176
- entityIds: string[];
177
+ entityId: string;
177
178
  adGroupId: string;
178
179
  additionalParams?: Record<string, unknown> | undefined;
179
180
  }, {
180
181
  entityType: "ad";
181
- entityIds: string[];
182
+ entityId: string;
182
183
  adGroupId: string;
183
184
  additionalParams?: Record<string, unknown> | undefined;
184
185
  }>, z.ZodObject<{
185
- entityIds: z.ZodArray<z.ZodString, "many">;
186
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
187
186
  entityType: z.ZodLiteral<"keyword">;
187
+ entityId: z.ZodString;
188
188
  adGroupId: z.ZodString;
189
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
189
190
  }, "strip", z.ZodTypeAny, {
190
191
  entityType: "keyword";
191
- entityIds: string[];
192
+ entityId: string;
192
193
  adGroupId: string;
193
194
  additionalParams?: Record<string, unknown> | undefined;
194
195
  }, {
195
196
  entityType: "keyword";
196
- entityIds: string[];
197
+ entityId: string;
197
198
  adGroupId: string;
198
199
  additionalParams?: Record<string, unknown> | undefined;
199
200
  }>, z.ZodObject<{
200
- entityIds: z.ZodArray<z.ZodString, "many">;
201
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
202
201
  entityType: z.ZodLiteral<"adExtension">;
202
+ entityId: z.ZodString;
203
203
  accountId: z.ZodString;
204
204
  adExtensionType: z.ZodString;
205
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
205
206
  }, "strip", z.ZodTypeAny, {
206
207
  entityType: "adExtension";
207
208
  accountId: string;
208
- entityIds: string[];
209
+ entityId: string;
209
210
  adExtensionType: string;
210
211
  additionalParams?: Record<string, unknown> | undefined;
211
212
  }, {
212
213
  entityType: "adExtension";
213
214
  accountId: string;
214
- entityIds: string[];
215
+ entityId: string;
215
216
  adExtensionType: string;
216
217
  additionalParams?: Record<string, unknown> | undefined;
217
218
  }>, z.ZodObject<{
218
- entityIds: z.ZodArray<z.ZodString, "many">;
219
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
220
219
  entityType: z.ZodLiteral<"budget">;
220
+ entityId: z.ZodString;
221
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
221
222
  }, "strip", z.ZodTypeAny, {
222
223
  entityType: "budget";
223
- entityIds: string[];
224
+ entityId: string;
224
225
  additionalParams?: Record<string, unknown> | undefined;
225
226
  }, {
226
227
  entityType: "budget";
227
- entityIds: string[];
228
+ entityId: string;
228
229
  additionalParams?: Record<string, unknown> | undefined;
229
230
  }>, z.ZodObject<{
230
- entityIds: z.ZodArray<z.ZodString, "many">;
231
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
232
231
  entityType: z.ZodLiteral<"audience">;
232
+ entityId: z.ZodString;
233
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
233
234
  }, "strip", z.ZodTypeAny, {
234
235
  entityType: "audience";
235
- entityIds: string[];
236
+ entityId: string;
236
237
  additionalParams?: Record<string, unknown> | undefined;
237
238
  }, {
238
239
  entityType: "audience";
239
- entityIds: string[];
240
+ entityId: string;
240
241
  additionalParams?: Record<string, unknown> | undefined;
241
242
  }>, z.ZodObject<{
242
- entityIds: z.ZodArray<z.ZodString, "many">;
243
- additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
244
243
  entityType: z.ZodLiteral<"label">;
244
+ entityId: z.ZodString;
245
+ additionalParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
245
246
  }, "strip", z.ZodTypeAny, {
246
247
  entityType: "label";
247
- entityIds: string[];
248
+ entityId: string;
248
249
  additionalParams?: Record<string, unknown> | undefined;
249
250
  }, {
250
251
  entityType: "label";
251
- entityIds: string[];
252
+ entityId: string;
252
253
  additionalParams?: Record<string, unknown> | undefined;
253
254
  }>]>;
254
255
  outputSchema: z.ZodObject<{
255
- entities: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">;
256
+ entity: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>;
256
257
  entityType: z.ZodString;
257
258
  timestamp: z.ZodString;
258
259
  }, "strip", z.ZodTypeAny, {
259
260
  entityType: string;
260
- entities: Record<string, any>[];
261
261
  timestamp: string;
262
+ entity: Record<string, any> | null;
262
263
  }, {
263
264
  entityType: string;
264
- entities: Record<string, any>[];
265
265
  timestamp: string;
266
+ entity: Record<string, any> | null;
266
267
  }>;
267
268
  annotations: {
268
269
  readOnlyHint: boolean;
269
270
  openWorldHint: boolean;
270
271
  idempotentHint: boolean;
271
272
  destructiveHint: boolean;
273
+ cesteral: {
274
+ kind: "read";
275
+ platform: string;
276
+ contractPlatformSlug: string;
277
+ contractToolSlug: string;
278
+ entityKinds: ("campaign" | "ad" | "ad_group" | "campaign_budget")[];
279
+ entityIdArgs: string[];
280
+ schemaVersion: number;
281
+ contractId: string;
282
+ };
272
283
  };
273
- inputExamples: {
284
+ inputExamples: ({
274
285
  label: string;
275
286
  input: {
276
287
  entityType: string;
277
- entityIds: string[];
288
+ entityId: string;
278
289
  accountId: string;
279
290
  };
280
- }[];
291
+ } | {
292
+ label: string;
293
+ input: {
294
+ entityType: string;
295
+ entityId: string;
296
+ accountId?: undefined;
297
+ };
298
+ })[];
281
299
  logic: typeof getEntityLogic;
282
300
  responseFormatter: typeof getEntityResponseFormatter;
283
301
  };
@@ -1 +1 @@
1
- {"version":3,"file":"get-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-entity.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkBnF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyCiC,CAAC;AAEnE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAMI,CAAC;AAEvC,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAC3D,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE7D,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,eAAe,CAAC,CAkC1B;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CAOpF;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBzB,CAAC"}
1
+ {"version":3,"file":"get-entity.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-entity.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAA+B,MAAM,kBAAkB,CAAC;AAiBhF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiDiC,CAAC;AAEnE,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAMI,CAAC;AAEvC,KAAK,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAC3D,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE7D,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,eAAe,CAAC,CAkC1B;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,EAAE,CASpF;AAED,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuCzB,CAAC"}
@@ -2,63 +2,70 @@ import { z } from "zod";
2
2
  import { resolveSessionServices } from "../utils/resolve-session.js";
3
3
  const TOOL_NAME = "msads_get_entity";
4
4
  const TOOL_TITLE = "Get Microsoft Ads Entity";
5
- const TOOL_DESCRIPTION = `Retrieve one or more Microsoft Advertising entities by their IDs.
5
+ const TOOL_DESCRIPTION = `Retrieve a single Microsoft Advertising entity by its ID.
6
6
 
7
- Returns full entity details for the specified entity type and IDs.
7
+ Returns full entity details for the specified entity type and ID.
8
8
 
9
- Some Microsoft Advertising query operations require parent or account context in addition to the IDs.`;
10
- const BaseGetEntitySchema = {
11
- entityIds: z.array(z.string()).min(1).describe("Array of entity IDs to retrieve"),
12
- additionalParams: z
13
- .record(z.unknown())
14
- .optional()
15
- .describe("Additional parameters such as ReturnAdditionalFields"),
16
- };
9
+ Some Microsoft Advertising query operations require parent or account context in
10
+ addition to the ID (campaign needs accountId, adGroup needs campaignId, etc.).`;
11
+ const idField = z.string().min(1).describe("The entity ID to retrieve");
12
+ const additionalParamsField = z
13
+ .record(z.unknown())
14
+ .optional()
15
+ .describe("Additional parameters such as ReturnAdditionalFields");
17
16
  export const GetEntityInputSchema = z
18
17
  .discriminatedUnion("entityType", [
19
18
  z.object({
20
19
  entityType: z.literal("campaign"),
20
+ entityId: idField,
21
21
  accountId: z.string().describe("AccountId required by GetCampaignsByIds"),
22
- ...BaseGetEntitySchema,
22
+ additionalParams: additionalParamsField,
23
23
  }),
24
24
  z.object({
25
25
  entityType: z.literal("adGroup"),
26
+ entityId: idField,
26
27
  campaignId: z.string().describe("CampaignId required by GetAdGroupsByIds"),
27
- ...BaseGetEntitySchema,
28
+ additionalParams: additionalParamsField,
28
29
  }),
29
30
  z.object({
30
31
  entityType: z.literal("ad"),
32
+ entityId: idField,
31
33
  adGroupId: z.string().describe("AdGroupId required by GetAdsByIds"),
32
- ...BaseGetEntitySchema,
34
+ additionalParams: additionalParamsField,
33
35
  }),
34
36
  z.object({
35
37
  entityType: z.literal("keyword"),
38
+ entityId: idField,
36
39
  adGroupId: z.string().describe("AdGroupId required by GetKeywordsByIds"),
37
- ...BaseGetEntitySchema,
40
+ additionalParams: additionalParamsField,
38
41
  }),
39
42
  z.object({
40
43
  entityType: z.literal("adExtension"),
44
+ entityId: idField,
41
45
  accountId: z.string().describe("AccountId required by GetAdExtensionsByIds"),
42
46
  adExtensionType: z.string().describe("AdExtensionType required by GetAdExtensionsByIds"),
43
- ...BaseGetEntitySchema,
47
+ additionalParams: additionalParamsField,
44
48
  }),
45
49
  z.object({
46
50
  entityType: z.literal("budget"),
47
- ...BaseGetEntitySchema,
51
+ entityId: idField,
52
+ additionalParams: additionalParamsField,
48
53
  }),
49
54
  z.object({
50
55
  entityType: z.literal("audience"),
51
- ...BaseGetEntitySchema,
56
+ entityId: idField,
57
+ additionalParams: additionalParamsField,
52
58
  }),
53
59
  z.object({
54
60
  entityType: z.literal("label"),
55
- ...BaseGetEntitySchema,
61
+ entityId: idField,
62
+ additionalParams: additionalParamsField,
56
63
  }),
57
64
  ])
58
- .describe("Parameters for getting Microsoft Ads entities by ID");
65
+ .describe("Parameters for getting a Microsoft Ads entity by ID");
59
66
  export const GetEntityOutputSchema = z
60
67
  .object({
61
- entities: z.array(z.record(z.any())),
68
+ entity: z.record(z.any()).nullable().describe("Retrieved entity data, or null if not found"),
62
69
  entityType: z.string(),
63
70
  timestamp: z.string().datetime(),
64
71
  })
@@ -80,10 +87,10 @@ export async function getEntityLogic(input, context, sdkContext) {
80
87
  if ("adExtensionType" in input) {
81
88
  additionalParams.AdExtensionType = input.adExtensionType;
82
89
  }
83
- const { entities: rawEntities } = await msadsService.getEntity(input.entityType, input.entityIds, additionalParams, context);
84
- const entities = rawEntities;
90
+ const { entities: rawEntities } = await msadsService.getEntity(input.entityType, [input.entityId], additionalParams, context);
91
+ const entity = rawEntities[0] ?? null;
85
92
  return {
86
- entities,
93
+ entity,
87
94
  entityType: input.entityType,
88
95
  timestamp: new Date().toISOString(),
89
96
  };
@@ -92,7 +99,9 @@ export function getEntityResponseFormatter(result) {
92
99
  return [
93
100
  {
94
101
  type: "text",
95
- text: `Retrieved ${result.entities.length} ${result.entityType} entities\n\n${JSON.stringify(result.entities, null, 2)}\n\nTimestamp: ${result.timestamp}`,
102
+ text: result.entity
103
+ ? `Retrieved ${result.entityType} entity\n\n${JSON.stringify(result.entity, null, 2)}\n\nTimestamp: ${result.timestamp}`
104
+ : `No ${result.entityType} entity found\n\nTimestamp: ${result.timestamp}`,
96
105
  },
97
106
  ];
98
107
  }
@@ -107,11 +116,25 @@ export const getEntityTool = {
107
116
  openWorldHint: false,
108
117
  idempotentHint: true,
109
118
  destructiveHint: false,
119
+ cesteral: {
120
+ kind: "read",
121
+ platform: "msads",
122
+ contractPlatformSlug: "msads",
123
+ contractToolSlug: "get_entity",
124
+ entityKinds: ["campaign", "ad_group", "ad", "campaign_budget"],
125
+ entityIdArgs: ["entityId"],
126
+ schemaVersion: 1,
127
+ contractId: "msads.get_entity.v1",
128
+ },
110
129
  },
111
130
  inputExamples: [
112
131
  {
113
132
  label: "Get a campaign by ID",
114
- input: { entityType: "campaign", entityIds: ["123456"], accountId: "789012" },
133
+ input: { entityType: "campaign", entityId: "123456", accountId: "789012" },
134
+ },
135
+ {
136
+ label: "Get a shared budget by ID",
137
+ input: { entityType: "budget", entityId: "555000" },
115
138
  },
116
139
  ],
117
140
  logic: getEntityLogic,