Διαμόρφωση ενός Τοπικού Διακομιστή MCP (STDIO)
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 — MCP Python SDK v2. Αυτό το μάθημα ακολουθεί πλέον την έκδοση 2 του SDK
mcp(2.3.0 από τις 2 Οκτωβρίου 2026): τοMCPServerαντικαθιστά τοFastMCP, οι ρυθμίσεις μεταφοράς μεταφέρονται στοrun()ή στοstreamable_http_app(), και μια εφαρμογή που εκτίθεται υπό πραγματικό όνομα κεντρικού υπολογιστή πρέπει να δηλώνει αυτό το όνομα (transport_security). Αυτή είναι επίσης η έκδοση που απαιτείται από το Mistral SDK: το πρόσθετοmistralai[agents]απαιτείmcp>=2.2.0,<3.0. Πηγές: Τι νέο υπάρχει στο v2 · Οδηγός Μετάβασης · Ανάπτυξη και κλιμάκωση.
Ο πρώτος σας τοπικός διακομιστής MCP
Η λειτουργία STDIO αποτελεί το φυσικό σημείο εκκίνησης για την ανάπτυξη και τη δοκιμή ενός διακομιστή MCP: όλα εκτελούνται στον υπολογιστή σας, χωρίς ανάπτυξη, χωρίς δημόσια URL και χωρίς πιστοποιητικά προς διαχείριση. Επεξεργάζεστε ένα αρχείο, κάνετε επανεκκίνηση και παρατηρείτε. Σε αυτό το μάθημα, θα γράψετε έναν τοπικό διακομιστή MCP σε Python και στη συνέχεια θα τον συνδέσετε με έναν πελάτη.
Όσον αφορά τις προαπαιτούμενες γνώσεις, χρειάζεστε Python 3.10 ή νεότερη έκδοση, ένα ενημερωμένο pip και κατά προτίμηση ένα αφιερωμένο εικονικό περιβάλλον. Το τελευταίο σημείο δεν είναι απλώς αισθητικό: τα πακέτα MCP εξελίσσονται γρήγορα και ένα ξεχωριστό venv ανά έργο σας εμποδίζει να χαλάσετε έναν λειτουργικό διακομιστή όταν εγκαθιστάτε μια εξάρτηση για έναν άλλον.
# Δημιουργία εικονικού περιβάλλοντος
python -m venv mcp-env
source mcp-env/bin/activate # Linux/Mac
# mcp-env\Scripts\activate # Windows
# Επίσημο MCP SDK (v2) και Mistral SDK με το πρόσθετο agents
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"
Συγγραφή του διακομιστή
Με το MCPServer, την κλάση υψηλού επιπέδου στο επίσημο SDK (πρώην FastMCP), ένας τοπικός διακομιστής απαιτεί μόνο λίγες γραμμές κώδικα. Δημιουργείτε μια εφαρμογή δίνοντάς της ένα περιγραφικό όνομα και στη συνέχεια διακοσμείτε τις συναρτήσεις Python με το @app.tool() για να τις εκθέσετε.
# serveur_local.py
from mcp.server.mcpserver import MCPServer
# Αρχικοποίηση του διακομιστή με ένα περιγραφικό όνομα
app = MCPServer("Local Demo Server")
@app.tool()
def greet(name: str) -> str:
"""Greets a person by name.
Args:
name: The first name of the person to greet
Returns:
A personalized greeting message
"""
return f"Hello {name}! Welcome to the world of MCP."
@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
"""Performs a simple mathematical calculation.
Args:
operation: The operation to perform (add, sub, mul, div)
a: First number
b: Second number
Returns:
The result of the calculation
"""
ops = {
"add": a + b,
"sub": a - b,
"mul": a * b,
"div": a / b if b != 0 else "Error: division by zero"
}
result = ops.get(operation, "Unknown operation")
return f"{a} {operation} {b} = {result}"
Αυτό το αρχείο εκθέτει δύο εργαλεία. Σημειώστε τον ρόλο των docstrings: δεν τεκμηριώνουν απλώς τον κώδικά σας για έναν συνάδελφο· γίνονται κυριολεκτικά η περιγραφή που διαβάζει το μοντέλο για να αποφασίσει αν θα καλέσει το calculate αντί για το greet. Μια πρόχειρη docstring εδώ οδηγεί σε erratic κλήσεις αργότερα.
Διαμόρφωση του πελάτη STDIO
Στην πλευρά του πελάτη, δεν συνδέεστε σε μια διεύθυνση· εξηγείτε πώς να ξεκινήσει ο διακομιστής. Αυτός είναι ο ρόλος του StdioServerParameters.
# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path
# Διαδρομή προς τον διακομιστή σας
path_to_server = Path("serveur_local.py")
# Διαμόρφωση διακομιστή STDIO
server_params = StdioServerParameters(
command="python", # Η εντολή για την εκκίνηση του διακομιστή
args=[str(path_to_server)], # Τα ορίσματα (το αρχείο Python)
env=None, # Μεταβλητές περιβάλλοντος (προαιρετικό)
)
# Δημιουργία του πελάτη MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)
Τρεις παράμετροι αξίζουν λεπτομερή ανάλυση.
command
Αυτή είναι η εντολή συστήματος που εκκινεί τη διαδικασία του διακομιστή: "python" για έναν διακομιστή Python, "node" για έναν διακομιστή JavaScript, ή η άμεση διαδρομή προς ένα δυαδικό αρχείο εάν ο διακομιστής σας είναι μεταγλωττισμένος.
# Python
command="python"
# Node.js
command="node"
# Ένας μεταγλωττισμένος εκτελέσιμος
command="./mon_serveur_mcp"
args
Αυτή είναι η λίστα των ορισμάτων που περνιούνται σε αυτή την εντολή. Για ένα σενάριο Python, αυτό είναι τουλάχιστον η διαδρομή του αρχείου, αλλά τίποτα δεν σας εμποδίζει να περάσετε εδώ τις επιλογές του διακομιστή σας.
# Απλό σενάριο
args=["serveur_local.py"]
# Με πρόσθετα ορίσματα
args=["serveur_local.py", "--port", "8080", "--verbose"]
env
Αυτό είναι το λεξικό των μεταβλητών περιβάλλοντος που περνιούνται στη διαδικασία του διακομιστή: το κανάλι μέσω του οποίου του περνάτε ένα κλειδί API, μια URL βάσης δεδομένων ή μια σημαία εντοπισμού σφαλμάτων.
import os
server_params = StdioServerParameters(
command="python",
args=["serveur_local.py"],
env={
**os.environ, # Κληρονομία από το τρέχον περιβάλλον
"API_KEY": "your_api_key",
"DATABASE_URL": "postgresql://...",
"DEBUG": "true",
},
)
Η συμπεριφορά αυτής της παραμέτρου συχνά εκπλήσσει τους χρήστες. Με env=None, ο διακομιστής κληρονομεί ολόκληρο το περιβάλλον της γονικής διαδικασίας· με ένα λεξικό, βλέπει αυστηρά μόνο τις μεταβλητές που αναφέρονται. Εάν παρέχετε ένα λεξικό χωρίς να συμπεριλάβετε το os.environ σε αυτό, μην εκπλαγείτε εάν ο διακομιστής σας δεν μπορεί πλέον να βρει το PATH ή το κλειδί API σας: η συμπεριφορά είναι απολύτως λογική, απλώς ριζοσπαστική.
Δοκιμή πριν την ενσωμάτωση
Πριν συνδέσετε τον διακομιστή σας με έναν πράκτορα, δοκιμάστε τον μεμονωμένα με το MCP Inspector. Η λογική είναι απλή: εάν μια κλήση αποτύχει μόλις ο διακομιστής συνδεθεί με ένα μοντέλο, δεν θα ξέρετε αν το πρόβλημα βρίσκεται στον κώδικά σας ή στην απόφαση του μοντέλου. Το Inspector εξαλείφει αυτή την ασάφεια.
npx @modelcontextprotocol/inspector python serveur_local.py
Η εντολή ανοίγει μια τοπική διεπαφή web όπου μπορείτε νααναφέρει τα εκτεθειμένα εργαλεία, να επιθεωρήσετε την περιγραφή και τις παραμέτρους που θα λάβει το μοντέλο, να ενεργοποιήσετε μια μη αυτόματη κλήση με ορίσματα της επιλογής σας και να επαληθεύσετε την ακριβή μορφή της τιμής επιστροφής. Κάντε συνήθεια να το χρησιμοποιείτε συστηματικά: είναι πέντε λεπτά που γλιτώνουν μία ώρα.
Τέλος, ορίστε μια οργάνωση αρχείων που αντέχει στον χρόνο, με τον διακομιστή, τον πελάτη, τις εξαρτήσεις, τα μυστικά κρατημένα εκτός του αποθετηρίου και τις δοκιμές μονάδας για τα εργαλεία σας:
mon-projet-mcp/
├── serveur_local.py # Ο διακομιστής MCP
├── client_stdio.py # Το σενάριο του πελάτη
├── requirements.txt # Εξαρτήσεις
├── .env # Μεταβλητές περιβάλλοντος (ποτέ δεν commit-άρονται)
└── tests/
└── test_tools.py # Δοκιμές μονάδας για εργαλεία
Βασικά σημεία
- Ένας διακομιστής STDIO εκκινείται ως τοπική διαδικασία
- Το
StdioServerParametersδιαμορφώνει την εντολή, τα ορίσματα και τις μεταβλητές περιβάλλοντος - Οι docstrings των εργαλείων σας λειτουργούν ως η περιγραφή για το μοντέλο
- Το MCP Inspector (
npx @modelcontextprotocol/inspector) είναι απαραίτητο για τη δοκιμή - Το
env=Noneκληρονομεί ολόκληρο το περιβάλλον· ένα ρητό λεξικό περιορίζει τις μεταβλητές