رُوجع 2026-11-10 · إصدار API 2026-11-09 · قراءة Markdown
إعداد MCP
خادم MCP محلي عبر stdio يغلّف الخدمات المشتركة نفسها المستخدمة في واجهة المستخدم
وواجهة REST API عبر /api/v1. يرسل المحوّل مفتاح منتجك فقط إلى واجهة AiVideoEditor API المكوَّنة.
لا تُستخدم بيانات اعتماد Supabase أو المزودين.
المتطلبات المسبقة
هذا محوّل من شيفرة مصدرية، وليس حزمة منشورة أو اتصالًا مستضافًا.
احصل على وصول مصرَّح به إلى مستودع AiVideoEditor، وثبّت Node 22+، وشغّل
npm ci في جذر المستودع. أنشئ مفتاح منتج لمساحة العمل في
/app/developers بالنطاقات المطلوبة فقط وبوصول الوجهات المطلوب. مفتاح المسودات
فقط لا يستطيع النشر أو الجدولة. لا تلصق المفتاح أبدًا في مطالبة دردشة.
تشغيله
export PUBLISHER_API_URL=https://app.example.com # HTTPS; http://localhost is allowed for dev
export PUBLISHER_API_KEY=pk_v1_… # create in /app/developers
node packages/mcp/bin/publisher-mcp.mjs # or: npm start --workspace packages/mcp
الملف التنفيذي مشغّل حقيقي (TypeScript + استيراد بلا امتدادات تُحل
عبر tsx). كل التشخيصات تذهب إلى stderr؛ ويحمل stdout
حركة البروتوكول فقط. يجب أن يكون PUBLISHER_API_URL بصيغة HTTPS (HTTP عادي فقط لتطوير
loopback) ويجب ألا يحمل بيانات اعتماد أو استعلامات أو أجزاء تقطيع.
تكوين عميل عام
{
"mcpServers": {
"autoposted": {
"command": "node",
"args": ["/absolute/path/to/packages/mcp/bin/publisher-mcp.mjs"],
"env": {
"PUBLISHER_API_URL": "https://app.example.com",
"PUBLISHER_API_KEY": "pk_v1_…"
}
}
}
}
يتطلب المشغّل Node 22+ وتبعيات مساحة العمل (tsx
و@modelcontextprotocol/sdk). نقل MCP مستضاف مع OAuth عمل مستقبلي؛
لا تفترض أن كل عميل مكتبي أو مستضاف يدعم مفاتيح الحامل الملصوقة.
الأدوات
| الأداة | قراءة/تغيير | ملاحظات |
|---|---|---|
list_accounts | قراءة | تحترم قائمة سماح الحسابات للمفتاح |
get_capabilities | قراءة | التنسيقات والحدود ومتطلبات الموافقة |
create_upload_intent | تغيير | تعيد تعليمات تحميل مباشرة؛ بايتات الوسائط لا تمر عبر الأدوات أبدًا |
finalize_upload | تغيير | معرّف الجلسة (+ إيصالات أجزاء multipart)؛ يفحص الخادم البايتات/MIME بنفسه |
create_draft | تغيير | المصدر + متغيرات الوجهة |
validate_post | قراءة | مشكلات مهيكلة لكل وجهة |
schedule_post | تغيير | لحظة واحدة، ≤90 يومًا مقدمًا، يتطلب expectedVersion |
publish_post | تغيير | دلالات 202؛ ليست دليل نشر |
get_post_status | قراءة | حالات كل وجهة والروابط الأصلية |
list_posts | قراءة | ترقيم بالمؤشرات |
cancel_delivery | تغيير | فقط ما دام غير مطالب به بأمان |
retry_delivery | تغيير | فقط الإخفاقات المعروفة؛ لا تكرار أبدًا |
get_usage | قراءة | لا يوجد عدّاد منشورات متبقية |
وسيطات الأدوات المطلوبة
| الأداة | الوسيطات المطلوبة |
|---|---|
list_accounts | بلا |
get_capabilities | بلا |
create_upload_intent | filename، declaredMime، declaredBytes |
finalize_upload | assetId، sessionId |
create_draft | caption، destinations |
validate_post | postId |
schedule_post | postId، scheduledAt، timezone، expectedVersion |
publish_post | postId |
get_post_status | postId |
list_posts | بلا |
cancel_delivery | deliveryId |
retry_delivery | deliveryId |
get_usage | بلا |
تشمل الوسيطات الاختيارية ترقيم الصفحات على أدوات القوائم، وidempotencyKey على
عمليات التغيير، وmultipart.parts لإنهاء multipart، ووسائط المسودة
ومتغيرات الوجهة. مخطط الأدوات الزمني المُعاد من tools/list هو المرجع
للحقول الاختيارية والأشكال المتداخلة وحدود التحقق.
تقبل أدوات التغيير وسيطة idempotencyKey اختيارية. عند إغفالها،
يولّدها الخادم ويعيدها في كل نتيجة: بما في ذلك إخفاقات
النقل، حيث قد تكون العملية قد وصلت إلى واجهة البرمجة بالفعل (يحمل الخطأ
transport_outcome_unknown مع المفتاح). الأدوات لا تعيد المحاولة تلقائيًا أبدًا؛ أعد المحاولة
بمفتاح idempotency نفسه لتجنب إنشاء عملية مكررة.
مثال سير عمل وكيل آلي
list_accounts+get_capabilities→ اختر وجهات صالحة.create_upload_intent→ ارفع البايتات مباشرة →finalize_upload.create_draft→validate_post→ صحّح أو ألغِ تحديد الوجهات غير الصالحة.publish_post(أوschedule_post) → سجّل معرّفات التسليم.get_post_status(استقصاء محدود أو خطافات ويب للعملاء): تعامل مع استجاباتrequires_actionكتعليمات قابلة للتنفيذ، مثل موافقة TikTok.
العملاء المختبرون
- عميل TypeScript الرسمي
@modelcontextprotocol/sdkعبر subprocess stdio حقيقي مقابل الملف التنفيذي الموثق (initialize → tools/list → tools/call): اختُبر فيpackages/mcp/tests/stdio.test.ts، بما في ذلك فحوص stdout النظيف وفحوص فشل بدء التشغيل. - عميل SDK الرسمي عبر نقل في الذاكرة: مغطى أيضًا.
- العملاء المكتبيون (Claude Desktop وCursor وغيرهما): لم يُختبروا بعد: كوّنهم وفق المقتطف العام أعلاه وأبلغ عن النتائج قبل الادعاء بالدعم.
توافق العملاء
| العميل أو النقل | الحالة | الإعداد |
|---|---|---|
| SDK الرسمي لـ TypeScript عبر subprocess stdio | تغطية اختبار آلي | المشغّل الموضح أعلاه في المستودع |
| نقل SDK الرسمي في الذاكرة | تغطية اختبار آلي | منصة الاختبار فقط |
| Claude Desktop / عملاء مكتبية أخرى | لم يُتحقق منه يدويًا | عميل محلي يدعم stdio؛ استخدم مسار مشغّل مطلقًا |
| اتصال ChatGPT المستضاف | غير مقدم من هذا المحوّل | يتطلب نقلًا مستضافًا؛ JSON الخاص بـ stdio المحلي ليس موصلًا مستضافًا |
| MCP مستضاف مع OAuth | غير منفَّذ | عمل منتج منفصل |
استكشاف الأخطاء وإصلاحها
- لا يستطيع المشغّل حل التبعيات: شغّل
npm ciفي نسخة المصدر المصرَّح بها وتحقق من إصدار Node. لا تستبدل حزمة عامة غير ذات صلة. - العميل لا يبدأ أبدًا: استخدم مسار المشغّل المطلق وافحص stderr. لا تكتب مخرجات التصحيح إلى stdout.
401: تحقق من أن مفتاح المنتج المكوَّن حالي؛ أنشئ بديلًا في واجهة المستخدم إذا أُبطل.403: تحقق من النطاقات وقيود الحسابات.transport_outcome_unknown: احتفظ بمفتاح idempotency المُعاد وأعد المحاولة للعملية المطابقة بذلك المفتاح، وليس أبدًا مفتاحًا جديدًا.requires_action: سلّم التعليمات المقدَّمة لشخص مصرَّح له؛ لا يستطيع وكيل آلي توفير موافقة TikTok البشرية.
التعامل مع بيانات الاعتماد
يُرسل مفتاح المنتج فقط إلى واجهة AiVideoEditor API المكوَّنة
(Authorization: Bearer). لا يُرسل أبدًا إلى مزودي النماذج أو الشبكات
الاجتماعية، ولا يُسجَّل أبدًا، وتتحقق عناوين URL بحيث لا يمكن للمفتاح
اتباع إعادة توجيه أو الهروب من المنشأ المكوَّن.