چیت‌شیت

درگاه‌های MCP، رجیستری‌ها و انطباق با استاندارد

MCP Gateways, Registries and Conformance

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

  • ۱۱ بخش
  • ۴ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. مسیر درخواست در درگاه
  2. اجرا و تأیید
  3. وظایف درگاه در کد
  4. پذیرش در رجیستری، دریفت، بازگشت به عقب
  5. بستر آزمایشی انطباق با استاندارد
  6. هفت کنترل پذیرش
  7. خطاهای درگاه
  8. پیش‌فرض‌ها و مقادیر عددی
  9. شکست‌های انتشار
  10. قوانین
  11. پرسش‌ها

مسیر درخواست در درگاه

معماری
POSTابتدا -32020مجازnotes.searchissues.listاتصالپذیرشکلاینتbearer and _metavalidate_wireبرابری هدرها با بدنهRBAC و TokenBucketبه ازای هر هویت (principal)قفل توصیف‌گرdescriptor_digestرکورد رجیستریفقط انتشاروضعیت پذیرشناشر تأییدشدهبک‌اند notesشناسه درخواست تازهبک‌اند issuesشناسه درخواست تازه

اجرا و تأیید

دستورها
دستورکاربرد
python3 code/main.pyاجرای دموی پوشه‌ی درس
python3 -m unittest discover code/tests -vاجرای تست‌های درگاه (درس 17)
python3 -m unittest discover -s code/tests -vاجرای مجموعه‌تست‌های رجیستری و انطباق با استاندارد
python3 -qباز کردن شل در code/ برای تمرین‌ها
from main import *بارگذاری توابع تمرین در آن شل

وظایف درگاه در کد

کار و کد
وظیفهکد
ساخت یک درخواست و هدرهاmake_request(method, request_id, params)
ارسال آن در قالب یک هویت (principal)gateway.handle("bearer-alice", body, headers)
بررسی اولیه‌ی بستر انتقالvalidate_wire(body, headers)
قفل کردن یک توصیف‌گرdescriptor_digest(tool)
اعمال محدودیت نرخ درخواست برای هویتTokenBucket().consume()
پذیرش یک رکورد رجیستریregistry_record_is_admissible
بررسی دامنه در پروژه نهایی (capstone)gateway_call(token, tool_name, args, ...)

پذیرش در رجیستری، دریفت، بازگشت به عقب

کد
python
controller = RegistryAdmissionController(clock=lambda: next(ticks))
active_meta = {OFFICIAL_META_KEY: {"status": "active"}}
controller.admit(sample_record("1.1.0"), active_meta,
    namespace_for_domain("example.com"),                       # com.example را می‌دهد
    evidence_for("1.1.0"), sample_live("1.1.0"))               # پذیرش 1.0.0 به همان روش
drift = controller.check_live("com.example/inventory", "1.1.0",
    sample_live("1.1.0", True))                                # ابزار اضافی: قرنطینه‌شده
controller.observe_registry_status("com.example/inventory", "1.1.0", "deprecated")
controller.rollback("com.example/inventory", "1.0.0", "unexpected delete tool")
controller.ledger.verify()                                     # False پس از هر ویرایش
namespace_matches("com.exampleevil/inventory", "com.example")  # False

بستر آزمایشی انطباق با استاندارد

کد
python
validate_result({"tools": []}, "legacy")                           # کامل بودن را استنتاج می‌کند
validate_result({"tools": []}, "modern")                           # خطای ProtocolViolation صادر می‌کند
select_era({"kind": "timeout"}, "fallback")                        # در حالت امن مسدود می‌شود (fails closed)
select_era({"kind": "jsonrpc_error", "code": -32021}, "fallback")  # مدرن
cases = [run_transcript(case) for case in transcript_suite()]      # 15 مورد
compare_sdk_view(raw_result, {"tools": []})                        # droppedFields futureHint
inspect_proxy(exchange)                                            # تبدیل 400 به 500 را شناسایی می‌کند
redact(value)                                                      # قبل از هش کردن یا آپلود
evaluate_health(healthy_window())                                  # نمونه‌ها، نرخ خطا، p95
ReleaseGate(signers).evaluate(cases, [sdk_report], [proxy_report],
                              healthy_window(), rollback)          # ارتقا یا بازگشت به عقب

هفت کنترل پذیرش

گام‌به‌گام
  1. فضای ناممقایسه‌ی دقیق بخش قبل از / با فضای نام تأییدشده.
  2. منشأ و سندیتتجمیع نوع رجیستری، شناسه، نسخه، مالکیت و هش محتوای دست‌سازه.
  3. قفل توصیف‌گرذخیره‌ی هشدارهای رکورد، منبع، جعبه‌ابزار و سندیت. هرگز ^1.4 یا latest نباشد.
  4. دریفت زندهفراخوانی server/discover. هرگونه تغییر هش توصیف‌گر موجب قرنطینه قفل می‌شود.
  5. وضعیتخواندن وضعیت رسمی _meta. موارد منسوخ یا حذف‌شده قرنطینه می‌شوند.
  6. بازگشت به عقبمسیریابی به یک قفل پذیرفته‌شده که فعال است و قرنطینه نشده.
  7. دفتر کلالصاق هر تصمیم همراه با هش قبلی و هش اختصاصی خودش.

