مرجع أدوات MCP

عند النجاح، تُعيد كل أداة باستثناء get-screen-image نتيجتها مرتين: كـ structuredContent (يُتحقق منه مقابل مخطط المخرجات المنشور للأداة)، وككائن نفسه مُسلسَل في كتلة نصية، { type: "text", text: "<json-string>" }، وذلك للعملاء التي لا تقرأ المحتوى المنظّم. أما get-screen-image فتُعيد كتلة صورة MCP فقط: { type: "image", data: "<base64>", mimeType: "image/png" }. عند الفشل، تُضبط isError: true وتحتوي الكتلة النصية على رسالة خطأ قصيرة. تشرح الأخطاء التي يمكنك التصرف بناءً عليها، مثل عدم تطابق الاسم عند الحذف، أو رابط Figma غير صالح، أو إرشادات تصميم غير صالحة، أو مشكلة في مرفق، أو انتهاء مهلة التوليد، ما يجب إصلاحه. أما الإخفاقات الأخرى فتُعيد رسالة عامة مثل Failed to list files.

التسعير: تستخدم أدوات التصميم بالذكاء الاصطناعي الثلاث، وهي ai-design-screens وai-generate-screen-variant وai-edit-screen-variant، حصة الرسائل نفسها التي يستخدمها تطبيق Flowstep. جميع الأدوات الأخرى مجانية. راجع حدود الاستخدام.

تنشر كل أداة أيضًا تعليقات توضيحية (annotations) من MCP ليعرف عميلك ما تفعله. تُوسَم delete-file وdelete-screen وdelete-design-guidelines وreplace-screen-jsx وai-design-screens وai-edit-screen-variant بأنها مدمّرة، لأنها تحذف محتوى موجودًا أو تكتب فوقه.

أدوات الملفات

`list-files`

اعرض البيانات الوصفية لملفات Flowstep الخاصة بك. استدعِ هذه الأداة أولًا للتحقق مما إذا كان هناك ملف ذو صلة موجود. لا تُعيد الأداة أي محتوى للشاشات، واستخدم get-screen-image أو get-screen-jsx لذلك. المدخلات

المعامل	النوع	القيمة الافتراضية	الوصف
`orderByCreation`	`boolean`	`true`	الفرز من الأحدث أولًا حسب `created_at` (`true`) أو حسب `updated_at` (`false`). استخدم `false` للعثور على الملفات المُعدَّلة مؤخرًا
`limit`	`integer` (1–100)	`20`	أقصى عدد من الملفات المُعادة. قد تعني الصفحة الممتلئة وجود ملفات أخرى
`offset`	`integer` (≥0)	`0`	عدد الملفات التي تُتخطى. الصفحة التالية هي `offset + limit`

المخرجات — { files }.

{
  "files": [
    {
      "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
      "name": "Dashboard redesign",
      "created_at": "2026-04-30T15:02:13.120152+00:00",
      "updated_at": "2026-04-30T15:02:13.120152+00:00",
      "organisation_id": "0b7f3c9e-2d4a-4f1b-9a5e-6c8d7e1f2a3b",
      "shared_with_me": false,
      "owner": true,
      "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
    }
  ]
}

owner — true إذا كنت أنت من أنشأ الملف.
shared_with_me — true إذا شاركك أحد الملف مباشرةً، وليس فقط عبر مؤسستك.
url — يفتح الملف في محرر Flowstep.

`get-file`

اعرض البيانات الوصفية لملف واحد. يُستبعد محتوى الملف عمدًا: استخدم get-screen-image أو get-screen-jsx لفحص الشاشات، واستخدم get-design-guidelines لاسترجاع إرشادات التصميم المرفقة. إذا كانت لديك دعوة معلّقة للملف، فإن استدعاء get-file يقبلها. المدخلات

المعامل	النوع	الوصف
`id`	`uuid`	معرّف الملف

المخرجات — { file, user_access_level }.

{
  "file": {
    "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
    "name": "Dashboard redesign",
    "created_at": "2026-04-30T15:02:13.120152+00:00",
    "updated_at": "2026-04-30T15:02:13.120152+00:00",
    "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d",
    "access_level": "private",
    "visibility": "private",
    "owner": true,
    "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0"
  },
  "user_access_level": "write"
}

access_level — private أو read أو write.
visibility — private أو member أو public.
user_access_level — صلاحيتك على الملف: read أو write.

`create-file`

