أضف Shager إلى Cursor عبر ‎.cursor/mcp.json: من ملاحظات الإصدار إلى مسودات لكل حسابات العميل

لربط Shager بـ Cursor، أنشئ الملف .cursor/mcp.json في مشروعك (أو ~/.cursor/mcp.json لكل المشاريع) وضع فيه إدخالًا باسم shager قيمة url فيه هي https://app.shager.ai/api/mcp، وتضبط headers فيه الترويسة Authorization على Bearer ${env:SHAGER_API_KEY}. يقرأ Cursor المتغير من بيئتك، ويتصل عبر HTTP، ويحصل الوكيل على أدوات Shager. لا خادم محلي ولا جسر.

يُعد Cursor مكانًا مثيرًا لإدارة التوزيع منه، لأن المادة الخام موجودة أصلًا في المستودع: سجلات التغييرات، والوثائق، وملاحظات الإصدار، ومسودات المدونة. يضبط هذا الدليل الاتصال كما ينبغي، ثم يستخدمه لهذه المهمة تحديدًا.

كيف يبدو إعداد MCP في Cursor لخادم بعيد؟

تعرض وثائق MCP في Cursor الخادم البعيد على شكل url مع كائن headers اختياري، وتوثّق استبدال المتغيرات بالصيغة ${env:NAME} في الحقلين url وheaders. وتذكر موقعين للملف: .cursor/mcp.json داخل المشروع للأدوات الخاصة به، و~/.cursor/mcp.json في مجلد المستخدم للأدوات المتاحة في كل مكان.

مع Shager:

{
  "mcpServers": {
    "shager": {
      "url": "https://app.shager.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SHAGER_API_KEY}"
      }
    }
  }
}

وفي ملف تعريف الصدفة:

export SHAGER_API_KEY="shgr_live_your_key_here"

يقرأ Cursor متغيرات البيئة من العملية التي شغّلته. على macOS، قد لا يرى التطبيق المفتوح من شريط Dock المتغيرات التي ضبطتها في ~/.zshrc. إذا فشل الخادم برمز 401 رغم صحة المفتاح، فأغلق Cursor وشغّله من الطرفية بالأمر cursor . لتتأكد من أن هذا هو السبب.

مرّر جانبيًا لرؤية المخطط كاملًا

ملف المشروع أم الملف العام؟

الموقع	يناسب	انتبه إلى
.cursor/mcp.json في المستودع	موقع تسويقي أو مستودع وثائق يجري فيه العمل على المحتوى	ارفعه إلى المستودع بصيغة ${env:...} فقط، ولا تكتب المفتاح نفسه أبدًا
~/.cursor/mcp.json	تريد Shager متاحًا في كل مساحة عمل	سيستطيع الوكيل في كل مشروع الوصول إلى مساحات عملك في Shager

بالنسبة إلى مطوّر في وكالة يدير مواقع عدة عملاء، يكون ملف المشروع غالبًا الخيار الأنسب. لا ينبغي أن يحتوي مستودع العميل A على وكيل يستطيع بسهولة أن يكتب مسودات في مساحة عمل العميل B. اجمع ملف المشروع مع مفتاح لا تضم مؤسسته إلا مساحات العمل المنطقية لهذا المستودع، أو على الأقل سمِّ مساحات العمل صراحة في تعليماتك.

من أين يأتي المفتاح؟

ينشئه شخص من الفريق في https://app.shager.ai/dashboard/agents ويختار النطاقات. للعمل داخل المحرر، فإن read مع write هو الخيار الافتراضي الصحيح: يستطيع الوكيل رفع الوسائط وإنشاء المسودات، لكن Shager يرفض الجدولة أو النشر دون النطاق publish. وإذا كنت تبني نموذجًا أوليًا وليس لديك حساب بعد، فيستطيع الوكيل إنشاء بيئة اختبار عبر التسجيل الذاتي؛ والوصفة منشورة في shager.ai/auth.md.

كيف تتحقق من أن Cursor يرى الأدوات؟

افتح إعدادات MCP في Cursor وابحث عن shager بحالة متصل مع قائمة أدواته: whoami وlist_workspaces وcreate_workspace وlist_channels وcreate_connect_link وlist_groups وcreate_group وupload_media_from_url وcreate_post وschedule_post وrequest_approval وget_post وlist_posts وcancel_post وget_analytics. إذا ظهر خطأ على الخادم، فالأسباب الثلاثة المعتادة هي متغير بيئة مفقود، أو غياب Bearer من قيمة الترويسة، أو خطأ في صياغة JSON داخل الملف.

ثم اكتب في دردشة الوكيل:

Call shager whoami and tell me which scopes this key has.

مرّر جانبيًا لرؤية المخطط كاملًا

مسار العمل: سجل التغييرات يصبح مسودات لكل حساب

هذه مهمة ملموسة تناسب Cursor جيدًا. لنفترض أنك تدير موقع موزّع برمجيات لديه اثنتا عشرة صفحة لشركاء إقليميين على Facebook وInstagram. مع كل إصدار، يعيد أحدهم كتابة سجل التغييرات يدويًا في صورة منشورات اجتماعية. بعد ربط Shager، يستطيع الوكيل إنجاز الجولة الأولى.

