Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Kompletný príklad: Lokálny server s agentom

Lekcia 6 z 14 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Spájanie dielov dohromady
  2. Server: weather_server.py
  3. Klient: main.py
  4. Spustenie projektu
  5. Sledovanie budovania odpovede
  6. Keď nástroj zlyhá
  7. Kľúčové poznatky

Aktualizované 2. novembra 2026 — MCP Python SDK v2. Tento kurz teraz nasleduje verziu 2 SDK mcp (2.3.0 k 2. októbru 2026): MCPServer nahrádza FastMCP, nastavenia transportu sa presúvajú do run() alebo streamable_http_app() a aplikácia vystavená pod skutočným hostname musí tento hostname deklarovať (transport_security). Toto je tiež verzia požadovaná Mistral SDK: extra balík mistralai[agents] vyžaduje mcp>=2.2.0,<3.0. Zdroje: Čo je nové vo v2 · Sprievodca migráciou · Nasadenie a škálovanie. Dodatok 3. novembra: výsledok run_async čítaj z result.output_as_text (SDK mistralai 3.7.0 nemá atribút output) a v režime streamovania je poslednou udalosťou RunResult, identifikovateľný pomocou isinstance, ako v oficiálnom príklade SDK.

Spájanie dielov dohromady

Predchádzajúce lekcie položili stavebné kamene oddelene: server s jeho nástrojmi, klient a jeho RunContext. Teraz ich spojíš do funkčného projektu – lokálneho MCP servera poskytujúceho informácie o počasí, poháňaného agentom Mistral schopným odpovedať na otázky v prirodzenom jazyku. Čítaj kód, ale venuj pozornosť tomu, čo rozhoduje každá časť: server rozhoduje o tom, čo je možné, agent rozhoduje o tom, čo je relevantné.

Server: weather_server.py

Tento server pozostáva z troch nástrojov. Prvý vracia počasie pre mesto, druhý porovnáva dve mestá a tretí vypisuje obsah databázy. Ten posledný nie je len ozdobný: dáva modelu spôsob, ako objaviť dostupný rozsah namiesto hádania názvov miest.

# weather_server.py
"""Local MCP server providing weather tools."""

from mcp.server.mcpserver import MCPServer
import json

app = MCPServer("Weather Service")

# Simulated database
WEATHER_DATA = {
    "paris": {"temp": 18.5, "condition": "Cloudy", "humidity": 72},
    "lyon": {"temp": 22.0, "condition": "Sunny", "humidity": 45},
    "marseille": {"temp": 25.3, "condition": "Sunny", "humidity": 38},
    "lille": {"temp": 14.2, "condition": "Rainy", "humidity": 88},
    "bordeaux": {"temp": 20.1, "condition": "Partly cloudy", "humidity": 55},
}

@app.tool()
def get_weather(city: str) -> str:
    """Retrieves current weather for a French city.

    Args:
        city: City name in lowercase (paris, lyon, marseille, etc.)

    Returns:
        JSON with temperature, condition, and humidity.
        Returns an error if the city is unknown.
    """
    city_lower = city.lower().strip()
    if city_lower in WEATHER_DATA:
        data = WEATHER_DATA[city_lower]
        return json.dumps({
            "city": city.capitalize(),
            "temperature_celsius": data["temp"],
            "condition": data["condition"],
            "humidity_percent": data["humidity"],
        }, ensure_ascii=False)
    return json.dumps({"error": f"City {city} not found. Available cities: {', '.join(WEATHER_DATA.keys())}"})

@app.tool()
def compare_weather(city_a: str, city_b: str) -> str:
    """Compares weather between two French cities.

    Args:
        city_a: First city (lowercase)
        city_b: Second city (lowercase)

    Returns:
        Comparison of temperatures and conditions for both cities
    """
    a = WEATHER_DATA.get(city_a.lower().strip())
    b = WEATHER_DATA.get(city_b.lower().strip())
    if not a:
        return f"Unknown city: {city_a}"
    if not b:
        return f"Unknown city: {city_b}"

    diff = a["temp"] - b["temp"]
    warmer = city_a if diff > 0 else city_b
    return json.dumps({
        "city_a": {"name": city_a.capitalize(), **a},
        "city_b": {"name": city_b.capitalize(), **b},
        "temperature_difference": abs(diff),
        "warmer_city": warmer.capitalize(),
    }, ensure_ascii=False)

@app.tool()
def list_cities() -> str:
    """Lists all cities available in the weather database.

    Returns:
        List of cities with their current temperature
    """
    cities = [
        {"city": k.capitalize(), "temp": v["temp"], "condition": v["condition"]}
        for k, v in WEATHER_DATA.items()
    ]
    return json.dumps(cities, ensure_ascii=False)

Dva detaily dizajnu si zaslúžia pozornosť. Nástroje normalizujú vstup pomocou .lower().strip(), pretože model môže napísať „Paris“ alebo „paris“ v závislosti od formulácie používateľa. A keď mesto chýba, get_weather nevyhodí výnimku: vráti JSON s chybou, ktorý vymenúva známe mestá, čím mení zlyhanie na informáciu, ktorú môže model využiť.

Klient: main.py

Klient robí štyri veci v poradí: inicializuje Mistral, vytvorí agenta, popíše, ako spustiť server, a potom otvorí RunContext na reťazenie konverzácií.

