MCP Events چیست؟ ساخت ایجنت واکنش‌گرا به رویدادها با Mastra

تعریف و انتشار رویداد در Mastra

نسخه‌های لازم و مسیر import را از مرجع همان انتشار بررسی کنید. الگوی زیر بخش تعریف رویداد در یک MCPServer پیکربندی‌شده است؛ برنامه کامل مستقل نیست و عمداً سرور عمومی بدون احراز هویت ایجاد نمی‌کند. API آزمایشی ممکن است تغییر کند، بنابراین فایل قفل و نمونه رسمی را با نسخه نصب‌شده تطبیق دهید. جزئیات گزینه‌ها در مرجع MCPServer و لینک‌های انتهای خبر رسمی آمده است.

// Inside the configured MCPServer options, with defineEvent and z imported
// from the documented modules for your installed Mastra version:
events: {
  'deployment.failed': defineEvent({
    description: 'A failed deployment in an authorized project',
    inputSchema: z.object({projectId: z.string()}),
    payloadSchema: z.object({
      eventId: z.string(), projectId: z.string(), runId: z.string()
    }),
    match: (args, data) => args.projectId === data.projectId,
  })
}

// Only after signature, ownership and durable acceptance checks:
await deploymentServer.events.emit('deployment.failed', payload);

تابع match فقط تطبیق داده اشتراک را نشان می‌دهد و جانشین احراز هویت نیست. کاربری که projectId حساب دیگری را وارد می‌کند، باید پیش از ثبت اشتراک رد شود. هنگام انتشار نیز payload را از ورودی معتبر بسازید، نه اینکه کل بدنه دریافتی را با همه فیلدهایش پخش کنید. در مسیر واقعی، شناسه پروژه و کاربر مجاز را از داده سرور استخراج کنید و از افشای رویداد بین حساب‌ها جلوگیری کنید.

دریافت رویداد و آغاز یک کار محدود

الگوی subscribe در آموزش رسمی رویدادهای Mastra توضیح داده شده است. در سمت مصرف‌کننده، رویداد را به یک کار با شناسه پایدار تبدیل کنید. حلقه دریافت نباید خودش تمام تحلیل طولانی را در اتصال ورودی انجام دهد. اگر مدل چند ده ثانیه زمان بخواهد، بستن درخواست تحویل به پایان تحلیل می‌تواند باعث timeout و تحویل دوباره شود. دریافت معتبر، ثبت پایدار و اجرای کار سه مرحله متفاوت‌اند.

// Partial consumer example; client/server authentication is configured separately.
const stream = await mcp.events.subscribe(
  'deployments', 'deployment.failed',
  {projectId: authorizedProjectId}, {delivery: 'push'}
);
for await (const event of stream) {
  // Validate event.data, then enqueue by its stable eventId.
  // Do not directly redeploy or execute shell commands from this callback.
  await enqueueAuthorizedAnalysis(event.data);
}

enqueueAuthorizedAnalysis در این قطعه تابع برنامه شماست، نه متد آماده Mastra. باید اعتبار ورودی و مالکیت را دوباره در مرز کار بررسی کند و پذیرش تکراری را به نتیجه قبلی متصل کند. برای نمونه صف، آموزش Worker با BullMQ و Redis مفید است. اگر ادامه اجرا و تأیید انسانی چندمرحله‌ای دارید، راهنمای LangGraph و مقاله صف در برابر Workflow را کنار آن مطالعه کنید.

امضای Webhook و جلوگیری از بازپخش

اگر منبع رویداد GitHub است، روش رسمی اعتبارسنجی تحویل Webhook را اجرا کنید. امضا روی بایت‌های بدنه اصلی محاسبه می‌شود؛ تبدیل JSON به رشته جدید پیش از بررسی می‌تواند نتیجه را تغییر دهد. مقایسه امضا باید با روش مناسب زمان‌ثابت و کنترل طول انجام شود. Secret را از محیط امن بخوانید و در لاگ یا پاسخ خطا ننویسید. HTTPS جای بررسی امضای منبع را نمی‌گیرد.