Read CHANGELOG.md and take the entry for v4.2 only.
In Shager workspace "Brightline Partners":
1. list_groups and use the group "Regional partners".
2. list_channels so you know each channel's name and network.
3. Write one short post about v4.2 for a non-technical audience.
4. Create a DRAFT with create_post (no schedule_at):
   group_ids: the "Regional partners" group
   per_channel: a caption per channel that names the region from the channel
   name and varies the opening line; keep facts identical
   cta_url: https://brightline.example/releases/4-2
   campaign: "release-4-2"
   first_comment: "Full notes: " followed by the link
5. Print the post id and a table of channel, caption first line, format.

بعض الاختيارات في هذه التعليمات مقصودة.

الحقائق تبقى متطابقة بينما تتنوع الصياغة. يستبدل per_channel النص لكل حساب، وهذا هو النمط الموصى به. اثنتا عشرة نسخة من النص نفسه على صفحات مترابطة هي نوع التكرار الذي يحذّر منه مقالنا عن تجنّب الحظر بسبب الرسائل المزعجة عند النشر على نطاق واسع، كما أنها تبدو سيئة لكل من يتابع صفحتين منها.

الرابط مُتتبَّع لكل حساب. تمرير cta_url يجعل Shager ينشئ رابطًا قصيرًا ومجموعة UTM منفصلين لكل حساب، مع utm_content لتمييزه. لاحقًا تُرجع get_analytics النقرات حسب الحساب وحسب المنشور، فيرى الشريك في كل منطقة ما الذي جلبته صفحته.

والناتج مسودة. لا يزال شخص ما يقرؤها في Shager قبل نشرها، سواء كان مراجعًا داخليًا أو العميل عبر رابط موافقة.

ماذا لو فضّلت استدعاء الواجهة البرمجية من الشيفرة؟

أحيانًا تريد ذلك سكربتًا في المستودع لا محادثة. مسار الإصدار في CI مثلًا يجب ألا يعتمد على أن يفتح أحدهم Cursor. العمليات نفسها متاحة عبر REST، وموصوفة في مستند OpenAPI. هذا ما يعادل الخطوة الرابعة أعلاه بلغة TypeScript:

const API = "https://app.shager.ai/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.SHAGER_API_KEY}`,
  "Content-Type": "application/json",
};

const res = await fetch(`${API}/workspaces/${workspaceId}/posts`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    caption: defaultCaption,
    group_ids: [groupId],
    per_channel: captions.map((c) => ({ channel_id: c.channelId, caption: c.text })),
    cta_url: "https://brightline.example/releases/4-2",
    campaign: "release-4-2",
    first_comment: "Full notes: https://brightline.example/releases/4-2",
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data.id, body.data.status); // a DRAFT post

تأتي الاستجابات داخل { "data": ... } والأخطاء داخل { "error": { "code", "message" } }، فتبقى معالجة الأخطاء واحدة في كل مكان. ويغطي دليل البدء السريع لـ REST التسلسل كاملًا.

قواعد تستحق الإضافة إلى المشروع

يدعم Cursor قواعد المشروع، وقاعدة قصيرة توفر عليك تكرار القيود في كل تعليمات. شيء من هذا القبيل:

When using the shager MCP server:
Never pass schedule_at unless I explicitly give a date and time.
Always use per_channel captions when posting to more than one account.
Always pass cta_url for any link instead of pasting raw URLs into captions.
Use ISO 8601 with an offset for any time, in the workspace timezone.

القواعد توجيه للنموذج، لا إلزام. الإلزام يأتي من نطاق المفتاح. أبقِ publish خارج مفتاح المحرر، ولن يمكن كسر القاعدة الأولى حتى لو تجاهلها النموذج.

الأسئلة الشائعة

هل يدعم Cursor الاتصال بـ Shager دون OAuth؟

نعم. يرسل Cursor أي ترويسات تضبطها، فيعمل مفتاح API من نوع bearer مباشرة. ويدعم خادم MCP في Shager تسجيل الدخول عبر OAuth أيضًا للعملاء الذين يفضّلونه، لكن المفتاح وحده يكفي في Cursor.

هل يمكنني استخدام المفتاح نفسه في Cursor وClaude Code؟

يمكنك، لكن المفاتيح المنفصلة أفضل. يُسجَّل كل استدعاء في سجل التدقيق في Shager باسم المفتاح الذي نفّذه، والمفاتيح المنفصلة تتيح لك إلغاء أداة واحدة دون أن تتعطل الأخرى. ولإعداد Claude Code دليله الخاص في هذه السلسلة.

هل سينشر الوكيل فورًا إذا قلت له «انشر هذا»؟

فقط إذا كان المفتاح يتضمن النطاق publish، وكان إنسان قد تولى ملكية الحساب، ولم تكن مساحة العمل تشترط موافقة العميل أولًا. مع مفتاح قراءة وكتابة، يفشل الطلب برمز 403 واضح ولا يُنشر شيء.

الخطوة التالية

بعد أن يعمل الاتصال، المكسب الأكبر هو إجراء قابل للتكرار لا تعليمات ذكية. اقرأ كيف تبني مهارة Claude لـ Shager لتتعرف إلى البنية، فالتعليمات نفسها تتحول بسهولة إلى قواعد في Cursor، وأبقِ صفحة الوكلاء مفتوحة كمرجع لكل أداة وحقل.