Υλοποίηση Εργαλείων: JSON Schema και Handlers
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 — MCP Python SDK v2. Αυτό το μάθημα ακολουθεί πλέον την έκδοση 2 του
mcpSDK (2.3.0 από τις 2 Οκτωβρίου 2026): τοMCPServerαντικαθιστά τοFastMCP, οι ρυθμίσεις μεταφοράς μεταφέρονται στοrun()ή στοstreamable_http_app(), και μια εφαρμογή που εκτίθεται υπό πραγματικό όνομα host πρέπει να δηλώνει αυτό το όνομα host (transport_security). Αυτή είναι επίσης η έκδοση που απαιτείται από το Mistral SDK: το πρόσθετοmistralai[agents]απαιτείmcp>=2.2.0,<3.0. Πηγές: Τι νέο υπάρχει στο v2 · Οδηγός Μετάβασης · Ανάπτυξη και κλιμάκωση.
Η Ανατομία ενός Εργαλείου MCP
Ένα εργαλείο MCP μοιάζει με συνάρτηση Python, αλλά από την οπτική γωνία του μοντέλου, δεν είναι. Πρόκειται για μια σύμβαση τεσσάρων μερών: ένα όνομα, μια περιγραφή, ένα σχήμα εισόδου JSON και έναν handler που εκτελεί τη λογική. Το μοντέλο δεν βλέπει ποτέ τον κώδικά σας—βλέπει μόνο αυτή τη σύμβαση. Ένα εργαλείο που υλοποιείται τέλεια αλλά περιγράφεται ελλιπώς δεν θα κληθεί ποτέ, ή θα κληθεί λάθος στιγμή. Επομένως, η ποιότητα της σύμβασης καθορίζει την αποτελεσματικότητα του server πολύ περισσότερο από την ποιότητα της υλοποίησης.
Τι Κατασκευάζει ο Διακοσμητής για Εσάς
Το MCPServer χτίζει αυτή τη σύμβαση αυτόματα από την υπογραφή της συνάρτησής σας και το docstring. Γράφετε τυπική Python:
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def search_documents(
query: str,
max_results: int = 10,
language: str = "fr",
include_archived: bool = False,
) -> str:
"""Searches for documents in the knowledge base.
Args:
query: Search terms (2-500 characters)
max_results: Maximum number of results (1-100, default: 10)
language: ISO 639-1 language code (default: fr)
include_archived: Include archived documents (default: false)
Returns:
JSON with the list of found documents and the total count
"""
# Search logic
...
Και το μοντέλο λαμβάνει αυτό:
{
"name": "search_documents",
"description": "Searches for documents in the knowledge base.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search terms (2-500 characters)"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results (1-100, default: 10)",
"default": 10
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (default: fr)",
"default": "fr"
},
"include_archived": {
"type": "boolean",
"description": "Include archived documents (default: false)",
"default": false
}
},
"required": ["query"]
}
}
Συγκρίνετε τα δύο μπλοκ γραμμή προς γραμμή: κάθε annotation τύπου γίνεται τύπος JSON, κάθε προεπιλεγμένη τιμή γίνεται πεδίο default, κάθε γραμμή στην ενότητα Args γίνεται περιγραφή παραμέτρου, και το μόνο όρισμα χωρίς προεπιλεγμένη τιμή καταλήγει στο required. Με άλλα λόγια, οτιδήποτε παραλείψετε από το docstring εξαφανίζεται εντελώς από τη σύμβαση.
Ονοματοδοσία και Στη Συνέχεια Περιγραφή
Το όνομα του εργαλείου είναι το όνομα της συνάρτησης, και το μοντέλο το χρησιμοποιεί ως την πρώτη του ένδειξη. Ένα ρήμα δράσης ακολουθούμενο από ένα σαφές αντικείμενο δεν αφήνει περιθώρια ασάφειας, ενώ ένα γενικό ή τεχνικό όνομα αναγκάζει το μοντέλο να μαντέψει:
# Καλό: ρήμα δράσης + σαφές αντικείμενο
@app.tool()
def create_issue(title: str, body: str) -> str: ...
@app.tool()
def search_repositories(query: str) -> str: ...
@app.tool()
def get_user_profile(username: str) -> str: ...
# Κακό: ασαφές, διφορούμενο, τεχνικό
@app.tool()
def process(data: str) -> str: ... # Πολύ ασαφές
@app.tool()
def handle_request(req: str) -> str: ... # Ακατανόητο για το LLM
@app.tool()
def db_query(sql: str) -> str: ... # Πολύ τεχνικό
Το docstring αναλαμβάνει στη συνέχεια και αποτελεί το πιο κρίσιμο κομμάτι ολόκληρου του server σας. Πρέπει να απαντά σε τρία ερωτήματα με αυτή τη σειρά: πότε να χρησιμοποιηθεί αυτό το εργαλείο, ποιες παράμετροι να παρέχονται με τη μορφή και τους περιορισμούς τους, και τι να αναμένεται ως επιστροφή. Το παρακάτω παράδειγμα δείχνει πώς φαίνεται αυτό σε μια πραγματική περίπτωση:
@app.tool()
def book_restaurant(
restaurant_name: str,
date: str,
party_size: int,
special_requests: str = "",
) -> str:
"""Books a table at a restaurant.
Performs a complete reservation including email
confirmation. Use this tool when the user wants
to book a specific restaurant.
Args:
restaurant_name: Exact name of the restaurant
date: Date and time in ISO 8601 format (e.g., 2026-04-15T19:30:00)
party_size: Number of guests (1-20)
special_requests: Special requests (allergies, occasion, etc.)
Returns:
JSON with the reservation number, confirmation,
and restaurant details
"""
...
Η παράγραφος που ακολουθεί την πρώτη γραμμή είναι αυτό που συχνά λείπει από τους ερασιτεχνικούς servers. Χωρίς αυτήν, το μοντέλο γνωρίζει τι κάνει το εργαλείο, αλλά όχι σε ποια κατάσταση πρέπει να το ενεργοποιήσει. Και το παράδειγμα ημερομηνίας ISO 8601 θα σας γλιτώσει δεκάδες κλήσεις με μορφή "April 15 at 7:30 PM".
Τύποι, Async Handlers και Επικύρωση
Το MCPServer μεταφράζει κοινούς annotation τύπων Python στα αντίστοιχά τους σε JSON Schema.
| Python | JSON Schema | Παράδειγμα |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array από string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" ή null |
Μόλις ένα εργαλείο βγει έξω από τη διαδικασία του—κλήση δικτύου, ερώτημα βάσης δεδομένων, ανάγνωση απομακρυσμένου αρχείου—δηλώστε το ως async. Ένας synchronous handler που περιμένει μια απόκριση HTTP μπλοκάρει ολόκληρο τον server, και μαζί του τους υπόλοιπους χρήστες σας:
import httpx
@app.tool()
async def fetch_api_data(endpoint: str) -> str:
"""Retrieves data from an external API.
Args:
endpoint: The API endpoint path (e.g., /users/123)
Returns:
JSON data from the API
"""
async with httpx.AsyncClient() as client:
response = await client.get(f"https://api.example.com{endpoint}")
response.raise_for_status()
return response.text
Το σχήμα JSON περιορίζει τους τύπους, όχι τις τιμές: τίποτα δεν εμποδίζει το μοντέλο να στείλει ένα όνομα 3.000 χαρακτήρων ή έναν ρόλο φτιαγμένο στα γρήγορα. Επομένως, επικυρώνετε πάντα στο σημείο εισόδου του handler και επιστρέφετε ένα μήνυμα που υποδεικνύει τη διόρθωση που απαιτείται:
import json
@app.tool()
def create_user(name: str, email: str, role: str = "viewer") -> str:
"""Creates a new user.
Args:
name: Full name (2-100 characters)
email: Valid email address
role: Role: viewer, editor, admin (default: viewer)
Returns:
JSON with the created user details
"""
# Validation
if len(name) < 2 or len(name) > 100:
return json.dumps({"error": "Name must be between 2 and 100 characters"})
if "@" not in email or "." not in email:
return json.dumps({"error": "Invalid email address"})
valid_roles = ("viewer", "editor", "admin")
if role not in valid_roles:
return json.dumps({"error": f"Invalid role. Choices: {', '.join(valid_roles)}"})
# Creation...
return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})
Το τρίτο μήνυμα παραθέτει τις επιτρεπόμενες τιμές. Το μοντέλο μπορεί τότε να διορθώσει μόνο του και να καλέσει ξανά το εργαλείο, αντί να τα παρατήσει μπροστά σε ένα σφάλμα “Invalid role” χωρίς εξήγηση.
Βελτίωση της Τιμής Επιστροφής
Ένα εργαλείο MCP επιστρέφει πάντα κείμενο, αλλά αυτό το κείμενο μπορεί να είναι δομημένο JSON, το οποίο το μοντέλο ερμηνεύει πολύ καλά. Η αντίθεση μεταξύ αυτών των δύο επιστροφών συνοψίζει τα βασικά:
# Καλό: δομημένο, ευανάγνωστο JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Κακό: ακατέργαστα δεδομένα δύσκολα στη χρήση
return "OK:user_id=abc123:status=created"
Προτιμάτε πάντα τιμές ευανάγνωστες από άνθρωπο αντί για εσωτερικά αναγνωριστικά: το μοντέλο μπορεί να χρησιμοποιήσει άμεσα το "Alice Dupont" στην απάντησή του, ενώ ένα UUID επιβάλλει μια επιπλέον κλήση για να μάθει σε ποιον αναφέρεται. Αντιθέτως, προσέξτε τις υπερβολικά μεγάλες επιστροφές—πενήντα πεδία ανά εγγραφή γεμίζουν το context χωρίς να προσθέτουν αξία. Ο σωστός αντανακλασμός κατά τη συγγραφή ενός εργαλείου είναι να αναρωτηθείτε τι θα χρειαστεί το μοντέλο για να πει στον χρήστη, και να επιστρέψετε μόνο αυτό.
Βασικά σημεία
- Ο διακοσμητής
@app.tool()δημιουργεί αυτόματα το JSON Schema για τις παραμέτρους - Το όνομα της συνάρτησης = όνομα εργαλείου (ρήμα + αντικείμενο)
- Το docstring είναι κρίσιμο: καθοδηγεί το μοντέλο για το πότε και πώς να καλέσει το εργαλείο
- Χρησιμοποιήστε type annotations της Python για το σχήμα (str, int, float, bool, list, dict)
- Επικυρώνετε πάντα τις εισόδους και επιστρέφετε σφάλματα που οδηγούν σε δράση
- Επιστρέφετε δομημένο JSON με τιμές ευανάγνωστες από άνθρωπο