Watch
1
0
Fork
You've already forked arc
0
forked from hesabix/arc
arc/docs/AI_MCP_EXTERNAL_SERVER.md

20 KiB
Raw Permalink Blame History

اتصال امن دستیارهای هوش مصنوعی به حسابیکس از طریق MCP

معماری و وضعیت پیاده‌سازی

POST /api/v1/ai/mcp یک سرور راه‌دور MCP مبتنی بر Streamable HTTP است. ابزارها از registry اصلی AI حسابیکس گرفته می‌شوند و همان مجوزهای دامنه‌ای کاربر را رعایت می‌کنند. ابزار ask_hesabix_agent فقط برای credentialهای بدون allowlist ابزار (مانند اتصال دستی قدیمی) منتشر می‌شود؛ grantهای OAuth که فهرست ابزار انتخابی دارند آن را پنهان می‌کنند تا ایجنت نتواند از allowlist عبور کند. قابلیت‌های MCP شامل ابزارها، Resource پایهٔ کسب‌وکار، Resource پویای قابلیت‌های مجاز همین اتصال و Promptهای دامنه‌ای است. Resource hesabix://mcp/capabilities فقط ابزارهایی را نشان می‌دهد که برای همان کاربر، کسب‌وکار، scope و allowlist اتصال قابل مشاهده‌اند؛ شرح، دسته، capability، نوع اثر، مجوز لازم و JSON Schema ورودی را برای همان ابزارها ارائه می‌کند.

کاتالوگ AI علاوه بر CRUD فاکتور، upsert گروهی محدود، اقساط، محاسبه مانده، برچسب‌ها، پیش‌نمایش اثر حذف و لینک‌های عمومی امن را در اختیار می‌گذارد. عملیات لینک عمومی و حذف گروهی به تأیید نیاز دارند. گردش مالیاتی مرحله‌ای شامل مدیریت کارپوشه و مرجع، اعتبارسنجی، ارسال/ابطال/اصلاح، استعلام و پیگیری خطاهاست. ارسال گروهی به ۲۰ فاکتور و حذف گروهی از کارپوشه به ۵۰ فاکتور محدود است؛ ارسال، retry و health check تأیید جداگانه می‌خواهند. عملیات یک‌مرحله‌ای نامحدود در دسترس نیست. ابزارهای CRM چرخهٔ سرنخ، فرصت، فعالیت، یادداشت/تقویم، برچسب و فیلدهای سفارشی، فرایند و مرحله، تاریخچه، گزارش، نمای ۳۶۰ مشتری، صف کار و توالی‌های خودکار را پوشش می‌دهند. ابزارهای انبار شامل چرخه حواله و انبارگردانی محدودشده برای هر انبار/گروه کالا هستند؛ نتیجه انبارگردانی طبق تنظیم کسب‌وکار حواله تعدیل یا اسناد کالای هزینه/درآمد می‌سازد. ابزارهای چک شامل واگذاری، وصول، عودت، برگشت، پرداخت، سپرده و راس‌گیری هستند؛ actionهای حسابداری به مجوز accounting.write و تأیید نیاز دارند. این ابزارها از tenant اتصال و مجوز زندهٔ عضو استفاده می‌کنند؛ کاتالوگ capabilityها در زمان اتصال، فهرست واقعی و مجاز همان کاربر را نشان می‌دهد.

برای ثبت هم‌زمان اسناد مالی، bulk_upsert_receipts_payments و bulk_upsert_expense_income هرکدام حداکثر ۲۵ آیتم می‌پذیرند. هر آیتم payload هم‌ساخت ورودی ابزار تک‌سندی دارد؛ document_id را برای ویرایش بفرستید و برای ایجاد حذف کنید. مجوز افزودن/ویرایش برای هر آیتم در کسب‌وکار متصل بررسی می‌شود؛ خطای یک آیتم مانع بقیه نیست. migration_mode عمداً از ابزار MCP در دسترس نیست. هر دو ابزار نوشتنی و نیازمند تأیید هستند. bulk_delete_expense_income حذف حداکثر ۱۰۰ سند را پس از بررسی مالکیت tenant، نوع سند و permission حذف انجام می‌دهد.

