ربطت كلود بحساب باعلانات فيسبوك .. لقيت كارثة | كلود سنيور ميديا باير

أول ما ربطت كلود بحساب الإعلانات.. اتفاجأت

مش بالطريقة اللي كنت بتوقعها.

اتصورت إن كلود هيشوف الكامبينات ويقولي “صح” أو “غلط”. بس اللي حصل كان مختلف تمامًا — كلود كان بيشوف كل حاجة، ويفهمها بطريقة ميديا باير سنيور فعلاً.

---

إيه اللي حصل بالضبط؟

بنيت MCP Server كامل بـ Next.js على Vercel — ربطته بـ Meta Graph API مباشرة بدون أي SDK. الفكرة إنك تقدر تتكلم مع كلود بالعربي، وكلود يترجم كلامك لـ API calls على حساب إعلاناتك مباشرة.

النتيجة؟ كلود قدر يـ:

• يشوف كل الكامبينات والأد سيتس والأدز بالتفصيل
• يجيب الـ ROAS والـ CPP لكل كامبين
• يوقف ويشغل إعلانات بأمر واحد في المحادثة
• ينشئ كامبينات جديدة كاملة (بـ PAUSED تلقائياً للأمان)
• يعمل Custom Audiences ويضيف عليها يوزرز
• يعمل Lookalike Audiences من جمهور موجود
• وياخد قرارات زي ما بياخدها ميديا باير بـ 5 سنين خبرة

---

الكارثة الحقيقية؟

مش إن كلود عمل حاجة غلط.

الكارثة إني لقيت مشاكل في أكاونتي أنا ما كنتش شايفها! كلود طلع الـ error codes وشرحلي ليه كامبين معين مش بيشتغل صح — وكشف إن فيه conversion event مش متأكد في Events Manager. ده كان بيكلفني فلوس من غير ما أحس.

لو كنت بشتغل على Ads Manager العادي، كنت هشوف الرقم بس. كلود شالي الستار عن السبب الحقيقي.

---

السيستم اللي بنيته: 22 أداة في محادثة واحدة

من غير ما تفتح Ads Manager خالص، تقدر تتحكم في كل حاجة:

📊 تقرأ وتحلل

• قائمة كل الأكاونتات مع aliases مخصصة
• تفاصيل الرصيد والإنفاق والـ spend cap
• الكامبينات والأد سيتس والأدز بكل تفاصيلها
• الكريتيف بتاع كل إعلان (صورة، نص، CTA، لينك)
• أداء تفصيلي مع ROAS وتكلفة الشراء الحقيقية

⚙️ تتحكم وتعدّل

• تشغيل وإيقاف كامبينات وأد سيتس وأدز فردية
• تعديل الميزانية اليومية أو مدى الحياة فوراً
• تغيير الكريتيف على إعلان موجود بـ creative swap

🚀 تنشئ من الصفر

• كامبينات بأهداف مختلفة (Conversions, Traffic, Awareness)
• أد سيتس باستهداف كامل مع Advantage+ Audience
• كريتيف لـ Facebook وInstagram
• أدز مربوطة بالكريتيف والأد سيت

👥 إدارة الجمهور

• Custom Audiences من قوائم العملاء
• رفع يوزرز مع PII hashing تلقائي (SHA256)
• Lookalike Audiences من جمهور موجود
• فلترة وعرض كل الـ Audiences بالتفصيل

---

السيكريت اللي اتعلمته من التجربة

Meta بترجع Error User Message وError User Title في الـ API errors — معظم الناس بتتجاهلهم وبتتعامل مع الـ error message الاساسي بس. ده اللي كان بيخلي debugging يتطلب ساعات بقى يتطلب ثواني.

كمان اكتشفت إن Meta من 2025 بقت بتطلب advantage_audience إلزامي على كل أد سيت جديد — بدونه بتاخد error غامض مش واضح سببه.

---

برومبت إنشاء السيستم

ده هو البرومبت الكامل اللي استخدمته مع كلود عشان يبني السيستم ده من الصفر:

أنت Claude بتبني MCP server لـ Meta Marketing API (Facebook + Instagram Ads)
يخدم Claude.ai كـ custom connector. الهدف: المستخدم يقدر ينشئ، يعدّل، ويحلل
كامبينات Meta من محادثة Claude مباشرة.

# Stack المطلوب

- Next.js 14 + TypeScript على Vercel
- Supabase للـ audit log + account aliases
- URL-token auth: `/api/mcp/[token]` (Claude custom connector ما بيدعمش
  Bearer header، فالـ token بيكون في الـ URL path كـ secret)
- Direct fetch للـ Meta Graph API بدون SDK

# الـ Credentials اللي عند المستخدم دلوقتي

