درس ۳۳ از ۳۳

جمع‌بندی course ۲ و قدم‌های بعدی (Course 2 wrap & next steps)

هدف یادگیری: ترکیب همه چیز در یک سیستم agentic که ارزش واقعی تولید می‌کند.

به‌عنوان تمرین جمع‌بندی، یک agent کدنویسی بسازید که از سه MCP server استفاده می‌کند: - Filesystem — برای read فایل‌های repo (resources + roots) - Git — برای commit، diff، branch (tools) - GitHub — برای ساخت PR (tools) + sampling برای تولید توضیح PR

این سیستم یک نمونه واقعی است: کاربر می‌گوید «این bug را fix کن و PR بفرست»، Claude Code (host) با Filesystem فایل‌ها را می‌خواند، با Git تغییرات را commit می‌کند، با GitHub یک PR می‌سازد و توضیح PR را با sampling از LLM خود host می‌گیرد.

قدم‌های بعدی

  • changelog رسمی spec را دنبال کنید: https://modelcontextprotocol.io/specification/
  • modelcontextprotocol/servers را به‌عنوان یادگیری بخوانید — هر چند ماه serverهای جدید اضافه می‌شود.
  • در مورد primitiveهای جدید (مثل Tasks که فعلاً Experimental است) خبردار باشید.
  • تجربه‌تان را به انجمن MCP بازخورد بدهید — open standard فقط با مشارکت community بهتر می‌شود.

Cheat-sheet جهانی «اشتباهات رایج» (در کل ۳۳ lecture)

  1. STDIO loop را بلاک نکنید. ابزارهای طولانی باید async def باشند (Python) یا درست await شوند (TypeScript).
  2. Capability درست ست کنید. هر دو طرف باید در init اعلام کنند چه پشتیبانی می‌کنند؛ هرگز methodای را که negotiate نشده صدا نزنید.
  3. Protocol error را از tool error جدا کنید. خطاهای JSON-RPC (-32xxx) برای method ناشناس، param بد، خطای داخلی هستند. شکست tool از content با isError: true استفاده می‌کند تا LLM آن را بخواند.
  4. هرگز چیز غیر JSON روی stdout ننویسید در یک STDIO server. بدون print()، بدون console.log()، بدون banner.
  5. Origin را validate کنید و به 127.0.0.1 bind کنید روی serverهای Streamable HTTP محلی. DNS rebinding واقعی است.
  6. Mcp-Session-Id cryptographically secure. مثل auth-adjacent با آن رفتار کنید.
  7. Progress یکنوای صعودی. هرگز کم نکنید.
  8. بدون secret در log. spec credential، PII و جزئیات داخلی را در notifications/message ممنوع می‌کند.
  9. Hint بدهید، نه نام. در sampling، modelPreferences.hints استفاده کنید — هرگز نام مدل vendor را hard-code نکنید.
  10. Roots فقط file:// URI در spec فعلی. سمت server validate کنید path-traversal را؛ symlink هم.
  11. Resources read هستند؛ tools act می‌کنند. اگر «resource» شما state را تغییر می‌دهد، refactor به tool.
  12. Prompts user-controlled هستند. LLM نباید خودسرانه prompts/get صدا بزند.
  13. Notification بدون id. انتظار response نداشته باشید.
  14. Pagination مهم است. همه methodهای */list از cursor/nextCursor پشتیبانی می‌کنند.
  15. Header MCP-Protocol-Version روی هر request Streamable HTTP بعد از init.

خلاصه فصل

  • MCP «USB-C برای AI applications» است: یک پروتکل باز روی JSON-RPC 2.0 که مسئله M×N integration را به M+N خلاصه می‌کند.
  • سه نقش، دو لایه، شش primitive: Host/Client/Server؛ Data/Transport؛ tools/resources/prompts (سمت server) و sampling/elicitation/roots (سمت client) به‌علاوه utility (logging, progress, completion).
  • Tools model-controlled، resources app-controlled، prompts user-controlled — این تمایز سه‌گانه پایه طراحی UX در host است.
  • STDIO برای local، Streamable HTTP برای remote. STDIO ساده و بدون overhead؛ Streamable HTTP با SSE برای جریان، session id برای state، و Last-Event-ID برای resumability.
  • امنیت تقاضای صریح spec است: validate Origin، bind به 127.0.0.1، session id cryptographically random، بدون secret در log، و file://-only roots با validation path-traversal.
  • ابزار debug رسمی Inspector است: UI روی port 6274، proxy روی 6277، CLI mode برای CI، tabهایی برای هر primitive.

تمرین‌های پیشنهادی

  1. پروژه پایه: یک Python FastMCP server بسازید با یک tool (محاسبه مالیات بر ارزش افزوده ایران)، یک resource (config://currency-rates) و یک prompt (generate-invoice). با mcp dev server.py اجرا کنید و در Inspector تست کنید.

  2. پروژه integration: یک MCP server برای Zoho Books بنویسید که tools برای create-invoice و get-customer دارد. از sampling استفاده کنید تا server بتواند توضیح فاکتور به فارسی تولید کند بدون اینکه API key مدل را داشته باشد.

  3. پروژه امنیت: یک Streamable HTTP server بسازید که OAuth 2.1 + PKCE را پیاده می‌کند، Origin را validate می‌کند، به 127.0.0.1 bind است، و session id‌های cryptographically random صادر می‌کند. با curl یک حمله DNS rebinding شبیه‌سازی کنید و verify کنید که server رد می‌کند.

  4. پروژه resumability: یک tool طولانی (مثلاً سه دقیقه index کردن یک repo) بنویسید که notifications/progress emit می‌کند. سپس server را در میانه کار kill کنید و verify کنید که client با Last-Event-ID reconnect می‌کند و کار را از همان جا ادامه می‌دهد.

  5. پروژه agent: یک سیستم سه serverی (Filesystem + Git + GitHub) بسازید که از Claude Code به‌عنوان host استفاده می‌کند. به Claude بگویید «یک bug در src/main.py پیدا کن، fix کن، و یک PR با توضیح فارسی بفرست». مراقب باشید سکرت در log نرود.

منابع تکمیلی

پایان فصل ۵. در فصل بعد، ساخت agent با Claude Code و subagentها را می‌بینیم — جایی که MCP در کنار skills و hooks کنار هم قرار می‌گیرند تا یک workflow کامل توسعه بسازند.