Phase 13: Tools & Protocols

اصول MCP: درخواست های بی شهرت و JSON-RPC

MCP مدرن هیچ دست دادن و هیچ جلسه پروتکل ندارد. هر درخواست باید دارای متادتا کافی باشد تا به تنهایی درک، مجوز، مسیر و آزمایش مجدد شود.

Type: Learn

Languages: Python

Prerequisites: Phase 13, Lessons 01 through 05

Time: ~55 minutes

اهداف یادگیری

ویژگی های اولیه سرور MCP را از ویژگی های طرف مشتری تشخیص دهید.
ایجاد درخواست های JSON-RPC 2.0 و پاسخ های معتبر برای MCP 2026-07-28. .
نسخه پروتکل، قابلیت های مشتری و هویت مشتری را به هر درخواست متصل کنید.
استفاده کنیدserver/discoverو دست و پنجهUnsupportedProtocolVersionErrorبدون دست دادن
یک درخواست مستقل را از اعتبارسنجی تا نتیجه کامل ردیابی کنید.

مشکل

یک سرور MCP می تواند دو درخواست متوالی از مشتریان مختلف، با قابلیت های مختلف، در یک فرآیند یا کارگر HTTP دریافت کند. اگر سرور آنچه که درخواست قبلی اعلام کرده است را به یاد داشته باشد، می تواند مجوزهای اشتباه را اعمال کند یا شکل سیم اشتباه را بازگرداند.

MCP 2026-07-28این دو طرفه رو از بین می برد. هسته پروتکل بدون حالت است. سرور باید تصمیم بگیرد که چگونه درخواست فعلی را از درخواست فعلی اداره کند، نه از تاریخچه اتصال.

این مدل ذهنی را تغییر می دهد. ترتیب قدیمی اول ارتباط بود، دوم دست دادن، سوم عملیات. ترتیب مدرن ساده تر است:

مشتری درخواست خودوصف ارسال می کند.
سرور نسخه و قابلیت آن درخواست را تایید می کند.
سرور روش رو اداره مي کنه
سرور یک نتیجه تایپ شده یا یک خطا JSON-RPC را باز می گرداند.

درخواست بعدی همان فرآیند را از ابتدا تکرار می کند.

مفهوم

سرور های اولیه

سرورهای MCP سه نوع اولیه را نشان می دهند:

Toolsاقدامات کنترل شده توسط مدل، کشف شده استtools/listو با آن دعوت شودtools/call. .
Resourcesداده های URI- آدرس شده، کشف شده با resources/listو با resources/read. .
Promptsقالب های قابل استفاده مجدد هستند که با prompts/listو با ترجمه اشprompts/get. .

ریشه ها، نمونه گیری و چوبگیری در این کشور باقی مانده است.2026-07-28برنامه های سازگاری، اما از نظر قدیمی هستند. پیاده سازی های جدید باید از ابزار صریح یا ورودی منابع برای ریشه ها، API های ارائه دهنده مدل مستقیم برای نمونه گیری و stderr یا OpenTelemetry برای ثبت استفاده کنند. درخواست ها از طریق درخواست های چند دور سفر در دسترس هستند، جایی که یک سرور یک درخواست ورودی را باز می گرداند و مشتری عملیات اصلی را دوباره انجام می دهد. یک سرور مدرن هرگز یک درخواست JSON-RPC مستقل را شروع نمی کند.

پاکت های JSON-RPC

MCP از JSON-RPC 2.0 استفاده می کند:

درخواست:{jsonrpc, id, method, params}
پاسخ:{jsonrpc, id, result}یا{jsonrpc, id, error}
اطلاع رسانی: {jsonrpc, method, params}بدون هیچid

درخواستidیک پاسخ را مرتبط می کند. این یک جلسه پروتکل ایجاد نمی کند.

متاداتا مورد نیاز درخواست

هر درخواست مدرن همراهی با یک_metaداخل اشعهparams:

json{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "course-client",
        "version": "1.0.0"
      }
    }
  }
}