أنشئ ملف Flowstep فارغًا دون أي شاشات. لإنشاء ملف وتوليد شاشات في خطوة واحدة، استدعِ ai-design-screens دون fileId بدلًا من ذلك. استخدم create-file لسير العمل الذي يبدأ من الكود، متبوعًا بـ add-screen-jsx. المدخلات

المعامل	النوع	الوصف
`name`	`string` (min 1)	الاسم المعروض للملف الجديد

المخرجات — { file, user_access_level }، بالبنية نفسها الموجودة في get-file. قيمة owner دائمًا true، وقيمة user_access_level دائمًا write. استخدم file.id المُعاد كقيمة fileId في استدعاءات الأدوات اللاحقة.

`update-file`

أعِد تسمية ملف. المدخلات

المعامل	النوع	الوصف
`id`	`uuid`	معرّف الملف
`name`	`string` (min 1)	الاسم المعروض الجديد

المخرجات — { file, user_access_level }، بالبنية نفسها الموجودة في get-file.

`delete-file`

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

المعامل	النوع	الوصف
`id`	`uuid`	معرّف الملف
`name`	`string`	الاسم المعروض الحالي للملف، يجب أن يتطابق وإلا أُلغي الحذف

المخرجات — { "deleted": true }

لا يمكن التراجع عن هذا الإجراء. تُحذف جميع الشاشات في الملف.

أدوات الشاشات

`list-screens`

اعرض الشاشات في ملف، بحسب ترتيبها على اللوحة. استدعِ هذه الأداة بعد list-files لمعرفة ما يحتويه ملف. استخدم قيم screenId المُعادة مع أدوات الشاشات الأخرى وأدوات التصميم بالذكاء الاصطناعي. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف

المخرجات — { screens }.

{
  "screens": [
    {
      "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
      "name": "Mobile login screen",
      "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button",
      "fidelity": "ui"
    }
  ]
}

prompt — آخر موجّه توليد للشاشة، أو نص فارغ إن لم تُولَّد قط (مثلًا شاشة أُضيفت باستخدام add-screen-jsx).
fidelity — lofi أو hifi أو ui.

`get-screen-image`

صيّر شاشة إلى PNG وأعِدها كصورة مضمّنة. تتطلب هذه الأداة عميلًا يدعم كتل الصور. استدعِ الأداة مرة واحدة لكل screenId تُعيده أداة تصميم بالذكاء الاصطناعي، أو add-screen-jsx، أو replace-screen-jsx، أو import-figma. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف
`screenId`	`uuid`	`screenId` من `list-screens` أو من مصفوفة `screenIds` التي تُعيدها أداة تصميم

المخرجات — كتلة محتوى صورة MCP (image/png). قيمة data هي base64 قياسية لبايتات PNG، وليست URI للبيانات. لا يوجد structuredContent لهذه الأداة.

`get-screen-jsx`

احصل على شاشة كـ JSX، مع بياناتها الوصفية، لتبني منها في قاعدة الكود، أو لتعدّلها وتكتبها مرة أخرى باستخدام replace-screen-jsx. استخدم get-screen-image للمعاينة المرئية بدلًا من ذلك. المدخلات

المعامل	النوع	القيمة الافتراضية	الوصف
`fileId`	`uuid`	—	معرّف الملف
`screenId`	`uuid`	—	`screenId` من `list-screens` أو من مصفوفة `screenIds` التي تُعيدها أداة تصميم
`includeIds`	`boolean`	`false`	تضمين السمة `data-id` في العناصر ضمن `jsx`. استخدمها عندما تحتاج إلى معرّفات العناصر لتمريرها كـ `elementIds` إلى `ai-design-screens`، سواء للتعديل في مكانها أو كمرجع بصري

المخرجات — { fileId, screenId, name, prompt, fidelity, screenType, colorTheme, jsx, fragments }.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0",
  "name": "World clock",
  "prompt": "A world clock screen with a city search and alert button",
  "fidelity": "ui",
  "screenType": "iphone-x-vertical",
  "colorTheme": "blue",
  "jsx": "<div className=\"bg-white text-zinc-950 w-full h-fit\">\n  <div className=\"flex p-6 flex-col gap-6\">\n    …\n  </div>\n</div>",
  "fragments": []
}

jsx — علامات الترميز فقط. تُضمَّن سمات data-id فقط عندما تكون includeIds مساوية لـ true.
prompt — آخر موجّه توليد، أو نص فارغ إن لم تُولَّد الشاشة قط.
fragments — عناصر الواجهة المشتركة المخزّنة على الشاشة، مثل شريط التنقل أو الترويسة أو الشعار، ككائنات { purpose, markup }. تكون فارغة إن لم توجد. مرّرها إلى replace-screen-jsx للاحتفاظ بها أو تحديثها.