حقوق‌ودستمزد از طریق ابزارهای payroll برای داشبورد و گزارش‌ها، تنظیمات، تعریف اقلام، پروفایل کارکنان، دوره و اجرای حقوق در دسترس است. permissionهای مشاهده، مدیریت، اجرا، تأیید و ثبت (payroll.view/manage/operate/approve/post) جداگانه اعمال می‌شوند. ساخت/ویرایش اجرای حقوق محدود به ۵۰۰ ردیف پرسنل است؛ تأیید، رد، نهایی‌سازی، لغو، ثبت حسابداری و پرداخت همگی writeهای پرخطر و نیازمند تأیید هستند. فایل‌های PDF و Excel به‌صورت باینری در MCP عرضه نمی‌شوند.

برای عملیات گروهی کالا، bulk_upsert_products حداکثر ۲۵ کالا و bulk_delete_products حداکثر ۱۰۰ شناسه می‌پذیرد. تغییر قیمت گروهی و انبار پیش‌فرض جفت ابزار preview/apply دارند و فقط روی حداکثر ۱۰۰ شناسهٔ صریح اجرا می‌شوند؛ درخواست‌های قیمت باید ابتدا preview شوند. ثبت تعداد اولیهٔ کالا به مجوز جداگانهٔ opening_balance.edit وابسته است.

گزارش‌های ساخت‌یافتهٔ انبار نیز با permission reports.view در دسترس‌اند: خلاصه حواله‌ها، کالاهای کم‌گردش/بحرانی، انتقال بین انبارها، تعدیل‌ها، عملکرد انبار، تاریخچه حرکت کالا، ارزش موجودی، حواله‌های draft و گردش موجودی. فهرست‌ها به حداکثر ۲۰۰ مورد در هر صفحه محدود هستند؛ دادهٔ گزارش XLSX به شکل خروجی باینری ارائه نمی‌شود.

ابزارهای تعمیرگاه از مجوزهای واقعی repair_shop.read/write/manage/delete استفاده می‌کنند. چرخه سفارش شامل ساخت/ویرایش/لغو، تخصیص تعمیرکار، ثبت قطعات، محاسبه هزینه، تغییر وضعیت، تکمیل/تحویل، صدور فاکتور و خواندن خلاصه حسابداری/تاریخچه گارانتی است. افزودن قطعه می‌تواند حواله خروج انبار بسازد؛ تکمیل تعمیر ممکن است حواله را قطعی کند؛ وضعیت‌ها می‌توانند اعلان بیرونی ارسال کنند؛ همه این اثرها در شرح ابزار آمده و عملیات حساس نیازمند تأیید هستند. Prompt repair_review فقط وقتی ارائه می‌شود که ابزار تعمیرگاه برای همان اتصال مجاز باشد.

ابزارهای مدیریت گارانتی شامل خواندن و ویرایش تنظیمات، جستجوی صفحه‌بندی‌شده بر اساس وضعیت/کالا، فهرست کدهای یک شخص، تولید دسته‌ای حداکثر ۵۰ کد برای کالای کسب‌وکار متصل، حذف تکی و حذف دسته‌ای حداکثر ۵۰ کد هستند. مجوزهای warranty.read/manage/write/delete با permissionهای واقعی API نگاشت می‌شوند. خروجی کدها اطلاعات تماس فعال‌ساز و توکن لینک رهگیری را حذف می‌کند. تولید کد، تغییر تنظیمات و حذف، تأیید صریح می‌خواهند؛ حذف کد فعال یا استفاده‌شده فقط با force=true انجام می‌شود و سوابق وابسته را هم پاک می‌کند. Prompt warranty_review فقط با ابزار مجاز گارانتی ارائه می‌شود. جریان‌های عمومی مشتری برای فعال‌سازی و رهگیری کد به MCP کسب‌وکاری داده نمی‌شوند، چون قرارداد عمومی و ضدسوءاستفاده دارند و داده‌های تماس مشتری می‌گیرند.

