Phase 11: LLM Engineering

مدل پروتکل زمینه (MCP)

Type: Build

Languages: Python

Prerequisites: Phase 11 · 09 (Function Calling), Phase 11 · 03 (Structured Outputs)

Time: ~75 minutes

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

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

مشکل

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

MCP آن ماتریس ادغام را کاهش می دهد. یک سرور یک سطح استاندارد JSON-RPC را منتشر می کند. یک مشتری سازگار می تواند سطح را کشف کند، آن را به یک مدل یا کاربر ارائه دهد، آن را فراخوانی کند و نتیجه را بدون یک آداپتور خاص سرور تفسیر کند.

مرز مهم را فراموش کردن آسان است. MCP ارتباطات را استاندارد می کند. این تصمیم نمی گیرد که مدل باید به کدام ابزار مراجعه کند، محتوای غیرقابل اعتماد را ایمن کند یا یک درخواست بدون دولت را به وضعیت کاربردی پایدار تبدیل کند. میزبان و سرور شما هنوز هم مالک این تصمیمات هستند.

مفهوم

!MCP host, stateless request, and server primitives

سه سرور ابتدایی

1. Toolsهر ابزار دارای نام، توصیف، ورودی JSON Schema و دستیار است.
2. Resourcesنامگذاری شده و محتوای URI که مشتری می تواند بخواند.
3. Promptsقالب های قابل استفاده مجدد هستند که میزبان می تواند به کاربر نشان دهد.

میزبان برنامه هوش مصنوعی است. یک مشتری MCP در داخل آن میزبان با یک سرور صحبت می کند. حمل و نقل پیام های JSON-RPC بین آنها را حمل می کند.

درخواست های بی تابعیت جایگزین دست دادن

MCP 2026-07-28 حذف می شود initializeوnotifications/initializedهمچنین جلسات سطح پروتکل را حذف می کند. هر درخواست زمینه ای را برای تفسیر آن درparams._meta:

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

نسخه پروتکل و قابلیت های مشتری مورد نیاز است. هویت مشتری توصیه می شود. یک گمشده_meta, یک فیلدی مورد نیاز که از دست رفته است یا یک فیلدی مورد نیاز با نوع اشتباه اشتباه است و Params Invalid را باز می گرداند (-32602). یک رشته نسخه خوب شکل گرفته که سرور پشتیبانی نمی کند باز می گردد UnsupportedProtocolVersionError(-32022) یک سرور می تواند درخواست معتبر را بدون بازیافت سابقه مذاکره قبلی پردازش کند.

بدون تابعیت به این معنی نیست که یک برنامه هرگز نمی تواند وضعیت را حفظ کند. به این معنی است که وضعیت در پشت یک اتصال MCP پنهان نیست یاMcp-Session-Idاگر یک جریان کار نیاز به تداوم دارد، سرور یک دستی نامشفق را می کند و مشتری آن را به عنوان یک استدلال ابزار معمولی در تماس های بعدی می گذرد. اجازه هنوز هم باید در هر درخواست بررسی شود.

کشف و انتخاب نسخه

هر سرور مدرن اجرا می کندserver/discoverنتیجه تبلیغات نسخه های پشتیبانی شده، قابلیت ها و هویت سرور:

jsonCopy{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "supportedVersions": ["2026-07-28"],
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {}
    },
    "ttlMs": 3600000,
    "cacheScope": "public",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "demo-server",
        "version": "1.0.0"
      }
    }
  }
}

یک مشتری ممکن است به طور مستقیم به یک روش دیگر زنگ بزند و یک خطا نسخه را مدیریت کنند، اما کشف باعث می شود نمایش قابلیت و انتخاب نسخه صریح شود. یک نسخه غیر پشتیبانی شده باز می گردد UnsupportedProtocolVersionErrorبا کد-32022داده های آن شاملsupported, مجموعه ای از اصلاحات سرور , و requested، اصلاح رد شده

در استودیو، یک مشتری دو دوره ای باserver/discover. نتیجه ی کشف یا خطا ی مدرن شناخته شده مانندUnsupportedProtocolVersionErrorهر خطا یا زمان بندی که به عنوان مدرن شناخته نمی شود اجازه می دهد به سال 2025-11-25 بازگرددinitializeرفتارهای میراث، کد سازگاری است، نه پیش فرض مدرن.

نتایج واضحه

هر هسته ای که در سال 2026-07-28 نتیجه داده شدهresultType:

• completeیعنی عملیات تمام شده
• input_requiredیعنی سرور به یک سفر دیگر از طریق الگوی درخواست های چند سفر دور نیاز دارد. سرورهای اصلی ممکن است آن را فقط از tools/call،resources/read، یاprompts/get. .

مشتری ها باید یک نتیجه قدیمی را که حذف می شود، درمان کنند.resultTypeتمام شد

سرورها باید شامل باشندio.modelcontextprotocol/serverInfoدر هر نتیجه ای_metaاین هویت خود گزارش شده است و برای نمایش، ثبت و اشکال زدایی است، نه برای تصمیمات امنیتی.