- Supabase project موجود (هيدّيك ref)
- GitHub account
- Vercel account
- Meta Access Token: مش جاهز لسه — هيجيبه في النهاية. ابني الكود كله
  بحيث يقرأ META_ACCESS_TOKEN من env، وفي النهاية اعطي المستخدم checklist
  لإزاي يجيب الـ token.

# هيكل المشروع

n8nar-meta-ads-mcp/
├── package.json (Next.js 14.2.15, @supabase/supabase-js)
├── next.config.js (typescript.ignoreBuildErrors=true, eslint.ignoreDuringBuilds=true)
├── tsconfig.json
├── .env.example
├── .gitignore
├── README.md (بالعربي — خطوات الـ deploy)
├── app/
│   ├── layout.tsx
│   ├── page.tsx (status page: env health check + tools list)
│   └── api/mcp/[token]/route.ts (URL-token auth + JSON-RPC)
├── lib/
│   ├── meta-ads.ts (Graph API client + MetaApiError + pagination + PII hashing)
│   ├── supabase.ts (createClient + resolveAlias + logToolCall)
│   └── mcp/
│       ├── tools.ts (registry — definitions + handlers map)
│       ├── rpc-handler.ts (JSON-RPC 2.0 dispatcher)
│       └── handlers/ (handler per tool)
└── supabase/migrations/001_initial.sql

# Supabase Schema

create table public.meta_account_aliases (
  id uuid primary key default gen_random_uuid(),
  ad_account_id text not null unique,
  alias text not null,
  notes text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table public.meta_tool_calls (
  id uuid primary key default gen_random_uuid(),
  tool_name text not null,
  arguments jsonb,
  result jsonb,
  error text,
  duration_ms integer,
  ad_account_id text,
  created_at timestamptz default now()
);

alter table public.meta_account_aliases enable row level security;
alter table public.meta_tool_calls enable row level security;

# Env Variables

MCP_BEARER_TOKEN=         # عشوائي 48+ حرف (للـ URL token auth)
META_ACCESS_TOKEN=        # System User token من Business Manager
META_API_VERSION=v22.0
NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=

# الـ Tools المطلوبة (22 tool)

## Read (9)
1. list_ad_accounts
2. get_account_details
3. list_campaigns
4. list_adsets
5. list_ads
6. get_ad_creative
7. list_pages
8. list_instagram_accounts
9. get_campaign_insights

## Write - Status & Budget (4)
10. set_campaign_status
11. set_adset_status
12. set_ad_status
13. update_budget

## Write - Creation (4)
14. create_campaign
15. create_adset
16. create_ad_creative
17. create_ad
18. update_ad_creative

## Audiences (4)
19. list_audiences
20. create_custom_audience
21. add_users_to_audience
22. create_lookalike_audience

# Safety Patterns (إلزامية)

1. كل entity جديد بيتعمل بـ status = PAUSED بغض النظر عن المُدخل.
2. Error extraction: استخرج error_user_title و error_user_msg دايماً.
3. Audit logging: كل tool call يتسجل في meta_tool_calls مع duration_ms.

# الـ URL-Token Route

export const runtime = 'nodejs';
export const maxDuration = 60;

function tokenOk(token: string): boolean {
  const expected = process.env.MCP_BEARER_TOKEN;
  if (!expected || token.length !== expected.length) return false;
  let diff = 0;
  for (let i = 0; i < token.length; i++) {
    diff |= token.charCodeAt(i) ^ expected.charCodeAt(i);
  }
  return diff === 0;
}

# Lessons من تجارب فعلية

1. Meta v23 شالت campaign.start_date و campaign.end_date من الـ API.
2. advantage_audience أصبح إلزامي 2025 على كل أد سيت جديد.
3. Events Manager confirmation مطلوب للـ conversion campaigns.
4. Domain verification مطلوب لكل sales campaign من Feb 2022.
5. Claude بيـ cache الـ tools list — بعد كل deploy جديد افعل disconnect + reconnect.

ابدأ بسؤال المستخدم: "إيه الـ Supabase project ref بتاعك؟ وعايز اسم الـ GitHub repo يكون إيه؟"

---

🎓 عايز تبني نفس السيستم ده؟

الـ AI Bundle بيشمل كل اللي محتاجه:

• 🤖 كورس n8n Automation — ابني أتمتة احترافية بدون كود
• 💻 كورس Vibe Coding — ابني أدوات وسيستمات بالـ AI زي ده
• 🎬 كورس AI Video Production — اعمل محتوى احترافي بالـ AI

3 كورسات بسعر 1 — وبيتحدثوا باستمرار بكل جديد.

---

📧 اشترك في النشرة الإخبارية

كل أسبوع: أدوات، برومبتات، وأسرار من تجاربنا الفعلية — مباشرة على إيميلك.