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

91 lines
20 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# اتصال امن دستیارهای هوش مصنوعی به حسابیکس از طریق 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` درخواست گرفته نمی‌شود:
```env
MCP_PUBLIC_BASE_URL=https://hsxn.hesabix.ir
```
HTTPS در production اجباری است. سپس migrationها را اجرا کنید:
```powershell
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 مدیریت اتصال قابل باطل‌سازی است.