لیست و نتایج خواندن نیز شامل ttlMsوcacheScope. یک تعیین کنندهtools/listسفارش به علاوه یک نکته تازه اجازه می دهد تا مشتریان کشف را به صورت ایمن ذخیره کنند و ثبات ذخیره سازی سریع را بهبود بخشد. cacheScope: publicاجازه ذخیره سازی مشترک؛ privateاستفاده مجدد به زمینه تماس محدود می شود.

شکل سیم و حمل و نقل

MCP از JSON-RPC 2.0 در stdio یا Streamable HTTP استفاده می کند.

• درخواست ای دارهjsonrpc،id،methodوparams. .
• پاسخ به همبستگی دارهidو یاresultیاerror. .
• اطلاعیه ای نیستidو انتظار پاسخگویی ندارد.

HTTP Streamable مدرن یک نقطه پایان را که POST را پذیرفته است نشان می دهد. هر پیام JSON-RPC POST خود را دریافت می کند. یک درخواست POST یک شی JSON یا یک جریان رویداد های سرور ارسال شده توسط درخواست را دریافت می کند که با پاسخ نهایی پایان می یابد. یک اطلاعیه POST پذیرفته شده HTTP 202 را بدون بدن پاسخ دریافت می کند. این تجدید نظر اصلی هیچ اطلاعیه مشتری به سرور را بر روی HTTP Streamable تعریف نمی کند.

هیچ جریان مستقل MCP GET وجود ندارد، نقطه پایان جلسه DELETE، Mcp-Session-Id، یاLast-Event-IDتکرار در 2026-07-28 . اطلاعیه های تغییر طولانی مدت از یکsubscriptions/listenPOST که پاسخ آن به عنوان یک جریان SSE باز باقی می ماند.

ورودی مشتری بدون درخواست های آغاز شده توسط سرور

نسخه های قبلی اجازه می دهد یک سرور درخواست هایی مانند sampling/createMessage،roots/list، یاelicitation/createبر روی یک جریان. پروتکل فعلی در عوض از درخواست های چند سفر دور استفاده می کند. یک تماس ابزار واجد شرایط، خواندن منابع، یا سریع دریافت بازپرداختresultType: input_requiredحداقل یک نفر ازinputRequestsیاrequestState. مشتری هر گونه ورودی مورد نیاز را جمع آوری می کند، روش اصلی را با یک شناسه JSON-RPC جدید و متناظر دوباره امتحان می کند inputResponsesو به طور دقیق هم مطابقت دارهrequestStateوقتی که یکی از آنها ارائه شد.inputRequestsاگه حضور داشته باشيد، دوباره امتحانش رو از دست ميدهيدinputResponses. .

ریشه ها، نمونه گیری و ثبت نام همچنان فعال هستند اما به طور منسوخ شده اند، بنابراین پیاده سازی های جدید نباید آنها را اتخاذ کنند. ریشه های موجود یا درخواست نمونه گیری در داخل MRTR سفر می کنند inputRequests، هرگز به عنوان درخواست های JSON-RPC مستقل سرور به مشتری. پارامترهای صریح فایل یا دایرکتوری، URIs منابع، پیکربندی سرور و یکپارچه سازی مستقیم ارائه دهنده مدل را ترجیح دهید. برای تشخیص استودیو از stderr و OpenTelemetry برای تله متری تولید استفاده کنید.

آن را بسازید

مرحله اول: سطح سرور را ثبت کنید

ثبت نام ساده باقی می ماند حتی اگر قرارداد درخواست تغییر کند:

pythonCopyserver = MCPServer("demo-server")

@server.tool(
    "add",
    "Add two integers.",
    {
        "type": "object",
        "properties": {
            "a": {"type": "integer"},
            "b": {"type": "integer"}
        },
        "required": ["a", "b"]
    }
)
def add(a: int, b: int) -> dict:
    return {"sum": a + b}

اجرای ارسال شده در code/main.pyهمچنین یک منبع و پرامپت را ثبت می کند. آن عمدا از کتابخانه استاندارد استفاده می کند تا شما بتوانید هر پاکت را ببینید به جای انتقال پروتکل به یک SDK.

مرحله دوم: متاداتا را به هر درخواست متصل کنید

pythonCopydef request(method, params=None):
    body_params = dict(params or {})
    body_params["_meta"] = {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {
            "name": "demo-client",
            "version": "1.0.0"
        }
    }
    return {
        "jsonrpc": "2.0",
        "id": 1,
        "method": method,
        "params": body_params
    }

این متاداتا را فقط در یک شی اتصال ذخیره نکنید. سرور آن را در هر درخواست تأیید می کند.

مرحله 3: انتخاب کنید قبل از لیست کردن

تماس بگیریدserver/discover، نسخه ای پشتیبانی شده را انتخاب کنید، سپس تماس بگیرید tools/list. یک مستقیمtools/listاگر نسخه را قبلاً می شناسید و می توانید آن را مدیریت کنید-32022. .

