Creiamo i server MCP

Ora che abbiamo lo strato dati a disposizione è il momento di creare i nostri due server MCP: uno per recuperare informazioni sugli hotel ed uno per i voli. Accederanno entrambi ad uno stesso database anche se, come ricordiamo, è una semplificazione visto che spesso ci troveremo ad utilizzare questo tipo di server come una sorta di gateway verso sorgenti dati molto diverse tra loro.

La libreria Python che utilizzeremo è FastMCP installabile con:

pip install fastmcp

Creazione del FlightService

Il primo servizio riguarda i voli e prende il nome di FlightService:

import json
from fastmcp import FastMCP
from db_manager import DBManager
from typing import Annotated
# inizializziamo il server e gli affidiamo un nome da "servizio"
mcp = FastMCP("FlightService")
# istanziamo il db_manager come collegamento ai dati
db = DBManager()
@mcp.tool()
def cerca_voli(
    origine: Annotated[str, "Departure city"],
    destinazione: Annotated[str, "Destination city"]):
    """
    Find available flights between two cities.
    Use this tool whenever a user asks to search for flights, check flight availability,
or find travel options from one city to another.
    Arguments:
    - origine: departure city
    - destinazione: arrival city
    Returns all matching flights available in the database.
    If no flights are found, returns a standard message.
    """
    risultati = db.cerca_voli(origine, destinazione)
    if not risultati:
        return f"Nessun volo disponibile da {origine} a {destinazione}."
    return json.dumps(risultati, ensure_ascii=False)
@mcp.tool()
def prenota_volo(
    flight_id: Annotated[
        str,
        "Unique identifier of the flight to book (e.g. FL-101)."
    ]
) -> str:
    successo = db.prenota_volo(flight_id)
    if successo:
        return f"Prenotazione confermata per il volo {flight_id}!"
    return f"Impossibile prenotare il volo {flight_id}: posti esauriti o ID non valido."

Questi i passaggi. Definiamo il servizio FastMCP con:

from fastmcp import FastMCP
from db_manager import DBManager
...
mcp = FastMCP("FlightService")

e nel frattempo ci preoccupiamo pure di istanziare il DBManager. Definiamo poi i due tool che offriremo agli agenti per recuperare informazioni usando il decorator @mcp.tool sulle funzioni che vogliamo trasformare in tool.

Notiamo che nel codice le descrizioni sono lunghe, articolate e in inglese. Ciò perchè un aspetto fondamentale da ricordare è che le descrizioni non sono per gli umani ma per gli LLM.

Gli LLM al giorno d'oggi comprendono ogni lingua ed ogni formato ma, nel dubbio, possiamo aderire al pensiero comune che abbiano un feeling migliore con l'inglese e con i dati schematizzati. Nel nostro caso, ci siamo fatti scrivere le descrizioni da un'Intelligenza Artificiale alla quale abbiamo passato la nostra descrizione semplice ed in Italiano chiedendo di fornircene una versione ben comprensibile da un LLM.

Notiamo anche che gli argomenti sono stati annotati con Annotated, altro elemento che permetterà a FastMCP di spiegare meglio agli LLM come si deve dialogare con i tool.

Creazione dell'HotelService

Abbiamo visto così la praticità del framework FastMCP per creare un servizio. Allo stesso modo, creiamo il servizio per alberghi:

import json
from typing import Annotated
from fastmcp import FastMCP
from db_manager import DBManager
mcp = FastMCP("HotelService")
db = DBManager()
@mcp.tool()
def cerca_hotel(
    citta: Annotated[str, "City name where to search for available hotels."]
) -> str:
    """
    Searches the internal hotel database for available hotels in a specific city.
    Use this tool when the user wants to find available hotels,
    check accommodation options, or explore hotels in a city.
    Arguments:
    - citta: city where the user wants to find hotels
    Returns a JSON string containing the matching hotels.
    If no hotels are found, returns a standard message indicating
    that no hotels are available in the requested city.
    """
    risultati = db.cerca_hotel(citta)
    if not risultati:
        return f"Nessun hotel disponibile a {citta}."
    return json.dumps(risultati, ensure_ascii=False)
@mcp.tool()
def prenota_hotel(
    hotel_id: Annotated[str, "Unique identifier of the hotel to book (e.g. HT-01)."]
) -> str:
    """
    Books a room at the specified hotel.
    Use this tool when the user wants to book or reserve a room
    at a specific hotel and provides the hotel identifier.
    Arguments:
    - hotel_id: unique identifier of the hotel to book (e.g. HT-01)
    Returns a standard confirmation message if the booking succeeds.
    Returns a standard error message if the hotel does not exist
    or no rooms are available.
    """
    successo = db.prenota_hotel(hotel_id)
    if successo:
        return f"Prenotazione confermata per l'hotel {hotel_id}!"
    return f"Impossibile prenotare l'hotel {hotel_id}: camere esaurite o ID non valido."

Avvio dei servizi

Ora che abbiamo i nostri servizi pronti è il momento di avviarli. Notiamo che alla fine di ogni script Python non c'è alcun punto di "lancio" del servizio. Ciò perchè usaremo direttamente il tool fastmcp come suggerisce la documentazione:

fastmcp run flight_server.py:mcp --transport http --port 8001
fastmcp run hotel_server.py:mcp --transport http --port 8002

I due comandi illustrati andrebbero lanciati singolarmente da riga di comando e in background. Noi li abbiamo lanciati dal DOS di Windows in background anteponendo start /b mentre sui sistemi Linux si può fare con un & alla fine dell'istruzione.

Notiamo che all'atto di invocare il comando impostiamo due parametri non definiti in alcun punto dello script: il metodo di trasporto impostato a http per permettere il collegamento a distanza e la porta TCP. Di default, l'host di pubblicazione sarà quello locale sull'indirizzo 127.0.0.1.

Ora che il nostro strato di servizi è avviato non ci resta che sottoporli a test ma lo faremo nella prossima puntata.