Pereiti prie pagrindinio turinio
Lietuvių— Pasirinkite kalbą
Meniu

Tinkamo MCP serverio architektūra

Paskaita 10 iš 14 Atnaujinta 2026 m. lapkričio 2 d. Kūrėjas
Šiame puslapyje
  1. Gamybinio MCP serverio projektavimas
  2. Karkaso pasirinkimas
  3. Ilgaamžė projekto struktūra
  4. Įvesties taškas: server.py
  5. Vienas įrankių modulis vienai sričiai
  6. Centralizuota konfigūracija
  7. Klaidos, kurias modelis gali perskaityti
  8. Su būsena ar be būsenos
  9. Svarbiausi punktai

Atnaujinta 2026 m. lapkričio 2 d. — MCP Python SDK v2. Šis kursas remiasi 2 versija (mcp SDK 2.3.0, pagal 2026 m. spalio 2 d. duomenis): MCPServer pakeičia FastMCP, transporto nustatymai perkeliami į run() arba streamable_http_app(), o realiu domenu eksponuojama programa privalo deklaruoti tą domeną (transport_security). Tai taip pat yra versija, kurią reikalauja Mistral SDK: mistralai[agents] papildinys reikalauja mcp>=2.2.0,<3.0. Šaltiniai: Kas naujo v2 · Migracijos gidas · Diegimas ir mastelio keitimas.

Gamybinio MCP serverio projektavimas

MCP prototipą galima sutalpinti į keturiasdešimties eilučių failą, ir dažnai to pakanka įtikinti komandą. Tačiau perėjimas prie realaus naudojimo viską pakeičia: serverį kviečia daugybė žmonių, įrankiai daugėja, konfigūracija skiriasi priklausomai nuo aplinkos, o vienas failas tampa nebeišmanomas. Šioje pamokoje nagrinėsime architektūrinius sprendimus, padedančius išvengti šių sunkumų: kaip pasirinkti karkasą, kaip struktūrizuoti projektą, kaip valdyti konfigūraciją bei klaidas ir kaip apsispręsti tarp būsenos išsaugojimo (stateful) ir be būsenos (stateless) serverių.

Karkaso pasirinkimas

Python kalboje standartinis įrankis yra oficialiojo SDK klasė MCPServer (anksčiau vadinta FastMCP). Ji pateikia dekoratoriais pagrįstą API ir pati tvarko MCP protokolą, todėl serveris pradeda veikti vos trimis eilutėmis:

from mcp.server.mcpserver import MCPServer

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

JavaScript ir TypeScript komandos turi oficialų MCP SDK, kurį leidžia „Anthropic“. Logika panaši, nors sintaksė skiriasi:

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

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

Pasirinkimas priklauso ne tiek nuo galimybių, kiek nuo ekosistemos, iš kurios serveris gaus duomenis. Serveris, kuris užklausia duomenų bazę naudodamas „SQLAlchemy“ arba pakartotinai naudoja esamas apdorojimo skriptus, natūraliai bus parašytas Python kalba; serveris, besiremiantis esama „Express“ programa, liks TypeScript kalba. Toliau pateiktoje lentelėje apibendrinti praktiniai skirtumai.

KriterijusMCPServer (Python SDK)MCP SDK (TypeScript)
BrandumasLabai brandusBrandus
Dekoratoriai@app.tool()server.tool() metodas
HTTP transportasIntegruotas (FastAPI)Integruotas (Express)
BendruomenėDidelėDidelė

Ilgaamžė projekto struktūra

Rekomenduojama katalogų struktūra atskiria keturias atsakomybes: ką mato modelis (tools/), kas prieina prie duomenų (services/), kas valdo prieigą (auth/) ir kas aprašo aplinką (config.py, .env).

my-mcp-server/
├── server.py              # FastAPI įvesties taškas + MCP prijungimas
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Projektų valdymo įrankiai
│   ├── file_tools.py      # Failų valdymo įrankiai
│   └── search_tools.py    # Paieškos įrankiai
├── services/
│   ├── __init__.py
│   ├── database.py        # Duomenų bazės prieiga
│   └── external_api.py    # Išorinių API kvietimai
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Autentifikavimo tarpinė programa
├── config.py              # Konfigūracija (aplinkos kintamieji)
├── Dockerfile             # Konteinerizavimas
├── requirements.txt       # Python priklausomybės
├── .env                   # Aplinkos kintamieji (neįtraukiami į versijų kontrolę)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Šis atskyrimas turi tiesioginę, konkrečią pasekmę: jūsų įrankiuose nebelieka SQL ar HTTP kvietimų, tik validavimas ir delegavimas servisui. Tuomet galite testuoti verslo logiką apeidami MCP ir keisti duomenų bazes neliesdami nė vieno modelio matomo dokumentacijos teksto (docstring).

Įvesties taškas: server.py

Pagrindinis failas tik surenka komponentus: sukuria „FastAPI“ programą, priduria tarpines programas (middleware) ir kiekvieną MCP serverį prijungia atskiru maršrutu.

# server.py
"""MCP serverio įvesties taškas."""

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

# Kiekvienas MCP serveris turi paleisti savo sesijų valdytoją
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# FastAPI programa
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS žiniatinklio klientams
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Autentifikavimo tarpinė programa
api.add_middleware(AuthMiddleware)