نسخه پروتکل و قابلیت های مشتری مورد نیاز است. هویت مشتری توصیه می شود. این داده های نمایش و اشکال زدایی خود گزارش شده است، نه اعتبار امنیتی.

سرور نباید هیچ یک از این ارزش ها را از یک درخواست قبلی، یک فرآیند stdio، یک اتصال HTTP یا یک سرپرستی حمل و نقل به تنهایی نتیجه دهد.

نتایج کامل و هویت سرور

هر نتیجه موفق مدرن شاملresultType. یک نتیجه نهایی عادی استفاده می کند"complete". سرورها باید خود را در متاداتا نتایج شناسایی کنند:

json{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "resultType": "complete",
    "tools": [],
    "ttlMs": 30000,
    "cacheScope": "public",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "notes-server",
        "version": "1.0.0"
      }
    }
  }
}

tools/list،resources/list،prompts/list،resources/templates/list،resources/readوserver/discoverنتایج قابل ذخیره هستند. شاملttlMsوcacheScope. یک پیش فرض امنttlMs: 0وcacheScope: "private". عناصر لیست باید دارای ترتیب تعیین کننده باشند تا پاسخ های معادل کلید های ذخیره سازی پایدار و زمینه مدل پایدار را ایجاد کنند.

کشف بدون دست دادن

هر سرور مدرن بايد اين كار رو انجام بدهserver/discover. مشتری می تواند قبل از روش دیگری برای بازیافت آن تماس بگیرد:

supportedVersions
سرورcapabilities
استفاده اختیاریinstructions
هویت سرور در نتیجه _meta
اشاره های زیر

کشف مفیده اما دروازه اي نيست.tools/listاول اینکه این درخواست قبلاً نسخه و قابلیت پروتکل خود را دارد.

اگر نسخه درخواست شده پشتیبانی نمی شود، سرور کد JSON-RPC را بازمی گرداند -32022با:

json{
  "requested": "2027-01-01",
  "supported": ["2026-07-28"]
}

مشتری یک نسخه مدرن متقابل پشتیبانی را انتخاب می کند و با یک ID درخواست JSON-RPC جدید دوباره تلاش می کند.

یک چرخه عمر درخواست

در اين ترتيب درخواست جديد رو دنبال کن:

پاکت JSON-RPC رو تجزیه کن
تایید کنjsonrpc."2.0"، یکidوجود دارهmethodیک رشته است وparamsیک شی هست.
از موضوع رشته و قابلیت نسخه در درخواست کنیدparams._meta؛ متاداتا های اشتباه یا گمشده-32602. .
در یک مرز HTTP، نسخه، روش و عنوان نام های قابل اجرا را با بدن مقایسه کنید.-32020حتی اگر یکی از دو مقدار نسخه پشتیبانی نشده باشد.
پس از برابری، نسخه ای که با هم مطابقت دارد اما پشتیبانی نشده است را رد کنید.-32022. .
قابلیت های لازم رو چک کن بعد ازش رویت کنmethodو استدلال های خاص روش را تأیید کنید.
قبل از اینکه کارگر آن اجرا شود، عملیات بتنی را تأیید و مجاز کنید.
یک نتیجه کامل با هویت سرور را برگردانید.
متاداتا پروتکل درخواست شده رو فراموش کن

این دستور مانع از تفسیر دو قسمت از تماس های مختلف می شود.Mcp-Name: notes.readدر حالی که اصل اجرا می شودparams.name: notes.deleteهمچنین ورودی های اشتباه، سردرگمی سر، مذاکره در مورد نسخه، شکست قابلیت، مجوز و شکست دستیار را به عنوان شواهد مشخص نگه می دارد.

بسته شدن stdin یا پاسخ HTTP فعالیت حمل و نقل را متوقف می کند. این یک جلسه پروتکل را متوقف نمی کند زیرا MCP مدرن هیچ جلسه پروتکل ندارد.

مطابقت صریح میراث

نسخه ها از طریق 2025-11-25استفادهinitialize،notifications/initializedاین رفتار هنوز هم در زمان صحبت کردن با یک سرور قدیمی مرتبط است.

