agent1st-ads-mcp

Instructions

Implementation Reference

• src/index.ts:543-588 (handler)

  The handler implementation for the create_tiktok_campaign tool.

  case 'create_tiktok_campaign': {
      const denied = licenseCheck('tiktok');
      if (denied) return fail(denied);
      if (!cfg.hasTikTok()) return fail('TikTok credentials not set.');
      if (!args.name || !args.budget_usd || !args.destination_url || !args.ad_text)
          return fail('Required: name, budget_usd, destination_url, ad_text');
  
      // Validate budget
      const budgetError = validateTikTokBudget(args.budget_usd);
      if (budgetError) return fail(budgetError);
  
      // Validate URL
      const urlError = validateUrl(args.destination_url);
      if (urlError) return fail(urlError);
  
      const campaignRes = await tikTokPost('/campaign/create/', {
          advertiser_id: cfg.tikTokAdvId(), campaign_name: args.name,
          objective_type: args.objective || 'TRAFFIC',
          budget_mode: 'BUDGET_MODE_DAY', budget: args.budget_usd, operation_status: 'DISABLE',
      });
      const campaignId = campaignRes.data?.campaign_id;
  
      const today = new Date().toISOString().split('T')[0].replace(/-/g, '');
      const adGroupRes = await tikTokPost('/adgroup/create/', {
          advertiser_id: cfg.tikTokAdvId(), campaign_id: campaignId,
          adgroup_name: `${args.name} — Group`, placement_type: 'PLACEMENT_TYPE_AUTOMATIC',
          location_ids: [2840], age: (args.age_groups as string[]) || ['AGE_18_24', 'AGE_25_34'],
          budget_mode: 'BUDGET_MODE_DAY', budget: args.budget_usd,
          schedule_type: 'SCHEDULE_START_END', schedule_start_time: `${today} 00:00:00`,
          schedule_end_time: '20380101 00:00:00', optimization_goal: 'CLICK',
          billing_event: 'CPC', operation_status: 'DISABLE',
      });
  
      const adRes = await tikTokPost('/ad/create/', {
          advertiser_id: cfg.tikTokAdvId(), adgroup_id: adGroupRes.data?.adgroup_id,
          ad_name: `${args.name} — Ad`, ad_text: args.ad_text,
          landing_page_url: args.destination_url, call_to_action: 'LEARN_MORE', operation_status: 'DISABLE',
      });
  
      return ok({
          success: true, status: 'DISABLE',
          next_step: 'Call enable_tiktok_campaign with campaign_id to start running.',
          campaign_id: campaignId, adgroup_id: adGroupRes.data?.adgroup_id, ad_id: adRes.data?.ad_id,
          budget_usd: args.budget_usd,
      });
  }

• src/index.ts:305-320 (schema)

  Tool registration and schema definition for create_tiktok_campaign.

      name: 'create_tiktok_campaign',
      description: 'Create a complete TikTok ad campaign in one call — campaign + ad group with targeting + ad. Created in DISABLE state. Call enable_tiktok_campaign to activate. TikTok minimum budget is $20/day. Requires Pro plan or higher ($69/mo).',
      inputSchema: {
          type: 'object',
          properties: {
              name:                { type: 'string',  description: 'Campaign name.' },
              objective:           { type: 'string',  description: 'Objective: TRAFFIC, LEAD_GENERATION, WEBSITE_CONVERSIONS, ENGAGEMENT, APP_PROMOTION. Default: TRAFFIC.' },
              budget_usd:          { type: 'number',  description: 'Daily budget in USD. TikTok minimum: 20.' },
              destination_url:     { type: 'string',  description: 'Landing page URL (must include https://).' },
              ad_text:             { type: 'string',  description: 'Ad copy text. Keep it punchy — TikTok is a fast-scroll platform.' },
              targeting_countries: { type: 'array',   items: { type: 'string' }, description: 'Country codes. Example: ["US"]. Default: ["US"].' },
              age_groups:          { type: 'array',   items: { type: 'string' }, description: 'Age brackets: AGE_13_17, AGE_18_24, AGE_25_34, AGE_35_44, AGE_45_54, AGE_55_100. Default: [AGE_18_24, AGE_25_34].' },
          },
          required: ['name', 'budget_usd', 'destination_url', 'ad_text'],
      },
  },