# Viešas domenas, kuriuo teikiami serveriai (kitaip: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# MCP serverių prijungimas skirtingais maršrutais
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Pagrindinis puslapis (nebūtinas, bet naudingas)
@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)

Prijungimas skirtingais maršrutais leidžia vartotojams įjungti tik jiems reikalingą sritį: kas ieško dokumentacijos, prisijungia prie /search/mcp ir nemato projektų valdymo įrankių. O pagrindinis puslapis atrodo nereikšmingas, kol kolega nepaklausia tikslios galinio taško URL; jis atsako už jus ir veikia kaip būsenos tikrinimas (health check).

Vienas įrankių modulis vienai sričiai

Kiekvienas tools/ aplanko failas deklaruoja savo MCPServer objektą ir sugrupuoja tos pačios funkcinės srities įrankius. Štai kaip atrodo projektų valdymo modulis, kurį anksčiau importavo server.py:

# tools/project_tools.py
"""MCP įrankiai projektų valdymui."""

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:
    """Sukuria naują projektą.

    Args:
        name: Projekto pavadinimas (2–100 simbolių)
        description: Projekto aprašymas (neprivaloma)

    Returns:
        JSON su sukurto projekto detalėmis
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Išvardija projektus pagal būseną.

    Args:
        status: Filtruoti pagal būseną: active, archived, all (numatyta: active)

    Returns:
        JSON su projektų sąrašu
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Atkreipk dėmesį, kokios trumpos yra funkcijų kūno eilutės: tik po dvi, nes duomenų prieiga gyvena faile services/database.py. Įrankis tik aprašo savo sutartį modeliui ir deleguoja darbą.

Centralizuota konfigūracija

Bet kuri reikšmė, kuri skiriasi tavo kompiuteryje ir gamybiniame serveryje, turi būti gaunama iš aplinkos, o ne iš kodo. Vienas config.py failas surenka šiuos kintamuosius su jų numatytosiomis reikšmėmis:

# config.py
"""MCP serverio konfigūracija."""

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()

Parametras max_results iliustruoja šio požiūrio naudą: jei vieną dieną įrankis grąžina per daug rezultatų ir perpildo modelio kontekstą, tu tiesiog pakoreguoji aplinkos kintamąjį ir paleidi iš naujo, išvengdamas kodo diegimo iš naujo.

Klaidos, kurias modelis gali perskaityti

Python išimtis, staiga iškylanti į viršų, modeliui nieko nepasako: jis mato nesėkmę, bet nesupranta priežasties, ir dažnai bando tą patį veiksmą iš naujo. Vietoj to, standartizuok aiškų klaidos atsako formatą su kodu ir žinute.

import json

def error_response(message: str, code: str = "error") -> str:
    """Suformatuoja standartizuotą klaidos žinutę."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Gauna projekto detales pagal 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")

Skirtumas pokalbyje yra lemiamas. Susidūręs su not_found, modelis supranta, kad pirmiausia turi išvardyti projektus, kad rastų tinkamą ID; susidūręs su tylia išimtimi, jis pasiduoda arba įstringa cikle.

Su būsena ar be būsenos

Su būsena (stateful) serveris išsaugo informaciją tarp kvietimų: atmintyje laikoma duomenų bazė, vartotojo sesijos, darbo kontekstas. Tai įprasta valdymo serveriams, pavyzdžiui, užduočių valdytojui iš ankstesnės pamokos. Be būsenos (stateless) serveris kiekvieną užklausą tvarko nepriklausomai, nieko neprisimindamas – tai rekomenduojama gryniems skaičiavimams ar transformacijoms ir leidžia horizontaliai didinti mastelį, nes bet kuris egzempliorius gali apdoroti bet kurią užklausą. SDK v2 versija tai įgalina per HTTP programos parametrą (jau nebeperduodamą konstruktoriui). Atkreipk dėmesį, kad pagal 2026-07-28 specifikaciją pats protokolas sesijų nebežino: šis nustatymas aktualus tik klientams, derantiems dėl ankstesnės protokolo versijos.

app = MCPServer("Stateless Server")

# Nustatymas perduodamas kuriant HTTP programą
mcp_app = app.streamable_http_app(stateless_http=True)

Šį klausimą išspręsk prieš rašydamas įrankius, o ne po to: perėjimas nuo serverio su būsena prie serverio be būsenos reiškia visos būsenos perkėlimą į išorinę duomenų bazę, o tai reikalauja perrašyti gerą dalį kodo.

Svarbiausi punktai

  • Atskirkite įrankius į teminius modulius aplanke tools/
  • Naudokite FastAPI kaip HTTP pagrindą, prijunkite MCP serverius atskirais maršrutais ir perduokite jų gyvavimo ciklą (lifespan)
  • Centralizuokite konfigūraciją naudodami aplinkos kintamuosius
  • Standartizuokite klaidų atsakų formatus, kad modelis galėtų jais naudotis
  • Pasirinkite tarp su būsena (duomenų valdymas) ir be būsenos (gryni skaičiavimai)
  • Pridėkite pagrindinį puslapį /, kuriame būtų dokumentuojami jūsų MCP galiniai taškai