Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Architektúra vlastného MCP servera

Lekcia 10 z 14 Aktualizované 2. novembra 2026 Vývojár
Na tejto strane
  1. Návrh produkčného MCP servera
  2. Výber tvojho frameworku
  3. Štruktúra projektu, ktorá vydrží
  4. Vstupný bod: server.py
  5. Jeden modul nástrojov na doménu
  6. Centralizovaná konfigurácia
  7. Chyby, ktorým model rozumie
  8. Stavový alebo bezstavový
  9. Kľúčové poznatky

Aktualizované 2. novembra 2026 — MCP Python SDK v2. Tento kurz teraz nasleduje verziu 2 SDK mcp (2.3.0 k 2. októbru 2026): MCPServer nahrádza FastMCP, nastavenia transportu sa presúvajú do run() alebo streamable_http_app() a aplikácia vystavená pod skutočným hostname musí tento hostname deklarovať (transport_security). Toto je tiež verzia požadovaná Mistral SDK: extra balík mistralai[agents] vyžaduje mcp>=2.2.0,<3.0. Zdroje: Čo je nové vo v2 · Sprievodca migráciou · Nasadenie a škálovanie.

Návrh produkčného MCP servera

Prototyp MCP sa zmestí do súboru so štyridsiatimi riadkami a to často stačí na presvedčenie tímu. Prechod na reálne použitie však mení všetko: server volá viacero ľudí, nástroje sa množia, konfigurácia sa líši podľa prostredia a jeden súbor sa stáva neudržateľným. Táto lekcia pokrýva architektonické rozhodnutia, ktoré ti pomôžu vyhnúť sa tejto stene – výber frameworku, štruktúrovanie projektu, správa konfigurácie a chýb a rozhodovanie medzi stavovými a bezstavovými servermi.

Výber tvojho frameworku

V Pythone je trieda MCPServer z oficiálneho SDK (predtým FastMCP) štandardným nástrojom. Poskytuje API založené na dekorátoroch a za teba vybavuje protokol MCP, takže server ožije na tri riadky:

from mcp.server.mcpserver import MCPServer

app = MCPServer(
    "My Server",
    instructions="MCP Server for project management",
)

Tímy pracujúce v JavaScripte a TypeScripte majú k dispozícii oficiálne MCP SDK vydané spoločnosťou Anthropic. Logika je porovnateľná, hoci sa syntax líši:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "My Server",
  version: "1.0.0",
});

Voľba závisí menej od schopností a viac od ekosystému, z ktorého bude server čerpať dáta. Server, ktorý dopytuje databázu cez SQLAlchemy alebo znovu používa existujúce spracovateľské skripty, bude prirodzene v Pythone; server založený na existujúcej aplikácii Express zostane v TypeScripte. Nasledujúca tabuľka sumarizuje praktické rozdiely.

KritériumMCPServer (Python SDK)MCP SDK (TypeScript)
ZrelosťVeľmi zreléZrelé
Dekorátory@app.tool()Metóda server.tool()
HTTP TransportVstavaný (FastAPI)Vstavaný (Express)
KomunitaVeľkáVeľká

Štruktúra projektu, ktorá vydrží

Odporúčaná štruktúra adresárov oddeľuje štyri zodpovednosti: čo vidí model (tools/), čo pristupuje k dátam (services/), čo riadi prístup (auth/) a čo opisuje prostredie (config.py, .env).

my-mcp-server/
├── server.py              # Vstupný bod FastAPI + pripojenie MCP
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Nástroje na správu projektov
│   ├── file_tools.py      # Nástroje na správu súborov
│   └── search_tools.py    # Nástroje na vyhľadávanie
├── services/
│   ├── __init__.py
│   ├── database.py        # Prístup k databáze
│   └── external_api.py    # Volania externých API
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Autentifikačný middleware
├── config.py              # Konfigurácia (premenné prostredia)
├── Dockerfile             # Kontajnerizácia
├── requirements.txt       # Python závislosti
├── .env                   # Premenné prostredia (neodosielajú sa do repozitára)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Toto oddelenie má priamy, konkrétny dôsledok: tvoje nástroje už neobsahujú SQL ani HTTP volania, iba validáciu a delegovanie na službu. Business logiku potom môžeš testovať bez prechodu cez MCP a meniť databázy bez toho, aby si sa dotkol jediného docstringu, ktorý vidí model.

Vstupný bod: server.py

Hlavný súbor nerobí nič iné, len zostavuje komponenty: vytvára aplikáciu FastAPI, skladá middleware a pripája každý MCP server na jeho vlastnú cestu.

# server.py
"""Vstupný bod MCP servera."""

from contextlib import asynccontextmanager

import os

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from mcp.server.transport_security import TransportSecuritySettings
from tools.project_tools import project_mcp
from tools.search_tools import search_mcp
from auth.middleware import AuthMiddleware

# Každý MCP server musí spustiť svojho správcu relácií
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# Aplikácia FastAPI
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS pre webových klientov
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Autentifikačný middleware
api.add_middleware(AuthMiddleware)

