Salt la conținutul principal
Română— Alege o limbă
Meniu

Exemplu complet: Server local cu agent

Lecția 6 din 14 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Asamblarea componentelor
  2. Serverul: weather_server.py
  3. Clientul: main.py
  4. Rularea proiectului
  5. Urmărirea construirii răspunsului
  6. Când un instrument eșuează
  7. Puncte cheie

Actualizat la 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului mcp (2.3.0 la data de 2 octombrie 2026): MCPServer înlocuiește FastMCP, setările de transport se mută în run() sau streamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ul mistralai[agents] necesită mcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale. Addendum 3 noiembrie: citiți rezultatul unui run_async din result.output_as_text (SDK-ul mistralai 3.7.0 nu are atributul output), iar în modul de streaming, ultimul eveniment este un RunResult, identificat cu isinstance, ca în exemplul oficial SDK.

Asamblarea componentelor

Lecțiile anterioare au prezentat blocurile de construcție separat: serverul și instrumentele sale, clientul și contextul său RunContext. Acum le veți asambla într-un proiect funcțional—un server MCP local care furnizează informații meteorologice, condus de un agent Mistral capabil să răspundă la întrebări în limbaj natural. Citiți codul, dar acordați o atenție deosebită deciziilor luate de fiecare parte: serverul decide ce este posibil, iar agentul decide ce este relevant.

Serverul: weather_server.py

Acest server constă în trei instrumente. Primul returnează vremea pentru un oraș, al doilea compară două orașe, iar al treilea listează conținutul bazei de date. Ultimul nu este decorativ: oferă modelului o modalitate de a descoperi domeniul de aplicare disponibil, în loc să ghicească nume de orașe.

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

Două detalii de design merită atenție. Instrumentele normalizează intrarea cu .lower().strip() deoarece modelul ar putea scrie „Paris“ sau „paris“ în funcție de formularea utilizatorului. Iar atunci când un oraș lipsește, get_weather nu aruncă o excepție: returnează un JSON de eroare care enumeră orașele cunoscute, transformând eșecul în informații pe care modelul le poate utiliza.

Clientul: main.py

Clientul face patru lucruri în ordine: inițializează Mistral, creează agentul, descrie modul de lansare a serverului, apoi deschide RunContext pentru a înlănțui conversațiile.

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

Observați calea serverului: Path(__file__).parent / "weather_server.py" localizează fișierul relativ la script, nu la directorul curent. Aceasta este singura modalitate de a garanta că lansarea funcționează indiferent de unde executați python main.py.

Rularea proiectului

# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"

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

Porniți un singur proces. Clientul creează agentul Mistral, RunContext lansează weather_server.py ca proces STDIO, descoperă cele trei instrumente—get_weather, compare_weather și list_cities—apoi, întrebare cu întrebare, permite modelului să aleagă pe care să le apeleze înainte de a integra rezultatele în răspunsul său. A treia întrebare din exemplu este cea mai interesant de observat: pentru a ști care oraș este cel mai cald, modelul nu are de ales decât să treacă prin list_cities, chiar dacă niciun cuvânt din întrebare nu sugerează acest lucru.

Urmărirea construirii răspunsului

Așteptarea răspunsului complet funcționează pentru un script; în fața unui utilizator, modul streaming oferă o experiență mult mai bună.

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

Fluxul de evenimente nu servește doar afișării: este, de asemenea, cel mai bun instrument de depanare, deoarece expune apelurile de instrumente și argumentele alese de model în timp real.

Când un instrument eșuează

Datorită continue_on_fn_error=True, o cerere în afara domeniului de aplicare nu strică nimic. Dacă utilizatorul cere vremea pentru Tokyo, get_weather returnează JSON-ul său de eroare, modelul îl citește și reacționează propunând orașele disponibile efectiv.

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

În final, proiectul se încadrează în patru fișiere, dintre care doar două conțin logică:

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

Puncte cheie

  • Un proiect MCP complet = server (instrumente) + client (agent + RunContext)
  • Serverul definește instrumente cu MCPServer și decoratorii @app.tool()
  • Clientul creează agentul, deschide RunContext și lansează conversațiile
  • Modul Streaming permite afișarea progresivă
  • continue_on_fn_error=True gestionează erorile instrumentelor cu grație
  • Tot codul este asincron—utilizați asyncio.run() ca punct de intrare