Įrankiai, ištekliai ir užuominos MCP
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. — MCP Python SDK v2. Šis kursas dabar remiasi 2 versija (
mcpSDK 2.3.0, 2026 m. spalio 2 d. duomenimis):MCPServerpakeičiaFastMCP, transporto nustatymai perkeliami įrun()arbastreamable_http_app(), o programa, eksponuojama tikru prieglobos vardu, privalo deklaruoti tą vardą (transport_security). Tai taip pat yra versija, reikalinga Mistral SDK:mistralai[agents]papildinys reikalaujamcp>=2.2.0,<3.0. Šaltiniai: Kas naujo v2 · Migracijos gidas · Diegimas ir mastelio keitimas.
Trys galimybės, trys tikslai
MCP serveris gali atverti klientams trijų tipų galimybes. Jos nėra keičiamos vietomis: kiekviena tenkina skirtingą poreikį, o jų painiojimas sukuria serverius, kuriuos modeliui sunku naudoti. Šioje pamokoje jas nagrinėsime po vieną, prieš imdamiesi klausimo, lemiančio serverio kokybę: kiek įrankių reikia ir kokio granuliškumo jie turi būti.
Įrankiai: vykdomosios funkcijos
Įrankiai yra dažniausiai naudojama protokolo galimybė. Įrankis yra funkcija, kurią modelis gali nuspręsti iškviesti veiksmui atlikti arba informacijai gauti. Jo apibrėžtis remiasi keturiais elementais: unikaliu, aiškiu pavadinimu (create_issue, get_weather), teksto aprašymu, nurodančiu modeliui, kada jį kviesti, JSON schema įvesties parametrams su jų tipais ir apribojimais bei grąžinamu formatu – dažniausiai tekstu arba 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})"
Neįvertinkite aprašymo ir tipų svarbos: modelis nemato nieko kito. Jis neturi prieigos prie tavo kodo, negali atspėti tavo ketinimų ir negali atlikti bandomojo kvietimo, kad pamatytų rezultatą. Neaiškūs aprašymai arba neteisingai nurodyti parametrai mechaniškai sukelia klaidingus kvietimus.
Keli įpročiai gali žymiai padidinti tavo įrankių patikimumą. Pavadinkite juos pagal tai, ką jie daro – book_restaurant pasako viską, o process_request nepasako nieko – ir aprašykite tiek veiksmą, tiek grąžinamą turinį, nes modelis turi numatyti, ką gaus. Visada anotacijomis nurodykite Python parametrų tipus ir rašykite struktūruotas dokumentacijos eilutes su Args ir Returns: jos maitina schemą, kurią mato modelis. Galiausiai grąžinkite skaitomas reikšmes, o ne nepermatomus identifikatorius; įrankis, grąžinantis "John Smith", leidžia modeliui sudaryti sakinį, o įrankis, grąžinantis UUID, verčia jį spėlioti.
Ištekliai: skaitomi duomenys
Ištekliai atveria duomenis, kuriuos klientas gali skaityti be šalutinio poveikio. Skirtumas nuo įrankių glūdi viename veiksmažodyje: įrankis ką nors daro, o išteklius ką nors turi. Konfigūracijos failo turinys, žinių bazė, API dokumentacija arba dabartinė sistemos būsena – visa tai yra natūralūs ištekliai.
@app.resource("config://database")
def get_db_config() -> str:
"""Current database configuration."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Kiekvienas išteklius identifikuojamas URI – config://database, file:///path/to/doc – kurį klientas gali išvardinti ir tada skaityti pagal poreikį. Praktiškai jie naudojami rečiau nei įrankiai, nes paprastas įrankis, grąžinantis duomenis, patenkina daugumą poreikių. Jie lieka naudingi, kai norite paskelbti statinius arba pusiau statinius duomenis be už jų slypinčios vykdymo logikos.
Užuominos: pakartotinai naudojami šablonai
MCP užuominos (Prompts) yra parametrizuojami šablonai, kuriuos serveris pateikia kaip prieinamus. Jos skirtos dalintis patikrintomis instrukcijomis konkrečiai užduočiai, užuot leidus kiekvienam iš naujo kurti savo formuluotes.
@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}
```"""
Šis naudojimas labiausiai prasmingas komandos aplinkoje. Vyresnysis programuotojas įkoduoja savo kodų peržiūros, derinimo arba architektūros analizės užuominas į MCP serverį, ir visa komanda gali jomis naudotis iš savo klientų, gaudama tą pačią instrukcijų kokybę.
Galimybių derinimas
Klientui prisijungus prie serverio, prieš bet kokį naudojimą vyksta derinimo fazė:
- Klientas prašo serverio galimybių sąrašo
- Serveris atsako savo įrankių, išteklių ir užuominų sąrašu
- Klientas pateikia šias galimybes kalbos modeliui
- Modelis, naudodamas aprašymus, nusprendžia, ką kviesti
Šis derinimas yra dinamiškas, ir tai yra savybė, kurią galima išnaudoti: tas pats serveris gali pranešti apie skirtingas galimybes priklausomai nuo prisijungusio naudotojo arba kvietimo konteksto – administratoriaus paskyra mato įrankius, kurių tik skaitymo teises turinti paskyra niekada nematys.
Kiek įrankių vienam serveriui?
Klausimas atrodo trivialus, tačiau jis lemia tavo agento klaidų dažnį. Laikyk savo serverius sutelktus: trys–dešimt gerai apibrėžtų įrankių veikia geriau nei penkiasdešimt bendro pobūdžio. Viršijus tam tikrą apimtį, modelis išbarsto savo pasirinkimus ir galiausiai iškviečia neteisingą įrankį arba atlieka nereikalingus kvietimus vieną po kito.
Jei tavo funkcinė apimtis plati, suskirstyk ją į kelis specializuotus serverius – vieną Git operacijoms, vieną projektų valdymui, vieną stebėsenai. Klientas moka vienu metu prisijungti prie kelių serverių ir aktyvuoti tik tuos, kurių reikia dabartinei užduočiai, o tai reiškia, kad užkraunamas tik naudingas kontekstas, o ne visas katalogas.
Vienas paskutinis kompromisas nusipelno tavo dėmesio: granuliškumas. Trijų įrankių eksponavimas restoranams išvardinti, laisvumui patikrinti ir tada rezervuoti verčia modelį orchestruoti seką, kur kiekviename žingsnyje kyla klaidų rizika. Vienas darbo eigos įrankis – book_restaurant – įkapsuliuoja visą seką, sumažina apsilankymų skaičių ir perkelia verslo logiką ten, kur ją galima testuoti: į tavo kodą.
Svarbiausi punktai
- Įrankiai = vykdomieji veiksmai (90 % naudojimo atvejų), reikalauja tikslaus aprašymo ir tipų
- Ištekliai = skaitomi duomenys per URI, be šalutinio poveikio
- Užuominos = pakartotinai naudojami šablonai, naudingi komandoms
- Laikyk savo serverius sutelktus (daugiausia 3–10 įrankių)
- Teik pirmenybę darbo eigos įrankiams, o ne pernelyg smulkiems įrankiams
- Aprašymo kokybė lemia modelio efektyvumą