راجع قيم حقول الشاشة للاطلاع على قيم fidelity وscreenType وcolorTheme.

`add-screen-jsx`

أضف شاشة جديدة إلى ملف من JSX كتبته. هذا هو المسار الذي يبدأ من الكود، وهو مجاني. استخدم ai-design-screens عندما تريد أن يصمم الذكاء الاصطناعي في Flowstep الشاشة. تُنشئ add-screen-jsx دائمًا شاشة جديدة: لكتابة فوق شاشة موجودة، استخدم replace-screen-jsx. لعرض صورة رفعتها، راجع الصور في JSX. إذا كانت الشاشة الجديدة مبنية على شاشة موجودة، فابدأ من get-screen-jsx (دون includeIds) للحصول على name وfidelity وscreenType وcolorTheme وjsx، ثم غيّر ما يجب أن يختلف. المدخلات

المعامل	النوع	القيمة الافتراضية	الوصف
`fileId`	`uuid`	—	معرّف الملف
`name`	`string` (1–100 حرف)	—	اسم معروض اختياري. احذفه ليُسمّى الشاشة تلقائيًا `Screen N`
`fidelity`	`string`	`"ui"`	مستوى الدقة للشاشة
`screenType`	`string`	—	مطلوب: الجهاز أو منفذ العرض الذي صُممت له الشاشة
`colorTheme`	`string`	`"default"`	سمة الألوان
`jsx`	`string`	—	علامات JSX فقط. تُتجاهل أي سمات `data-id`، فتحصل الشاشة الجديدة على معرّفات عناصر جديدة

المخرجات — { fileId, screenId }. استدعِ get-screen-image مع screenId لعرض النتيجة.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf"
}

`replace-screen-jsx`

اكتب فوق شاشة موجودة بـ JSX كتبته. تحتفظ الشاشة بـ screenId وموقعها على اللوحة، وتحصل العناصر المتداخلة على معرّفات جديدة. هذا هو المسار الذي يبدأ من الكود، وهو مجاني. استخدم ai-design-screens أو ai-edit-screen-variant للتغييرات بالذكاء الاصطناعي، واستخدم add-screen-jsx لإنشاء شاشة جديدة بدلًا من ذلك. ابدأ من get-screen-jsx (دون includeIds)، ثم غيّر ما يجب أن يختلف. لعرض صورة رفعتها، راجع الصور في JSX. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف
`screenId`	`uuid`	الشاشة المراد الكتابة فوقها
`jsx`	`string`	علامات JSX فقط. تُتجاهل أي سمات `data-id`
`name`	`string` (1–100 حرف)	اختياري. احذفه للإبقاء على الاسم الحالي
`fidelity`	`string`	اختياري. احذفه للإبقاء على مستوى الدقة الحالي
`screenType`	`string`	اختياري. احذفه للإبقاء على نوع الشاشة الحالي
`colorTheme`	`string`	اختياري. احذفه للإبقاء على سمة الألوان الحالية
`fragments`	`{ purpose, markup }[]`	اختياري. عناصر الواجهة المشتركة من `get-screen-jsx`. احذفه للإبقاء على العناصر الحالية، أو مرّر `[]` لمسحها

المخرجات — { fileId, screenId }. استدعِ get-screen-image مع screenId لعرض النتيجة.

هذا يستبدل محتوى الشاشة في مكانه.

`rename-screen`

أعِد تسمية شاشة على اللوحة، أي الاسم الذي يظهر في list-screens وفي المحرر. يغيّر هذا التسمية فقط، ولا يغيّر تخطيط الشاشة أو حجمها أو محتواها، لذا استخدم ai-design-screens لذلك. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف
`screenId`	`uuid`	`screenId` المُعاد من `list-screens`
`name`	`string` (1–100 حرف)	اسم الشاشة الجديد. تُقصّ المسافات البيضاء في بدايته ونهايته

المخرجات — { screenId, name }.

{ "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Checkout — empty cart" }

`delete-screen`

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

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف
`screenId`	`uuid`	الشاشة المراد حذفها
`name`	`string`	الاسم المعروض الحالي للشاشة، يجب أن يتطابق وإلا أُلغي الحذف

المخرجات — { "deleted": true }

الصور في JSX

