راهنما

MCP و مهارت چیست؟

MCP (Model Context Protocol) یک استاندارد باز است که به دستیارهای هوش مصنوعی مثل Claude، Cursor و Copilot اجازه می‌دهد به ابزارها و داده‌های بیرونی وصل شوند. هر سرور MCP چند «ابزار» دارد؛ مثلاً سرور دیجی‌کالا ابزار جستجوی کالا دارد و دستیار هر وقت لازم بداند آن را صدا می‌زند.

مهارت (Agent Skill) یک پوشه با فایل SKILL.md است: دستورالعمل‌هایی که Claude فقط وقتی لازم است می‌خواند. مهارت کدی اجرا نمی‌کند و به کلید یا اینترنت نیاز ندارد؛ فقط دانش و روش کار را به دستیار می‌دهد، مثل قواعد نیم‌فاصله یا روش درست ذخیره تاریخ شمسی.

پیش‌نیازها

• سرورهایی که با npx اجرا می‌شوند به Node.js نسخه ۲۰ یا بالاتر نیاز دارند. بعد از نصب، node -v را در ترمینال امتحان کنید.
• سرورهای پایتونی که با uvx اجرا می‌شوند به uv نیاز دارند.
• روی ویندوز، در صفحه هر ابزار گزینه «روی ویندوز اجرا می‌کنم» را بزنید تا دستور با cmd /c ساخته شود؛ Claude Desktop و Claude Code بدون آن نمی‌توانند npx را اجرا کنند.
• بعد از تغییر فایل تنظیمات، برنامه (Claude Desktop، Cursor و…) را کامل ببندید و دوباره باز کنید.

نکته‌های مخصوص ایران

سرویس‌های ایرانی و VPN

بعضی سرویس‌های ایرانی به درخواست‌هایی که از IP خارج می‌آیند پاسخ نمی‌دهند. اگر VPN یا پراکسی روشن است و سرور MCP خطای اتصال یا ۴۰۳ می‌دهد، دامنه‌های ایرانی را در کلاینت VPN «مستقیم» کنید (split tunneling). در v2ray و کلاینت‌های مشابه، قانون geoip:ir یا فهرست آماده دامنه‌های ایرانی را در بخش Direct بگذارید. ابزارهایی که فقط از IP ایران کار می‌کنند در صفحه‌شان برچسب «فقط از IP ایران» دارند.

سرویس‌های خارجی و پراکسی

برعکس، سرورهایی که به سرویس خارجی وصل می‌شوند ممکن است از ایران مسدود باشند. متغیر HTTPS_PROXY را در بخش env همان سرور بگذارید:

"env": {
  "HTTPS_PROXY": "http://127.0.0.1:10809",
  "NODE_USE_ENV_PROXY": "1"
}

کتابخانه‌های پایتون مثل requests و httpx این متغیر را خودشان می‌خوانند. Node.js فقط وقتی آن را رعایت می‌کند که NODE_USE_ENV_PROXY=1 هم تنظیم شده باشد (در نسخه‌های جدید Node). پورت را با پورت پراکسی خودتان عوض کنید.

نصب بسته‌ها

اگر npx در دانلود بسته گیر می‌کند، پراکسی npm را تنظیم کنید:npm config set proxy http://127.0.0.1:10809 و npm config set https-proxy http://127.0.0.1:10809. Docker Hub به IPهای ایران پاسخ نمی‌دهد؛ برای سرورهایی که با Docker اجرا می‌شوند از پراکسی یا mirror استفاده کنید.

APIهای غیررسمی

دیجی‌کالا و دیوار API عمومی مستند برای این کار ندارند و سرورهای ما از همان نشانی‌هایی استفاده می‌کنند که وب‌سایتشان استفاده می‌کند. این نشانی‌ها ممکن است بدون اطلاع تغییر کنند. آن‌ها را برای کار شخصی و آزمایشی به کار ببرید، درخواست انبوه نفرستید و قوانین استفاده هر سرویس را رعایت کنید.

امنیت

• سرور MCP یک برنامه است که روی سیستم شما و با دسترسی شما اجرا می‌شود. فقط ابزاری را نصب کنید که کد منبعش را دیده‌اید یا به سازنده‌اش اعتماد دارید.
• کلید API را در فایلی که در گیت ثبت (commit) می‌شود نگذارید. پیکربندی VS Code در این سایت کلیدها را به‌صورت ورودی محرمانه می‌سازد تا هنگام اجرا پرسیده شوند.
• کلیدهایی که در صفحه ابزارها وارد می‌کنید فقط در مرورگر خودتان در متن دستور قرار می‌گیرند و به جایی ارسال نمی‌شوند.
• برای ابزارهایی که پول جابه‌جا می‌کنند یا پیامک می‌فرستند، از کلید آزمایشی (sandbox) شروع کنید.

برای سازندگان ابزار

ساده‌ترین راه ساخت سرور MCP، کیت‌های رسمی TypeScript و Python است. سرورهای ساخت بازارچه در پوشه servers/ مخزن ما نمونه‌های کوتاهی هستند که می‌توانید از آن‌ها شروع کنید.

1. سرور را در npm یا PyPI منتشر کنید تا با npx یا uvx نصب شود.
2. توضیح ابزارها را برای مدل به انگلیسی و دقیق بنویسید و ورودی فارسی را بپذیرید.
3. در صفحه ثبت ابزار مشخصات را وارد کنید و فایل ساخته‌شده را بفرستید.

API فهرست

کل فهرست به‌صورت JSON در /api/catalog.json در دسترس است: نام، خلاصه، دسته، ابزارها، تنظیمات نصب و توضیحات هر ابزار. این فایل در هر بار ساخت سایت دوباره تولید می‌شود و برای ساختن افزونه یا کلاینت خودتان آزاد است.

const res = await fetch('{SITE}/api/catalog.json');
const { items } = await res.json();
const persian = items.filter((i) => i.category === 'language');