Tool Registry و Qualification

1. مسئله واقعی: پیدا شدن ابزار با مجاز بودن آن یکی نیست

در یک سیستم عامل‌محور، دیدن نام docs.lookup در یک فهرست ابزار یا Registry فقط می‌گوید یک قابلیت با این برچسب قابل کشف است. این مشاهده به‌تنهایی ثابت نمی‌کند همان نسخه‌ای است که قبلاً بررسی شده، schema ورودی و خروجی تغییر نکرده، scopeهای دسترسی همان‌اند، ابزار فقط خواندنی است، مقصد شبکه همان مقصد مورد انتظار است یا شواهد Qualification هنوز معتبرند. هدف این درس ساختن یک Tool Registry عملیاتی است که discovery را از admission جدا کند.

رکوردی که در این درس می‌سازیم «Qualified Tool Registry Entry & Admission Evidence Record v1» است. تصمیم نهایی باید بدون تکیه به نام آشنا یا یک فراخوانی موفق، به نسخه و شواهد دقیق قابل ممیزی متصل باشد.

2. سه لایه را از هم جدا کن: Discovery، Qualification و Authorization

Discovery پاسخ می‌دهد «چه چیزی اعلام شده؟». Qualification پاسخ می‌دهد «کدام هویت دقیق با چه قرارداد و شواهدی آزموده شده؟». Authorization/Workflow Policy پاسخ می‌دهد «آیا همین درخواست مشخص اجازه استفاده از آن قابلیت را دارد؟». قاطی‌کردن این سه لایه یکی از رایج‌ترین راه‌های ایجاد اختیار ناخواسته برای عامل هوش مصنوعی است.

ممکن است یک ابزار واقعاً QUALIFIED باشد اما workflow جاری در allowlist آن نباشد؛ در این حالت Qualification سالم است ولی invocation باید BLOCKED شود. برعکس، ممکن است احراز هویت موفق شود اما permission set نسبت به رکورد qualification تغییر کرده باشد؛ این موفقیت شبکه‌ای مجوز ادامه استفاده نیست.

3. واقعیت فعلی MCP و مرز استنتاج

در نسخه MCP 2026-07-28 نام روش و ابزار در metadata/header قابل حمل است، پاسخ‌های فهرست می‌توانند cache hint داشته باشند و schema ابزارها از JSON Schema 2020-12 کامل استفاده می‌کنند. این امکانات برای discovery، routing و validation مفیدند؛ اما هیچ‌کدام به‌تنهایی نمی‌گویند ابزار برای مرز محصول شما امن یا تأییدشده است.

قاعده عملی: «قابلیت پروتکل» را به «اثبات محصول» تبدیل نکن. ما از metadata برای ساخت candidate identity استفاده می‌کنیم، نه برای اعطای خودکار QUALIFIED.

4. Official MCP Registry چه چیزی می‌دهد و چه چیزی نمی‌دهد

Official MCP Registry در تاریخ کنترل این درس هنوز Preview است و خودش را مخزن متمرکز metadata برای MCP serverهای عمومی معرفی می‌کند. namespace authentication، اطلاعات نصب/پیکربندی و discovery API ارزشمندند. همین مستندات همچنین توضیح می‌دهند که Registry روی metadata hosting و namespace authenticity تمرکز دارد و security scanning کد را به package registryها و aggregatorها واگذار می‌کند.

پس حضور در Registry یک signal منشأ/انتشار است، نه گواهی MAKNOW. رکورد discovery باید discovery_source داشته باشد، ولی وضعیت QUALIFIED فقط از qualification suite و evidence bundle خود شما می‌آید.

5. هویت دقیق Tool Entry

کلید عملی یک entry نباید فقط tool_name باشد. حداقل باید server identity، server version، tool name/version، protocol version، endpoint identity و digestهای schema ورودی/خروجی کنار هم ثبت شوند. اگر implementation version جدا از server version است، آن هم باید versioned باشد.