يقبل add-screen-jsx وreplace-screen-jsx صورًا في src لعنصر img، أو كخلفية في className باستخدام bg-[url(...)]. اكتب نص alt لكل صورة، واضبط حجمها بما يناسب غرضها. لإضافة صورة من عندك:

ارفعها باستخدام upload-attachment في الوضع A (mimeType + fileName)، ثم شغّل uploadCommand المُعاد.
إذا كانت قيمة type في الاستجابة "image"، فضع assetUrl كما أُعيد تمامًا في img src أو bg-[url(assetUrl)].

أبقِ أي عنوان صورة آخر كما أعاده get-screen-jsx تمامًا. لا تضع path أو signedUrl أو uploadCommand في src.

<img src="ASSET_URL" alt="Team photo" className="w-full h-48 object-cover rounded-lg" />

قيم حقول الشاشة

تُعيد get-screen-jsx، ويقبل add-screen-jsx وreplace-screen-jsx، هذه القيم:

الحقل	القيم
`fidelity`	`lofi`، `hifi`، `ui`
`screenType`	`web`، `desktop`، `desktop-large`، `desktop-medium`، `desktop-small`، `tablet`، `ipad-tablet-horizontal`، `ipad-tablet-vertical`، `android-tablet-horizontal`، `android-tablet-vertical`، `mobile_ios`، `mobile_android`، `iphone-vertical`، `iphone-horizontal`، `iphone-x-vertical`، `iphone-x-horizontal`، `android-vertical`، `android-horizontal`، `android-small-vertical`، `android-small-horizontal`
`colorTheme`	`default`، `defaultDark`، `blue`، `blueDark`، `ice`، `iceDark`، `grayscale`، `grayscaleDark`، `green`، `greenDark`، `orange`، `orangeDark`، `red`، `redDark`، `rose`، `roseDark`، `violet`، `violetDark`، `yellow`، `yellowDark`

أدوات إرشادات التصميم

إرشادات التصميم نصّ بصيغة DESIGN.md مخزّن على ملف. عند ضبطها، تُدرج في كل توليد بالذكاء الاصطناعي لذلك الملف. راجع إرشادات التصميم.

`get-design-guidelines`

احصل على إرشادات التصميم المرفقة بملف. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف

المخرجات — { guidelines }.

{
  "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter"
}

تكون قيمة guidelines هي null إذا لم تُضبط أي إرشادات.

`update-design-guidelines`

اضبط إرشادات التصميم لملف أو استبدلها. مرّر الإرشادات كنص عادي بصيغة DESIGN.md من Google، وليس ككائن أو JSON. إذا كنت تقرأ من ملف، فمرّر نص ذلك الملف. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف
`designGuidelines`	`string` (min 1)	النص الخام للإرشادات. يجب أن يكون نصًا عاديًا، وليس مُرمَّزًا بصيغة JSON

قواعد التحقق

يجب فتح الواجهة (frontmatter) وإغلاقها بشكل صحيح
يجب أن تكون أسطر الواجهة بصيغة YAML كتلية (block-style) صالحة
يجب ألا يحتوي النص الرئيسي بصيغة Markdown على عناوين ## مكررة

إذا فشل التحقق، يُعيد الاستدعاء خطأً يبدأ بـ Invalid design guidelines:. المخرجات — { updated, warnings? }.

{ "updated": true, "warnings": ["…"] }

يسرد warnings مشكلات التحقق غير الصارمة (مفاتيح غير معروفة، وألوان ليست بصيغة hex) التي قُبلت لكن قد يتجاهلها الذكاء الاصطناعي. تُحذف هذه القائمة عند عدم وجود مشكلات. اعرض هذه التحذيرات على المستخدم.

`delete-design-guidelines`

امسح إرشادات التصميم لملف. حذف إرشادات غير موجودة لا يُحدث أي أثر. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف

المخرجات — { "deleted": true }

أدوات المحادثة

`get-chat-history`

احصل على محادثة التصميم المرتبطة بملف، أي محادثة Flowstep الخاصة بالملف، وليس محادثة عميل MCP لديك. استخدمها لاستئناف العمل السابق على الملف. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	معرّف الملف

المخرجات — { messages }. تكون messages فارغة إذا لم تكن لديك محادثة تصميم على الملف. لكل رسالة type (وهو "request" أو "response")، وauthor (وهو "human" أو "ai")، وcontent_type. تستخدم رسائل الاستجابة القيم "text" أو "summary" أو "followup".

