agent1st-ads-mcp

Instructions

Implementation Reference

• src/index.ts:372-392 (handler)

  Handler implementation for the check_setup tool, which verifies license tier and ad platform connectivity.

  case 'check_setup': {
      const tier = getLicenseTier();
      const tierLabels: Record<Tier, string> = {
          starter: 'Starter ($29/mo) — Meta OR TikTok',
          pro:     'Pro ($69/mo) — Meta + TikTok',
          premium: 'Premium ($149/mo) — Meta + TikTok + Advanced',
          elite:   'Elite ($399/mo) — Unlimited',
          none:    'No license — purchase at https://agent1st.io/ads/',
      };
      const result: CheckSetupResult = {
          license: { tier, description: tierLabels[tier], valid: tier !== 'none' },
          meta: cfg.hasMeta()
              ? { connected: true, account_id: cfg.metaAccount(), has_page: !!cfg.metaPage(), available: tier !== 'none' }
              : { connected: false, message: 'Set META_ADS_ACCESS_TOKEN, META_ADS_ACCOUNT_ID, META_PAGE_ID' },
          tiktok: cfg.hasTikTok()
              ? { connected: true, advertiser_id: cfg.tikTokAdvId(), available: tier !== 'none' && tier !== 'starter' }
              : { connected: false, message: 'Set TIKTOK_ADS_ACCESS_TOKEN, TIKTOK_ADVERTISER_ID' },
          ready: tier !== 'none' && (cfg.hasMeta() || cfg.hasTikTok()),
      };
      return ok(result);
  }

• src/index.ts:48-53 (schema)

  Definition of the result schema for the check_setup tool.

  interface CheckSetupResult {
      license: { tier: Tier; description: string; valid: boolean };
      meta: { connected: boolean; account_id?: string; has_page?: boolean; available?: boolean; message?: string };
      tiktok: { connected: boolean; advertiser_id?: string; available?: boolean; message?: string };
      ready: boolean;
  }

• src/index.ts:203-207 (registration)

  Tool registration for check_setup.

  {
      name: 'check_setup',
      description: 'ALWAYS call this first. Verifies license tier and which ad platforms are connected. Shows what is available based on your plan (Starter/Pro/Premium/Elite). Use this before any other tool.',
      inputSchema: { type: 'object', properties: {}, required: [] },
  },