‏نمونه‌های Apps SDK؛ اپ ساختن برای ChatGPT

به گفتهٔ اوپن‌ای‌آی، این مخزن یه نقطهٔ شروع برای ساختن اپ داخل ChatGPT ـه. پایه‌ش MCP یا همون Model Context Protocol ـه، یعنی یه استاندارد باز برای وصل‌کردن مدل‌های زبانی به ابزار، داده و رابط کاربری بیرونی. سرور MCP ابزارهاش رو معرفی می‌کنه، مدل توی گفت‌وگو صداشون می‌زنه و نتیجه برمی‌گرده. فرقش با یه API معمولی اینه که کنار دادهٔ ساختاریافته، HTML هم برمی‌گردونه.

یه یکپارچگی حداقلی سه کار انجام می‌ده: معرفی ابزارها همراه قرارداد ورودی و خروجی به شکل JSON Schema، اجرای ابزار وقتی مدل انتخابش می‌کنه، و برگردوندن ویجت. اون ویجت از طریق متادیتای _meta.ui.resourceUri به Apps SDK شناسونده می‌شه و کنار پیام دستیار رندر می‌شه. پروتکل هم به ترنسپورت گیر نمی‌ده، پس می‌تونی روی SSE یا HTTP استریمی سوارش کنی.

نمونه‌ها متنوعن. Pizzaz چند نوع نما رو نشون می‌ده: لیست، کروسل، نقشه و یه فروشگاه با صفحهٔ تسویه. kitchen sink lite کل سطح window.openai رو یکجا تمرین می‌کنه، از خوندن toolInput و toolOutput و theme گرفته تا نوشتن با setWidgetState و صداکردن یه ابزار MCP دیگه از داخل خود ویجت. solar system یه نمایشگر سه‌بعدیه و authenticated سطوح مختلف OAuth رو نشون می‌ده.

نمونهٔ سبد خرید سراغ سخت‌ترین بخش می‌ره: نگه‌داشتن وضعیت بین چند فراخوانی. با widgetSessionId که توی _meta می‌آد، widgetState بین نوبت‌ها همگام می‌مونه. یعنی وقتی کاربر تعداد یه محصول رو زیاد می‌کنه، دستیار هم همون سبد به‌روز رو می‌بینه و جفتشون یه تصویر مشترک از سبد دارن. توی خود مخزن هشدار داده شده که تو محیط واقعی باید سبد رو سمت سرور ذخیره کنی و این نمونه فقط مکانیزم رو نشون می‌ده.

برای اجرا Node نسخهٔ ۱۸ به بالا و Python نسخهٔ ۳.۱۰ به بالا لازمه. بعد از بیلد، فایل‌های HTML و JS و CSS نسخه‌دار توی پوشهٔ assets/ ساخته می‌شن و باید از سرور استاتیک محلی روی پورت ۴۴۴۴ سرو بشن، وگرنه سرورهای MCP چیزی برای نمایش ندارن. برای تست هم developer mode رو توی ChatGPT روشن می‌کنی و سرور محلی رو از بخش Connectors اضافه می‌کنی؛ اگه سرور روی دستگاه خودته، با یه تونل عمومی می‌تونی آدرسش رو در دسترس بذاری.

نکات کلیدی:

• مخزن شامل ویجت‌های نمونه به‌علاوهٔ سرورهای MCP آماده با Node و Python ـه و لایسنسش MIT ـه
• ویجت با متادیتای _meta.ui.resourceUri به Apps SDK معرفی می‌شه و کنار پیام دستیار رندر می‌شه
• نگه‌داشتن وضعیت بین نوبت‌ها با _meta["widgetSessionId"] و widgetState انجام می‌شه
• پیش‌نیازها: Node.js نسخهٔ ۱۸ به بالا، Python نسخهٔ ۳.۱۰ به بالا و pnpm
• دارایی‌های بیلدشده باید روی پورت ۴۴۴۴ با CORS فعال سرو بشن؛ سرور پایتونی Pizzaz خروجی HTML رو کش می‌کنه، پس بعد از بیلد دوباره باید ری‌استارتش کنی
• SDK پایتونی MCP محافظت DNS rebinding داره، پس موقع تونل‌زدن باید هاست تونل رو با متغیرهای MCP_ALLOWED_HOSTS و MCP_ALLOWED_ORIGINS مجاز کنی
• روی کروم نسخهٔ ۱۴۲ باید فلگ local-network-access رو غیرفعال کنی وگرنه رابط ویجت‌ها بالا نمی‌آد