{
  "messages": [
    {
      "id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "type": "request",
      "status": "success",
      "content": "Generate a simple mobile login screen with email and password fields",
      "author": "human",
      "content_type": "text",
      "sequence": 1,
      "targets": [],
      "attachments": []
    },
    {
      "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf",
      "type": "response",
      "status": "success",
      "content": "Generated a mobile login screen with email and password input fields, a sign in button, and a sign up link.",
      "author": "ai",
      "content_type": "summary",
      "sequence": 7,
      "request_message_id": "453f593d-2380-425b-ba29-127db08d6a8e",
      "targets": [{ "target_id": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" }]
    }
  ]
}

أدوات المرفقات

`upload-attachment`

ارفع ملفًا مرجعيًا ليُستخدم كمرفق في ai-design-screens، أو صورة لوضعها في JSX الخاص بك باستخدام add-screen-jsx أو replace-screen-jsx. لا تقبل ai-generate-screen-variant وai-edit-screen-variant مرفقات. لا تمرّ بايتات الملفات عبر النموذج، ولا يجلب الخادم عناوين URL نيابةً عنك. للإشارة إلى صفحة ويب، ضمّن عنوانها URL في message الخاص بـ ai-design-screens بدلًا من ذلك. توجد طريقتان، استخدم واحدة فقط ولا تجمع بينهما. الوضع A: الملفات والصور (mimeType + fileName) تدفق إلزامي من ثلاث خطوات لأي صورة أو ملف PDF أو ملف نصي كبير:

استدعِ upload-attachment بالمعاملين mimeType وfileName فقط (مثلًا image/png وdog.png). الاستجابة هي رفع مُجهّز، وليست ملفًا مخزّنًا:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "image",
  "mimeType": "image/png",
  "signedUrl": "https://…",
  "uploadCommand": "curl -sS -f -X PUT '…' -H 'Content-Type: image/png' -H 'x-metadata: …' --data-binary @LOCAL_FILE_PATH",
  "nextStep": "…"
}

استبدل LOCAL_FILE_PATH في uploadCommand بالمسار المطلق لملفك، ثم نفّذ الأمر تمامًا في الصدفة لديك، ويجب أن ينتهي بالرمز 0. يصرّح الرمز المميز في signedUrl بهذا الرفع الواحد فقط. تخطّي هذه الخطوة يترك التخزين فارغًا، فتفشل أداة التصميم في فحص التحقق المسبق (preflight).
مرّر { id, path, type } فقط إلى مصفوفة attachments في ai-design-screens، لا signedUrl أو uploadCommand أو nextStep. لوضع صورة في JSX الخاص بك بدلًا من ذلك، ضع assetUrl في img src أو bg-[url(...)] في JSX الذي تمرره إلى add-screen-jsx أو replace-screen-jsx. راجع الصور في JSX.

لإرفاق ملف عن بُعد، نزّله إلى مسار محلي بنفسك أولًا (مثلًا باستخدام curl)، ثم اتبع الخطوات الثلاث نفسها. لا تمرر عنوان URL إلى upload-attachment أبدًا.

المعامل	النوع	الوصف
`mimeType`	enum	نوع MIME للملف. واحد من `image/jpeg` و`image/png` و`image/webp` و`application/pdf` و`text/markdown` و`text/plain` و`text/javascript`. استخدم `text/javascript` لملفات `.jsx` و`.tsx` و`.js` و`.ts`
`fileName`	`string` (min 1)	اسم الملف الأصلي مع امتداده، مثل `cat.png` أو `design.md`

الوضع B: نص قصير (text + mimeType) ارفع نصًا موجودًا بالفعل في السياق، دون الحاجة إلى أمر صدفة. الاستجابة جاهزة للاستخدام مباشرةً:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "assetUrl": "https://…",
  "type": "document",
  "mimeType": "text/plain"
}

المعامل	النوع	الوصف
`text`	`string` (بحد أقصى 64,000 حرف)	محتوى نصي خام. ملفات نصية فقط، لا تستخدمه للصور أو ملفات PDF. أطول من 64,000 حرف؟ استخدم الوضع A بدلًا من ذلك
`mimeType`	enum	واحد من `text/markdown` و`text/plain` و`text/javascript`

مرّر { id, path, type } الناتج إلى مصفوفة attachments في ai-design-screens. أقصى حجم للملف هو 3 MB في الوضعين، ويقتصر ملف PDF على 100 صفحة. المخرجات — { id, path, assetUrl, type, mimeType, signedUrl?, uploadCommand?, nextStep? }.

