mcp-google-ads 1.4.2 → 1.4.4

package/dist/assetHelpers.d.ts

@@ -52,4 +52,47 @@ export interface PauseLinksDryRun {
         ad_group_asset: string[];
     };
 }
+export interface CreateSitelinkArgs {
+    customer_id?: string;
+    link_text: string;
+    final_urls: string[];
+    description1?: string;
+    description2?: string;
+    confirm?: boolean;
+}
+export interface CreateSitelinkDryRun {
+    dry_run: true;
+    message: string;
+    customer_id: string;
+    link_text: string;
+    final_urls: string[];
+    description1?: string;
+    description2?: string;
+}
+export declare function normalizeCreateSitelinkArgs(raw: Record<string, unknown> | undefined): CreateSitelinkArgs | {
+    error: string;
+};
+export declare function buildCreateSitelinkDryRun(args: CreateSitelinkArgs): CreateSitelinkDryRun;
+export interface ReplaceSitelinkArgs {
+    customer_id?: string;
+    old_asset_id: string;
+    new_final_urls: string[];
+    new_link_text?: string;
+    new_description1?: string;
+    new_description2?: string;
+    confirm?: boolean;
+}
+export interface ReplaceSitelinkDryRun {
+    dry_run: true;
+    message: string;
+    customer_id: string;
+    old_asset_id: string;
+    new_final_urls: string[];
+    new_link_text_override?: string;
+    warning: string;
+}
+export declare function normalizeReplaceSitelinkArgs(raw: Record<string, unknown> | undefined): ReplaceSitelinkArgs | {
+    error: string;
+};
+export declare function buildReplaceSitelinkDryRun(args: ReplaceSitelinkArgs): ReplaceSitelinkDryRun;
 export declare function buildPauseLinksDryRun(args: PauseAssetLinksArgs): PauseLinksDryRun;

package/dist/assetHelpers.js

@@ -99,6 +99,95 @@ function buildUpdateUrlsDryRun(args) {
     warning: "Updating an asset's final_urls affects EVERY campaign/ad group/customer link that uses this asset ID. Verify attachments before confirming."
   };
 }