ابزارهای توزیع اکنون گردش‌های قلمرو و مسیر، توقف و تخصیص، برنامه ویزیت، بازدید و مرجوعی، تنظیمات، خودرو و موجودی آن، هدف و تسویه، پیش‌فروش، پروموشن، تحویل، بارگیری، کمیسیون، بازرسی قفسه، پروفایل مشتری و ترکیب کالا را پوشش می‌دهند. دسترسی‌ها از distribution.view/manage/operate/settle/approve_returns به مجوزهای واقعی عضو نگاشت می‌شوند. پایان بازدید ممکن است فاکتور و خروج موجودی خودرو بسازد؛ تأیید مرجوعی، بارگیری/تخلیه و تأیید تسویه هم اثر مالی یا انباری دارند و تأیید MCP می‌خواهند. عملیات مکان، دادهٔ مکانی را ذخیره یا نمایش می‌دهد و فقط با permission عملیات توزیع عرضه می‌شود. Prompt distribution_review بر محدودکردن داده‌های مکانی و تأیید اثر عملیات تأکید می‌کند. PDF و sync آفلاین فعلاً ابزار نشده‌اند؛ اولی خروجی باینری است و دومی مجموعهٔ باز از actionها را می‌پذیرد و نیازمند قرارداد محدود و قابل ممیزی است.

برای اتصال دستیارهایی مانند ChatGPT، OAuth Authorization Code به همراه PKCE با S256، کشف OAuth، ثبت کلاینت DCR و Client ID Metadata Document (برای دامنهٔ مجاز ChatGPT)، رضایت کاربر، refresh token چرخشی، لغو توکن و انتخاب کسب‌وکار پیاده شده است. کلاینت‌های قدیمی‌تر می‌توانند با اتصال Bearer دستی که در API اتصال‌های MCP ساخته می‌شود نیز کار کنند.

استقرار

در محیط production مقدار origin عمومی و ثابت API را تنظیم کنید؛ این مقدار منبع issuer و audience است و از Host درخواست گرفته نمی‌شود:

MCP_PUBLIC_BASE_URL=https://hsxn.hesabix.ir

HTTPS در production اجباری است. سپس migrationها را اجرا کنید:

cd hesabixAPI
alembic upgrade head

Originهای مرورگری و hostهای callback مجاز را در deployment مطابق کلاینت‌های مورد استفاده محدود کنید. مقادیر پیش‌فرض ChatGPT و Claude را پوشش می‌دهند. دامنه‌های دیگر باید با MCP_ALLOWED_ORIGINS و MCP_OAUTH_TRUSTED_REDIRECT_HOSTS صریحاً اضافه شوند. MCP_CIMD_ALLOWED_HOSTS فقط باید به دامنه‌های قابل‌اعتمادِ سند هویت کلاینت محدود شود؛ پیش‌فرض آن chatgpt.com است. مقدارهای list در Pydantic Settings به صورت JSON آرایه‌ای از رشته‌ها تنظیم می‌شوند.

اتصال در ChatGPT

  1. آدرس MCP را به صورت https://hsxn.hesabix.ir/api/v1/ai/mcp به عنوان Custom MCP server اضافه کنید.
  2. روش احراز هویت را OAuth بگذارید و جریان اتصال را کامل کنید.
  3. وارد حساب حسابیکس شوید، کسب‌وکار درست را انتخاب کنید و فقط مجوزهای مورد نیاز را تایید کنید.
  4. پس از انتخاب کسب‌وکار، فهرست ابزارهایی که کاربر در همان کسب‌وکار مجاز به استفاده از آن‌هاست نمایش داده می‌شود. فقط ابزارهای انتخاب‌شده به این اتصال اعطا می‌شوند و هیچ ابزاری از ابتدا انتخاب نشده است.
  5. ابزارهای خواندنی و نوشتنی بر اساس مجوزهای همان عضو در کسب‌وکار فیلتر می‌شوند. عضو می‌تواند ابزارهای مجاز خود را جداگانه انتخاب کند؛ در صورت انتخاب ابزار نوشتنی، scope نوشتن نیز با رضایت صریح همان کاربر صادر می‌شود. دکمهٔ «فعال‌سازی همهٔ دسترسی‌های مجاز» همهٔ گزینه‌های قابل‌اعطای همان کاربر را انتخاب می‌کند.
  6. پس از اتصال، Resource hesabix://mcp/capabilities فهرست زندهٔ ابزارهای مجاز همین اتصال را می‌دهد. فقط از ابزارهای موجود در این فهرست استفاده کنید؛ نام یا پارامتر ابزارهای غایب را حدس نزنید.

