Salt la conținutul principal
Română— Alege o limbă
Meniu

Instrumente, resurse și prompturi în MCP

Lecția 3 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Trei capabilități, trei intenții
  2. Instrumente: funcții executabile
  3. Resurse: date citibile
  4. Prompturi: șabloane reutilizabile
  5. Negocierea capabilităților
  6. Câte instrumente per server?
  7. Puncte cheie

Actualizat pe 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului mcp (2.3.0 la data de 2 octombrie 2026): MCPServer înlocuiește FastMCP, setările de transport se mută în run() sau streamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ul mistralai[agents] necesită mcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale.

Trei capabilități, trei intenții

Un server MCP poate expune clienților săi trei tipuri de capabilități. Acestea nu sunt interschimbabile: fiecare răspunde unei nevoi distincte, iar confundarea lor duce la servere greu de utilizat de către model. Această lecție le examinează pe rând, înainte de a aborda întrebarea care determină calitatea serverului: câte instrumente și la ce granularitate.

Instrumente: funcții executabile

Instrumentele reprezintă cea mai utilizată capabilitate a protocolului. Un instrument este o funcție pe care modelul poate decide să o apeleze pentru a efectua o acțiune sau pentru a recupera informații. Definiția sa se bazează pe patru elemente: un nume unic și descriptiv (create_issue, get_weather), o descriere textuală care indică modelului când să îl apeleze, o schemă JSON pentru parametrii de intrare cu tipurile și constrângerile lor și un format de returnare—cel mai adesea text sau JSON.

from mcp.server.mcpserver import MCPServer

app = MCPServer("My Server")

@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
    """Retrieves current weather for the given coordinates.

    Args:
        latitude: Latitude in decimal degrees (-90 to 90)
        longitude: Longitude in decimal degrees (-180 to 180)

    Returns:
        Text description of current weather
    """
    # Weather API call logic
    return f"Sunny, 22°C at ({latitude}, {longitude})"

Nu subestimați descrierea și tipizarea: modelul nu vede nimic altceva. Nu are acces la codul dumneavoastră, nu poate ghici intențiile și nu poate testa un apel pentru a vedea ce se întâmplă. Descrierile vagi sau parametrii tipizați necorespunzător produc mecanic apeluri incorecte.

Câteva obiceiuri fac instrumentele dumneavoastră semnificativ mai fiabile. Denumiți-le în funcție de ceea ce fac—book_restaurant spune totul, process_request nu spune nimic—și descrieți atât acțiunea, cât și conținutul returnat, deoarece modelul trebuie să anticipeze ce va recupera. Anotați întotdeauna parametrii în Python și scrieți docstring-uri structurate cu Args și Returns: acestea alimentează schema pe care o vede modelul. În final, returnați valori lizibile, nu identificatori opaci; un instrument care returnează "John Smith" permite modelului să compună o propoziție, în timp ce un instrument care returnează un UUID îl forțează să ghicească.

Resurse: date citibile

Resursele expun date pe care clientul le poate citi fără efecte secundare. Nuanța față de instrumente se rezumă la un verb: un instrument face ceva, o resursă conține ceva. Conținutul unui fișier de configurare, unei baze de cunoștințe, documentației API sau starea curentă a unui sistem sunt toate resurse naturale.

@app.resource("config://database")
def get_db_config() -> str:
    """Current database configuration."""
    return json.dumps({
        "host": "localhost",
        "port": 5432,
        "database": "production"
    })

Fiecare resursă este identificată printr-un URI—config://database, file:///path/to/doc—pe care clientul îl poate lista și apoi citi la cerere. În practică, acestea sunt utilizate mai rar decât instrumentele, deoarece un simplu instrument care returnează date acoperă majoritatea nevoilor. Ele rămân utile atunci când doriți să publicați date statice sau semi-statice fără logică de execuție în spatele lor.

Prompturi: șabloane reutilizabile

Prompturile MCP sunt șabloane parametrizabile pe care serverul le pune la dispoziție. Ele servesc la partajarea unor instrucțiuni dovedite pentru o anumită sarcină, în loc să lase pe fiecare să își reinventeze formularea.

@app.prompt()
def code_review(language: str, code: str) -> str:
    """Generates a code review prompt for the given language."""
    return f"""You are an expert in {language}.
Analyze the following code and identify:
1. Potential bugs
2. Performance issues
3. Readability improvements

Code to analyze:
```{language}
{code}
```"""

Această utilizare are cel mai mult sens într-un context de echipă. Un dezvoltator senior encodează prompturile sale de revizuire a codului, depanare sau analiză a arhitecturii într-un server MCP, iar întreaga echipă le accesează din propriul client cu aceeași calitate a instrucțiunilor.

Negocierea capabilităților

Atunci când un client se conectează la un server, o fază de negociere precede orice utilizare:

  1. Clientul solicită capabilitățile serverului
  2. Serverul răspunde cu lista sa de instrumente, resurse și prompturi
  3. Clientul prezintă aceste capabilități modelului lingvistic
  4. Modelul folosește descrierile pentru a decide ce să apeleze

Această negociere este dinamică, iar aceasta este o proprietate exploatabilă: același server poate anunța capabilități diferite în funcție de utilizatorul conectat sau de contextul apelului—un cont de administrator văzând instrumente pe care un cont de tip read-only nu le va vedea niciodată.

Câte instrumente per server?

Întrebarea pare trivială, dar condiționează rata de eroare a agentului dumneavoastră. Mențineți serverele focalizate: trei până la zece instrumente bine definite funcționează mai bine decât cincizeci generice. Dincolo de un anumit volum, modelul își împrăștie alegerile și ajunge să apeleze instrumentul greșit sau să înșiruiască apeluri inutile.

Dacă domeniul funcțional este larg, divizați-l în mai multe servere specializate—unul pentru operațiuni Git, unul pentru gestionarea proiectelor, unul pentru monitorizare. Clientul știe cum să se conecteze la mai multe servere simultan și să le activeze doar pe cele necesare sarcinii curente, ceea ce echivalează cu încărcarea contextului util, nu a întregului catalog.

Un ultim compromis merită atenția dumneavoastră: granularitatea. Expunerea a trei instrumente pentru a lista restaurantele, a verifica disponibilitatea și apoi a rezerva forțează modelul să orchestreze o secvență, cu un risc de eroare la fiecare pas. Un singur instrument de flux de lucru—book_restaurant—encapsulează secvența completă, reduce numărul de dus-întors și mută logica de afaceri acolo unde este testabilă: în codul dumneavoastră.

Puncte cheie

  • Instrumente = acțiuni executabile (90% din cazurile de utilizare), necesită descriere și tipizare precise
  • Resurse = date citibile prin URI, fără efecte secundare
  • Prompturi = șabloane reutilizabile, utile pentru echipe
  • Mențineți serverele focalizate (maximum 3–10 instrumente)
  • Preferați instrumentele de flux de lucru în detrimentul celor prea granulare
  • Calitatea descrierii determină eficiența modelului