چگونه نرم‌افزار داخلی شرکت را با کانکتور اختصاصی به هوش مصنوعی متصل کنیم؟
راهنمای طراحی کانکتور اختصاصی برای نرم‌افزار داخلی؛ از شناسایی عملیات و احراز هویت تا Schema ابزار، تأیید انسانی، Audit، تست و انتشار در MCP Gateway.
بسیاری از شرکت‌ها نرم‌افزارهایی دارند که در هیچ کاتالوگ عمومی پیدا نمی‌شوند: ERP داخلی، سامانه انبار، پنل خدمات، سیستم قیمت‌گذاری، CRM سفارشی یا API مخصوص عملیات. برای استفاده ایمن هوش مصنوعی از این سیستم‌ها، کانکتور اختصاصی باید مرز روشنی میان مدل و منطق واقعی کسب‌وکار ایجاد کند.
کانکتور خوب API را فقط به Tool تبدیل نمی‌کند؛ هویت، مجوز، مدل خطا، تأیید، Audit و محدودیت عملیات را نیز تعریف می‌کند.
اول مشخص کنید اتصال قرار است چه مسئله‌ای را حل کند
پیش از طراحی Toolها، یک یا دو سناریوی قابل‌اندازه‌گیری انتخاب کنید. عبارت «همه امکانات نرم‌افزار را به AI بدهیم» دامنه‌ای مبهم و پرریسک می‌سازد.
- نمایش وضعیت درخواست مشتری
- تهیه گزارش سفارش‌های معوق
- جست‌وجوی موجودی چند انبار
- ساخت پیش‌نویس تیکت
- تغییر وضعیت یک رکورد پس از تأیید
- اجرای Workflow مشخص برای یک فرایند داخلی
برای هر سناریو مشخص کنید کاربر چه می‌پرسد، کدام داده لازم است، چه عملیاتی اجرا می‌شود و نتیجه موفق یا ناموفق چگونه قابل تشخیص است.
API موجود را ارزیابی کنید
اگر نرم‌افزار API پایدار و مستند دارد، کانکتور باید از همان قرارداد استفاده کند. اتصال مستقیم به پایگاه داده معمولاً انتخاب اول نیست؛ چون منطق اعتبارسنجی، مجوز و Side Effectهای نرم‌افزار را دور می‌زند.
چک‌لیست ارزیابی API
- احراز هویت چگونه انجام می‌شود؟
- آیا محیط Test یا Sandbox وجود دارد؟
- عملیات خواندن و نوشتن جدا هستند؟
- صفحه‌بندی، فیلتر و Sort چگونه کار می‌کند؟
- Rate Limit و Timeout چیست؟
- خطاها ساختار ثابت دارند؟
- برای درخواست تکراری Idempotency وجود دارد؟
- Webhook یا Change Feed در دسترس است؟
- شناسه رکوردها پایدار است؟
- API چگونه نسخه‌بندی می‌شود؟
Connection و Tool را از هم جدا کنید
Connection مشخص می‌کند به کدام نمونه از سرویس و با چه Credentialی وصل می‌شویم. Tool مشخص می‌کند روی آن Connection چه عملیاتی قابل اجراست. یک سازمان ممکن است دو ERP یا چند شعبه داشته باشد؛ بنابراین Tool نباید مقصد را در کد ثابت کند.
Credential نیز نباید داخل Schema ابزار یا متن Prompt قرار گیرد. Gateway آن را از Connection امن می‌گیرد و هنگام فراخوانی مقصد استفاده می‌کند.
عملیات را بر اساس ریسک دسته‌بندی کنید
- Read: فقط مشاهده داده و گزارش.
- Write کم‌ریسک: ایجاد پیش‌نویس یا ویرایش محدود و قابل بازگشت.
- Execute حساس: ثبت نهایی، ارسال پیام، تغییر وضعیت یا اجرای فرایند.
- Destructive: حذف، لغو مالی، Revoke یا تغییر زیرساخت.
این دسته‌بندی روی مجوز عضو، نیاز به Confirmation، Audit و محدودیت Rate اثر می‌گذارد. نام‌گذاری Tool به‌تنهایی کافی نیست؛ ریسک باید Metadata صریح داشته باشد.
Toolها را بر اساس هدف کاربر طراحی کنید
هر Endpoint نباید الزاماً یک Tool شود. API ممکن است ده‌ها Endpoint فنی داشته باشد، اما کاربر فقط چند کار مشخص انجام دهد. Tool سطح بالاتر می‌تواند چند فراخوانی امن را پشت یک قرارداد قابل‌فهم جمع کند.
برای مثال به‌جای Toolهای پراکنده برای خواندن سفارش، مشتری و آیتم‌ها، ابزار «نمایش جزئیات کامل سفارش» می‌تواند نتیجه‌ای یکپارچه برگرداند. در مقابل عملیات نوشتنی بهتر است کوچک، شفاف و قابل تأیید بماند.
نام و توضیح Tool
نام Tool باید پایدار، کوتاه و قابل پیش‌بینی باشد. توضیح باید مشخص کند ابزار چه کاری انجام می‌دهد، چه زمانی نباید استفاده شود و آیا داده را تغییر می‌دهد.
- نام ضعیف: processData
- نام بهتر: orders.get
- نام ضعیف: update
- نام بهتر: orders.change-status
- توضیح ضعیف: سفارش را مدیریت می‌کند
- توضیح بهتر: وضعیت یک سفارش موجود را پس از بررسی مجوز تغییر می‌دهد؛ مبلغ و اقلام را تغییر نمی‌دهد
Input Schema را محدود طراحی کنید
مدل باید فقط پارامترهایی را ببیند که واقعاً نیاز دارد. ورودی آزاد با additionalProperties گسترده، احتمال خطا و دورزدن سیاست را بالا می‌برد.
- نوع داده و Requiredها مشخص باشند.
- طول String و بازه عدد محدود شود.
- Enum برای وضعیت‌های مجاز استفاده شود.
- شناسه و تاریخ Format روشن داشته باشند.
- آرایه‌ها سقف تعداد داشته باشند.
- فیلدهای Secret هرگز ورودی Tool نباشند.
- پارامتر خطرناک مانند raw SQL یا raw command ارائه نشود.
Output را برای تصمیم‌گیری قابل اتکا کنید
پاسخ Tool باید ساختار ثابت داشته باشد و بین «داده وجود ندارد»، «صفر واقعی»، «دسترسی ممنوع» و «خطای سرویس» تفاوت بگذارد. متن آزاد و مبهم، مدل را مجبور به حدس می‌کند.
بهتر است شناسه رکورد، وضعیت، زمان منبع و در صورت امکان لینک بازبینی انسانی در خروجی باشد. داده حساس اضافی را فقط چون API برمی‌گرداند عبور ندهید.
احراز هویت و OAuth
برای سرویس کاربرمحور، OAuth با Scope حداقلی و PKCE انتخاب مناسب‌تری از دریافت رمز اصلی است. برای ارتباط سروربه‌سرور می‌توان از Client Credentials، API Token محدود یا mTLS استفاده کرد.
کانکتور باید Rotation، Expiry و Revoke را پشتیبانی کند و Credentialها را در Vault نگه دارد. Test Connection نیز باید عملیاتی کم‌ریسک و فقط‌خواندنی باشد.
مجوز مقصد را حفظ کنید
Gateway نباید مجوز بومی نرم‌افزار را دور بزند. اگر کاربر در CRM اجازه مشاهده قرارداد خاصی را ندارد، Tool نیز نباید صرفاً به‌دلیل مجوز کلی Gateway آن قرارداد را برگرداند.
مدل مناسب ترکیبی است: Gateway بررسی می‌کند عضو اجازه Tool و Connection را دارد؛ سرویس مقصد بررسی می‌کند Credential اجازه رکورد و عملیات را دارد.
تأیید انسانی را دقیق طراحی کنید
Confirmation باید قبل از اجرای اثر واقعی انجام شود و خلاصه‌ای قابل‌فهم نشان دهد: چه عملیاتی، روی کدام رکورد، با چه تغییر و توسط چه کسی انجام خواهد شد.
- نمایش گزارش یا جست‌وجو: معمولاً بدون تأیید.
- ایجاد Draft: بسته به سیاست.
- ارسال پیام، تغییر وضعیت نهایی یا ثبت سند: تأیید.
- حذف، بازپرداخت یا تغییر دسترسی: تأیید قوی یا ممنوع.
Idempotency برای عملیات نوشتنی
Retry شبکه یا تکرار Tool Call نباید دو فاکتور، دو پیام یا دو درخواست بسازد. Client یا Gateway باید Idempotency Key تولید کند و سرویس مقصد یا کانکتور نتیجه اجرای قبلی را تشخیص دهد.
اگر API مقصد Idempotency ندارد، کانکتور باید با کلید کسب‌وکار، قفل کوتاه‌عمر یا جدول ثبت درخواست راهکار مطمئنی بسازد؛ نه اینکه فقط امیدوار باشد درخواست تکرار نشود.
Webhook و Change Feed
برای داده‌ای که مرتب تغییر می‌کند، Polling مداوم مناسب نیست. Webhook امضاشده می‌تواند Cache، Index یا Job را به‌روز کند و Tool هنگام درخواست آخرین داده معتبر را بخواند.
Webhook باید Signature، Timestamp، Replay Protection و محدودیت اندازه Payload داشته باشد. رویداد ورودی نباید مستقیماً به‌عنوان دستور مدل اجرا شود.
خطاها را طبقه‌بندی کنید
- Validation error: ورودی نامعتبر است و مدل می‌تواند اصلاح کند.
- Unauthorized: Credential معتبر نیست یا منقضی شده.
- Forbidden: هویت معتبر است اما مجوز عملیات ندارد.
- Not found: رکورد وجود ندارد یا قابل مشاهده نیست.
- Conflict: نسخه رکورد یا وضعیت فعلی اجازه تغییر نمی‌دهد.
- Rate limited: باید با Backoff دوباره تلاش شود.
- Upstream unavailable: سرویس مقصد موقتاً در دسترس نیست.
پیام خطا نباید Stack Trace، Token، Query داخلی یا اطلاعات حساس را فاش کند. در عین حال باید به اندازه کافی دقیق باشد تا کاربر بداند قدم بعدی چیست.
Audit چه چیزهایی را ثبت کند؟
- سازمان، عضو و کلاینت AI
- Connection و Tool
- Request ID و Idempotency Key
- زمان شروع و پایان
- نتیجه و کد خطا
- تأییدکننده و زمان تأیید
- شناسه رکورد تغییرکرده
- نسخه Maskشده ورودی بدون Secret
تست کانکتور
- Unit Test برای Validation و Mapping
- Contract Test در برابر Sandbox یا Mock API
- تست مجوز عضو و مرز سازمان
- تست Expiry و Revoke Credential
- تست Retry و Idempotency
- تست داده خالی، صفحه‌بندی و حجم بالا
- تست عملیات حساس با Approval
- تست عدم افشای Secret در Log و Error
نسخه‌بندی Toolها
تغییر Required Field، نوع داده یا معنای خروجی می‌تواند Client موجود را خراب کند. تغییر ناسازگار باید Tool یا Version جدید داشته باشد و نسخه قبلی با دوره مهاجرت بازنشسته شود.
اضافه‌شدن Tool جدید نباید به‌صورت بی‌صدا به همه اعضا مجوز بدهد. مدیر باید ابزار و سطح ریسک جدید را بازبینی کند.
مستندات کانکتور
- پیش‌نیاز و روش دریافت Credential
- دامنه‌ها و Endpointهای موردنیاز
- Scopeها و مجوز سرویس مقصد
- فهرست Toolها و Risk
- نمونه درخواست و خروجی
- محدودیت نرخ و حجم
- روش Test، Rotate، Disable و Delete
- رفع خطاهای رایج
- نسخه کانکتور و Changelog
استقرار و مانیتورینگ
کانکتور باید Timeout، Circuit Breaker، Retry محدود و Metricهای تعداد فراخوانی، خطا و Latency داشته باشد. Alarm روی افزایش خطا یا Expiry Credential کمک می‌کند قبل از کاربر متوجه مشکل شوید.
در استقرار اولیه، ابزارهای Read را فعال کنید و Writeها را با Allowlist محدود آزمایش کنید. انتشار یک‌باره همه عملیات معمولاً ریسک غیرضروری ایجاد می‌کند.
کانکتور اختصاصی در وصلک
در وصلک، کانکتور می‌تواند Connection Schema، Tool Manifest، Risk، Scope، روش احراز هویت و Documentation خود را داشته باشد. ابزارها سپس بر اساس سازمان، عضو و اتصال در MCP Gateway منتشر می‌شوند.
این مدل اجازه می‌دهد نرم‌افزار داخلی فقط یک‌بار به‌صورت استاندارد پیاده‌سازی شود و چند کلاینت هوش مصنوعی بدون دریافت Credential مستقیم از همان ابزارها استفاده کنند.
چه زمانی کانکتور نسازیم؟
- سرویس API پایدار یا مجوز قانونی برای اتصال ندارد.
- نیاز فقط یک Export دستی و موقت است.
- عملیات با Screen Scraping شکننده و پرخطر انجام می‌شود.
- داده آن‌قدر حساس است که هیچ مسیر کنترل‌شده‌ای برای AI قابل قبول نیست.
- ارزش فرایند هزینه نگهداری بلندمدت را توجیه نمی‌کند.
نقشه اجرای پیشنهادی
- یک سناریوی Read با ارزش انتخاب کنید.
- API و مجوزهای مقصد را مستند کنید.
- Connection و Credential Schema را بسازید.
- دو یا سه Tool محدود با Schema دقیق پیاده کنید.
- Contract Test و Audit را کامل کنید.
- در یک سازمان آزمایشی منتشر کنید.
- خروجی را با فرایند دستی مقایسه کنید.
- Write را فقط پس از تثبیت Read و Approval اضافه کنید.
جمع‌بندی
کانکتور اختصاصی یک Adapter ساده نیست؛ یک مرز امنیتی و محصول قابل نگهداری است. طراحی درست از مسئله کسب‌وکار شروع می‌شود، Toolهای محدود و قابل‌فهم می‌سازد و مجوز، تأیید، Idempotency و Audit را از ابتدا در قرارداد قرار می‌دهد.
هرچه Tool قدرت بیشتری دارد، باید ورودی محدودتر، مجوز دقیق‌تر و ردپای روشن‌تری داشته باشد.