زمان ها را جداگانه نگه دارید. یک درخواست مدرن توسط متاداتا مورد نیاز در هر درخواست شناسایی می شود. یک اتصال قدیمی تنها از طریق مسیر برگشت مستند انتخاب می شود. ارسال نکنید initializeبه عنوان پیش فرض برای یک2026-07-28سرور

بنابراین، "غیرمتوطنی" معنای خاصی برای عصر دارد.2026-07-28این یک پروتکل غیر متغیر است: هر درخواست معمولی به طور مستقل قابل تفسیر است و هیچ جلسه MCP وجود ندارد.2025-11-25یک اپدیتور سازگاری ممکن است وضعیت اتصال قدیمی را حفظ کند. یک پیاده سازی دو عصر یک ماشین حالت اجازه دار نیست. این یک هسته مدرن بی دولتی است در کنار یک اپدیتور قدیمی جداگانه، با یک تصمیم انتخاب صریح قبل از اجرا هر یک از پارسر.

هیچ یک از این معنی ها وضعیت کاربردی پایدار را ممنوع نمی کند. یک جریان کار، کار یا مسود می تواند در پشت یک دستی نامشخص در یک فروشگاه مشترک زندگی کند. مشتری آن دستی را به عنوان ورودی معمولی ارسال می کند و هر نسخه تأیید و مجوز استفاده از آن را می دهد. زمینه پروتکل نباید به عنوان جایگزینی برای جلسه حذف شده به آن فروشگاه نفوذ کند.

ازش استفاده کن

code/main.pyایجاد، اعتبار، ردیابی و ارسال پیام های مدرن MCP بدون چارچوب. اجرا کنید:

bashpython3 code/main.py
python3 -m unittest discover code/tests -v

مراقب سه متغیر در خروجی باشید:

هر درخواست تکرارش ميکنه_meta. میدان ها
هر نتیجه موفقresultType: "complete"و شامل هویت سرور است.
نتیجه لیست به صورت تعیین کننده ترتیب داده شده و اشاره های آشکار به حافظه کش دارد.

-باده

اين درس به ما ميگيرهoutputs/skill-mcp-handshake-tracer.md. نام فایل تاریخی ثابت باقی می ماند، اما این آرتیفاکت اکنون یک ردیاب درخواست بی دولتی است. این هر پیام را به طور مستقل بررسی می کند و ترافیک دست دادن قدیمی را تنها زمانی که واقعاً موجود باشد برچسب می زند.

تمرینات

نسخه پروتکل یک درخواست را به تغییر دهید2027-01-01. کد خطا رو تایید کن-32022و داده ها نسخه پشتیبانی شده را تبلیغ می کنند.
حذف کنio.modelcontextprotocol/clientCapabilitiesاز درخواست دوم. تایید کنید که سرور از قابلیت های درخواست اول استفاده نمی کند.
ثبت ابزار حافظه را برگردانید. تایید کنید tools/listهنوز هم همان ترتیب تعیین کننده را باز می گرداند.
تغییرcacheScopeازpublicبهprivateتوضیح دهید که در هر مورد چه زمینه های مجوز می توانند پاسخ را دوباره استفاده کنند.
یک گزینه اختیاری اضافه کنیدclientInfoآزمون حذف: درخواست باید معتبر بماند چون هویت مشتری توصیه می شود، نه مورد نیاز است.

اصطلاحات کلیدی

Term	Meaning
Stateless protocol	Every request supplies the metadata needed to interpret it
Request metadata	Version, client capabilities, and recommended client identity in `params._meta`
`server/discover`	Mandatory server method for versions, capabilities, instructions, and identity
`resultType`	Discriminator on every successful modern result
Cacheable result	Result that includes required `ttlMs` and `cacheScope` hints
Protocol era	Modern per-request metadata or legacy connection-scoped initialization
Transport lifetime	Process, connection, or response-stream lifetime, not protocol session state
`-32022`	Unsupported protocol version error with requested and supported versions

خواندن بیشتر

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.