type — "image" للصور، و"document" لملفات PDF والملفات النصية.
assetUrl — عنوان URL للملف المرفوع، ويُعاد في الوضعين. استخدمه في JSX مع add-screen-jsx أو replace-screen-jsx فقط عندما تكون قيمة type هي "image"، وبعد تشغيل uploadCommand في الوضع A.
signedUrl وuploadCommand وnextStep — تُضبط في الوضع A فقط. لا تمررها إلى أدوات التصميم.

أدوات Figma

`import-figma`

استورد إطار Figma إلى ملف Flowstep كعناصر قابلة للتحرير على لوحته. كل استيراد يضيف شاشة جديدة، فاستيراد الإطار نفسه مرتين يعطيك شاشتين، لذا احذف القديمة باستخدام delete-screen إذا كنت تقصد استبدالها. يجب أن تكون مؤسسة الملف متصلة بـ Figma في إعدادات Flowstep. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	ملف Flowstep الذي يُستورد إليه الإطار. هذا ليس مفتاح ملف Figma في `figmaUrl`
`figmaUrl`	`string`	رابط إلى إطار Figma محدد يحتوي على `node-id`. في Figma، انقر بزر الفأرة الأيمن على الإطار واختر Copy/Paste as → Copy link to selection. يؤدي رابط الصفحة إلى استيراد جميع الإطارات ذات المستوى الأعلى في تلك الصفحة (بحد أقصى 20 إطارًا عبر MCP)

المخرجات — { fileId, screenId, frameCount? }. screenId هو الشاشة المستوردة، مرّرها إلى get-screen-image لعرض النتيجة. عندما يستورد رابط الصفحة عدة إطارات، تكون قيمة screenId هي null ويُعاد frameCount بدلًا منها. استدعِ list-screens ثم get-screen-image لكل شاشة جديدة.

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe"
}

أدوات الخطة والفوترة

`get-plan-details`

احصل على خطة مؤسستك في Flowstep، وحالة اشتراكها، واستخدامها، والحصة المتبقية. لا تأخذ هذه الأداة أي مدخلات، إذ تُحدَّد المؤسسة من المستخدم المسجّل الدخول. استخدمها للتحقق من حصتك قبل استدعاء أدوات التصميم بالذكاء الاصطناعي. المخرجات — { plan, subscription, limits, usage, remaining }.

الحقل	الوصف
`plan`	`{ name, code, type }`. قيمة `type` هي `"free"` أو `"paid"`
`subscription`	`{ isPaid, isTrial, startDate, endDate, trialDaysRemaining }`
`limits`	حدود كل ميزة، مفهرسة حسب الميزة (مثلًا `messages`). لكل ميزة كائنات اختيارية `daily` و`monthly` تحتوي على القيمتين `max` و`warn`، بالإضافة إلى علامة `unlimited`
`usage`	استخدام كل ميزة حتى الآن، ككائن `{ daily, monthly }`
`remaining`	الحصة المتبقية لكل ميزة، ككائن `{ daily, monthly }`. تُحذف للميزات غير المحدودة

تختلف الحدود حسب الخطة، راجع الأسعار وحدود الاستخدام.

أدوات التصميم بالذكاء الاصطناعي

تصمّم هذه الأدوات الثلاث من وصف أو إعداد جاهز، ولا تستقبل JSX ولا تعيد استخدامه أبدًا. يستهلك كل استدعاء من حصة الرسائل نفسها التي يستخدمها تطبيق Flowstep، وينتظر حتى يكتمل التوليد أو تنتهي مهلته (180 ثانية).

الأداة	استخدمها لـ
`ai-design-screens`	توليد شاشات جديدة، أو تغيير شاشات موجودة في مكانها، أو كليهما، من وصف حر
`ai-generate-screen-variant`	إضافة الخطوة التالية، أو حالة خطأ أو حالة فارغة، أو نسخة لمنصة أخرى لشاشة موجودة واحدة
`ai-edit-screen-variant`	تطبيق إعداد تعديل أو إعادة تصميم جاهز على شاشة موجودة كاملة

تُعيد الأدوات الثلاث { status, fileId, screenIds, designGuidelinesUpdated }. استدعِ get-screen-image مرة واحدة لكل screenId لعرض النتيجة.

designGuidelinesUpdated — ملخص قصير للتغيير عندما تُحدَّث إرشادات DESIGN.md للملف تلقائيًا خلال هذا الدور؛ وإلا فقيمته null.

`ai-design-screens`

