سرفصل‌ها درس 139 از 250 · خروجی‌های ساختاریافته و فراخوانی تابع/ابزار
خروجی‌های ساختاریافته و فراخوانی تابع/ابزار

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

وقتی اپلیکیشن شما بیش از یک ابزار داشته باشد، هر فروشنده مدل شکل JSON مخصوص خود را برای فراخوانی آن‌ها ابداع می‌کند و در نهایت مجبور می‌شوید برای هر ارائه‌دهنده یک آداپتور بنویسید. پروتکل زمینهٔ مدل (MCP) استاندارد باز است که این مشکل را حل می‌کند. این یک جی‌اسان-آر‌پی‌سی ۲.۰ پروتکل سیمی برای افشا ابزارها (تابع‌هایی که مدل می‌تواند فراخوانی کند)، منابع (داده‌هایی که می‌تواند بخواند)، و موضوعات برای هر مدل مشتری. یک سرور MCP را تنها یک‌بار بنویسید و هر مشتری آگاه به MCP (یک دستیار IDE، یک برنامه دسکتاپ، یک عامل) می‌تواند از آن استفاده کند.

هر پیام JSON-RPC 2.0 است که یک پاکت کوچک و ثابت است. یک درخواست همیشه چهار کلید همراه دارد:

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "add", "arguments": {"a": 2, "b": 3}}}

آن id پاسخ را به درخواست خود متصل می‌کند. سرور با یک پاسخ که بازتاب همان است id و حمل می‌کند یا a result یا یک error یک شیء، هرگز هر دو:

{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "5"}], "isError": false}}
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found"}}

کدهای منفی مطابق استاندارد JSON-RPC هستند: -32601 «روش یافت نشد» است، -32602 «پارامترها نامعتبر هستند» و غیره. یک tools/call نتیجه همیشه آن شکل را دارد: a content فهرست بلوک‌ها (متن، تصاویر و غیره) به علاوه isError. ابزاری که اجرا شد اما شکست خورد (مثلاً به دلیل نام نادرست یک شهر) با پاسخ می‌دهد isError: true در یک نتیجهٔ عادی، تا مدل بتواند خطا را بخواند؛ JSON-RPC error object برای مشکلات پروتکل مانند متد ناشناخته است.

یک جلسه با یک دست‌دادن: مشتری یک ارسال می‌کند initialize درخواست (نسخه پروتکل آن، قابلیت‌های آن و نام آن)، سرور با قابلیت‌های خود پاسخ می‌دهد و کلاینت با یک notifications/initialized اطلاعیه (پیامی بدون id، چون هیچ‌کس به آن پاسخ نمی‌دهد). تنها در آن صورت است که کلاینت کشف کن ابزارها را با فراخوانی tools/list با پارامترهای خالی؛ سرور فهرست توصیف‌کننده‌های ابزار را بازمی‌گرداند.

یک سرور واقعی MCP روی stdio یا HTTP اجرا می‌شود و این را به SDK متصل می‌کند؛ در اینجا ما پیام‌ها را با کتابخانهٔ استاندارد می‌سازیم و تجزیه می‌کنیم. json ماژول، بنابراین قالب سیم مشخص است. شما در حال نوشتن سه تابع هستید.

  • build_request(id, method, params) -> یک JSON رشته برای پاکت {"jsonrpc": "2.0", "id": id, "method": method, "params": params}. استفاده کنید json.dumps.
  • parse_response(text) -> json.loads متن، نیاز jsonrpc == "2.0" (بالا بردن ValueError در غیر این صورت). اگر آن داشته باشد result، بازگشت {"id": ..., "ok": True, "result": ...}. اگر آن داشته باشد errorبازگشت {"id": ..., "ok": False, "error": {"code": ..., "message": ...}}. اگر هیچ‌کدام را نداشته باشد، افزایش دهید ValueError.
  • list_tools_request(id) -> درخواست کشف ابزار: a build_request با روش "tools/list" و خالی params {}.

زیرا build_request یک رشته را بازمی‌گرداند، تست‌ها آن را با ... تجزیه می‌کنند json.loads و دیک را مقایسه کنید، بنابراین ترتیب کلیدها اهمیتی ندارد. مطمئن شوید که نتیجه و خطا هر دو به صورت رفت و برگشتی ارسال شوند، درخواست کشف روش صحیح را دارد و پیامی که مفقود است. jsonrpc یا هیچ‌کدام را ندارد result نه error افزایش می‌دهد

نوبت شما

با استفاده از ...، پیام‌های JSON-RPC 2.0 به سبک MCP را بسازید و تجزیه کنید. json ماژول. build_request(id, method, params) متن JSON را برای {"jsonrpc": "2.0", "id", "method", "params"}. parse_response(text) متن را بارگذاری می‌کند، نیازمند jsonrpc == "2.0" (در غیر این صورت خطا صادر می‌کند ValueError)، و مقدار بازگشتی را برمی‌گرداند {"id", "ok": True, "result"} برای یک نتیجه یا {"id", "ok": False, "error": {"code", "message"}} برای خطا، در صورتی که هیچ‌یک از آنها را نداشته باشد، خطا را به وجود می‌آورد. list_tools_request(id) بازمی‌گرداند tools/list درخواست کشف (ارسال‌شده پس از دست‌دادن) با پارامترهای خالی.

مشکلی در این درس دیدید؟ گزارشش کنید · دربارهٔ این درس بپرسید

این تمرین به‌زودی باز می‌شود

درس پیش از آن را تمام کنید تا این یکی باز شود. کل دوره رایگان است، حساب کاربری لازم نیست، و می‌توانید همین الان این درس را بخوانید.