نمایش لیست ابزارها را به ترتیب نامها و پیوست ها باز می کند ttlMs،cacheScope،resultTypeیک تماس ابزار یک نتیجه کامل و غیر قابل کیش را به ارمغان می آورد زیرا تولید آن می تواند به وضعیت فعلی بستگی داشته باشد.

مرحله 4: نقشه همان درخواست به HTTP

یک راه دورtools/callPOST شامل عناوین است که بدن JSON-RPC را منعکس می کند:

httpCopyPOST /mcp HTTP/1.1
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: add

.MCP-Protocol-Versionعنوان باید با نسخه در _meta.Mcp-Methodدر هر درخواست JSON-RPC مورد نیاز است و باید مطابقت داشته باشد method.Mcp-Nameفقط برای tools/call،resources/readوprompts/getدر این حالت، در این حالت باید نام ابزار، URI منابع یا نام پرامپت را مطابقت دهد. یک عنوان مورد نیاز یا عدم مطابقت از دست رفته HTTP 400 را با HeaderMismatchکد-32020. .

مرحله 5: اجرای ایمنی خارج از حالت پروتکل

• مجوز و مخاطبان را در هر درخواست HTTP تأیید کنید.
• سرورهای محلی را به میزبان محلی متصل کنید و تایید کنیدOriginدر HTTP قابل پخش
• ابزار جهشگر را با destructiveHint: trueو نیاز به تایید میزبان دارند.
• دامنه دایرکتوری و فایل را به وضوح عبور دهید به جای وابستگی به ریشه های قدیمی.
• منابع و ابزار تولید را به عنوان داده های غیرقابل اعتماد در نظر بگیرید.
• ذخیره stdout برای JSON-RPC در stdio؛ تشخیص را به stderr بنویسید.

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

درس رو از فهرستش اجرا کن

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

اولين خط بايد گزارش پيدا کردنdemo-serverدر پروتکل2026-07-28پس بازرسی کنMCPClient.request: بازسازی می کنه_metaبرای هر تماس. متاداتا را از یک درخواست حذف کنید و مشاهده کنید که سرور آن را رد می کند.

-باده

outputs/skill-mcp-server-designer.mdیک دامنه را به یک طراحی MCP بدون دولت تبدیل می کند. دروازه پذیرش آن نیاز به یک نتیجه کشف، سیاست متادتا هر درخواست، لیست های تعیین کننده آگاه از کش، دستی های صریح حالت، سرنخ حمل و نقل، مجوز و قوانین تأیید دارد.

ادامه دادن به غوطه عميق MCP

در این درس شما مدل پروتکل را می بینید. مرحله 13 چهار مرز تولید را به آموزش های جداگانه ساخت و تأیید تبدیل می کند:

1. MCP Tool Contracts and Contentشامل طرح های ورودی بسته، محتوای ساختاری، متاداتا مسیر، صفحات غیر شفاف، مجوز تکمیل و تفاوت بین خطاهای پروتکل و دامنه ابزار است.
2. MCP Reliability, Cancellation, and Flow Controlشامل لغو درخواست، لغو کار ماندگار، مهلت ها، بی اختیار، فشار، بفرینگ پراکسی و رفتار اتصال مجدد است.
3. MCP Registry Supply Chain, Admission, Drift, and Rollbackشامل اثبات فضای نام، اصل اثاث، پین های غیر قابل تغییر، حرکت زنده، وضعیت ثبت نام، شواهد پذیرش و بازگشت.
4. MCP Conformance Engineeringپوشش داده شده است نقاش های سیم طلایی و منفی، دوره های نسخه سخت، تفاوت های SDK، شواهد استازی، ویرایش، دروازه های سلامتی و بازپرداخت انتشار.

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

تمرینات

1. اضافه کنیدsubtractابزار و تاییدtools/listبه ترتیب الفبایی باقی می ماند.
2. کلید نسخه پروتکل را حذف کنید و Params Invalid را تایید کنید (-32602پس نسخه خوبي که درست شده ولي پشتیبانی نشده رو بفرست2025-11-25، تایید کنید-32022، تایید کنrequestedبه نظر مي رسد که اين نظرسنجي شده و از بينش انتخاب ميکنهsupported. .
3. اضافه کردن یک سرور-minted draftIdبرای ایجاد یک عملیات، سپس آن را به عنوان یک استدلال برای به روز رسانی نیاز دارید. توضیح دهید که چرا این وضعیت برنامه است نه یک جلسه پروتکل.
4. برگشتinput_requiredاز یک ابزار که نیاز به تایید کاربر دارد. تماس اصلی را با یک شناسه جدید، یک inputResponsesوارد شدن و دقیق بودنrequestStateبه جای اختراع یک درخواست JSON-RPC از سرور به مشتری.
5. یک مشتری استودیویی دو دوره را رسم کنید. یک نتیجه یا خطا مدرن را به عنوان مدرن و اجازه بازگشت به initializeفقط بخاطر خطا ناشناخته يا زمانبندی

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

خواندن بیشتر

• MCP 2026-07-28 key changes
• MCP server discovery
• MCP Streamable HTTP
• MCP Multi Round-Trip Requests
• MCP deprecated features

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.