# main.py
"""MCP client with Mistral agent for weather queries."""

import asyncio
import os
from pathlib import Path

from mistralai.client import Mistral
from mistralai.extra.run.context import RunContext
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from mcp import StdioServerParameters
from pydantic import BaseModel

# Configuration
MISTRAL_API_KEY = os.environ.get("MISTRAL_API_KEY")
SERVER_PATH = Path(__file__).parent / "weather_server.py"

# Structured output format (optional)
class WeatherResponse(BaseModel):
    summary: str
    details: dict | None = None

async def main():
    # 1. Initialize Mistral client
    client = Mistral(api_key=MISTRAL_API_KEY)

    # 2. Create the agent
    agent = client.beta.agents.create(
        model="mistral-medium-latest",
        name="weather-assistant",
        instructions=(
            "You are a weather assistant for France. "
            "Use available tools to answer questions. "
            "Always respond in French with metric units."
        ),
    )

    # 3. Configure local MCP server
    server_params = StdioServerParameters(
        command="python",
        args=[str(SERVER_PATH)],
        env=None,
    )
    mcp_client = MCPClientSTDIO(stdio_params=server_params)

    # 4. Open context and register MCP client
    async with RunContext(
        agent_id=agent.id,
        continue_on_fn_error=True,
    ) as run_ctx:
        await run_ctx.register_mcp_client(mcp_client=mcp_client)

        # 5. Launch conversations
        questions = [
            "What's the weather like in Paris?",
            "Compare the weather between Marseille and Lille.",
            "Which city is the warmest right now?",
        ]

        for question in questions:
            print(f"\n{'='*60}")
            print(f"Question: {question}")
            print(f"{'='*60}")

            result = await client.beta.conversations.run_async(
                run_ctx=run_ctx,
                inputs=question,
            )

            print(f"Response: {result.output_as_text}")

    # 6. Automatic cleanup upon exiting context manager
    print("\nAgent and MCP server closed cleanly.")

if __name__ == "__main__":
    asyncio.run(main())

Všimni si cestu k serveru: Path(__file__).parent / "weather_server.py" lokalizuje súbor relatívne k skriptu, nie k aktuálnemu adresáru. Toto je jediný spôsob, ako zaručiť, že spustenie bude fungovať bez ohľadu na to, odkiaľ spustíš python main.py.

Spustenie projektu

# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"

# Launch client (it will launch the server automatically)
python main.py

Spustíš iba jeden proces. Klient vytvorí agenta Mistral, RunContext spustí weather_server.py ako proces STDIO, objaví tri nástroje – get_weather, compare_weather a list_cities – a potom, otázku po otázke, nechá model vybrať, ktoré z nich zavolať, predtým než integruje výsledky do svojej odpovede. Tretia otázka v príklade je najzaujímavejšia na pozorovanie: aby vedel, ktoré mesto je najteplejšie, model nemá na výber a musí prejsť cez list_cities, hoci žiadne slovo v otázke to nenaznačuje.

Sledovanie budovania odpovede

Čakanie na úplnú odpoveď funguje pre skript; pri práci s používateľom však režim streamovania ponúka oveľa lepší zážitok.

from mistralai.extra.run.result import RunResult

async with RunContext(agent_id=agent.id) as run_ctx:
    await run_ctx.register_mcp_client(mcp_client=mcp_client)

    events = await client.beta.conversations.run_stream_async(
        run_ctx=run_ctx,
        inputs="What's the weather like in Lyon?",
    )

    async for event in events:
        if isinstance(event, RunResult):
            # Last event: complete run result
            print(event.output_as_text)
        else:
            # Intermediate events (tool calls, etc.)
            print(f"[Event] {event}")

Stream udalostí nie je len na zobrazenie: je to aj tvoj najlepší nástroj na ladenie, pretože v reálnom čase odhaľuje volania nástrojov a argumenty vybrané modelom.

Keď nástroj zlyhá

Vďaka continue_on_fn_error=True požiadavka mimo rozsahu nič nerozbije. Ak používateľ požiada o počasie v Tokiu, get_weather vráti svoj JSON s chybou, model si ho prečíta a reaguje návrhom skutočne dostupných miest.

# If the user requests a non-existent city:
# → get_weather returns {"error": "City tokyo not found..."}
# → The model reads the error and reformulates its response
# → "I'm sorry, Tokyo is not in my database. Here are the available cities..."

Nakoniec, projekt sa zmestí do štyroch súborov, z ktorých iba dva obsahujú logiku:

weather-mcp-project/
├── weather_server.py    # MCP server (3 tools)
├── main.py              # Client with Mistral agent
├── requirements.txt     # mcp>=2.2,<3, mistralai[agents], pydantic
└── .env                 # MISTRAL_API_KEY=...

Kľúčové poznatky

  • Kompletný projekt MCP = server (nástroje) + klient (agent + RunContext)
  • Server definuje nástroje pomocou MCPServer a dekorátorov @app.tool()
  • Klient vytvára agenta, otvára RunContext a spúšťa konverzácie
  • Režim streamovania umožňuje postupné zobrazovanie
  • continue_on_fn_error=True elegantne rieši chyby nástrojov
  • Všetok kód je asynchrónny – ako vstupný bod používaj asyncio.run()