Пълен пример: Локален сървър с агент
На тази страница
Обновено на 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на
mcpSDK (2.3.0 към 2 октомври 2026 г.):MCPServerзаместваFastMCP, настройките за транспорт се преместват вrun()илиstreamable_http_app(), а приложение, изложено под реално име на хост, трябва да декларира това име (transport_security). Това е също версията, изисквана от Mistral SDK: допълнениетоmistralai[agents]изискваmcp>=2.2.0,<3.0. Източници: Какво е ново във v2 · Ръководство за миграция · Разполагане и мащабиране. Добавка от 3 ноември: четете резултата отrun_asyncотresult.output_as_text(Mistral SDK 3.7.0 няма атрибутoutput), а в режим на потоково предаване последното събитие еRunResult, идентифицирано чрезisinstance, както в официалния пример на SDK.
Сглобяване на частите
Предишните уроци разгледаха строителните блокове поотделно: сървъра и неговите инструменти, клиента и неговия RunContext. Сега ще ги сглобите в работещ проект – локален MCP сървър, предоставящ информация за времето, управляван от агент на Mistral, способен да отговаря на въпроси на естествен език. Прочетете кода, но обърнете специално внимание на решенията, които всяка част взема: сървърът решава какво е възможно, а агентът решава какво е релевантно.
Сървърът: weather_server.py
Този сървър се състои от три инструмента. Първият връща времето за даден град, вторият сравнява два града, а третият изброява какво съдържа базата данни. Последният не е декоративен: той дава на модела начин да открие наличния обхват, вместо да guessed имена на градове.
# 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)
Два детайла в дизайна заслужават внимание. Инструментите нормализират входа с .lower().strip(), защото моделът може да напише „Paris“ или „paris“ в зависимост от формулировката на потребителя. И когато липсва град, get_weather не хвърля изключение: той връща JSON с грешка, който изброява известните градове, превръщайки неуспеха в информация, която моделът може да използва.
Клиентът: main.py
Клиентът прави четири неща последователно: инициира Mistral, създава агента, описва как да се стартира сървърът, след което отваря RunContext, за да свърже разговорите.
# 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())
Забележете пътя до сървъра: Path(__file__).parent / "weather_server.py" локализира файла спрямо скрипта, а не спрямо текущата директория. Това е единственият начин да гарантирате, че стартирането ще работи, независимо откъде изпълнявате python main.py.
Стартиране на проекта
# Set API key
export MISTRAL_API_KEY="your_mistral_api_key"
# Launch client (it will launch the server automatically)
python main.py
Стартирате само един процес. Клиентът създава агента на Mistral, RunContext стартира weather_server.py като STDIO процес, открива трите инструмента – get_weather, compare_weather и list_cities – и след това, въпрос по въпрос, позволява на модела да избере кои да извика, преди да интегрира резултатите в своя отговор. Третият въпрос в примера е най-интересен за наблюдение: за да разбере кой град е най-топъл, моделът няма друг избор, освен да премине през list_cities, въпреки че нито една дума във въпроса не подсказва това.
Наблюдаване на изграждането на отговора
Изчакването на пълния отговор работи за скрипт; при работа с потребител режимът на потоково предаване предлага много по-добро преживяване.
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}")
Потокът от събития не е просто за показване: той е и най-добрият ви инструмент за отстраняване на грешки, тъй като разкрива извикванията на инструменти и аргументите, избрани от модела в реално време.
Когато инструмент се провали
Благодарение на continue_on_fn_error=True, заявка извън обхвата не прекъсва нищо. Ако потребителят поиска времето в Токио, get_weather връща своя JSON с грешка, моделът го прочита и реагира, предлагайки действително наличните градове.
# 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..."
В крайна сметка проектът се събира в четири файла, от които само два съдържат логика:
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=...
Ключови изводи
- Един завършен MCP проект = сървър (инструменти) + клиент (агент + RunContext)
- Сървърът дефинира инструменти с декораторите
MCPServerи@app.tool() - Клиентът създава агента, отваря RunContext и стартира разговорите
- Режимът на потоково предаване позволява прогресивно показване
continue_on_fn_error=Trueобработва грешките в инструментите без прекъсване- Целият код е асинхронен – използвайте
asyncio.run()като входна точка