Għodod, Riżorsi, u Prompts fl-MCP
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 — MCP Python SDK v2. Dan il-kors issa jsegwi l-verżjoni 2 tal-SDK
mcp(2.3.0 sal-2 ta’ Ottubru, 2026):MCPServertissostitwixxiFastMCP, is-settings tat-trasport jiċċaqalqu lejnrun()jewstreamable_http_app(), u applikazzjoni esposta taħt hostname reali trid tiddikjara dak l-hostname (transport_security). Din hija wkoll il-verżjoni meħtieġa mill-Mistral SDK: l-extramistralai[agents]jeħtieġmcp>=2.2.0,<3.0. Sorsi: X’hemm ġdid fil-v2 · Gwida għall-Migrazzjoni · Iddispjega u skala.
Tliet kapaċitajiet, tliet intenzjonijiet
Server MCP jista’ jesponi tliet tipi ta’ kapaċitajiet lill-klijenti tiegħu. Dawn mhumiex interkambjabbli: kull wieħed jindirizza ħtieġa distinta, u l-konfużjoni bejn it-tlieta twassal għal servers li l-mudell isib diffiċli biex jużahom. Din il-lezzjoni teħodhom wieħed wieħed, qabel ma nittrattaw il-mistoqsija li tiddetermina l-kwalità tas-server: kemm għodda, u b’liema granularità.
Għodod: funzjonijiet eżegwibbli
L-Għodod huma l-aktar kapaċità użata tal-protokoll. Għodda hija funzjoni li l-mudell jista’ jiddeċiedi li jsejjaħ biex iwettaq azzjoni jew jirkupra informazzjoni. Id-definizzjoni tagħha tiddependi fuq erba’ elementi: isem uniku u deskrittiv (create_issue, get_weather), deskrizzjoni testwali li tgħid lill-mudell meta għandu jsejjaħha, skema JSON għall-parametri tal-input bit-tipi u l-vincoli tagħhom, u format ta’ ritorn—l-aktar spiss test jew 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})"
Tistmax id-deskrizzjoni u t-tajpjar: il-mudell ma jara xejn ħlief dan. M’għandux aċċess għall-kodiċi tiegħek, ma jistax jiggwissa l-intenzjonijiet tiegħek, u ma jistax jittestja sejħa biex jara x’jiġri. Deskrizzjonijiet vagi jew parametri miktuba ħażin mekkanikament jipproduċu sejħiet żbaljati.
Xi drawwiet jagħmlu l-għodod tiegħek ferm aktar affidabbli. Semmihom skont x’jagħmlu—book_restaurant tgħid kollox, process_request ma tgħid xejn—u ddeskrivi kemm l-azzjoni kif ukoll il-kontenut tar-ritorn, peress li l-mudell irid jantiċipa x’se jirkupra. Dejjem annota l-parametri f’Python u ikteb docstrings strutturati b’Args u Returns: dawn jgħinu lill-iskema li jara l-mudell. Fl-aħħar nett, irritorna valuri li jinqraw minflok identifikaturi opaki; għodda li tirritorna "John Smith" tippermetti lill-mudell jifforma sentenza, filwaqt li għodda li tirritorna UUID tifforzah jiggwissa.
Riżorsi: data li tista’ tinqara
Ir-Riżorsi jesponu data li l-klijent jista’ jaqra mingħajr effetti sekondarji. In-nuansa mal-għodod tinżel għal verb wieħed: għodda tagħmel xi ħaġa, riżorsa fiha xi ħaġa. Il-kontenut ta’ fajl ta’ konfigurazzjoni, bażi tal-għarfien, dokumentazzjoni tal-API, jew l-istat attwali ta’ sistema huma kollha riżorsi naturali.
@app.resource("config://database")
def get_db_config() -> str:
"""Current database configuration."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Kull riżorsa hija identifikata minn URI—config://database, file:///path/to/doc—li l-klijent jista’ jelenka u mbagħad jaqra meta jkun meħtieġ. Fil-prattika, jintużaw inqas mill-għodod, peress li għodda sempliċi li tirritorna data tkopri l-biċċa l-kbira tal-ħtiġijiet. Jibqgħu utli meta trid tippubblika data statika jew semi-statika mingħajr loġika ta’ eżekuzzjoni warajha.
Prompts: mudelli riutilizzabbli
Il-Prompts tal-MCP huma mudelli li jistgħu jiġu pparametrizzati li s-server jagħmel disponibbli. Iservu biex jaqsmu struzzjonijiet ippruvati għal kompitu partikolari, minflok ma jħallu lil kulħadd jerġa’ jinventa l-formulazzjoni tiegħu.
@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}
```"""
Dan l-użu jagħmel l-aktar sens f’ambjent ta’ tim. Żviluppatur senior jikkodifika l-prompts tar-reviżjoni tal-kodiċi, tad-debugging, jew tal-analiżi tal-arkitettura tiegħu f’server MCP, u t-tim kollu jaċċessahom mill-klijent tiegħu stess bl-istess kwalità ta’ struzzjoni.
Negozjar tal-kapaċità
Meta klijent jikkonnettja ma’ server, fażi ta’ negozjar tippreċedi kwalunkwe użu:
- Il-klijent jitlob il-kapaċitajiet tas-server
- Is-server iwieġeb bil-lista tal-għodod, ir-riżorsi, u l-prompts tiegħu
- Il-klijent jippreżenta dawn il-kapaċitajiet lill-mudell tal-lingwa
- Il-mudell juża d-deskrizzjonijiet biex jiddeċiedi x’għandu jsejjaħ
Dan in-negozjar huwa dinamiku, u dik hija proprjetà li tista’ tiġi sfruttata: l-istess server jista’ jħabbar kapaċitajiet differenti skont l-utent konness jew il-kuntest tas-sejħa—kont ta’ amministratur jara għodod li kont ta’ qari biss qatt ma se jara.
Kemm-il għodda għal kull server?
Il-mistoqsija tidher trivjali, madankollu tikkundizzjona r-rata ta’ żball tal-aġent tiegħek. Żomm is-servers tiegħek iffukati: tlieta sa għaxar għodod iddefiniti sew jaħdmu aħjar minn ħamsin ġeneriċi. Lil hinn minn volum partikolari, il-mudell jixxerred fil-għażliet tiegħu u jispiċċa jsejjaħ l-għodda ħażina, jew iġemma’ sejħiet mhux meħtieġa.
Jekk l-ambitu funzjonali tiegħek huwa wiesa’, aqsmu f’diversi servers speċjalizzati—wieħed għall-operazzjonijiet ta’ Git, ieħor għall-ġestjoni tal-proġetti, ieħor għall-monitoraġġ. Il-klijent jaf kif jikkonnettja ma’ diversi servers simultanjament u jattiva biss dawk meħtieġa mill-kompitu attwali, li jammonta għat-tagħbija tal-kuntest utli minflok il-katalgu sħiħ.
Kompromess wieħed tal-aħħar jistħoqqilhom l-attenzjoni tiegħek: il-granularità. L-espożizzjoni ta’ tliet għodod biex telenka r-ristoranti, tiċċekkja d-disponibbiltà, u mbagħad tibbokka tifforza lill-mudell jorkestra sekwenza, b’riskju ta’ żball f’kull pass. Għodda waħda ta’ fluss tax-xogħol—book_restaurant—tinkapsula s-sekwenza sħiħa, tnaqqas in-numru ta’ vjaġġi mar-ritorn, u tmexxi l-loġika tan-negozju fejn hija ttestjabbli: fil-kodiċi tiegħek.
Punti Ewlenin
- Għodod = azzjonijiet eżegwibbli (90% tal-każijiet ta’ użu), jeħtieġu deskrizzjoni u tajpjar preċiżi
- Riżorsi = data li tista’ tinqara permezz ta’ URI, mingħajr effetti sekondarji
- Prompts = mudelli riutilizzabbli, utli għat-timijiet
- Żomm is-servers tiegħek iffukati (massimu ta’ 3–10 għodod)
- Ippreferixxi għodod ta’ fluss tax-xogħol fuq għodod granulari wisq
- Il-kwalità tad-deskrizzjoni tiddetermina l-effiċjenza tal-mudell