ساخت یک سرور Python MCP از صفر

پروتکل مدل کانتکست (MCP) اکنون به یک استاندارد صنعتی تبدیل شده است. تعداد دانلودهای ماهانه SDK آن به ۹۷ میلیون رسیده است. تمام ابزارهای اصلی هوش مصنوعی از آن استفاده می‌کنند. بیشتر راهنماها فقط نحوه نصب سرورهای موجود را نشان می‌دهند. این راهنما به شما نشان می‌دهد که چگونه با استفاده از Python و GitHub API سرور خودتان را بسازید.

MCP چیست؟

این پروتکلی است که به کلاینت‌های هوش مصنوعی اجازه می‌دهد سرویس‌های خارجی را فراخوانی کنند. سرور شما درخواست‌های ابزارهایی مانند Claude یا Cursor را مدیریت می‌کند.

سه بخش اصلی MCP:

  • ابزارها (Tools): توابعی که هوش مصنوعی برای انجام یک اقدام یا دریافت داده آن‌ها را فراخوانی می‌کند.
  • منابع (Resources): نقاط پایانی داده‌های فقط-خواندنی مانند فایل‌ها یا رکوردهای پایگاه داده.
  • پرامپت‌ها (Prompts): قالب‌های دستورالعمل قابل استفاده مجدد برای جریان‌های کاری منسجم.

راه‌اندازی پروژه

یک دایرکتوری ایجاد کنید و کتابخانه‌های لازم را با استفاده از uv نصب کنید:

mkdir github-mcp-server
cd github-mcp-server
uv init .
uv add "mcp[cli]" httpx

ساخت سرور

از FastMCP برای انجام کارهای سنگین استفاده کنید. یک سرور MCP خوب از سه فایل مشخص استفاده می‌کند: server.py ، pyproject.toml و یک فایل اختیاری .env برای توکن GitHub شما.

نکات حرفه‌ای برای توسعه:

  • از مدل‌های Pydantic برای خروجی ابزارها استفاده کنید. این کار به جای رشته‌های متنی نامنظم، داده‌های ساختاریافته‌ای را به هوش مصنوعی ارائه می‌دهد.
  • docstringهای شفاف بنویسید. هوش مصنوعی این‌ها را می‌خواند تا تصمیم بگیرد چه زمانی از ابزار شما استفاده کند.
  • ورودی‌های عددی را محدود (Clamp) کنید. مدل‌های هوش مصنوعی اغلب اعداد غیرمنتظره‌ای مانند ۰ یا ۱۰۰ ارسال می‌کنند.
  • استثناها (Exceptions) را مدیریت کنید. کرش کردن سرور شما می‌تواند کل اتصال را قطع کند.

تست و استقرار

منتظر نمانید تا در Claude تست کنید. ابتدا از MCP Inspector استفاده کنید. دستور زیر را اجرا کنید:

uv run mcp dev server.py

این دستور یک رابط کاربری محلی در http://localhost:5173 باز می‌کند. شما می‌توانید ابزارها، منابع و پرامپت‌ها را در یک جا تست کنید.

اتصال به Claude Desktop:

فایل تنظیمات (config) خود را برای شامل کردن سرورتان به‌روزرسانی کنید. از مسیر کامل فایل server.py استفاده کنید. همیشه به جای دستور ساده python از uv run استفاده کنید تا از خطاهای محیطی (environment errors) جلوگیری شود.

اتصال به Claude Code:

از دستور CLI زیر استفاده کنید:

claude mcp add github-tools -- uv run python /path/to/server.py

ساخت سرورهای MCP سفارشی به شما اجازه می‌دهد داده‌های زنده را به جریان‌های کاری هوش مصنوعی خود بیاورید.

منبع: https://dev.to/moksh/building-a-python-mcp-server-from-scratch-a-practical-github-api-guide-397k

انجمن یادگیری اختیاری: https://t.me/GyaanSetuAi