چیت‌شیت

پروتکل کانتکست مدل (MCP)

Model Context Protocol (MCP)

ساخت، فراخوانی و ارائه‌ی سرورهای بی‌وضعیت MCP نسخه‌ی 2026-07-28 روی stdio و پروتکل HTTP جریانی.

۱۲ بخش
۷ درس مرتبط
کد و دستورها عیناً از دوره‌ی اصلی

فهرست مطالب

وظایف
تعریف و اجرای یک ابزار
یک tools/call روی HTTP
معماری
شناسایی، فهرست، فراخوانی
متدها
مفاهیم کلیدی
پیش‌فرض‌ها
عیب‌یابی
واژه‌نامه
پرسش و پاسخ
نکات

وظایف

کار و کد

وظیفه	کد
ارائه روی stdio	`python3 main.py`
اجرای دموی stdio	`python3 main.py --demo`
ارائه با پروتکل HTTP جریانی	`python3 main.py --serve`
آزمون ارزیابی سرور HTTP	`python3 main.py --probe`
شناسایی یک سرور	`make_request(1, "server/discover")`
فهرست کردن ابزارها	`make_request(2, "tools/list")`
فراخوانی یک ابزار	`make_request(5, "tools/call", {"name": "<tool>", "arguments": <args>})`
افزودن طرف ارتباط قدیمی (legacy)	`client.add_server("<name>", <transport>, allow_legacy=True)`

تعریف و اجرای یک ابزار

کد

python

TOOLS = [{
    "name": "notes_search",                 # نامی که مدل می‌بیند
    "description": "Search note titles and bodies by keyword.",
    "inputSchema": {"type": "object",       # اسکیمای JSON آرگومان‌ها
        "properties": {"query": {"type": "string"}},
        "required": ["query"]},
    "annotations": {"readOnlyHint": True},  # صرفاً راهنما
}]
def handle_tools_call(params):
    executor = TOOL_EXECUTORS.get(params.get("name"))
    if executor is None:                    # ابزار ناشناخته
        return complete({"content": [...], "isError": True})
    content = executor(params.get("arguments", {}))
    return complete({"content": content, "isError": False})

یک tools/call روی HTTP

کد

text

POST /mcp                         # یک پیام به ازای هر POST
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28  # برابر با نسخه‌ی _meta
Mcp-Method: tools/call            # برابر با متد JSON-RPC
Mcp-Name: notes_search            # برابر با params.name
{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
 "params": {"name": "notes_search", "arguments": {"query": "MCP"},
  "_meta": {
   "io.modelcontextprotocol/protocolVersion": "2026-07-28",
   "io.modelcontextprotocol/clientCapabilities": {}}}}

معماری

شناسایی، فهرست، فراخوانی

گام‌به‌گام

کلاینتمتد server/discover را همراه نسخه و قابلیت‌ها در params._meta ارسال می‌کند.
سرورsupportedVersions و capabilities را برمی‌گرداند. هیچ نشستی شروع نمی‌شود.
کلاینتمتد tools/list را می‌فرستد. فهرستی مرتب‌شده همراه ttlMs و cacheScope دریافت می‌کند.
کلاینتمتد tools/call را با name، arguments و یک id جدید می‌فرستد.
سرورمتد validate_request() بخش params._meta را بررسی می‌کند. نسخه نامعتبر خطای -32022 می‌دهد.
سرورتابع dispatch() بر اساس method به handle_tools_call() مسیریابی می‌کند.
سرورویژگی resultType را با مقدار complete همراه با content و isError برمی‌گرداند.

متدها

دستورها

دستور	کارکرد
`server/discover`	نسخه‌ها، قابلیت‌ها، دستورالعمل‌ها، هویت سرور
`tools/list`	فهرست کردن ابزارها. کش‌پذیر
`tools/call`	اجرای یک ابزار. بلوک‌های محتوا را برمی‌گرداند
`resources/list`	فهرست داده‌های آدرس‌دهی‌شده با URI. کش‌پذیر
`resources/read`	خواندن یک منبع با URI
`prompts/list`, `prompts/get`	فهرست و رندر قالب‌های پرامپت
`subscriptions/listen`	استریم بلندمدت POST برای رویدادهای تغییر
`notifications/cancelled`	لغو یک درخواست روی stdio. بدون پاسخ

مفاهیم کلیدی

مفهوم‌ها

هسته‌ی بی‌وضعیت: هر درخواست فراداده‌ی لازم برای تفسیر خود را حمل می‌کند.
فراداده‌ی درخواست: نسخه و قابلیت‌ها الزامی هستند. clientInfo توصیه می‌شود.
نتیجه‌ی کامل: در هر پاسخ موفق، مقدار resultType برابر با complete است.
نتیجه کش‌پذیر: فهرست‌ها، خواندن‌ها و شناسایی دارای ttlMs و cacheScope هستند.
یادداشت‌های ابزار: readOnlyHint و destructiveHint صرفاً راهنما هستند. اعمال بر عهده‌ی سرور است.
stdio: زیرفرایند اجراشده توسط کلاینت. خروجی JSON روی stdout، لاگ‌ها روی stderr.
پروتکل HTTP جریانی: یک اندپوینت /mcp. هر پیام یک درخواست POST جدید است.
دوران نسخه‌های قدیمی: تا نسخه‌ی 2025-11-25، ابتدا initialize و سپس notifications/initialized.

