Przejdź do głównej treści
Polski— Wybierz język
Menu

Przykład kompletny: Serwer lokalny z agentem

Lekcja 6 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Składanie elementów w całość
  2. Serwer: weather_server.py
  3. Klient: main.py
  4. Uruchamianie projektu
  5. Obserwowanie budowania odpowiedzi
  6. Gdy narzędzie zawiedzie
  7. Kluczowe wnioski

Zaktualizowano 2 listopada 2026 — MCP Python SDK v2. Ten kurs opiera się na wersji 2 SDK mcp (2.3.0 na dzień 2 października 2026): MCPServer zastępuje FastMCP, ustawienia transportu przeniesiono do run() lub streamable_http_app(), a aplikacja wystawiona pod rzeczywistą nazwą hosta musi ją zadeklarować (transport_security). Jest to również wersja wymagana przez Mistral SDK: dodatek mistralai[agents] wymaga mcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie. Dodatkowa uwaga z 3 listopada: wynik wywołania run_async odczytujesz z result.output_as_text (SDK mistralai w wersji 3.7.0 nie ma atrybutu output), a w trybie strumieniowania ostatnim zdarzeniem jest RunResult, co identyfikujesz za pomocą isinstance, zgodnie z oficjalnym przykładem w SDK.

Składanie elementów w całość

Poprzednie lekcje przedstawiły poszczególne bloki konstrukcyjne osobno: serwer i jego narzędzia, klienta oraz jego kontekst wykonania (RunContext). Teraz połączysz je w działający projekt — lokalny serwer MCP udostępniający informacje o pogodzie, sterowany przez agenta Mistral zdolnego odpowiadać na pytania w języku naturalnym. Przeczytaj kod, ale zwróć szczególną uwagę na decyzje podejmowane przez każdą część: serwer decyduje, co jest możliwe, natomiast agent decyduje, co jest istotne.

Serwer: weather_server.py

Ten serwer składa się z trzech narzędzi. Pierwsze zwraca pogodę dla danego miasta, drugie porównuje dwa miasta, a trzecie wymienia zawartość bazy danych. To ostatnie nie jest ozdobnikiem: daje modelowi możliwość odkrycia dostępnego zakresu danych, zamiast zgadywania nazw miast.

# 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)

Dwa szczegóły projektowe zasługują na uwagę. Narzędzia normalizują dane wejściowe za pomocą .lower().strip(), ponieważ model może zapisać „Paris“ lub „paris“ w zależności od sformułowania użytkownika. Gdy miasto nie istnieje, get_weather nie zgłasza wyjątku: zwraca JSON z błędem, który wymienia znane miasta, zamieniając niepowodzenie w informację użyteczną dla modelu.

Klient: main.py

Klient wykonuje cztery czynności po kolei: inicjalizuje Mistral, tworzy agenta, opisuje sposób uruchomienia serwera, a następnie otwiera RunContext, aby łączyć rozmowy w sekwencje.

# 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())

Zwróć uwagę na ścieżkę do serwera: Path(__file__).parent / "weather_server.py" lokalizuje plik względem skryptu, a nie względem bieżącego katalogu. To jedyny sposób, aby zagwarantować poprawne uruchomienie niezależnie od tego, z jakiego katalogu wywołasz python main.py.

Uruchamianie projektu

# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"

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

Uruchamiasz tylko jeden proces. Klient tworzy agenta Mistral, RunContext uruchamia weather_server.py jako proces STDIO, wykrywa trzy narzędzia — get_weather, compare_weather i list_cities — a następnie, pytanie po pytaniu, pozwala modelowi wybrać, których z nich użyć, zanim zintegruje wyniki ze swoją odpowiedzią. Trzecie pytanie w przykładzie jest najbardziej interesujące do obserwacji: aby wiedzieć, które miasto jest najcieplejsze, model nie ma wyboru i musi skorzystać z list_cities, mimo że żadne słowo w pytaniu tego nie sugeruje.

Obserwowanie budowania odpowiedzi

Oczekiwanie na pełną odpowiedź sprawdza się w skryptach; w interakcji z użytkownikiem tryb strumieniowania zapewnia znacznie lepsze doświadczenie.

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}")

Strumień zdarzeń służy nie tylko do wyświetlania: to także najlepsze narzędzie do debugowania, ponieważ ujawnia w czasie rzeczywistym wywołania narzędzi i argumenty wybrane przez model.

Gdy narzędzie zawiedzie

Dzięki continue_on_fn_error=True żądanie wykraczające poza zakres nie powoduje awarii. Jeśli użytkownik zapyta o pogodę w Tokio, get_weather zwróci swój JSON z błędem, model go odczyta i zareaguje, proponując faktycznie dostępne miasta.

# 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..."

Podsumowując, projekt mieści się w czterech plikach, z których tylko dwa zawierają logikę:

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=...

Kluczowe wnioski

  • Kompletny projekt MCP = serwer (narzędzia) + klient (agent + RunContext)
  • Serwer definiuje narzędzia za pomocą MCPServer i dekoratorów @app.tool()
  • Klient tworzy agenta, otwiera RunContext i uruchamia rozmowy
  • Tryb strumieniowania umożliwia progresywne wyświetlanie
  • continue_on_fn_error=True zapewnia eleganckie obsługiwanie błędów narzędzi
  • Cały kod jest asynchroniczny — użyj asyncio.run() jako punktu wejścia