نام یکسان با schema متفاوت یعنی candidate متفاوت. نسخه جدید server با همان نام ابزار نیز candidate جدید است تا زمانی که قواعد شما خلاف آن را با evidence مشخص ثابت کنند. تاریخچه رکورد قبلی را بازنویسی نکن؛ entry جدید بساز و رابطه supersedes یا discovered-after را ثبت کن.

6. قرارداد Schema و Argument

input_schema_digest و output_schema_digest باید از representation نرمال‌شده و versioned schema محاسبه شوند. فقط مقایسه عنوان فیلدها کافی نیست؛ required arguments، enumها، conditionalها، references و shape خروجی می‌توانند رفتار workflow را تغییر دهند.

در کنار digest، argument_contract و required_arguments را ثبت کن. تغییر schema یک drift signal است. اگر output schema عوض شد حتی وقتی نام ابزار و endpoint ثابت‌اند، qualification قبلی نباید با نام به نسخه جدید منتقل شود.

7. Permission، Credential و Tenant Boundary

رکورد qualification باید scopeهای مورد انتظار، permission set، credential mode و tenant boundary را ثبت کند. این بخش مشخص می‌کند ابزار با چه اختیار واقعی آزموده شده است. «سرور این scope را پشتیبانی می‌کند» با «credential این invocation همین scope محدود را دارد» دو گزاره متفاوت‌اند.

اگر qualification برای docs:read انجام شده و configuration بعداً docs:admin را نیز وارد مرز اختیار کند، این permission drift است. حتی اگر درخواست فعلی read-only باشد، تصمیم باید دوباره از policy عبور کند؛ موفق بودن authentication یا فراخوانی قبلی جایگزین این ارزیابی نیست.

8. Side Effect، Data Access و Network Boundary

هر tool باید یک side-effect class داشته باشد: برای مثال READ_ONLY، WRITE_CAPABLE یا DESTRUCTIVE. data_access_class می‌تواند public، tenant-private یا sensitive باشد. network_scope و endpoint_identity نیز مقصدهایی را که اجرای ابزار مجاز است لمس کند مشخص می‌کنند.

ابزاری که از read-only به write-capable تغییر می‌کند، حتی با schema ظاهراً مشابه، همان قرارداد قبلی نیست. تغییر دامنه شبکه از docs.example به یک مقصد دیگر نیز requalification trigger است. این فیلدها باید hard gate باشند، نه صرفاً metadata نمایشی.

9. Admission Contract کامل‌تر از «کار کرد» است

برای ابزارهای دارای اثر، فیلدهایی مانند idempotency class، approval requirement، rollback capability و dry-run capability تعیین می‌کنند آیا می‌توان خطا یا retry را کنترل کرد. timeout، rate-limit behavior، error taxonomy و observability contract نیز باید تا حد لازم ثبت شوند.

یک call موفق فقط یک نمونه اجراست. Qualification باید مجموعه fixtureهای مثبت و منفی داشته باشد تا رفتار در خطا، timeout، permission denial و response invalid نیز قابل پیش‌بینی باشد. نبودن شواهد لازم به معنی UNKNOWN یا CANDIDATE است، نه PASS ضمنی.

10. چرخه عمر Registry

حالت پایه را با CANDIDATE شروع کن. پس از تطبیق identity، schema، permission، side-effect، data/network boundary و اجرای qualification suite، entry می‌تواند QUALIFIED شود. اگر evidence منقضی شد، STALE; اگر drift تعیین‌کننده مشاهده شد، SUSPENDED; اگر policy جاری invocation را منع کرد، eligibility آن invocation BLOCKED می‌شود؛ و اگر اعتماد به آن entry پس گرفته شد، REVOKED مناسب است.

نکته مهم: وضعیت Qualification entry و eligibility یک درخواست یک چیز نیستند. یک entry ممکن است QUALIFIED باقی بماند ولی برای workflow خاص مجاز نباشد.

11. Drift Detection و Requalification Trigger

