Tööriistad, ressursid ja vihjed MCP-s
Sellel lehel
Uuendatud 2. novembril 2026 — MCP Python SDK v2. See kursus järgib nüüd
mcpSDK versiooni 2 (seisuga 2. oktoober 2026 on see 2.3.0):MCPServerasendabFastMCP-i, transpordiseaded liiguvad meetoditesserun()võistreamable_http_app()ja reaalse hostinime all avaldatud rakendus peab selle hostinime deklareerima (transport_security). See on ka versioon, mida nõuab Mistral SDK: lisapakettmistralai[agents]eeldabmcp>=2.2.0,<3.0. Allikad: Mis on uut v2-s · Rändejuhend · Kasutuselevõtt ja skaleerimine.
Kolm võimekust, kolm eesmärki
MCP server võib oma klientidele avaldada kolme tüüpi võimekusi. Need ei ole omavahel asendatavad: igaüks lahendab kindla vajaduse ja nende segiajamine tekitab servereid, mida mudelil on raske kasutada. Selles õppetükis vaatleme neid ükshaaval, enne kui asume käsitlema serveri kvaliteeti määravat küsimust: kui palju tööriistu ja millise granulaarsusega.
Tööriistad: käivitatavad funktsioonid
Tööriistad on protokolli kõige laiemalt kasutatav võimekus. Tööriist on funktsioon, mida mudel võib otsustada kutsuda toimingu sooritamiseks või teabe hankimiseks. Selle definitsioon tugineb neljale elemendile: unikaalne ja kirjeldav nimi (create_issue, get_weather), tekstiline kirjeldus, mis ütleb mudelile, millal seda kutsuda, sisendparameetrite JSON-skeem koos nende tüüpide ja piirangutega ning tagastusvorming – enamasti tekst või 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})"
Ära alahinda kirjelduse ja tüüpimise tähtsust: mudel ei näe midagi muud. Tal puudub ligipääs sinu koodile, ta ei saa arvata sinu kavatsusi ega testida kutset, et näha, mis juhtub. Ebamäärased kirjeldused või halvasti tüübitud parameetrid toodavad mehaaniliselt vigaseid kutseid.
Mõned harjumused muudavad sinu tööriistad oluliselt usaldusväärsemaks. Nimeta need selle järgi, mida need teevad – book_restaurant ütleb kõik, process_request ei ütle midagi – ja kirjelda nii tegevust kui ka tagastatavat sisu, sest mudel peab ette nägema, mida ta saab. Annoteeri parameetrid alati Pythonis ja kirjuta struktureeritud docstringid koos Args ja Returns osadega: need toidavad mudeli nähtavat skeemi. Lõpuks tagasta loetavad väärtused, mitte läbipaistmatud identifikaatorid; tööriist, mis tagastab "John Smith", võimaldab mudelil lause koostada, samas kui UUID-i tagastav tööriist sunnib teda arvama.
Ressursid: loetavad andmed
Ressursid avaldavad andmeid, mida klient saab lugeda ilma kõrvalmõjudeta. Peamine erinevus tööriistadest taandub ühele tegusõnale: tööriist teeb midagi, ressurss sisaldab midagi. Konfiguratsioonifaili sisu, teadmistebaas, API dokumentatsioon või süsteemi praegune olek on kõik loomulikud ressursid.
@app.resource("config://database")
def get_db_config() -> str:
"""Current database configuration."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Iga ressurss on identifitseeritud URI-ga – config://database, file:///path/to/doc – mida klient saab loetleda ja seejärel vajadusel lugeda. Praktikas kasutatakse neid harvemini kui tööriistu, kuna lihtne andmeid tagastav tööriist katab enamiku vajadusi. Need jäävad kasulikuks, kui soovid avaldada staatilisi või poolstaatilisi andmeid ilma taha peidetud täitmise loogikata.
Vihjed: taasutatavad mallid
MCP vihjed (Prompts) on parameetritestatud mallid, mida server kättesaadavaks teeb. Need teenivad eesmärki jagada tõestatud juhiseid kindla ülesande jaoks, selle asemel et lasta kõigil oma sõnastust nullist leiutada.
@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}
```"""
See kasutusviis on kõige mõttekam meeskonnakeskkonnas. Kogenud arendaja kodeerib oma koodiülevaatuse, silumise või arhitektuuri analüüsi vihjed MCP serverisse ja kogu meeskond pääseb neile oma kliendi kaudu ligi sama juhiste kvaliteediga.
Võimekuste läbirääkimine
Kui klient serveriga ühenduse loob, eelneb igale kasutusele läbirääkimiste faas:
- Klient küsib serveri võimekusi
- Server vastab oma tööriistade, ressursside ja vihjete loendiga
- Klient esitab need võimekused keelemudelile
- Mudel kasutab kirjeldusi, et otsustada, mida kutsuda
See läbirääkimine on dünaamiline ja see on omadus, mida saab ära kasutada: sama server võib avaldada erinevaid võimekusi sõltuvalt ühendatud kasutajast või kutse kontekstist – administraatori konto näeb tööriistu, mida ainult lugemisõigusega konto mitte kunagi ei näe.
Kui palju tööriistu serveri kohta?
Küsimus tundub triviaalne, ometi määrab see sinu agendi veamäära. Hoia oma serverid fokuseerituna: kolm kuni kümme hästi defineeritud tööriista toimivad paremini kui viiskümmend üldist. Teatud mahu ületamisel hajutab mudel oma valikuid ja lõpetab vale tööriista kutsumise või mittevajalike kutsete kuhjamisega.
Kui sinu funktsionaalne ulatus on lai, jaga see mitmeks spetsialiseeritud serveriks – üks Git-toimingute jaoks, üks projektijuhtimise jaoks, üks monitooringu jaoks. Klient oskab ühenduda mitme serveriga samaaegselt ja aktiveerida ainult need, mida praegune ülesanne nõuab, mis tähendab sisuliselt kasuliku konteksti laadimist, mitte kogu kataloogi.
Viimane kompromiss väärib sinu tähelepanu: granulaarsus. Kolme tööriista avaldamine restoranide loetlemiseks, vabaduse kontrollimiseks ja seejärel broneerimiseks sunnib mudelit orkestreerima jada, kus iga sammuga kaasneb veaoht. Üksainus töövoo tööriist – book_restaurant – kapseldab kogu jada, vähendab päringute arvu ja viib äriloogika sinna, kus seda on testitav: sinu koodi.
Peamised punktid
- Tööriistad = käivitatavad tegevused (90% kasutusjuhtudest), nõuavad täpset kirjeldust ja tüüpimist
- Ressursid = URI kaudu loetavad andmed, ilma kõrvalmõjudeta
- Vihjed = taasutatavad mallid, kasulikud meeskondadele
- Hoia oma serverid fokuseerituna (maksimaalselt 3–10 tööriista)
- Eelista töövoo tööriistu liiga peeneteralistele tööriistadele
- Kirjelduse kvaliteet määrab mudeli efektiivsuse