امضای درست مانع همه بازپخش‌ها نیست؛ همان تحویل معتبر ممکن است دوباره ارسال شود. شناسه تحویل را در محدوده منبع و حساب با قید یکتا ذخیره کنید. اگر منبع قرارداد زمان یا nonce دارد، آن را مطابق مستند همان منبع بررسی کنید؛ هدر خیالی برای همه ارائه‌دهندگان نسازید. حذف سریع سوابق شناسه‌های پردازش‌شده هم می‌تواند پنجره تکرار باز کند. سیاست نگهداری را با زمان تحویل مجدد و هزینه داده هماهنگ کنید.

ثبت پایدار، صف و عملیات تکراری

برای پذیرش مطمئن، ذخیره رویداد و ثبت کار قابل اجرا باید مرز تراکنشی روشن داشته باشند. اگر ابتدا پاسخ موفق بدهید و سپس برنامه پیش از ذخیره کار متوقف شود، خبر گم می‌شود. اگر کار را در صف خارجی گذاشته و پیش از ثبت وضعیت قطع شوید، تحویل بعدی ممکن است کار دیگری بسازد. الگوی Outbox یکی از راه‌های جداکردن تراکنش دیتابیس از انتشار بعدی است؛ اما انتخاب آن باید متناسب با حجم و نیاز پروژه باشد، نه صرفاً برای پیچیده‌کردن نمونه.

در مقایسه صف پیام و Durable Workflow این مرز را با مثال بررسی می‌کنیم. حتی اگر یک کار فقط یک بار در صف دیده شود، اثر بیرونی آن ممکن است در نقطه نامعلوم شبکه تکرار شود. برای عملی مانند ارسال اعلان، کلید یکتای عملیات و امکان خواندن نتیجه قبلی لازم است. در تحلیل متنی نیز شمار تلاش و سقف هزینه را محدود کنید تا تکرار رویداد باعث مصرف بی‌دلیل API نشود.

نقش API و PaaS پاستا در این معماری

API هوش مصنوعی پاستا در این سناریو نقش تولید گزارش پیشنهادی از داده مجاز را دارد؛ سرویس تحویل MCP Events یا صف برنامه نیست. درخواست مدل را از Backend ارسال کنید، شناسه مدل موجود را از کاتالوگ بردارید و از یک کلید مستقل استفاده کنید. سازگاری اتصال مدل Mastra با endpoint انتخابی باید در نسخه نصب‌شده آزمایش شود. پشتیبانی از متن به معنی پشتیبانی خودکار همه ابزارها یا خروجی ساختاریافته نیست.

در پلتفرم ابری پاستا می‌توانید دریافت‌کننده و Worker برنامه خودتان را با تنظیمات مستقل مستقر کنید. داده پایدار را در سرویس مناسب و با سیاست بازیابی نگه دارید؛ فایل محلی موقت جای سابقه رویدادها نیست. برای اتصال مدل، مستند API و برای ذخیره وضعیت، امکانات جاری دیتابیس مدیریت‌شده را بررسی کنید. این مقاله عرضه سرویس مدیریت‌شده Mastra یا MCP Events در پاستا را ادعا نمی‌کند.

آزمون پذیرش و قدم بعدی

آزمایش را با رویداد ساختگی و پروژه آزمایشی انجام دهید. امضای غلط، بدنه بیش از حد، پروژه غیرمجاز، تحویل دوباره، قطع Worker و خطای مدل باید نتیجه مشخص داشته باشند. تعداد کار ذخیره‌شده و نتیجه پایدار را بررسی کنید، نه فقط کد موفق HTTP. برای اتصال Push، قطع و برقراری دوباره را هم امتحان کنید. اگر رویدادی از دست رفت، باید بتوانید با وضعیت منبع تطبیق دهید؛ جریان زنده تنها مرجع حقیقت محصول نباشد.

با یک نوع رویداد و یک خروجی کم‌ریسک شروع کنید. ابتدا دریافت و مجوز را درست کنید، بعد تولید متن با API پاستا را اضافه کنید و تنها پس از آزمون به اقدام بیرونی فکر کنید. هدف، ساخت ایجنتی است که تغییرهای مرتبط را به کار قابل بررسی تبدیل کند؛ نه سرویسی که هر پیام ورودی را دستور معتبر بداند. همین مرز، تفاوت یک نمایش جذاب با گردش‌کار قابل نگهداری را مشخص می‌کند.