خطاهای درگاه

عیب‌یابی
  • 401 -32001

    علت
    توکن Bearer شناخته‌شده نیست
    راه‌حل
    احراز هویت principal
  • 403 -32003

    علت
    ابزار در RBAC کاربر وجود ندارد
    راه‌حل
    اعطای نقش یا حفظ وضعیت عدم دسترسی
  • 429 -32029

    علت
    TokenBucket خالی است
    راه‌حل
    صبر کردن برای پر شدن مجدد سطل
  • 409 -32010

    علت
    توصیف‌گر زنده با نسخه قفل‌شده تفاوت دارد
    راه‌حل
    بررسی مجدد و تایید دوباره‌ی قفل
  • 400 -32020

    علت
    عدم تطابق هدر با بدنه
    راه‌حل
    همگام‌سازی Mcp-Method و Mcp-Name
  • 400 -32022

    علت
    نسخه‌ی منطبق پشتیبانی نمی‌شود
    راه‌حل
    ارسال نسخه‌ای موجود در supported
  • 406 در subscriptions/listen

    علت
    هدر Accept فاقد text/event-stream است
    راه‌حل
    پذیرش SSE
  • 405

    علت
    ارسال GET یا DELETE به اندپوینت
    راه‌حل
    ارسال هر پیام به صورت POST

پیش‌فرض‌ها و مقادیر عددی

پیش‌فرض‌ها
تنظیمپیش‌فرضنکته
Gateway discover `ttlMs`30_000cacheScope به صورت private
Gateway tools/list `ttlMs`10_000خصوصی، چون توسط RBAC فیلتر می‌شود
`TokenBucket` `capacity`5refill_per_second برابر با 1.0
maxErrorRate0.01پیش‌فرض گیت سلامت
maxP95Ms500پیش‌فرض گیت سلامت
MODERN_VERSION2026-07-28نیازمند resultType است
LEGACY_VERSION2025-11-25صرفاً با لیست مجاز و initialize معتبر
Registry schema2025-12-11مستقل از نسخه‌ی پروتکل

شکست‌های انتشار

عیب‌یابی
  • کلاینت پس از -32021 به حالت قدیمی می‌رود

    علت
    خطای مدرن شناخته‌شده به عنوان قدیمی خوانده شده
    راه‌حل
    هرگز پس از یک خطای مدرن به حالت قدیمی برنگردید
  • SDK ویژگی resultType را نشان می‌دهد که روی بستر انتقال نبود

    علت
    SDK تفکیک‌کننده را می‌سازد
    راه‌حل
    اعتبارسنجی بدنه‌ی خام
  • خطای 400 مبدأ به صورت 500 می‌رسد

    علت
    پروکسی خطا را یکسان‌سازی کرده است
    راه‌حل
    مقایسه‌ی ورودی، مبدأ و خروجی
  • قناری خطای صفر دارد و فاقد ترافیک است

    علت
    حداقل تعداد نمونه تعیین نشده
    راه‌حل
    اجبار sampleCount به مقدار بیشتر از 0
  • ظهور ابزار جدید پس از تایید

    علت
    انحراف محیط اجرا
    راه‌حل
    قرنطینه‌سازی مسیر
  • مقصد بازگشت به عقب هرگز پذیرش نشده بود

    علت
    قطع ارتباط میان مسیر و وضعیت تایید
    راه‌حل
    رد درخواست، اجرای فرآیند پذیرش جدید

قوانین

نکته‌ها
  • هرگز توکن درگاه بیرونی را به بک‌اند ارسال نکنید.
  • قابلیت‌های کلاینت بیرونی را به بک‌اند کپی نکنید. درگاه خود کلاینتِ آن است.
  • محدودیت نرخ درخواست بر اساس هویت، صادرکننده، منبع، ابزار، دسته‌ی هزینه و بازه زمانی.
  • حفظ بایت‌به‌بایت requestState. احراز هویت مجدد در هر تلاش مجدد MRTR.
  • مسیریابی tasks/get، tasks/update و tasks/cancel بر اساس params.taskId در Mcp-Name.
  • اجرای فرآیند پذیرش پیش از نمایش یک سرور در tools/list.
  • پاک‌سازی داده‌های حساس پیش از سریال‌سازی، هش کردن، ثبت در لاگ یا آپلود.

پرسش‌ها

پرسش و پاسخ
آیا حضور در رجیستری به معنای تایید سرور است؟
خیر. سیاست پذیرش تعیین‌کننده است.
آیا serverInfo هویت ناشر را اثبات می‌کند؟
خیر. صرفاً داده‌های تشخیصی است.
آیا فیلد ناشناخته نشانه‌ی یک نتیجه‌ی ناشناخته است؟
خیر. فیلد را نگه دارید. یک resultType ناشناخته را رد کنید.
آیا بازگشت به عقب رکورد قدیمی را ویرایش می‌کند؟
خیر. مسیر فعال را تغییر می‌دهد.
آیا اجرای موفق پروژه نهایی بستر انتقال را اثبات می‌کند؟
خیر. صرفاً شبیه‌سازی را اعتبارسنجی می‌کند.