سرور Protected Resource Metadata را در /.well-known/oauth-protected-resource/api/v1/ai/mcp و Authorization Server Metadata را در /.well-known/oauth-authorization-server منتشر می‌کند. پاسخ 401 نیز آدرس metadata را در WWW-Authenticate می‌دهد. Client ID Metadata برای ChatGPT و ثبت پویای کلاینت برای کلاینت‌های سازگار ارائه می‌شوند.

جریان OAuth

  1. کلاینت MCP metadata را کشف می‌کند و برای URL دقیق MCP، پارامتر resource را می‌فرستد.
  2. کلاینت از CIMD مجاز یا DCR یک شناسهٔ کلاینت می‌گیرد.
  3. authorization endpoint، callback ثبت‌شده، state در صورت ارسال، resource و PKCE S256 را اعتبارسنجی می‌کند.
  4. کاربر از OTP و کپچا وارد می‌شود. API key نشست OTP بلافاصله به یک مجوز رضایت یک‌بارمصرف و محدود به همان درخواست تبدیل و لغو می‌شود.
  5. کاربر کسب‌وکار را انتخاب می‌کند؛ سرور کاتالوگ ابزارهای مجاز همان عضو را بارگذاری می‌کند و کاربر ابزارهای موردنیاز را جداگانه انتخاب می‌کند. ابزارهای نوشتنی با مجوز دامنه‌ای فعلی کاربر فیلتر می‌شوند و فقط پس از انتخاب صریح او اعطا می‌شوند. عضویت در لحظهٔ تایید و هنگام هر استفاده از ابزار دوباره بررسی می‌شود.
  6. authorization code تصادفی، کوتاه‌عمر، یک‌بارمصرف و به client، redirect URI، کسب‌وکار، resource و PKCE متصل صادر می‌شود.
  7. token endpoint کد را با PKCE تعویض می‌کند و access token پانزده‌دقیقه‌ای Bearer با audience همان MCP می‌دهد. Refresh token سی‌روزه فقط در صورت درخواست و رضایت offline_access صادر و در هر refresh چرخانده می‌شود.
  8. لغو refresh token، replay آن، یا لغو اتصال، تمام توکن‌های همان grant را باطل می‌کند.

