سرویس MCP هُما
عیبیابی
مسیر عیبیابی — از کجا شروع کنم؟
قبل از هر چیز، دو ابزار تشخیصی را به ترتیب امتحان کنید — هم در دستیار و هم با دکمهٔ تست زنده همین صفحه:
homa_whoami— آیا توکن معتبر است؟ به کدام پرتال وصل است؟ سطح Owner/Developer/Read-only چیست؟ چه scopeهایی دارد؟homa_get_capabilities— کدام ابزارها برای این توکن available هستند و کدامها به scope اضافه نیاز دارند؟
💬 «این توکن به کدام پرتال وصل است و چه ابزارهایی در دسترس دارم؟»
دستیار اول homa_whoami را صدا میزند، بعد homa_get_capabilities — خروجی دوم دقیقاً میگوید مثلاً warehouse_get_inventory یا finance_list_invoices برای توکن شما فعال است یا نه.
اگر دستیار میگوید «ابزار پیدا نشد» یا «دسترسی ندارید»، همیشه با همین دو ابزار شروع کنید — ۹۰٪ مواقع مشکل از scope یا توکن منقضی است، نه از خود MCP.
مشکلات اتصال و راهاندازی
| چه میبینید؟ | چکار کنید؟ |
|---|---|
| دستیار به پرتال وصل نمیشود | در اتصال مستقیم (HTTP) مطمئن شوید فیلد url برابر https://www.HomaCRM.com/mcp و هدر Authorization: Bearer <token> درست است. در روش پکیج، از پنل دوباره «کپی کانفیگ با توکن» بزنید و مطمئن شوید HOMA_API_TOKEN در env ست شده است. |
| سرور هُما در فهرست MCP نیست | کانفیگ را ذخیره کنید، Cursor یا Claude را کاملاً ببندید و دوباره باز کنید. در روش پکیج، Node.js نسخهٔ ۱۸+ لازم است و مسیر args باید به dist/index.js اشاره کند. در روش مستقیم، دستیار باید ترنسپورت HTTP (فیلد url) را پشتیبانی کند. |
پیام HOMA_API_TOKEN is not set در stderr | توکن در بلوک env فایل mcp.json نیست یا نام متغیر اشتباه است — دقیقاً HOMA_API_TOKEN باشد. |
| پیام خطای اتصال یا شبکه / timeout | اینترنت و دسترسی به www.HomaCRM.com را بررسی کنید؛ VPN یا فایروال سازمانی ممکن است مسدود کند. خطای NETWORK_ERROR یعنی درخواست اصلاً به سرور نرسیده. |
| توکن نامعتبر یا منقضی (۴۰۱) | توکن تازه از پنل بگیرید و کانفیگ را دوباره کپی کنید. توکن ثانویهٔ غیرفعالشده یا حذفشده فوراً قطع میشود. |
| MCP وصل است ولی هیچ ابزاری کار نمیکند | homa_whoami را تست کنید. اگر این هم خطا داد مشکل auth است؛ اگر OK بود homa_get_capabilities را ببینید کدام ابزارها available: false هستند. |
مشکلات دسترسی (Scope)
هر ابزار MCP به یک scope مشخص در REST API نیاز دارد. توکن فقطخواندنی (readonly) ابزارهای نوشتنی ✍️ را نمیبیند — حتی اگر scope نوشتنی داشته باشد.
| ماژول / کار | scope لازم | ابزارهای مرتبط |
|---|---|---|
| مخاطبین — خواندن | crm:contacts:read | crm_search_contacts, crm_get_contact, crm_count_contacts |
| گروههای مخاطب | crm:groups:read | crm_list_contact_groups |
| معاملات و قیف فروش | crm:deals:read / crm:pipelines:read | crm_list_deals, crm_list_pipelines |
| سرنخها | crm:leads:read | crm_list_leads |
| تیکت پشتیبانی — خواندن | support:tickets:read | support_list_tickets, support_get_ticket, support_search_tickets |
| دانشنامه | knowledge:read | knowledge_search, knowledge_get_entry |
| کارتابل | kartable:tasks:read / kartable:tasks:write | kartable_list_tasks, kartable_get_task, kartable_create_task, kartable_comment_task, kartable_update_task_status |
| اعتبار و خطوط پیامک | messaging:credit:read / messaging:numbers:read | messaging_get_credit, messaging_list_numbers |
| گزارش ارسال/دریافت | messaging:reports:read | messaging_outbox_report, messaging_inbox_report |
| پیشنویس و WhoIS | messaging:drafts:read / messaging:whois:read | messaging_list_drafts, messaging_get_draft, messaging_get_whois_profile |
| ارسال گروهی و لیست سیاه | messaging:bulk:read / messaging:bulk:write / messaging:blacklist:read | messaging_list_programs, messaging_get_program, messaging_create_bulk_send, messaging_list_blacklist |
| نمایندگی (پرتالهای زیرمجموعه) | deputy:portals:read / deputy:stats:read / deputy:portal:create / deputy:portals:write | deputy_list_portals, deputy_get_portal, deputy_get_portal_credit, deputy_get_portal_stats, deputy_stats, deputy_create_portal, deputy_charge_credit |
| انبار | warehouse:products:read / warehouse:inventory:read (write برای ثبت) | warehouse_list_products, warehouse_list_categories, warehouse_get_inventory, warehouse_list_stocktakings |
| مالی | finance:invoices:read / finance:payments:read / finance:accounts:read / finance:treasury:read | finance_list_invoices, finance_get_invoice, finance_list_payments, finance_get_accounts_tree, finance_list_cheques, finance_list_funds, finance_list_banks |
| تولید | production:orders:read / production:formulas:read | production_list_orders, production_get_order, production_list_formulas |
| حقوق و حضور و غیاب | payroll:periods:read / payroll:runs:read / payroll:employees:read / payroll:attendance:read / payroll:requests:read / payroll:loans:read / payroll:payslips:read | payroll_list_periods, payroll_list_runs, payroll_get_run_summary, payroll_list_employees, payroll_get_employee, payroll_list_attendance, payroll_list_requests, payroll_list_loans, payroll_get_payslip_summary |
| جلسات · باشگاه · کیف پول · گزارشها | meetings:read / club:members:read / wallet:read / reports:read | meetings_list, meetings_get, club_list_members, club_get_member, wallet_get_balance, wallet_list_transactions, reports_sales_summary, reports_sms_usage |
| فایل و اعلان (نوشتنی) | files:write / notifications:write | files_upload, notifications_send |
| ابزارهای کاربردی | بدون scope | utilities_get_datetime, utilities_generate_qrcode |
| سیستم | system:packages:read | system_list_packages (وضعیت سرویس: بدون scope) |
| نوشتن (تیکت، CRM، پیامک، انبار، مالی…) | *:write یا messaging:send | توکن Developer یا Owner — Read-only هرگز نمیتواند |
خطای E1003 یا E2003 با پیام Missing required scope یعنی توکن معتبر است ولی scope آن ماژول را ندارد. در پنل توکن ثانویه با دسترسی مناسب بسازید یا از Owner استفاده کنید.
admin:full روی توکن اصلی همه scopeها را باز میکند.
ابزارهای نوشتنی ✍️ و تأیید (confirm)
همهٔ ابزارهایی که داده ثبت یا تغییر میدهند — از support_create_ticket تا messaging_send_sms — بدون confirm: true اجرا نمیشوند.
| پیام / رفتار | معنی و راهحل |
|---|---|
| CONFIRMATION_REQUIRED | دستیار هنوز تأیید شما را نگرفته — طبیعی است. به دستیار بگویید «بله، تأیید میکنم» تا confirm: true بفرستد. هیچ درخواست REST تا قبل از تأیید ارسال نمیشود. |
| دستیار میگوید انجام داد ولی چیزی ثبت نشده | احتمالاً فقط پیشنمایش داده — scope نوشتنی ندارید یا confirm رد شده. support_get_ticket یا crm_search_contacts را برای بررسی واقعی صدا بزنید. |
| ارسال پیامک شکست خورد | scope messaging:send، اعتبار کافی (messaging_get_credit)، خط فعال (messaging_list_numbers) و شمارهٔ گیرندهٔ معتبر (09…) را چک کنید. |
| ساخت معامله خطا میدهد | اول crm_list_pipelines — pipelineId و stageId باید از خروجی واقعی پرتال باشد، نه حدس دستیار. |
| ساخت مخاطب — ۴۰۹ Duplicate | موبایل تکراری است. با crm_search_contacts مخاطب موجود را پیدا کنید؛ برای ویرایش crm_update_contact ✍️. |
| پاسخ به تیکت بسته | تیکتهای بسته پاسخ نمیپذیرند — وضعیت را با support_get_ticket ببینید؛ تیکت جدید بسازید. |
ابزارهای نوشتنی فعال:
support_create_ticket, support_reply_ticket, support_followup_ticket, support_request_callback, support_close_ticket,
crm_create_contact, crm_update_contact, crm_delete_contact,
crm_create_group, crm_update_group, crm_delete_group,
crm_create_deal, crm_update_deal, crm_delete_deal,
crm_create_lead, crm_update_lead, crm_delete_lead,
messaging_send_sms, messaging_create_draft, messaging_update_draft, messaging_delete_draft, messaging_create_bulk_send,
kartable_create_task, kartable_comment_task, kartable_update_task_status,
deputy_create_portal, deputy_charge_credit,
warehouse_create_product, warehouse_update_product, warehouse_create_stock_movement,
finance_create_invoice, finance_record_payment,
files_upload, notifications_send
عیبیابی ماژولبهماژول
🧭 پرتال و جستجوی سراسری
homa_searchبخشهای بدون scope را درskippedگزارش میکند — اگر فقط مخاطب میآید یعنی scope تیکت ندارید.homa_stats_overviewهم scope-aware است؛ بخش انبار/مالی بدون دسترسی «skipped» میشود.
👥 CRM
- جستجو نتیجه نمیدهد: شماره را با
09امتحان کنید؛ جستجو substring است نه دقیق. - جزئیات حساس (کد ملی، آدرس): فقط
crm_get_contact— در نتایج جستجو عمداً حذف شدهاند. - گروه خالی:
crm_list_contact_groupsنیاز بهcrm:groups:readدارد، جدا از contacts:read.
🎫 پشتیبانی
- تیکت پیدا نمیشود: شناسه را از
support_list_ticketsبگیرید — ID حدسی اشتباه است. - اقدامهای جدید (پاسخ، پیگیری، تماس): همه
support:tickets:write+ confirm میخواهند.
✉️ پیامک
- گزارش خالی: بازهٔ تاریخ (
fromDate/toDate) را گشاد کنید؛ فرمت ISO یا YYYY-MM-DD. - خط ارسال:
senderIdازmessaging_list_numbers— عدد مثبت = ID خط،-11= Black List. - WhoIS: فقط وقتی کاربر صریحاً بخواهد — دادهٔ هویتی حساس است.
📦 انبار · 💰 مالی · 🏭 تولید · 🧾 حقوق
- ماژول تازه اضافه شده: scope مربوطه را در توکن ثانویه فعال کنید — Read-only پیشفرض ممکن است فقط CRM/Support داشته باشد.
- موجودی صفر:
warehouse_get_inventoryموجودی خالص (ورود منهای خروج) را نشان میدهد — کالا را باsearchیاproductIdدقیق مشخص کنید. - فاکتور پیدا نمیشود:
finance_list_invoicesبا فیلترstatus(paid/unpaid/partial). - حقوق:
payroll_get_run_summaryفقط جمعها را میدهد — فیش فردی در API/MCP نیست. - تولید: پیشرفت از نسبت
plannedQtyبهproducedQtyدرproduction_get_order.
کدهای خطا و پیامهای رایج
| کد / HTTP | معنی | اقدام |
|---|---|---|
| 401 | توکن نامعتبر یا منقضی | توکن تازه + کپی کانفیگ |
| 403 / E1003 / E2003 | scope کافی نیست | توکن با scope مناسب یا homa_get_capabilities |
| 404 | رکورد پیدا نشد (تیکت، مخاطب، فاکتور…) | ID را از لیست/جستجو بگیرید |
| 409 | تعارض (موبایل تکراری) | جستجو + update بهجای create |
| 429 | محدودیت نرخ درخواست | کمی صبر کنید؛ ۱۰۰ req/min per token |
| CONFIRMATION_REQUIRED | ابزار نوشتنی بدون تأیید | به دستیار تأیید دهید |
| NETWORK_ERROR | شبکه / DNS / فایروال | اتصال و دسترسی به HomaCRM.com |
💬 «چرا نمیتوانم موجودی انبار را ببینم؟»
دستیار homa_get_capabilities را چک میکند — اگر warehouse_get_inventory با available: false بود، در پنل scope warehouse:inventory:read را به توکن اضافه کنید.
مستندات REST کاملتر خطاها را توضیح میدهد: Error Codes · مستندات MCP · صفحهٔ سرویس MCP
اگر مشکل حل نشد، با support_create_ticket ✍️ یا پنل پشتیبانی هُما تماس بگیرید — requestId در پاسخ خطا را ضمیمه کنید.
نکات
- با دستیار بپرسید توکن به چه چیزهایی دسترسی دارد.
- توکن ثانویه با دسترسی متناسب بسازید — برخی ابزارها (ارسال پیامک، ثبت مخاطب و تیکت) نوشتنی هستند.