+function validateSitelinkText(value, field, max) {
+  if (typeof value !== "string") return { ok: false, error: `${field} must be a string` };
+  const t = value.trim();
+  if (!t) return { ok: false, error: `${field} must be non-empty` };
+  if (t.length > max) return { ok: false, error: `${field} exceeds ${max} chars (got ${t.length})` };
+  return { ok: true, value: t };
+}
+function normalizeCreateSitelinkArgs(raw) {
+  const r = raw ?? {};
+  const customer_id = typeof r.customer_id === "string" ? r.customer_id : void 0;
+  const linkText = validateSitelinkText(r.link_text, "link_text", 25);
+  if (!linkText.ok) return { error: linkText.error };
+  const urls = validateFinalUrls(r.final_urls);
+  if (!urls.ok) return { error: urls.error };
+  const out = {
+    customer_id,
+    link_text: linkText.value,
+    final_urls: urls.urls,
+    confirm: r.confirm === true || r.confirm === "true"
+  };
+  if (r.description1 !== void 0 && r.description1 !== null && r.description1 !== "") {
+    const d = validateSitelinkText(r.description1, "description1", 35);
+    if (!d.ok) return { error: d.error };
+    out.description1 = d.value;
+  }
+  if (r.description2 !== void 0 && r.description2 !== null && r.description2 !== "") {
+    const d = validateSitelinkText(r.description2, "description2", 35);
+    if (!d.ok) return { error: d.error };
+    out.description2 = d.value;
+  }
+  if (out.description1 && !out.description2 || !out.description1 && out.description2) {
+    return { error: "description1 and description2 must both be set or both omitted" };
+  }
+  return out;
+}
+function buildCreateSitelinkDryRun(args) {
+  return {
+    dry_run: true,
+    message: "DRY RUN. Nothing created. Pass confirm: true to actually create the sitelink asset.",
+    customer_id: args.customer_id ?? "",
+    link_text: args.link_text,
+    final_urls: args.final_urls,
+    description1: args.description1,
+    description2: args.description2
+  };
+}
+function normalizeReplaceSitelinkArgs(raw) {
+  const r = raw ?? {};
+  const customer_id = typeof r.customer_id === "string" ? r.customer_id : void 0;
+  const assetIdRaw = typeof r.old_asset_id === "string" ? r.old_asset_id.trim() : typeof r.old_asset_id === "number" ? String(r.old_asset_id) : "";
+  if (!assetIdRaw || !/^\d+$/.test(assetIdRaw)) {
+    return { error: `invalid old_asset_id: ${JSON.stringify(r.old_asset_id)}. Expected numeric asset ID.` };
+  }
+  const urls = validateFinalUrls(r.new_final_urls);
+  if (!urls.ok) return { error: urls.error };
+  const out = {
+    customer_id,
+    old_asset_id: assetIdRaw,
+    new_final_urls: urls.urls,
+    confirm: r.confirm === true || r.confirm === "true"
+  };
+  if (r.new_link_text !== void 0 && r.new_link_text !== null && r.new_link_text !== "") {
+    const d = validateSitelinkText(r.new_link_text, "new_link_text", 25);
+    if (!d.ok) return { error: d.error };
+    out.new_link_text = d.value;
+  }
+  if (r.new_description1 !== void 0 && r.new_description1 !== null && r.new_description1 !== "") {
+    const d = validateSitelinkText(r.new_description1, "new_description1", 35);
+    if (!d.ok) return { error: d.error };
+    out.new_description1 = d.value;
+  }
+  if (r.new_description2 !== void 0 && r.new_description2 !== null && r.new_description2 !== "") {
+    const d = validateSitelinkText(r.new_description2, "new_description2", 35);
+    if (!d.ok) return { error: d.error };
+    out.new_description2 = d.value;
+  }
+  return out;
+}
+function buildReplaceSitelinkDryRun(args) {
+  return {
+    dry_run: true,
+    message: "DRY RUN. Nothing changed. Pass confirm: true to replace the sitelink.",
+    customer_id: args.customer_id ?? "",
+    old_asset_id: args.old_asset_id,
+    new_final_urls: args.new_final_urls,
+    new_link_text_override: args.new_link_text,
+    warning: "Will create a NEW sitelink asset, re-link every campaign/ad-group/customer link currently pointing at old_asset_id, then remove the old links. The old Asset itself is NOT deleted and can still be re-used manually."
+  };
+}
 function buildPauseLinksDryRun(args) {
   const would = {
     customer_asset: [],
@@ -119,9 +208,13 @@ function buildPauseLinksDryRun(args) {
   };
 }
 export {
+  buildCreateSitelinkDryRun,
   buildPauseLinksDryRun,
+  buildReplaceSitelinkDryRun,
   buildUpdateUrlsDryRun,
+  normalizeCreateSitelinkArgs,
   normalizePauseAssetLinksArgs,
+  normalizeReplaceSitelinkArgs,
   normalizeUpdateAssetUrlsArgs,
   parseAssetLinkResourceName,
   validateFinalUrls

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "baabc65",
-  "builtAt": "2026-04-18T17:46:42.713Z",
+  "sha": "77d847b",
+  "builtAt": "2026-04-18T18:38:13.085Z",
   "embeddedSecrets": true
 }

package/dist/index.js

@@ -28,7 +28,11 @@ import {
   normalizeUpdateAssetUrlsArgs,
   normalizePauseAssetLinksArgs,
   buildUpdateUrlsDryRun,
-  buildPauseLinksDryRun
+  buildPauseLinksDryRun,
+  normalizeCreateSitelinkArgs,
+  buildCreateSitelinkDryRun,
+  normalizeReplaceSitelinkArgs,
+  buildReplaceSitelinkDryRun
 } from "./assetHelpers.js";
 import {
   buildCampaignCreatePayload
@@ -1211,7 +1215,7 @@ class GoogleAdsManager {
       else if (/\/adGroupAssets\//.test(rn)) byLevel.ad_group_asset.push(rn);
       else throw new Error(`Unrecognized asset-link resource name: ${rn}`);
     }
-    const PAUSED = 2;
+    const PAUSED = enums.AssetLinkStatus.PAUSED;
     const result = { customer_id: cleanId, paused: { customer_asset: 0, campaign_asset: 0, ad_group_asset: 0 } };
     if (byLevel.customer_asset.length > 0) {
       const ops = byLevel.customer_asset.map((rn) => ({ resource_name: rn, status: PAUSED }));
@@ -1240,6 +1244,217 @@ class GoogleAdsManager {
     return result;
   }
   // ============================================
+  // SITELINK CREATE + REPLACE
+  // ============================================
+  async createSitelink(customerId, args) {
+    const customer = this.getCustomer(customerId);
+    const cleanId = customerId.replace(/-/g, "");
+    const sitelink = { link_text: args.link_text };
+    if (args.description1) sitelink.description1 = args.description1;
+    if (args.description2) sitelink.description2 = args.description2;
+    const result = await withResilience(
+      () => customer.assets.create([
+        {
+          type: enums.AssetType.SITELINK,
+          final_urls: args.final_urls,
+          sitelink_asset: sitelink
+        }
+      ]),
+      "createSitelink"
+    );
+    const results = result.results || [];
+    const resourceName = results[0]?.resource_name;
+    const assetId = resourceName ? resourceName.split("/").pop() : void 0;
+    if (resourceName) {
+      await this.autoLabelCreated(customerId, [resourceName], "asset");
+    }
+    return {
+      customer_id: cleanId,
+      asset_id: assetId,
+      resource_name: resourceName,
+      link_text: args.link_text,
+      final_urls: args.final_urls,
+      description1: args.description1,
+      description2: args.description2
+    };
+  }
+  async replaceSitelinkUrl(customerId, args) {
+    const customer = this.getCustomer(customerId);
+    const cleanId = customerId.replace(/-/g, "");
+    const oldAssetRows = await withResilience(
+      () => customer.query(`
+          SELECT
+            asset.id,
+            asset.type,
+            asset.final_urls,
+            asset.sitelink_asset.link_text,
+            asset.sitelink_asset.description1,
+            asset.sitelink_asset.description2
+          FROM asset
+          WHERE asset.id = ${args.old_asset_id}
+        `),
+      "replaceSitelinkUrl.queryAsset"
+    );
+    const oldAsset = oldAssetRows[0]?.asset;
+    if (!oldAsset) {
+      throw new Error(`Asset ${args.old_asset_id} not found in customer ${cleanId}`);
+    }
+    if (oldAsset.type !== enums.AssetType.SITELINK && oldAsset.type !== 13) {
+      throw new Error(
+        `Asset ${args.old_asset_id} is type ${oldAsset.type} (not SITELINK). This tool only replaces sitelink assets; use google_ads_update_asset_urls for other asset types.`
+      );
+    }
+    const link_text = args.new_link_text ?? oldAsset.sitelink_asset?.link_text;
+    if (!link_text) {
+      throw new Error(
+        `Old asset has no link_text and none was provided. Pass new_link_text to override.`
+      );
+    }
+    const description1 = args.new_description1 ?? oldAsset.sitelink_asset?.description1 ?? void 0;
+    const description2 = args.new_description2 ?? oldAsset.sitelink_asset?.description2 ?? void 0;
+    const campaignLinksRows = await withResilience(
+      () => customer.query(`
+          SELECT
+            campaign_asset.resource_name,
+            campaign_asset.campaign,
+            campaign_asset.field_type,
+            campaign_asset.status
+          FROM campaign_asset
+          WHERE campaign_asset.asset = 'customers/${cleanId}/assets/${args.old_asset_id}'
+            AND campaign_asset.field_type = 'SITELINK'
+            AND campaign_asset.status = 'ENABLED'
+        `),
+      "replaceSitelinkUrl.queryCampaignAssets"
+    );
+    const adGroupLinksRows = await withResilience(
+      () => customer.query(`
+          SELECT
+            ad_group_asset.resource_name,
+            ad_group_asset.ad_group,
+            ad_group_asset.field_type,
+            ad_group_asset.status
+          FROM ad_group_asset
+          WHERE ad_group_asset.asset = 'customers/${cleanId}/assets/${args.old_asset_id}'
+            AND ad_group_asset.field_type = 'SITELINK'
+            AND ad_group_asset.status = 'ENABLED'
+        `),
+      "replaceSitelinkUrl.queryAdGroupAssets"
+    );
+    const customerLinksRows = await withResilience(
+      () => customer.query(`
+          SELECT
+            customer_asset.resource_name,
+            customer_asset.field_type,
+            customer_asset.status
+          FROM customer_asset
+          WHERE customer_asset.asset = 'customers/${cleanId}/assets/${args.old_asset_id}'
+            AND customer_asset.field_type = 'SITELINK'
+            AND customer_asset.status = 'ENABLED'
+        `),
+      "replaceSitelinkUrl.queryCustomerAssets"
+    );
+    const campaignLinks = campaignLinksRows.map((r) => ({
+      resource_name: r.campaign_asset.resource_name,
+      campaign: r.campaign_asset.campaign
+    }));
+    const adGroupLinks = adGroupLinksRows.map((r) => ({
+      resource_name: r.ad_group_asset.resource_name,
+      ad_group: r.ad_group_asset.ad_group
+    }));
+    const customerLinks = customerLinksRows.map((r) => ({
+      resource_name: r.customer_asset.resource_name
+    }));
+    const newSitelink = { link_text };
+    if (description1) newSitelink.description1 = description1;
+    if (description2) newSitelink.description2 = description2;
+    const createResult = await withResilience(
+      () => customer.assets.create([
+        {
+          type: enums.AssetType.SITELINK,
+          final_urls: args.new_final_urls,
+          sitelink_asset: newSitelink
+        }
+      ]),
+      "replaceSitelinkUrl.createAsset"
+    );
+    const newAssetResource = createResult.results?.[0]?.resource_name;
+    if (!newAssetResource) {
+      throw new Error("Failed to create replacement sitelink asset (no resource_name in response)");
+    }
+    const newAssetId = newAssetResource.split("/").pop() || "";
+    await this.autoLabelCreated(customerId, [newAssetResource], "asset");
+    const SITELINK_FIELD_TYPE = enums.AssetFieldType.SITELINK;
+    if (campaignLinks.length > 0) {
+      await withResilience(
+        () => customer.campaignAssets.create(
+          campaignLinks.map((l) => ({
+            campaign: l.campaign,
+            asset: newAssetResource,
+            field_type: SITELINK_FIELD_TYPE
+          }))
+        ),
+        "replaceSitelinkUrl.createCampaignAssets"
+      );
+    }
+    if (adGroupLinks.length > 0) {
+      await withResilience(
+        () => customer.adGroupAssets.create(
+          adGroupLinks.map((l) => ({
+            ad_group: l.ad_group,
+            asset: newAssetResource,
+            field_type: SITELINK_FIELD_TYPE
+          }))
+        ),
+        "replaceSitelinkUrl.createAdGroupAssets"
+      );
+    }
+    if (customerLinks.length > 0) {
+      await withResilience(
+        () => customer.customerAssets.create(
+          customerLinks.map(() => ({
+            asset: newAssetResource,
+            field_type: SITELINK_FIELD_TYPE
+          }))
+        ),
+        "replaceSitelinkUrl.createCustomerAssets"
+      );
+    }
+    if (campaignLinks.length > 0) {
+      await withResilience(
+        () => customer.campaignAssets.remove(campaignLinks.map((l) => l.resource_name)),
+        "replaceSitelinkUrl.removeCampaignAssets"
+      );
+    }
+    if (adGroupLinks.length > 0) {
+      await withResilience(
+        () => customer.adGroupAssets.remove(adGroupLinks.map((l) => l.resource_name)),
+        "replaceSitelinkUrl.removeAdGroupAssets"
+      );
+    }
+    if (customerLinks.length > 0) {
+      await withResilience(
+        () => customer.customerAssets.remove(customerLinks.map((l) => l.resource_name)),
+        "replaceSitelinkUrl.removeCustomerAssets"
+      );
+    }
+    return {
+      customer_id: cleanId,
+      old_asset_id: args.old_asset_id,
+      new_asset_id: newAssetId,
+      new_asset_resource_name: newAssetResource,
+      link_text,
+      final_urls: args.new_final_urls,
+      description1,
+      description2,
+      relinked: {
+        campaign_assets: campaignLinks.length,
+        ad_group_assets: adGroupLinks.length,
+        customer_assets: customerLinks.length
+      },
+      note: "The old Asset is not deleted; only its ENABLED links were migrated. Paused/removed links on the old asset were left alone."
+    };
+  }
+  // ============================================
   // REPORTING METHODS
   // ============================================
   // Get keyword performance report
@@ -2444,6 +2659,41 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const result = await adsManager.updateAssetUrls(customerId, normalized.updates);
         return { content: [{ type: "text", text: JSON.stringify({ success: true, ...result }, null, 2) }] };
       }
+      case "google_ads_create_sitelink": {
+        const normalized = normalizeCreateSitelinkArgs(args);
+        if ("error" in normalized) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: normalized.error }, null, 2) }] };
+        }
+        if (!normalized.confirm) {
+          return { content: [{ type: "text", text: JSON.stringify(buildCreateSitelinkDryRun(normalized), null, 2) }] };
+        }
+        const customerId = normalized.customer_id || "";
+        const result = await adsManager.createSitelink(customerId, {
+          link_text: normalized.link_text,
+          final_urls: normalized.final_urls,
+          description1: normalized.description1,
+          description2: normalized.description2
+        });
+        return { content: [{ type: "text", text: JSON.stringify({ success: true, ...result }, null, 2) }] };
+      }
+      case "google_ads_replace_sitelink_url": {
+        const normalized = normalizeReplaceSitelinkArgs(args);
+        if ("error" in normalized) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: normalized.error }, null, 2) }] };
+        }
+        if (!normalized.confirm) {
+          return { content: [{ type: "text", text: JSON.stringify(buildReplaceSitelinkDryRun(normalized), null, 2) }] };
+        }
+        const customerId = normalized.customer_id || "";
+        const result = await adsManager.replaceSitelinkUrl(customerId, {
+          old_asset_id: normalized.old_asset_id,
+          new_final_urls: normalized.new_final_urls,
+          new_link_text: normalized.new_link_text,
+          new_description1: normalized.new_description1,
+          new_description2: normalized.new_description2
+        });
+        return { content: [{ type: "text", text: JSON.stringify({ success: true, ...result }, null, 2) }] };
+      }
       case "google_ads_pause_asset_links": {
         const normalized = normalizePauseAssetLinksArgs(args);
         if ("error" in normalized) {

package/dist/tools.js

@@ -748,6 +748,55 @@ const tools = [
       required: ["updates"]
     }
   },
+  {
+    name: "google_ads_create_sitelink",
+    description: "Create a new sitelink Asset (link_text + final_urls, optional two description lines). Sitelinks are shared across campaigns/ad groups -- use google_ads_replace_sitelink_url if the goal is to fix a broken URL on an existing sitelink (sitelink final_urls are immutable; the correct pattern is create new + re-link). DRY-RUN BY DEFAULT: omit `confirm` or pass `confirm: false` to preview.",
+    inputSchema: {
+      additionalProperties: false,
+      type: "object",
+      properties: {
+        customer_id: { type: "string" },
+        link_text: { type: "string", description: "Clickable sitelink label (max 25 chars)." },
+        final_urls: {
+          type: "array",
+          items: { type: "string" },
+          description: "Destination URLs. Must start with http:// or https://."
+        },
+        description1: { type: "string", description: "Optional description line 1 (max 35 chars). If set, description2 must also be set." },
+        description2: { type: "string", description: "Optional description line 2 (max 35 chars). If set, description1 must also be set." },
+        confirm: {
+          type: "boolean",
+          description: "Must be true to actually create. Omit or false for dry-run preview."
+        }
+      },
+      required: ["link_text", "final_urls"]
+    }
+  },
+  {
+    name: "google_ads_replace_sitelink_url",
+    description: "Fix a broken/outdated sitelink URL. Google Ads treats sitelink Asset.final_urls as immutable, so this creates a new sitelink asset with the corrected URL (preserving link_text + descriptions from the old one unless overridden), re-links every campaign / ad-group / customer-level attachment to the new asset, then removes the old links. The old Asset itself is NOT deleted. DRY-RUN BY DEFAULT.",
+    inputSchema: {
+      additionalProperties: false,
+      type: "object",
+      properties: {
+        customer_id: { type: "string" },
+        old_asset_id: { type: "string", description: "Numeric ID of the existing sitelink asset to replace." },
+        new_final_urls: {
+          type: "array",
+          items: { type: "string" },
+          description: "New destination URLs for the replacement sitelink. Must start with http:// or https://."
+        },
+        new_link_text: { type: "string", description: "Optional override for the sitelink click text (default: preserve from old asset). Max 25 chars." },
+        new_description1: { type: "string", description: "Optional override for description line 1 (default: preserve from old asset). Max 35 chars." },
+        new_description2: { type: "string", description: "Optional override for description line 2 (default: preserve from old asset). Max 35 chars." },
+        confirm: {
+          type: "boolean",
+          description: "Must be true to actually replace. Omit or false for dry-run preview."
+        }
+      },
+      required: ["old_asset_id", "new_final_urls"]
+    }
+  },
   {
     name: "google_ads_pause_asset_links",
     description: "Pause asset links (customer_asset, campaign_asset, or ad_group_asset). Use this to stop a sitelink from serving without deleting the underlying asset. DRY-RUN BY DEFAULT: omit `confirm` or pass `confirm: false` to get a preview. Resource name form: customers/{cid}/customerAssets/{assetId}~SITELINK, customers/{cid}/campaignAssets/{campId}~{assetId}~SITELINK, or customers/{cid}/adGroupAssets/{agId}~{assetId}~SITELINK.",

package/dist/writeGate.js

@@ -22,7 +22,9 @@ const WRITE_TOOLS = /* @__PURE__ */ new Set([
   "google_ads_update_campaign_tracking",
   "google_ads_update_campaign_budget",
   "google_ads_update_campaign_bidding",
-  "google_ads_update_asset_urls"
+  "google_ads_update_asset_urls",
+  "google_ads_create_sitelink",
+  "google_ads_replace_sitelink_url"
 ]);
 function isWriteTool(name) {
   return WRITE_TOOLS.has(name);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "mcp-google-ads",
   "mcpName": "io.github.mharnett/google-ads",
-  "version": "1.4.2",
-  "description": "MCP server for Google Ads API with MCC support, 41 tools for campaign management, reporting, and optimization. Read-only by default -- mutating tools require GOOGLE_ADS_MCP_WRITE=true. All creates/updates land PAUSED.",
+  "version": "1.4.4",
+  "description": "MCP server for Google Ads API with MCC support, 43 tools for campaign management, reporting, and optimization. Read-only by default -- mutating tools require GOOGLE_ADS_MCP_WRITE=true. All creates/updates land PAUSED.",
   "main": "dist/index.js",
   "bin": {
     "mcp-google-ads": "dist/index.js",