مرزهای دسترسی و محافظت از داده

  • business_id فقط از رضایت OAuth یا credential سمت سرور گرفته می‌شود؛ مدل نمی‌تواند tenant درخواست را تعیین کند.
  • هر credential دقیقاً به یک کسب‌وکار وصل است. عضویت، حذف کسب‌وکار، فعال بودن کاربر، scope و audience در درخواست‌ها دوباره اعتبارسنجی می‌شوند.
  • OAuth علاوه بر scope پایه، فهرست ابزارهای انتخاب‌شده را به grant، access token و refresh token متصل می‌کند. tools/list و tools/call هر دو این فهرست را enforce می‌کنند؛ refresh اتصال این انتخاب‌ها را حفظ می‌کند. ابزار ask_hesabix_agent برای grantهای دارای محدودیت per-tool مخفی است تا اجرای داخلی Agent نتواند از allowlist عبور کند.
  • خواندن نیازمند ai:tools:read است. هر ابزار نوشتنی انتخاب‌شده علاوه بر allowlist به ai:tools:write و رضایت کاربر متصل نیاز دارد؛ scope نوشتن از RPC یا آرگومان‌های مدل قابل جعل نیست. مالک و عضو کسب‌وکار هر دو فقط ابزارهای سازگار با مجوز دامنه‌ای جاری خود را می‌بینند؛ allowlist ابزار جایگزین یا توسعه‌دهندهٔ permissionهای نرم‌افزار نیست.
  • ابزارهایی که registry برای کاربر یا کسب‌وکار جاری مجاز نمی‌کند اصلاً در فهرست MCP ظاهر نمی‌شوند و فراخوانی مستقیم‌شان نیز رد می‌شود.
  • schema ورودی ابزار قبل از handler اعتبارسنجی می‌شود؛ business/user identity از آرگومان‌های مدل پذیرفته نمی‌شود. ابزارهای حذف، ارسال خارجی، retry و ثبت قطعی با metadata اثر جانبی و سطح تأیید مناسب عرضه می‌شوند.
  • در tools/call مستقیم MCP، scope نوشتن و مجوز دامنه‌ای پیش از اجرا بررسی می‌شود، اما جریان تأیید write داخل چت حسابیکس اجرا نمی‌شود و سرور تأیید انسانیِ همان عملیات را جداگانه راستی‌آزمایی نمی‌کند. بنابراین کلاینت MCP باید پیش از ارسال هر write، خلاصهٔ عملیات و آرگومان‌های مهم را نشان دهد و تأیید صریح همان عملیات را بگیرد. داشتن scope نوشتن به‌تنهایی تأیید تراکنش نیست؛ اگر کلاینت این توقف و تأیید را تضمین نمی‌کند، اتصال را فقط‌خواندنی نگه دارید.
  • ایجنت MCP در حالت Analyzer اجرا می‌شود و خودکار عملیات نوشتنی انجام نمی‌دهد.
  • authorization code، access token، refresh token و مجوز رضایت خام در دیتابیس ذخیره نمی‌شوند؛ hash ذخیره می‌شود. کد و توکن در log ثبت نمی‌شوند.
  • Redirect URI باید دقیقاً با ثبت کلاینت برابر و میزبانش در allowlist deployment باشد. CIMD فقط از HTTPS و hostهای از پیش مجاز خوانده می‌شود و redirect دنبال نمی‌شود.
  • Origin مرورگرهای MCP باید در allowlist باشد؛ درخواست‌های غیرمرورگری بدون Origin پذیرفته می‌شوند.
  • توکن OAuth فقط به resource canonical همین سرور صادر می‌شود. توکن منقضی، لغوشده یا متعلق به resource دیگر رد می‌شود.

مدیریت و سازگاری

APIهای قبلی credential دستی همچنان موجودند:

  • POST /api/v1/ai/mcp/connections ساخت Bearer token محدود به کسب‌وکار
  • GET /api/v1/ai/mcp/connections?business_id=<id> فهرست اتصالات
  • DELETE /api/v1/ai/mcp/connections/<connection_id> لغو اتصال؛ برای OAuth، کل grant و refresh tokenهایش نیز لغو می‌شوند

سرور نسخه‌های MCP 2025-03-26، 2025-06-18 و 2025-11-25 را با initialize و نسخهٔ 2026-07-28 را با متادیتای هر درخواست و server/discover می‌پذیرد. درخواست‌های modern باید MCP-Protocol-Version و Mcp-Method را مطابق body بفرستند؛ درخواست‌های tools/call، resources/read و prompts/get همچنین به Mcp-Name منطبق نیاز دارند. Promptهای دامنه‌ای فقط زمانی فهرست می‌شوند که دستهٔ ابزار مربوطه برای اتصال موجود باشد و مدل را به همان tenant و ابزارهای مجاز محدود می‌کنند.

عملیات نگهداری

کلید MCP_PUBLIC_BASE_URL باید با آدرس اتصال خارجی و proxy TLS هم‌خوان باشد. بعد از تغییر دامنهٔ عمومی، metadata، redirect allowlist و URL ثبت‌شده در کلاینت‌ها را به‌روز کنید. ثبت DCR و endpointهای OAuth دارای rate limit هستند. اتصال‌ها را از API مدیریت لغو کنید؛ نشست‌های OAuth در خروجی فهرست اتصال‌ها، مثل credentialهای دستی، به شکل یکپارچهٔ قابل‌نمایش نیستند، اما با revoke اتصال OAuth هر grant از endpoint مدیریت اتصال قابل باطل‌سازی است.