تعریف resources (Defining resources)

عنوان اصلی: Defining resources

هدف یادگیری: تعریف MCP resources: ثابت، parameterized template، و محتوای binary.

مفاهیم کلیدی: Resource URI، resources/list، resources/read، resources/templates/list، URI template (RFC 6570)، text vs blob content، MIME type، application-controlled.

Resourceها application-controlled هستند. داده‌های فقط خواندنی هستند که host می‌تواند به context مدل ضمیمه کند — فایل‌ها، schema database، پاسخ‌های API، snippetهای log. هر resource یک URI یکتا (اغلب file://، https://، git:// یا scheme سفارشی)، یک name، title اختیاری، description اختیاری، mimeType اختیاری و size اختیاری دارد. محتوای resource یا text است یا blob (base64). resourceها می‌توانند parameterized هم باشند — resource templates که RFC 6570 URI template هستند، مثل file:///{path} که host می‌تواند پر کند.

سرورها بهتر است capability resources را با sub-flagهای اختیاری subscribe و listChanged اعلام کنند. resourceها با resources/list (paginated با cursor/nextCursor)، templateها با resources/templates/list، و read با resources/read لیست می‌شوند.

طراحی application-controlled (در مقابل tools که model-controlled است) عامدانه است: UI host، resourceها را به‌عنوان @-mentionable context item یا یک tree picker نشان می‌دهد؛ به LLM اجازه نمی‌دهد به‌صورت مستقل آن‌ها را enumerate و read کند.

مثال عملی — Python (resource ثابت + parameterized)

@mcp.resource("config://settings")
def get_settings() -> str:
    """Get application settings."""
    return '{"theme": "dark", "language": "en", "debug": false}'

@mcp.resource("file://documents/{name}")
def read_document(name: str) -> str:
    """Read a document by name (parameterized resource template)."""
    return f"Content of {name}"

مثال عملی — JSON-RPC خام

{ "jsonrpc": "2.0", "id": 2, "method": "resources/read",
  "params": { "uri": "file:///project/src/main.rs" } }

دیاگرام معماری (متنی): UI host یک resource picker نشان می‌دهد. کاربر file://documents/report.md را انتخاب می‌کند. Host → Server: resources/read با همان URI. Server → Host: آرایه contents با text یا blob. Host متن را به context window مدل تزریق می‌کند.

اشتباهات رایج

• یکی گرفتن resources با tools. resourceها read هستند؛ toolها act می‌کنند. اگر یک «resource» state را تغییر می‌دهد، باید tool باشد.
• استفاده از https:// برای محتوایی که client مستقیماً نمی‌تواند fetch کند. طبق spec: فقط وقتی از https:// استفاده کنید که خود client می‌تواند fetch کند؛ در غیر این صورت از scheme سفارشی استفاده کنید تا server fetch را proxy کند.
• برگرداندن binary در فیلد text. برای غیرمتنی از blob (base64) استفاده کنید.