@cesteral/gads-mcp 1.0.0

package/dist/mcp-server/tools/definitions/create-entity.tool.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { getEntityTypeEnum } from "../utils/entity-mapping.js";
+import { addParentValidationIssue } from "../utils/parent-id-validation.js";
+const TOOL_NAME = "gads_create_entity";
+const TOOL_TITLE = "Create Google Ads Entity";
+const TOOL_DESCRIPTION = `Create a new Google Ads entity using the :mutate API.
+
+**Supported entity types:** ${getEntityTypeEnum().join(", ")}
+
+Provide entity data matching the Google Ads API v23 field format.
+Refer to \`entity-schema://{entityType}\` resources for field reference.
+
+**Important**: For campaigns, create a campaignBudget first and reference it via the \`campaignBudget\` field.`;
+export const CreateEntityInputSchema = z
+    .object({
+    entityType: z.enum(getEntityTypeEnum()).describe("Type of entity to create"),
+    customerId: z.string().min(1).describe("Google Ads customer ID (no dashes)"),
+    data: z
+        .record(z.any())
+        .describe("Entity data to create (fields vary by entity type — see entity-schema resources)"),
+})
+    .superRefine((input, ctx) => {
+    addParentValidationIssue(ctx, input.entityType, input);
+})
+    .describe("Parameters for creating a Google Ads entity");
+export const CreateEntityOutputSchema = z
+    .object({
+    mutateResult: z.record(z.any()).describe("Mutate operation result"),
+    timestamp: z.string().datetime(),
+})
+    .describe("Entity creation result");
+export async function createEntityLogic(input, context, sdkContext) {
+    const { gadsService } = resolveSessionServices(sdkContext);
+    const result = await gadsService.createEntity(input.entityType, input.customerId, input.data, context);
+    return {
+        mutateResult: result,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function createEntityResponseFormatter(result) {
+    return [
+        {
+            type: "text",
+            text: `Entity created successfully\n${JSON.stringify(result.mutateResult, null, 2)}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const createEntityTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: CreateEntityInputSchema,
+    outputSchema: CreateEntityOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Create a campaign budget",
+            input: {
+                entityType: "campaignBudget",
+                customerId: "1234567890",
+                data: {
+                    name: "Q1 2025 Search Budget",
+                    amountMicros: "50000000000",
+                    deliveryMethod: "STANDARD",
+                },
+            },
+        },
+        {
+            label: "Create a search campaign",
+            input: {
+                entityType: "campaign",
+                customerId: "1234567890",
+                data: {
+                    name: "Q1 2025 Brand Search",
+                    advertisingChannelType: "SEARCH",
+                    status: "PAUSED",
+                    campaignBudget: "customers/1234567890/campaignBudgets/9876543",
+                    startDate: "2025-01-15",
+                    endDate: "2025-03-31",
+                    networkSettings: {
+                        targetGoogleSearch: true,
+                        targetSearchNetwork: false,
+                        targetContentNetwork: false,
+                    },
+                },
+            },
+        },
+    ],
+    logic: createEntityLogic,
+    responseFormatter: createEntityResponseFormatter,
+};
+//# sourceMappingURL=create-entity.tool.js.map

package/dist/mcp-server/tools/definitions/create-entity.tool.js.map

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

package/dist/mcp-server/tools/definitions/gaql-search.tool.d.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const GAQLSearchInputSchema: z.ZodObject<{
+    customerId: z.ZodString;
+    query: z.ZodString;
+    pageSize: z.ZodOptional<z.ZodNumber>;
+    pageToken: z.ZodOptional<z.ZodString>;
+} & Omit<{
+    mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["summary", "rows"]>>>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    maxRows: z.ZodOptional<z.ZodNumber>;
+    aggregateBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aggregateMetrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["sum", "avg", "count", "min", "max"]>>>;
+}, "offset">, "strip", z.ZodTypeAny, {
+    customerId: string;
+    query: string;
+    mode: "summary" | "rows";
+    pageSize?: number | undefined;
+    pageToken?: string | undefined;
+    columns?: string[] | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+}, {
+    customerId: string;
+    query: string;
+    pageSize?: number | undefined;
+    pageToken?: string | undefined;
+    mode?: "summary" | "rows" | undefined;
+    columns?: string[] | undefined;
+    maxRows?: number | undefined;
+    aggregateBy?: string[] | undefined;
+    aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+}>;
+export declare const GAQLSearchOutputSchema: z.ZodObject<{
+    totalResultsCount: z.ZodOptional<z.ZodNumber>;
+    nextPageToken: z.ZodOptional<z.ZodString>;
+    has_more: z.ZodBoolean;
+    timestamp: z.ZodString;
+    totalRows: z.ZodNumber;
+    returnedRows: z.ZodNumber;
+    truncated: z.ZodBoolean;
+    nextOffset: z.ZodNullable<z.ZodNumber>;
+    headers: z.ZodArray<z.ZodString, "many">;
+    selectedColumns: z.ZodArray<z.ZodString, "many">;
+    mode: z.ZodEnum<["summary", "rows"]>;
+    previewRows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    warnings: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    mode: "summary" | "rows";
+    has_more: boolean;
+    timestamp: string;
+    totalRows: number;
+    returnedRows: number;
+    truncated: boolean;
+    nextOffset: number | null;
+    headers: string[];
+    selectedColumns: string[];
+    warnings: string[];
+    nextPageToken?: string | undefined;
+    totalResultsCount?: number | undefined;
+    rows?: Record<string, any>[] | undefined;
+    previewRows?: Record<string, any>[] | undefined;
+}, {
+    mode: "summary" | "rows";
+    has_more: boolean;
+    timestamp: string;
+    totalRows: number;
+    returnedRows: number;
+    truncated: boolean;
+    nextOffset: number | null;
+    headers: string[];
+    selectedColumns: string[];
+    warnings: string[];
+    nextPageToken?: string | undefined;
+    totalResultsCount?: number | undefined;
+    rows?: Record<string, any>[] | undefined;
+    previewRows?: Record<string, any>[] | undefined;
+}>;
+type GAQLSearchInput = z.infer<typeof GAQLSearchInputSchema>;
+type GAQLSearchOutput = z.infer<typeof GAQLSearchOutputSchema>;
+export declare function gaqlSearchLogic(input: GAQLSearchInput, context: RequestContext, sdkContext?: SdkContext): Promise<GAQLSearchOutput>;
+export declare function gaqlSearchResponseFormatter(result: GAQLSearchOutput): McpTextContent[];
+export declare const gaqlSearchTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        customerId: z.ZodString;
+        query: z.ZodString;
+        pageSize: z.ZodOptional<z.ZodNumber>;
+        pageToken: z.ZodOptional<z.ZodString>;
+    } & Omit<{
+        mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<["summary", "rows"]>>>;
+        columns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        offset: z.ZodOptional<z.ZodNumber>;
+        maxRows: z.ZodOptional<z.ZodNumber>;
+        aggregateBy: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        aggregateMetrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<["sum", "avg", "count", "min", "max"]>>>;
+    }, "offset">, "strip", z.ZodTypeAny, {
+        customerId: string;
+        query: string;
+        mode: "summary" | "rows";
+        pageSize?: number | undefined;
+        pageToken?: string | undefined;
+        columns?: string[] | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    }, {
+        customerId: string;
+        query: string;
+        pageSize?: number | undefined;
+        pageToken?: string | undefined;
+        mode?: "summary" | "rows" | undefined;
+        columns?: string[] | undefined;
+        maxRows?: number | undefined;
+        aggregateBy?: string[] | undefined;
+        aggregateMetrics?: Record<string, "count" | "sum" | "avg" | "min" | "max"> | undefined;
+    }>;
+    outputSchema: z.ZodObject<{
+        totalResultsCount: z.ZodOptional<z.ZodNumber>;
+        nextPageToken: z.ZodOptional<z.ZodString>;
+        has_more: z.ZodBoolean;
+        timestamp: z.ZodString;
+        totalRows: z.ZodNumber;
+        returnedRows: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        nextOffset: z.ZodNullable<z.ZodNumber>;
+        headers: z.ZodArray<z.ZodString, "many">;
+        selectedColumns: z.ZodArray<z.ZodString, "many">;
+        mode: z.ZodEnum<["summary", "rows"]>;
+        previewRows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+        rows: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+        warnings: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        mode: "summary" | "rows";
+        has_more: boolean;
+        timestamp: string;
+        totalRows: number;
+        returnedRows: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        headers: string[];
+        selectedColumns: string[];
+        warnings: string[];
+        nextPageToken?: string | undefined;
+        totalResultsCount?: number | undefined;
+        rows?: Record<string, any>[] | undefined;
+        previewRows?: Record<string, any>[] | undefined;
+    }, {
+        mode: "summary" | "rows";
+        has_more: boolean;
+        timestamp: string;
+        totalRows: number;
+        returnedRows: number;
+        truncated: boolean;
+        nextOffset: number | null;
+        headers: string[];
+        selectedColumns: string[];
+        warnings: string[];
+        nextPageToken?: string | undefined;
+        totalResultsCount?: number | undefined;
+        rows?: Record<string, any>[] | undefined;
+        previewRows?: Record<string, any>[] | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+    };
+    inputExamples: ({
+        label: string;
+        input: {
+            customerId: string;
+            query: string;
+            mode?: undefined;
+            maxRows?: undefined;
+        };
+    } | {
+        label: string;
+        input: {
+            customerId: string;
+            query: string;
+            mode: string;
+            maxRows: number;
+        };
+    })[];
+    logic: typeof gaqlSearchLogic;
+    responseFormatter: typeof gaqlSearchResponseFormatter;
+};
+export {};
+//# sourceMappingURL=gaql-search.tool.d.ts.map

package/dist/mcp-server/tools/definitions/gaql-search.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gaql-search.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/gaql-search.tool.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AASxB,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAMnD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqBkB,CAAC;AAErD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAaD,CAAC;AAEnC,KAAK,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAC7D,KAAK,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE/D,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,gBAAgB,CAAC,CA8B3B;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAWtF;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C1B,CAAC"}

package/dist/mcp-server/tools/definitions/gaql-search.tool.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+import { createReportView, formatReportViewResponse, getReportViewFetchLimit, ReportViewInputSchema, ReportViewOutputSchema, } from "@cesteral/shared";
+const TOOL_NAME = "gads_gaql_search";
+const TOOL_TITLE = "Google Ads GAQL Search";
+const TOOL_DESCRIPTION = `Execute a Google Ads Query Language (GAQL) query against any Google Ads resource. Supports resource fields, segment fields, and metrics with SQL-like syntax. See \`gaql-reference://syntax\` resource for full reference.`;
+export const GAQLSearchInputSchema = z
+    .object({
+    customerId: z
+        .string()
+        .min(1)
+        .describe("Google Ads customer ID (no dashes, e.g., '1234567890')"),
+    query: z.string().min(1).describe("GAQL query string (must include SELECT and FROM clauses)"),
+    pageSize: z
+        .number()
+        .min(1)
+        .max(10000)
+        .optional()
+        .describe("Deprecated. Use maxRows for the returned row count."),
+    pageToken: z
+        .string()
+        .optional()
+        .describe("Page token for pagination (from previous response). This tool pages across result sets via pageToken; offset is not supported."),
+})
+    .merge(ReportViewInputSchema.omit({ offset: true }))
+    .describe("Parameters for executing a GAQL query");
+export const GAQLSearchOutputSchema = z
+    .object({
+    ...ReportViewOutputSchema.shape,
+    totalResultsCount: z
+        .number()
+        .optional()
+        .describe("Total results available (when known; otherwise totalRows is a lower bound and nextPageToken indicates more are available)"),
+    nextPageToken: z.string().optional().describe("Token for next page"),
+    has_more: z.boolean().describe("Whether more results are available via pagination"),
+    timestamp: z.string().datetime(),
+})
+    .describe("GAQL search results");
+export async function gaqlSearchLogic(input, context, sdkContext) {
+    const { gadsService } = resolveSessionServices(sdkContext);
+    const viewInput = input.maxRows === undefined && input.pageSize !== undefined
+        ? { ...input, maxRows: input.pageSize }
+        : input;
+    const result = await gadsService.gaqlSearch(input.customerId, input.query, getReportViewFetchLimit(viewInput), input.pageToken, context);
+    const rows = result.results;
+    return {
+        ...createReportView({
+            rows,
+            totalRows: result.totalResultsCount ?? rows.length + (result.nextPageToken ? 1 : 0),
+            input: viewInput,
+            warnings: result.nextPageToken
+                ? ["More rows are available. Call again with pageToken set to nextPageToken to continue."]
+                : [],
+        }),
+        totalResultsCount: result.totalResultsCount,
+        nextPageToken: result.nextPageToken,
+        has_more: !!result.nextPageToken,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function gaqlSearchResponseFormatter(result) {
+    const summary = `GAQL query returned ${result.returnedRows} result(s)${result.totalResultsCount ? ` (${result.totalResultsCount} total)` : ""}${result.nextPageToken ? " — more pages available" : ""}`;
+    return [
+        {
+            type: "text",
+            text: `${summary}\n\n${formatReportViewResponse(result, "Query data")}\n\nTimestamp: ${result.timestamp}`,
+        },
+    ];
+}
+export const gaqlSearchTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: GAQLSearchInputSchema,
+    outputSchema: GAQLSearchOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+    },
+    inputExamples: [
+        {
+            label: "Campaign performance metrics",
+            input: {
+                customerId: "1234567890",
+                query: "SELECT campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 50",
+            },
+        },
+        {
+            label: "Ad group performance for a campaign",
+            input: {
+                customerId: "1234567890",
+                query: "SELECT ad_group.id, ad_group.name, ad_group.status, metrics.impressions, metrics.conversions FROM ad_group WHERE campaign.id = 123456789 AND segments.date DURING LAST_7_DAYS",
+                mode: "rows",
+                maxRows: 50,
+            },
+        },
+        {
+            label: "Keyword quality scores",
+            input: {
+                customerId: "1234567890",
+                query: "SELECT ad_group_criterion.keyword.text, ad_group_criterion.quality_info.quality_score, ad_group_criterion.quality_info.creative_quality_score FROM keyword_view WHERE campaign.id = 123456789",
+            },
+        },
+    ],
+    logic: gaqlSearchLogic,
+    responseFormatter: gaqlSearchResponseFormatter,
+};
+//# sourceMappingURL=gaql-search.tool.js.map

package/dist/mcp-server/tools/definitions/gaql-search.tool.js.map

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

package/dist/mcp-server/tools/definitions/get-ad-preview.tool.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import type { RequestContext, McpTextContent } from "@cesteral/shared";
+import type { SdkContext } from "@cesteral/shared";
+export declare const GetAdPreviewInputSchema: z.ZodObject<{
+    customerId: z.ZodString;
+    adId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    customerId: string;
+    adId: string;
+}, {
+    customerId: string;
+    adId: string;
+}>;
+export declare const GetAdPreviewOutputSchema: z.ZodObject<{
+    adType: z.ZodOptional<z.ZodString>;
+    finalUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    adId: z.ZodString;
+    customerId: z.ZodString;
+    resourceName: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    customerId: string;
+    resourceName: string;
+    adId: string;
+    adType?: string | undefined;
+    finalUrls?: string[] | undefined;
+}, {
+    customerId: string;
+    resourceName: string;
+    adId: string;
+    adType?: string | undefined;
+    finalUrls?: string[] | undefined;
+}>;
+type GetAdPreviewInput = z.infer<typeof GetAdPreviewInputSchema>;
+type GetAdPreviewOutput = z.infer<typeof GetAdPreviewOutputSchema>;
+export declare function getAdPreviewLogic(input: GetAdPreviewInput, context: RequestContext, sdkContext?: SdkContext): Promise<GetAdPreviewOutput>;
+export declare function getAdPreviewResponseFormatter(result: GetAdPreviewOutput): McpTextContent[];
+export declare const getAdPreviewTool: {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        customerId: z.ZodString;
+        adId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        customerId: string;
+        adId: string;
+    }, {
+        customerId: string;
+        adId: string;
+    }>;
+    outputSchema: z.ZodObject<{
+        adType: z.ZodOptional<z.ZodString>;
+        finalUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        adId: z.ZodString;
+        customerId: z.ZodString;
+        resourceName: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        customerId: string;
+        resourceName: string;
+        adId: string;
+        adType?: string | undefined;
+        finalUrls?: string[] | undefined;
+    }, {
+        customerId: string;
+        resourceName: string;
+        adId: string;
+        adType?: string | undefined;
+        finalUrls?: string[] | undefined;
+    }>;
+    annotations: {
+        readOnlyHint: boolean;
+        openWorldHint: boolean;
+        idempotentHint: boolean;
+        destructiveHint: boolean;
+    };
+    inputExamples: {
+        label: string;
+        input: {
+            customerId: string;
+            adId: string;
+        };
+    }[];
+    logic: typeof getAdPreviewLogic;
+    responseFormatter: typeof getAdPreviewResponseFormatter;
+};
+export {};
+//# sourceMappingURL=get-ad-preview.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-ad-preview.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-ad-preview.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-ad-preview.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,EAAE,MAAM,kBAAkB,CAAC;AAYnD,eAAO,MAAM,uBAAuB;;;;;;;;;EAQyB,CAAC;AAE9D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;EAclC,CAAC;AAEJ,KAAK,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACjE,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAanE,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,UAAU,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAqB7B;AAED,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAqB1F;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuB5B,CAAC"}

package/dist/mcp-server/tools/definitions/get-ad-preview.tool.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { resolveSessionServices } from "../utils/resolve-session.js";
+const TOOL_NAME = "gads_get_ad_preview";
+const TOOL_TITLE = "Get Google Ads Ad Preview";
+const TOOL_DESCRIPTION = `Get preview information for a Google Ads ad.
+
+Fetches the ad entity via GAQL and returns its type, resource name, and final URLs.
+The resource name can be used with the Google Ads generateAdPreview API for a full HTML render.
+
+**Usage:** Use adId from gads_list_entities with entityType=ad or gads_create_entity.
+The adId is the numeric ID, not the resource name.`;
+export const GetAdPreviewInputSchema = z
+    .object({
+    customerId: z
+        .string()
+        .min(1)
+        .describe("Google Ads Customer ID (without dashes, e.g., 1234567890)"),
+    adId: z.string().min(1).describe("Google Ads Ad ID"),
+})
+    .describe("Parameters for getting a Google Ads ad preview");
+export const GetAdPreviewOutputSchema = z
+    .object({
+    adType: z.string().optional().describe("Ad type (e.g., RESPONSIVE_SEARCH_AD, IMAGE_AD)"),
+    finalUrls: z.array(z.string()).optional().describe("Final destination URLs for the ad"),
+    adId: z.string(),
+    customerId: z.string(),
+    resourceName: z
+        .string()
+        .describe("Ad resource name for use with generateAdPreview API (customers/{customerId}/ads/{adId})"),
+})
+    .describe("Google Ads ad entity data. Use resourceName with the Google Ads generateAdPreview API to obtain an HTML preview.");
+export async function getAdPreviewLogic(input, context, sdkContext) {
+    const { gadsService } = resolveSessionServices(sdkContext);
+    const row = (await gadsService.getEntity("ad", input.customerId, input.adId, context));
+    const ad = row?.adGroupAd?.ad;
+    const resourceName = ad?.resourceName ?? `customers/${input.customerId}/ads/${input.adId}`;
+    return {
+        adType: ad?.type,
+        finalUrls: ad?.finalUrls,
+        adId: input.adId,
+        customerId: input.customerId,
+        resourceName,
+    };
+}
+export function getAdPreviewResponseFormatter(result) {
+    const lines = [
+        "Google Ads Ad Preview",
+        "",
+        `Ad ID: ${result.adId}`,
+        `Customer ID: ${result.customerId}`,
+    ];
+    if (result.adType)
+        lines.push(`Ad Type: ${result.adType}`);
+    if (result.resourceName)
+        lines.push(`Resource Name: ${result.resourceName}`);
+    if (result.finalUrls && result.finalUrls.length > 0) {
+        lines.push(`Final URLs: ${result.finalUrls.join(", ")}`);
+    }
+    lines.push("", `Use resourceName with the Google Ads generateAdPreview API for an HTML render.`);
+    return [
+        {
+            type: "text",
+            text: lines.join("\n"),
+        },
+    ];
+}
+export const getAdPreviewTool = {
+    name: TOOL_NAME,
+    title: TOOL_TITLE,
+    description: TOOL_DESCRIPTION,
+    inputSchema: GetAdPreviewInputSchema,
+    outputSchema: GetAdPreviewOutputSchema,
+    annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+        idempotentHint: true,
+        destructiveHint: false,
+    },
+    inputExamples: [
+        {
+            label: "Preview a Google Ads ad",
+            input: {
+                customerId: "1234567890",
+                adId: "987654321",
+            },
+        },
+    ],
+    logic: getAdPreviewLogic,
+    responseFormatter: getAdPreviewResponseFormatter,
+};
+//# sourceMappingURL=get-ad-preview.tool.js.map

package/dist/mcp-server/tools/definitions/get-ad-preview.tool.js.map

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