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

Configurați un server MCP local (STDIO)

Lecția 4 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Primul dumneavoastră server MCP local
  2. Scrierea serverului
  3. Configurarea clientului STDIO
  4. Testați înainte de integrare
  5. Puncte cheie

Actualizat pe 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.

Primul dumneavoastră server MCP local

Modul STDIO este punctul de plecare natural pentru dezvoltarea și testarea unui server MCP: totul rulează pe mașina dumneavoastră, fără deploy, fără URL public și fără certificate de gestionat. Editați un fișier, reporniți și observați. În această lecție, veți scrie un server MCP local în Python și apoi îl veți conecta la un client.

În ceea ce privește prerechizitele, aveți nevoie de Python 3.10 sau o versiune superioară, de un pip actualizat și, de preferință, de un mediu virtual dedicat. Ultimul punct nu este doar cosmetic: pachetele MCP evoluează rapid, iar un venv separat per proiect vă împiedică să stricați un server funcțional atunci când instalați o dependență pentru altul.

# Crearea unui mediu virtual
python -m venv mcp-env
source mcp-env/bin/activate  # Linux/Mac
# mcp-env\Scripts\activate   # Windows

# SDK-ul oficial MCP (v2) și Mistral SDK cu extra-ul său pentru agenți
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"

Scrierea serverului

Cu MCPServer, clasa de nivel înalt din SDK-ul oficial (fostul FastMCP), un server local necesită doar câteva linii de cod. Instanțiați o aplicație oferindu-i un nume descriptiv, apoi decorați funcțiile Python cu @app.tool() pentru a le expune.

# serveur_local.py
from mcp.server.mcpserver import MCPServer

# Inițializarea serverului cu un nume descriptiv
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}"

Acest fișier expune două instrumente. Observați rolul docstring-urilor: ele nu doar documentează codul pentru un coleg; ele devin literalmente descrierea pe care modelul o citește pentru a decide dacă să apeleze calculate în loc de greet. Un docstring neglijent aici duce la apeluri eronatice mai târziu.

Configurarea clientului STDIO

Din partea clientului, nu vă conectați la o adresă; explicați cum să porniți serverul. Acesta este rolul lui StdioServerParameters.

# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path

# Calea către serverul dumneavoastră
path_to_server = Path("serveur_local.py")

# Configurarea serverului STDIO
server_params = StdioServerParameters(
    command="python",           # Comanda pentru lansarea serverului
    args=[str(path_to_server)], # Argumentele (fișierul Python)
    env=None,                   # Variabile de mediu (opțional)
)

# Crearea clientului MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)

Trei parametri merită detalii suplimentare.

command

Aceasta este comanda de sistem care lansează procesul serverului: "python" pentru un server Python, "node" pentru un server JavaScript sau calea directă către un binar dacă serverul dumneavoastră este compilat.

# Python
command="python"

# Node.js
command="node"

# Un executabil compilat
command="./mon_serveur_mcp"

args

Aceasta este lista de argumente transmise acelei comenzi. Pentru un script Python, acesta este cel puțin calea fișierului, dar nimic nu vă împiedică să transmiteți aici opțiunile serverului dumneavoastră.

# Script simplu
args=["serveur_local.py"]

# Cu argumente suplimentare
args=["serveur_local.py", "--port", "8080", "--verbose"]

env

Acesta este dicționarul de variabile de mediu transmise procesului serverului: canalul prin care îi transmiteți o cheie API, un URL de bază de date sau un flag de depanare.

import os

server_params = StdioServerParameters(
    command="python",
    args=["serveur_local.py"],
    env={
        **os.environ,  # Moștenire din mediul curent
        "API_KEY": "your_api_key",
        "DATABASE_URL": "postgresql://...",
        "DEBUG": "true",
    },
)

Comportamentul acestui parametru surprinde adesea oamenii. Cu env=None, serverul moștenește întregul mediul procesului părinte; cu un dicționar, vede strict doar variabilele listate. Dacă furnizați un dicționar fără a turna os.environ în el, nu fiți surprins dacă serverul dumneavoastră nu mai poate găsi PATH-ul sau cheia API: comportamentul este perfect logic, pur și simplu radical.

Testați înainte de integrare

Înainte de a conecta serverul la un agent, testați-l izolat cu MCP Inspector. Raționamentul este simplu: dacă un apel eșuează odată ce serverul este conectat la un model, nu veți ști dacă problema stă în codul dumneavoastră sau în decizia modelului. Inspectorul elimină această ambiguitate.

npx @modelcontextprotocol/inspector python serveur_local.py

Comanda deschide o interfață web locală unde puteți lista instrumentele expuse, inspecta descrierea și parametrii pe care modelul îi va primi, declanșa un apel manual cu argumente la alegerea dumneavoastră și verifica formatul exact al valorii returnate. Faceți din aceasta o obișnuință sistematică: sunt cinci minute care economisesc o oră.

În final, iată o organizare a fișierelor care rezistă testului timpului, cu serverul, clientul, dependențele, secretele ținute în afara repository-ului și teste unitare pentru instrumentele dumneavoastră:

mon-projet-mcp/
├── serveur_local.py     # Serverul MCP
├── client_stdio.py      # Scriptul client
├── requirements.txt     # Dependențe
├── .env                 # Variabile de mediu (niciodată comitate)
└── tests/
    └── test_tools.py    # Teste unitare pentru instrumente

Puncte cheie

  • Un server STDIO se lansează ca un proces local
  • StdioServerParameters configurează comanda, argumentele și variabilele de mediu
  • Docstring-urile instrumentelor dumneavoastră servesc drept descriere pentru model
  • MCP Inspector (npx @modelcontextprotocol/inspector) este esențial pentru testare
  • env=None moștenește întregul mediu; un dicționar explicit limitează variabilele