وَلِّد شاشة أو أكثر جديدة، أو غيّر شاشات موجودة في مكانها، أو افعل الأمرين في استدعاء واحد، انطلاقًا من وصف نصي: تدفقات جديدة، وتطبيق السمات، والنصوص، والتخطيط، أو تغييرات منسقة عبر عدة شاشات. هذا هو وكيل التصميم نفسه الموجود في المحادثة داخل محرر Flowstep: يقرر من message وelementIds ما يجب بناؤه وما يجب تغييره. احذف fileId لبدء ملف جديد، ومرّر fileId للعمل في ملف موجود. إذا كان الطلب قد ينطبق على ملف موجود لديك، فيجب على وكيلك التحقق من list-files وlist-screens أولًا. للخطوة التالية، أو حالة خطأ أو حالة فارغة، أو نسخة منصة لشاشة واحدة، استخدم ai-generate-screen-variant. لتعديل جاهز أو إعادة تصميم شاشة واحدة، استخدم ai-edit-screen-variant. إذا كان لديك JSX بالفعل، فاستخدم add-screen-jsx أو replace-screen-jsx بدلًا من ذلك. المدخلات

المعامل	النوع	القيمة الافتراضية	الوصف
`fileId`	`uuid`	—	الملف المستهدف. احذفه لإنشاء ملف جديد. مطلوب عند تعيين `elementIds`
`message`	`string`	—	وصف الشاشات المراد توليدها و/أو التغييرات المطلوبة. عند تمرير `elementIds`، وضّح ما إذا كنت تريد تعديلها أو استخدامها كمرجع. ضمّن هنا أي عناوين URL لصفحات ويب تريد أن تُشير إليها Flowstep
`elementIds`	`uuid[]`	`[]`	اختياري. `screenId` من `list-screens` و/أو `data-id` للعناصر من `get-screen-jsx` (مع `includeIds`)، مثل تحديد في المحرر. يمكن تعديلها في مكانها، أو استخدامها كمرجع بصري للشاشات الجديدة. يستهدف `screenId` الشاشة كاملة
`attachments`	`{ id, path, type }[]` (بحد أقصى 5)	`[]`	الملفات من `upload-attachment`: صور أو ملفات PDF أو ملفات كود ونص. لا تضمّن محتويات الملفات داخل الرسالة

مثال: عدّل شاشة واحدة وأضف أخرى في استدعاء واحد:

{
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "message": "Switch this sign-in screen to dark mode, then add a matching forgot-password screen.",
  "elementIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}

المخرجات — { status, fileId, screenIds, designGuidelinesUpdated, reply? }.

{
  "status": "generated",
  "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0",
  "screenIds": [
    "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0"
  ],
  "designGuidelinesUpdated": null
}

status — "generated" عندما بُنيت شاشات أو تغيّرت. و"chat" عندما ردّت Flowstep دون بناء، وفي هذه الحالة يحتوي reply على إجابتها وتكون screenIds فارغة. إذا كان طلبك غامضًا، فيجب على وكيلك أن يطلب منك التوضيح ثم يستدعي الأداة مرة أخرى.
screenIds — كل شاشة بُنيت أو تغيّرت أثناء الاستدعاء، بما في ذلك الشاشات المعدّلة في مكانها. إذا انتهت المهلة بعد بناء بعض الشاشات، فإنه يُعيد تلك الشاشات بدلًا من خطأ.

تُكتب الشاشات التي تطلب تعديلها فوق محتواها في مكانها.

`ai-generate-screen-variant`

أضف شاشة جديدة مشتقة من شاشة موجودة واحدة بالضبط: الخطوة التالية في التدفق، أو حالة خطأ أو فارغة، أو نسخة لمنصة أخرى. تبقى الشاشة الأصلية دون تغيير. لإضافة شاشة ليست نسخة من شاشة موجودة (مثل شاشة الإعدادات)، استخدم ai-design-screens مع fileId. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	الملف المستهدف
`screenId`	`uuid`	الشاشة الموجودة المراد الاشتقاق منها
`operationVariant`	enum	مطلوب: كيف ترتبط الشاشة الجديدة بالشاشة الموجودة

`operationVariant`	تضيف
`next_screen`	الشاشة التالية في تدفق المستخدم
`error_state`	حالة خطأ للشاشة
`empty_state`	حالة فارغة للشاشة
`web_version`	نسخة للويب
`mobile_version`	نسخة للجوال
`tablet_version`	نسخة للتابلت
`mobile_ios_version`	نسخة لنظام iOS
`mobile_android_version`	نسخة لنظام Android

المخرجات — { status, fileId, screenIds, designGuidelinesUpdated }. قيمة status دائمًا "generated".

`ai-edit-screen-variant`

غيّر شاشة موجودة واحدة بالضبط في مكانها باستخدام إعداد جاهز: طبّق عليها سمة أو حسّنها، أو جرّب تخطيطًا أو أسلوبًا بصريًا مختلفًا، أو أعد تصميمها من الصفر. للشاشات الجديدة، أو التعليمات الحرة، أو التعديل الدقيق لعناصر فردية، استخدم ai-design-screens. المدخلات

المعامل	النوع	الوصف
`fileId`	`uuid`	الملف المستهدف
`screenId`	`uuid`	الشاشة الموجودة المراد تغييرها
`operationVariant`	enum	مطلوب: إعداد التعديل أو إعادة التصميم المراد تطبيقه

`operationVariant`	النوع	التأثير
`dark_theme`	تعديل	تحويل الشاشة إلى سمة داكنة
`light_theme`	تعديل	تحويل الشاشة إلى سمة فاتحة
`make_pretty`	تعديل	تحسين التصميم البصري للشاشة
`different_layout`	إعادة تصميم	تجربة تخطيط مختلف
`different_style`	إعادة تصميم	تجربة أسلوب بصري مختلف
`from_scratch`	إعادة تصميم	إعادة تصميم الشاشة من الصفر

المخرجات — { status, fileId, screenIds, designGuidelinesUpdated }. قيمة status دائمًا "generated".

هذا يستبدل محتوى الشاشة في مكانه.

الأدوات المُعاد تسميتها

تغيّرت أسماء الأدوات في سبتمبر وأكتوبر 2026. إذا كانت لديك موجّهات أو سكربتات أو تعليمات لوكيل تستخدم الأسماء القديمة، فحدّثها:

الاسم القديم	الاسم الجديد
`get-screen`	`get-screen-jsx`
`add-screen`	`add-screen-jsx`
`replace-screen`	`replace-screen-jsx`
`ai-generate-screens`	`ai-design-screens`
`ai-edit-screens`	`ai-design-screens`
`create-new-design`	`ai-design-screens`
`edit-design` (تعليمات حرة)	`ai-design-screens`
`edit-design` (مع إعداد `operationVariant` جاهز)	`ai-edit-screen-variant`
`regenerate-design`	`ai-edit-screen-variant`
`expand-design`	`ai-generate-screen-variant`

تغيّرت المدخلات أيضًا: تأخذ أدوات التصميم بالذكاء الاصطناعي elementIds (أو screenId واحدًا لأدوات النسخ المتغيرة) بدلًا من targets، ويأخذ add-screen-jsx القيمة jsx وحقول بيانات وصفية صريحة بدلًا من jsxContent مع تعليق بيانات وصفية، ويأخذ create-file القيمة name بدلًا من title، وتأخذ أدوات إرشادات التصميم القيمة fileId بدلًا من resourceId وlinkedTo.

​أدوات الملفات

​list-files

​get-file

​create-file

​update-file

​delete-file

​أدوات الشاشات

​list-screens

​get-screen-image

​get-screen-jsx

​add-screen-jsx

​replace-screen-jsx

​rename-screen

​delete-screen

​الصور في JSX

​قيم حقول الشاشة

​أدوات إرشادات التصميم

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​أدوات المحادثة

​get-chat-history

​أدوات المرفقات

​upload-attachment

​أدوات Figma

​import-figma

​أدوات الخطة والفوترة

​get-plan-details

​أدوات التصميم بالذكاء الاصطناعي

​ai-design-screens

​ai-generate-screen-variant

​ai-edit-screen-variant

​الأدوات المُعاد تسميتها

أدوات الملفات

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

أدوات الشاشات

`list-screens`

`get-screen-image`

`get-screen-jsx`

`add-screen-jsx`

`replace-screen-jsx`

`rename-screen`

`delete-screen`

الصور في JSX

قيم حقول الشاشة

أدوات إرشادات التصميم

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

أدوات المحادثة

`get-chat-history`

أدوات المرفقات

`upload-attachment`

أدوات Figma

`import-figma`

أدوات الخطة والفوترة

`get-plan-details`

أدوات التصميم بالذكاء الاصطناعي

`ai-design-screens`

`ai-generate-screen-variant`

`ai-edit-screen-variant`

الأدوات المُعاد تسميتها