پیش‌فرض‌ها

تنظیم	پیش‌فرض	نکته
`PROTOCOL_VERSION`	`2026-07-28`	بازنگری مدرن در درس‌ها
`server/discover` ttl	`3_600_000`	میلی‌ثانیه، `cacheScope` عمومی (public)
`tools/list` ttl	`60_000`	میلی‌ثانیه، `cacheScope` عمومی (public)
`resources/read` ttl	`5_000`	میلی‌ثانیه، `cacheScope` اختصاصی (private)
`cache_scope`	`private`	پیش‌فرض `complete()`
`HTTP port`	`8017`	دستور `--serve` به 127.0.0.1 متصل می‌شود
`MAX_REQUEST_BYTES`	`1_048_576`	حداکثر حجم بدنه‌ی HTTP
`legacy_probe_timeout_ms`	`1_000`	مهلت زمانی برای یک آزمون ارزیابی `initialize`

عیب‌یابی

-32022
علت
نسخه پشتیبانی نمی‌شود
راه‌حل
از data.supported انتخاب کنید. تلاش مجدد با id جدید
-32602
علت
فراداده‌ی درخواست موجود نیست
راه‌حل
ثبت _meta روی تمام درخواست‌ها
HTTP 400 -32020
علت
عدم تطابق هدر با بدنه
راه‌حل
مطابقت دادن دقیق نسخه، متد و نام
HTTP 403 روی POST
علت
Origin مجاز نیست
راه‌حل
افزودن مبدأ (origin) دقیق به لیست مجاز
HTTP 405
علت
متد GET یا DELETE روی /mcp
راه‌حل
استفاده از POST، و subscriptions/listen برای رویدادها
کلاینت stdio در پارس کردن ناموفق است
علت
لاگ‌ها روی stdout نوشته شده‌اند
راه‌حل
نوشتن پیام‌های تشخیصی روی stderr
HTTP 401
علت
توکن نامعتبر، منقضی‌شده یا با مخاطب نادرست
راه‌حل
دریافت توکن برای این منبع
403 insufficient_scope
علت
ابزار به دامنه‌ی بیشتری نیاز دارد
راه‌حل
ارتقای دسترسی با دامنه‌ی اعلام‌شده در چالش

واژه‌نامه

اصطلاح‌ها

JSON-RPC 2.0: بسته‌بندیِ (envelope) هر درخواست، پاسخ و اعلان در MCP.
SSE: پاسخ از نوع text/event-stream. ابتدا اعلان‌ها، سپس پاسخ نهایی.
MRTR: درخواست چند مرحله‌ای (Multi Round-Trip Request). ابتدا input_required، سپس تلاش مجددِ تازه.
PKCE: مدل اعتبارسنج و چالش S256. محافظت در برابر کد رهگیری‌شده.
CIMD: سند فراداده‌ی HTTPS که URL آن همان شناسه‌ی کلاینت است.
DCR: ثبت‌نام پویا و منسوخ‌شده‌ی کلاینت جهت سازگاری.
RFC 9728: فراداده‌ی منبع حفاظت‌شده. سرورهای احراز هویت را مشخص می‌کند.

پرسش و پاسخ

خطای ابزار یا خطای پروتکل؟: isError: true برای فراخوانی معتبری که شکست بخورد. خطای JSON-RPC برای درخواست نادرست.
آیا سرور می‌تواند کلاینت را فراخوانی کند؟: خیر. مقدار input_required را برمی‌گرداند. کلاینت با id جدید دوباره تلاش می‌کند.
چگونه لغو کنم؟: در stdio: ارسال notifications/cancelled. در HTTP: بستن استریم پاسخ.
آیا stdio به OAuth نیاز دارد؟: خیر. احراز هویت مختص بسترهای انتقال HTTP است.
چه زمانی initialize بفرستم؟: فقط به طرف ارتباط قدیمی مجاز. هیچ‌وقت به‌صورت پیش‌فرض نفرستید.

نکات

نکته‌ها

آیتم‌های فهرست را مرتب کنید. ترتیب پایدار کلیدهای کش و کانتکست مدل پایداری می‌سازد.
سرورهای محلی را به 127.0.0.1 متصل کنید. بررسی مبدأ احراز هویت نیست.
مبدأها را دقیقاً مطابقت دهید. بررسی پیشوند پسوندهای مهاجم را می‌پذیرد.
توکن حامل (bearer) را در Authorization بفرستید. هرگز در URL قرار ندهید.
یک دستگیره‌ی وضعیت صریح برگردانید. مسیریابی چسبنده در تغییر مسیر خودکار هنگام خرابی از کار می‌افتد.
در تداخل نام ابزار، پیشوند اضافه کنید یا رد کنید. هرگز بازنویسی (overwrite) نکنید.

درس‌هایی که این موضوع را از صفر می‌سازند