Премини към основното съдържание
Български— Изберете език
Меню

Конфигуриране на локален MCP сървър (STDIO)

Урок 4 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Вашият първи локален MCP сървър
  2. Написване на сървъра
  3. Конфигуриране на STDIO клиента
  4. Тестване преди интегриране
  5. Ключови изводи

Обновено на 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на mcp SDK (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 пакетите еволюират бързо и отделна виртуална среда за всеки проект Ви предпазва от нарушаване на работещ сървър при инсталиране на зависимост за друг.

# Създаване на виртуална среда
python -m venv mcp-env
source mcp-env/bin/activate  # Linux/Mac
# mcp-env\Scripts\activate   # Windows

# Официален MCP SDK (v2) и Mistral SDK с неговото допълнение за агенти
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:
    """Поздравява човек по име.

    Args:
        name: Името на човека, който да бъде поздравен

    Returns:
        Персонализирано поздравително съобщение
    """
    return f"Hello {name}! Welcome to the world of MCP."

@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
    """Извършва проста математическа операция.

    Args:
        operation: Операцията за изпълнение (add, sub, mul, div)
        a: Първо число
        b: Второ число

    Returns:
        Резултатът от изчислението
    """
    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

Командата отваря локален уеб интерфейс, където можете да изброите изложените инструменти, да инспектирате описанието и параметрите, които моделът ще получи, да задействате ръчно извикване с аргументи по Ваш избор и да проверите точния формат на върнатата стойност. Направете си навик да използвате това систематично: това са пет минути, които спестяват един час.

Накрая, ето организация на файлове, която остарява добре, със сървъра, клиента, зависимостите, тайните, държани извън хранилището, и модулни тестове за Вашите инструменти:

mon-projet-mcp/
├── serveur_local.py     # MCP сървърът
├── client_stdio.py      # Скриптът на клиента
├── requirements.txt     # Зависимости
├── .env                 # Променливи на средата (никога не се комитват)
└── tests/
    └── test_tools.py    # Модулни тестове за инструменти

Ключови изводи

  • STDIO сървърът се стартира като локален процес
  • StdioServerParameters конфигурира командата, аргументите и променливите на средата
  • Docstrings на Вашите инструменти служат като описание за модела
  • MCP Inspector (npx @modelcontextprotocol/inspector) е съществен за тестване
  • env=None наследява цялата среда; изричен речник ограничава променливите