سرور Vonage MCP Tooling Server متنباز و مناسب افراد تازهکار است. با ارسال Pull Requestهای ساده و پیروی از راهنمای شفاف MCP، قابلیتهای واقعی SDK را به آن اضافه کنید.
مقدمه
فرض کنید دارید با سرور Vonage MCP Tooling بازی میکنید. دیدهاید که عاملهای هوش مصنوعی چطور میتوانند پیامهای شاد تبریک تعطیلات را از طریق WhatsApp یا RCS ارسال کنند، یا اینکه یک چتبات Claude ساختهاید که با سرور MCP تعامل دارد. خیلی تمیز و جذاب، نه؟
اما بعد ذهنتان جرقه میزند:
«صبر کن ببینم… اگر بخواهم MMS اضافه کنم چی؟ یا قبل از ارسال اطلاعات حساس، بررسی کنم که آیا این شماره اخیراً دچار SIM Swap شده یا نه؟ یا حتی چند قابلیت دیگر از Voice API اضافه کنم؟»
سرور Vonage MCP Tooling کاملاً متنباز است و آماده دریافت مشارکتهای شماست. این راهنما به شما نشان میدهد چطور یک ابزار جدید (مثلاً verify-number) اضافه کنید و یک Pull Request (PR) ارسال کنید، در حالی که همهچیز با ساختار ابزارهای موجود همخوان باقی بماند.
اول ساختار را بشناسید
قبل از اینکه وارد کدنویسی شوید، کمی وقت بگذارید و معماری پروژه را بررسی کنید. لازم نیست تکتک خطوط را حفظ کنید، اما درک اینکه اجزا چطور کنار هم قرار گرفتهاند، کمک میکند ابزار شما بدون دردسر در پروژه جا بیفتد.
اجزای اصلی
-
راهاندازی محیط و احراز هویت
-
پیکربندی ماژولار کانالها
- عملکرد پیامرسانی یکپارچه
ساختاری ساده، تمیز و طراحیشده برای استفاده مجدد.
الگوهای MCP
در طول ساخت اولین ابزارها، چیزهای زیادی یاد گرفتیم و به چند قاعده سرانگشتی رسیدیم که یکپارچهسازی با عاملهای هوش مصنوعی را روانتر و قابلپیشبینیتر میکند. اگر قصد مشارکت دارید، لطفاً به اینها پایبند باشید:
۱. یک ابزار = یک کار
ابزارهای شفاف و تکمنظوره برای عاملهای هوش مصنوعی بسیار قابلفهمتر هستند. وقتی هر ابزار دقیقاً یک کار انجام میدهد، کشفپذیرتر است، مستندسازیاش سادهتر است و احتمال سردرگمکردن منطق برنامهریزی عامل بهشدت کاهش مییابد.
از ابزارهای «همهفنحریف» پرهیز کنید.
۲. اعتبارسنجی را جدی بگیرید
ورودی بد؟ متغیر محیطیِ گمشده؟
همه اینها را زود و شفاف تشخیص دهید.
و همیشه پاسخها را بهصورت ساختاریافته برگردانید، طوری که عامل هوش مصنوعی بتواند آن را بهدرستی پردازش کند.
۳. استفاده از Zod برای اسکیماهای ورودی
همهچیز را ایمن از نظر نوع داده و خوشمستند نگه دارید.
اگر قبلاً با Zod کار نکردهاید، میتوانید آن را راهی برای تعریف و اعتبارسنجی ورودیها در یک نقطه واحد در نظر بگیرید؛ شبیه TypeScript، اما با بررسی در زمان اجرا. این کار تضمین میکند ابزار فقط زمانی اجرا شود که ورودیها معتبر باشند و به عاملها توضیح روشنی از معنی هر فیلد بدهد.
این inputSchema را بهعنوان بخشی از فراخوانی server.registerTool() اضافه میکنید، تا هنگام ثبت ابزار، سرور دقیقاً بداند چه شکلی از ورودی را انتظار دارد و چطور باید آن را اعتبارسنجی کند.
۴. مستندات، همیشه اول
ابزار خود را به جدول README اضافه کنید و یک مثال استفاده هم بیاورید. خودِ آیندهتان و هر توسعهدهندهای که بعد از شما میآید، قدردان شما خواهند بود.
بیایید با هم یک ابزار اضافه کنیم
فرض کنید میخواهید با افزودن یک ابزار جدیدِ متمرکز، به بهبود سرور MCP Tooling کمک کنید. در این مثال، ابزاری میسازیم که بررسی میکند آیا یک شماره تلفن اخیراً دچار SIM Swap شده یا نه؛ که یکی از نشانههای رایج تقلب است. اسم ابزار را میگذاریم check-sim-swap.
این ابزار از Identity Insights API استفاده میکند که اطلاعات بلادرنگ درباره یک شماره تلفن ارائه میدهد، از جمله رویدادهای SIM Swap. دامنه را محدود نگه میداریم: یک ابزار، یک کار.
گام ۱: راهاندازی محیط توسعه محلی
ابتدا مخزن سرور MCP را Fork کنید و Fork خودتان را Clone بگیرید.
اگر قبلاً از make استفاده نکردهاید، در اصل یک اجراکننده وظایف است که چند فرمان را با هم بستهبندی میکند. فایل Makefile را ببینید تا متوجه شوید چه دستورهایی اجرا میشوند.
هرچند make ریشه در اکوسیستم C و C++ دارد، اما برای گردشکارهای عمومی هم بسیار خوب عمل میکند، از جمله پروژههای JavaScript و TypeScript. در این مخزن، از آن برای سادهسازی کارهای تکراری مثل نصب وابستگیها یا آمادهسازی محیط توسعه استفاده میکنیم.
در اینجا، دستور make setup وابستگیها را نصب میکند و محیط را برای کار با پروژه آماده میسازد.
گام ۲: نوشتن ابزار
حالا فایل src/index.ts را باز کنید و ابزار جدیدتان را در سرور ثبت کنید.
کد زیر را اضافه کنید:
این ابزار فقط یک کار انجام میدهد: با گرفتن یک شماره تلفن، بررسی میکند آیا سیمکارت آن در ۱۰ روز گذشته (۲۴۰ ساعت) تعویض شده یا نه. اگر شده باشد، زمان آن را برمیگرداند و اگر نه، تأیید میکند که تعویض اخیر رخ نداده است.
گام ۳: بهروزرسانی مستندات
فایل README.md را باز کنید و ابزار جدید را به جدول ابزارها اضافه کنید.
| **Identity** | `check-sim-swap` | Check if a phone number has had a recent SIM change |
سپس یک مثال استفاده هم اضافه کنید.
#### Check if a phone number has had a SIM swap
Can you check whether +14155550123 has had a SIM swap in the past 10 days?
گام ۴: تست محلی
مطمئن شوید ابزار شما Build میشود و همه بررسیها را پاس میکند.
گام ۵: ساخت Pull Request
وقتی همهچیز درست به نظر رسید، تغییرات را Commit و Push کنید.
بعد به GitHub بروید و Pull Request خودتان را باز کنید. امتیاز اضافه اگر یک اسکرینشات از کارکرد ابزار با عامل هوش مصنوعیتان هم ضمیمه کنید!
الگوهای پیشرفته برای قابلیتهای پیچیدهتر
احتمالاً برای ابزارهای ساده به اینها نیاز ندارید، اما برای فرآیندهای طولانی یا حجیم، این ساختارها را در نظر بگیرید.
مدیریت عملیات ناهمگام با رهگیری وضعیت
برای عملیاتهایی که زمانبر هستند (مثل گردشکارهای تأیید):
عملیات دستهای (Batch)
برای عملیاتهای انبوه:
چند نکته مهم که باید حواستان باشد
قبل از ارسال Pull Request، مطمئن شوید همهچیز هنوز درست کار میکند. اجرای make check بیشتر خطاهای lint و نوع داده را میگیرد، اما به همین بسنده نکنید. دستی بررسی کنید که همه ابزارهای موجود درست رفتار میکنند و مطمئن شوید اضافهکردن شما ناخواسته چیزی را خراب نکرده است. TypeScript باید بدون خطا کامپایل شود.
نامگذاری خیلی مهمتر از چیزی است که فکر میکنید. برای نام ابزارها از kebab-case استفاده کنید (مثلاً check-sim-swap، نه checkSimSwap). متغیرهای محیطی باید با الگوی UPPER_SNAKE_CASE باشند و همیشه با VONAGE_ شروع شوند. برای توابع هم همان camelCase قدیمی و قابلاعتماد را استفاده کنید.
مدیریت خطا هم بخش حیاتی دیگری است. فرض نکنید همهچیز همیشه خوب پیش میرود. موارد لبهای مثل قطع شبکه، اعتبارنامه نامعتبر، محدودیت نرخ API و ورودی نادرست کاربر را مدیریت کنید. اگر ابزار شما بهشکل مناسب شکست نخورد، برای کاربران و عاملهای بعدی دردسر درست میکند.
در نهایت، اگر ابزار شما متغیر محیطی جدیدی معرفی میکند، آن را شفاف مستند کنید. به جدول متغیرهای محیطی در README اضافهاش کنید، با توضیح کوتاه درباره اینکه هر کلید چه کاری میکند و آیا اجباری است یا نه. همین کار کوچک میتواند کلی سردرگمی آینده را کم کند.
امتیاز اضافه: استفاده همزمان از دو سرور MCP
هنگام کار با یک عامل هوش مصنوعی، میتوانید با اجرای همزمان Vonage MCP Tooling Server و Vonage Documentation MCP Server فرآیند مشارکت را سادهتر کنید. این ترکیب به عامل شما هم به تعریف ابزارهای پروژه دسترسی میدهد و هم به مستندات رسمی APIهای Vonage، و نوشتن ابزارهای جدید مطابق الگوهای موجود را راحتتر میکند.
با فعال بودن هر دو سرور، معمولاً میتوانید از پرامپتی شبیه این شروع کنید:
«میخواهم یک ابزار جدید به Vonage MCP Tooling Server اضافه کنم که از Verify API برای شروع گردشکار تأیید شماره تلفن استفاده کند. لطفاً ساختار یک ابزار در هر فایل را رعایت کن، از Zod برای اعتبارسنجی ورودی استفاده کن و یک مثال استفاده برای README اضافه کن. برای پارامترهای جدید به مستندات Vonage رجوع کن.»
این روش جای تست و بازبینی را نمیگیرد، اما کمک میکند سریعتر جلو بروید و تغییراتتان با قراردادهای پروژه همراستا بماند.
جمعبندی
متنباز زمانی بهترین نتیجه را میدهد که آدمهایی مثل شما وارد عمل شوند. اگر ایدهای برای یک قابلیت جدید SDK دارید، چه MMS باشد، چه مدیریت تماس یا حتی مدیریت حساب، بسازیدش! و اگر نمیدانید از کجا شروع کنید، پیام بدهید؛ با هم جلو میرویم. ما عاشق PR هستیم.
بیصبرانه منتظریم ببینیم چه چیزی میسازید.
سؤالی دارید یا چیزی برای بهاشتراکگذاری؟ به گفتوگو در Slack جامعه Vonage بپیوندید، با خبرنامه توسعهدهندگان بهروز بمانید، ما را در X (توییتر سابق) دنبال کنید، کانال YouTube را برای آموزشهای ویدیویی سابسکرایب کنید و صفحه توسعهدهندگان Vonage را در LinkedIn دنبال کنید؛ جایی برای یادگیری، ارتباط و رشد در کنار جامعه توسعهدهندگان. در ارتباط بمانید، پیشرفتتان را به اشتراک بگذارید و از آخرین اخبار، نکات و رویدادهای توسعهدهندگان جا نمانید!