Drift را به‌صورت فیلدهای مشخص ثبت کن: VERSION_DRIFT، INPUT_SCHEMA_DRIFT، OUTPUT_SCHEMA_DRIFT، PERMISSION_DRIFT، SIDE_EFFECT_DRIFT، DATA_ACCESS_DRIFT، NETWORK_DRIFT یا EVIDENCE_STALE. این نام‌گذاری باعث می‌شود علت suspension قابل ممیزی بماند.

قانون این درس: drift تعیین‌کننده هیچ‌وقت با silent inheritance بسته نمی‌شود. یا entry تازه CANDIDATE می‌سازی، یا entry موجود را SUSPENDED می‌کنی و qualification suite مربوط به همان dimension را دوباره اجرا می‌کنی.

12. Lab: سناریوی docs.lookup

Fixture پایه از server com.example/docs نسخه 2.4.1 و tool docs.lookup تشکیل شده است. input digest برابر s-in-17، output digest برابر s-out-9، scope برابر docs:read، side effect برابر READ_ONLY، data access برابر PUBLIC و network target برابر docs.example است. suite می‌گذرد و entry به QUALIFIED می‌رسد.

در fixtureهای بعدی فقط یک بعد تعیین‌کننده تغییر می‌کند: نسخه/schema، permission expansion، network، side effect، freshness، policy allowlist یا وضعیت discovery. هدف این است که بفهمی کدام تغییر Qualification را می‌شکند و کدام تغییر فقط availability/discovery را تغییر می‌دهد.

13. Counterexample: همان نام، ابزار دیگر

فرض کن discovery بعدی هنوز docs.lookup را برمی‌گرداند اما server به 2.5.0 رفته، output schema تغییر کرده و قابلیت write افزوده شده است. اگر سیستم فقط نام را key کند، qualification قدیمی را ناخواسته به قابلیت جدید قرض می‌دهد.

تصمیم درست: رکورد 2.4.1 را برای تاریخچه حفظ کن، candidate جدید بساز، eligibility قابلیت تغییرکرده را تا اجرای qualification تازه متوقف کن و دقیقاً VERSION_DRIFT، OUTPUT_SCHEMA_DRIFT و SIDE_EFFECT/PERMISSION_DRIFT را ثبت کن.

14. Transfer: scope بیشتر، schema همان

در مسئله انتقال، server version و schemaها byte-identical مانده‌اند اما authorization configuration از docs:read به مجموعه‌ای شامل docs:admin گسترش یافته است. workflow فقط read می‌خواهد. چون قرارداد qualification قبلی permission boundary محدودتری داشته، نباید از authentication موفق نتیجه بگیریم که همه چیز همان است.

در policy این درس، permission expansion یک requalification trigger است. اگر معماری شما بتواند credential را به‌طور قابل اثبات فقط به docs:read محدود کند، می‌توان بعد از ثبت evidence جدید یک qualification مشروط و محدود ساخت؛ اما رکورد قبلی بدون evidence تازه به‌صورت silent ادامه پیدا نمی‌کند.

15. Definition of Done و چک‌لیست ممیزی

خروجی خوب باید هویت exact ابزار، schema digestها، scope/permission، side effect، data/network boundary، qualification suite و evidence ref، lifecycle state، drift signal، requalification trigger، workflow allowlist و audit event را داشته باشد. هر ادعا باید مشخص کند fact پروتکل است، metadata discovery است یا design/policy محصول.

برای PASS نهایی پنج سؤال را جواب بده: آیا discovery از qualification جداست؟ آیا entry به version/schema/permission دقیق bind شده؟ آیا negative fixture وجود دارد؟ آیا UNKNOWN/STALE/SUSPENDED/BLOCKED حفظ می‌شوند؟ و آیا تغییر context باعث تصمیم تازه می‌شود؟ اگر پاسخ یکی از این‌ها نه است، Tool Registry هنوز برای admission قابل اتکا نیست.