# Verejný hostname, pod ktorým sú servery poskytované (inak: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# Pripojenie MCP serverov na odlišné cesty
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Domovská stránka (voliteľné, ale užitočné)
@api.get("/")
async def root():
    return {
        "service": "My MCP Server",
        "version": "1.0.0",
        "endpoints": {
            "projects": "/projects/mcp",
            "search": "/search/mcp",
        },
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(api, host="0.0.0.0", port=8000)

Pripojenie na odlišné cesty umožňuje používateľom povoliť iba doménu, ktorú potrebujú: niekto, kto hľadá dokumentáciu, sa pripojí na /search/mcp, bez toho aby mu boli ponúkané nástroje na správu projektov. Čo sa týka domovskej stránky, zdá sa byť triviálna, kým sa kolega neopýta na presnú URL koncového bodu; odpovie za teba a slúži ako kontrola zdravotného stavu.

Jeden modul nástrojov na doménu

Každý súbor v priečinku tools/ deklaruje svoj vlastný objekt MCPServer a zoskupuje nástroje z rovnakej funkčnej domény. Takto vyzerá modul správy projektov, ktorý bol predtým importovaný v server.py:

# tools/project_tools.py
"""MCP nástroje na správu projektov."""

from mcp.server.mcpserver import MCPServer
from services.database import db

project_mcp = MCPServer(
    "Project Manager",
    instructions="Tools for project and task management",
)

@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
    """Vytvorí nový projekt.

    Args:
        name: Názov projektu (2-100 znakov)
        description: Popis projektu (voliteľné)

    Returns:
        JSON s detailmi vytvoreného projektu
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Zoznam projektov podľa stavu.

    Args:
        status: Filter podľa stavu: active, archived, all (predvolené: active)

    Returns:
        JSON so zoznamom projektov
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Všimni si, aké krátke sú telá funkcií: len dva riadky každá, pretože prístup k dátam žije v services/database.py. Nástroj iba opisuje svoju zmluvu modelu a deleguje prácu.

Centralizovaná konfigurácia

Akákoľvek hodnota, ktorá sa mení medzi tvojím strojom a produkčným serverom, musí pochádzať z prostredia, nikdy z kódu. Jediný súbor config.py zhromažďuje tieto premenné spolu s ich predvolenými hodnotami:

# config.py
"""Konfigurácia MCP servera."""

import os
from dataclasses import dataclass

@dataclass
class Config:
    api_token: str = os.getenv("MCP_API_TOKEN", "")
    database_url: str = os.getenv("DATABASE_URL", "sqlite:///data.db")
    debug: bool = os.getenv("DEBUG", "false").lower() == "true"
    port: int = int(os.getenv("PORT", "8000"))
    max_results: int = int(os.getenv("MAX_RESULTS", "50"))

config = Config()

Parameter max_results ilustruje výhodu tohto prístupu: v deň, keď nástroj vráti príliš veľa výsledkov a zaplaví kontext modelu, upravíš premennú prostredia a reštartuješ službu bez opätovného nasadenia kódu.

Chyby, ktorým model rozumie

Výnimka v Pythone, ktorá náhle prebublá nahor, modelu nič nepovie: vidí zlyhanie, ale nechápe prečo, a často sa pokúsi o to isté znova. Namiesto toho štandardizuj explicitný formát odpovede pri chybe s kódom a správou.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formátuje štandardizovanú chybovú správu."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Získa detaily projektu podľa ID."""
    try:
        project = await db.projects.get(project_id)
        if not project:
            return error_response(f"Project {project_id} not found", "not_found")
        return project.to_json()
    except Exception as e:
        return error_response(f"Server error: {str(e)}", "server_error")

Rozdiel je v konverzácii rozhodujúci. Ak model dostane not_found, pochopí, že musí najprv vypísať zoznam projektov, aby našiel správne ID; ak narazí na tichú výnimku, vzdá to alebo sa dostane do slučky.

Stavový alebo bezstavový

Stavový server si uchováva informácie medzi volaniami: databáza v pamäti, relácie používateľov, kontext práce. Toto je bežné pre manažérske servery, ako bol správca úloh z predchádzajúcej lekcie. Bezstavový server spracováva každú požiadavku nezávisle a nič si nepamätá – odporúča sa pre čisté výpočty alebo transformácie a umožňuje horizontálne škálovanie, keďže ktorákoľvek inštancia môže vybaviť ktorúkoľvek požiadavku. SDK v2 to umožňuje pomocou parametra HTTP aplikácie (už sa neposiela do konštruktora). Všimni si, že so špecifikáciou z 28. 7. 2026 protokol sám o sebe už nepozná relácie: toto nastavenie sa týka len klientov vyjednávajúcich staršiu verziu protokolu.

app = MCPServer("Stateless Server")

# Nastavenie sa odovzdáva pri vytváraní HTTP aplikácie
mcp_app = app.streamable_http_app(stateless_http=True)

Túto otázku sa rozhodni skôr, než napíšeš svoje nástroje, nie až potom: prechod zo stavového na bezstavový server znamená presun všetkého stavu do externej databázy, čo prepíše dobrú časť kódu.

Kľúčové poznatky

  • Rozdeľ svoje nástroje do tematických modulov v priečinku tools/
  • Použi FastAPI ako HTTP základ, pripoj MCP servery na vyhradené cesty a odovzdaj im ich životný cyklus (lifespan)
  • Centralizuj konfiguráciu cez premenné prostredia
  • Štandardizuj formáty odpovedí pri chybách, aby ich model vedel využiť
  • Vyber si medzi stavovým (správa dát) a bezstavovým (čisté výpočty)
  • Pridaj domovskú stránku / na zdokumentovanie svojich MCP koncových bodov