@mcp.resource() și @mcp.prompt() în SDK-ul Python (MCPServer) în Model Context Protocol (MCP)

@mcp.resource("schema://cale/{param}", mime_type="...")
@mcp.prompt()

Ce face @mcp.resource() și @mcp.prompt() în SDK-ul Python (MCPServer)

@mcp.resource(uri) pe o funcție o transformă în resursă. URI-ul este adresa, numele funcției devine name, docstring-ul devine descrierea, iar valoarea întoarsă este conținutul. Funcția nu rulează la resources/list, ci doar la resources/read, pentru URI-ul cerut. Un str se trimite ca text, bytes devine blob base64, orice altceva serializabil (dict, listă, model Pydantic) devine text JSON. mime_type este implicit text/plain, iar SDK-ul nu îl deduce din valoarea întoarsă.

Un URI cu {parametru} devine șablon de resursă: apare în resources/templates/list, nu în resources/list, iar valoarea potrivită ajunge în parametrul cu același nume al funcției. Dacă numele din URI și din funcție nu coincid, decoratorul aruncă ValueError la import. În v2 șabloanele respectă RFC 6570 ({+path}, {?q,lang}), potrivirea este exactă, iar path traversal în valorile extrase este respins implicit.

@mcp.prompt() transformă o funcție într-un prompt. Argumentele vin din parametri, ca listă de valori text cu nume (fără JSON Schema); un parametru fără valoare implicită este obligatoriu, iar lipsa lui la prompts/get produce eroarea -32602. Un str întors devine un singur mesaj user; pentru o conversație întoarce o listă de UserMessage și AssistantMessage din mcp.server.mcpserver.prompts.base. Pentru imagini și audio, SDK-ul are ajutoarele Image și Audio din mcp.server.mcpserver.

Sintaxă și opțiuni

Opțiune / Parametru	Descriere
@mcp.resource(uri)	Resursă fixă sau șablon (dacă URI-ul are {...}). Acceptă și name=, title=, description=, mime_type=.
{param} / {+path} / {?q}	Variabile RFC 6570; numele trebuie să coincidă cu parametrii funcției.
@mcp.prompt()	Prompt cu argumentele luate din parametri; acceptă title= și descrieri pentru argumente.
UserMessage / AssistantMessage	Mesaje dintr-un prompt cu mai multe ture; Message este tipul lor comun.
Image(path=...) / Audio(path=...)	Întorc conținut image sau audio; tipul MIME se deduce din extensia fișierului.
mcp.add_resource(...)	Înregistrează clase gata făcute: TextResource, BinaryResource, FileResource, HttpResource, DirectoryResource.

Exemple practice

Exemplul 1: Resursă fixă și șablon de resursă

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")


@mcp.resource("config://app")
def get_config() -> str:
    """The active shop configuration."""
    return "theme=dark\nlanguage=en"


@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """A customer's profile."""
    return f"User {user_id}: 12 orders since 2021."

Exemplul 2: Prompt cu mai multe mesaje

from mcp.server import MCPServer
from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage

mcp = MCPServer("Code Helper")


@mcp.prompt()
def debug_error(error: str) -> list[Message]:
    """Start a debugging conversation."""
    return [
        UserMessage("I'm seeing this error:"),
        UserMessage(error),
        AssistantMessage("I'll help debug that. What have you tried so far?"),
    ]

Exemplul 3: Unealtă care întoarce o imagine

from pathlib import Path

from mcp.server import MCPServer
from mcp.server.mcpserver import Image

mcp = MCPServer("Brand kit")

LOGO_FILE = Path(__file__).parent / "logo.png"


@mcp.tool()
def logo() -> Image:
    """The brand logo as a PNG."""
    return Image(path=LOGO_FILE)

Greșeli frecvente și bune practici

• Întorci un dict fără mime_type="application/json". Conținutul devine JSON, dar resursa este anunțată ca text/plain.
• Folosești alt nume în URI decât în semnătura funcției ({user_id} și user). Serverul nu pornește: decoratorul aruncă ValueError la import.
• Pui logică scumpă în listarea resurselor. Funcția rulează doar la citire; listarea este ieftină chiar și pentru multe resurse.

Comenzi înrudite

• fastmcp-python-server
• mcp-resources-uri
• mcp-prompts-sampling
• mcp-context-lifespan