چیتشیت
درگاههای MCP، رجیستریها و انطباق با استاندارد
MCP Gateways, Registries and Conformance
مسیریابی از طریق یک درگاه بیوضعیت، پذیرش نسخههای رجیستری، شناسایی دریفت، تست بستر انتقال و مدیریت انتشارها.
فهرست مطالب
مسیر درخواست در درگاه
معماریاجرا و تأیید
دستورها| دستور | کاربرد |
|---|---|
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.4یا latest نباشد. - دریفت زندهفراخوانی
server/discover. هرگونه تغییر هش توصیفگر موجب قرنطینه قفل میشود. - وضعیتخواندن وضعیت رسمی
_meta. موارد منسوخ یا حذفشده قرنطینه میشوند. - بازگشت به عقبمسیریابی به یک قفل پذیرفتهشده که فعال است و قرنطینه نشده.
- دفتر کلالصاق هر تصمیم همراه با هش قبلی و هش اختصاصی خودش.
خطاهای درگاه
عیبیابی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_000 | cacheScope به صورت private |
Gateway tools/list `ttlMs` | 10_000 | خصوصی، چون توسط RBAC فیلتر میشود |
`TokenBucket` `capacity` | 5 | refill_per_second برابر با 1.0 |
maxErrorRate | 0.01 | پیشفرض گیت سلامت |
maxP95Ms | 500 | پیشفرض گیت سلامت |
MODERN_VERSION | 2026-07-28 | نیازمند resultType است |
LEGACY_VERSION | 2025-11-25 | صرفاً با لیست مجاز و initialize معتبر |
Registry schema | 2025-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ناشناخته را رد کنید. - آیا بازگشت به عقب رکورد قدیمی را ویرایش میکند؟
- خیر. مسیر فعال را تغییر میدهد.
- آیا اجرای موفق پروژه نهایی بستر انتقال را اثبات میکند؟
- خیر. صرفاً شبیهسازی را اعتبارسنجی میکند.