Pāriet uz galveno saturu
Latviešu— Izvēlēties valodu
Izvēlne

Arhitektūra pielāgotam MCP serverim

Nodarbība 10 no 14 Atjaunota 2026. gada 2. novembris Programmētājs
Šajā lapā
  1. Ražošanas MCP servera projektēšana
  2. Sava ietvara izvēle
  3. Ilgtspējīga projekta struktūra
  4. Ieejas punkts: server.py
  5. Viens rīku modulis katrai domēnai
  6. Centralizēta konfigurācija
  7. Kļūdas, ko modelis var lasīt
  8. Ar stāvokli vai bez stāvokļa
  9. Galvenās atziņas

Atjaunināts 2026. gada 2. novembrī — MCP Python SDK v2. Šis kurss tagad seko mcp SDK 2. versijai (2.3.0, sākot no 2026. gada 2. oktobra): MCPServer aizstāj FastMCP, transporta iestatījumi tiek pārvietoti uz run() vai streamable_http_app(), un lietojumprogrammai, kas eksponēta zem reāla resursdatora nosaukuma, ir jādeklarē šis nosaukums (transport_security). Tā ir arī versija, ko pieprasa Mistral SDK: papildinājums mistralai[agents] prasa mcp>=2.2.0,<3.0. Avoti: Kas jauns v2 · Migrācijas ceļvedis · Izvietošana un mērogošana.

Ražošanas MCP servera projektēšana

MCP prototips ietilpst četrdesmit rindu failā, un bieži vien tas ir pietiekami, lai pārliecinātu komandu. Pāreja uz reālu lietošanu maina visu: serveri izsauc vairāki cilvēki, rīku skaits pieaug, konfigurācija atšķiras dažādās vidēs, un viens fails kļūst neuzturams. Šī nodarbība aptver arhitektūras lēmumus, kas novērš šīs problēmas: ietvara izvēle, projekta strukturēšana, konfigurācijas un kļūdu pārvaldība, kā arī lēmums par labu stāvokli saglabājošiem vai bezstāvokļa serveriem.

Sava ietvara izvēle

Python valodā oficiālā SDK standarta rīks ir klase MCPServer (agrāk FastMCP). Tā nodrošina dekoratoros balstītu API un apstrādā MCP protokolu tavā vietā, tāpēc serveris tiek aktivizēts trīs rindās:

from mcp.server.mcpserver import MCPServer

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

JavaScript un TypeScript komandām ir Anthropic publicētais oficiālais MCP SDK. Loģika ir līdzīga, lai gan sintakse atšķiras:

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

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

Izvēle ir atkarīga mazāk no iespējām un vairāk no ekosistēmas, kurā tavs serveris iegūs datus. Serveris, kas vaicā datubāzi, izmantojot SQLAlchemy, vai atkārtoti izmanto esošus apstrādes skriptus, dabiski būs Python valodā; serveris, kas balstīts uz esošu Express lietojumprogrammu, paliks TypeScript valodā. Zemāk esošajā tabulā apkopotas praktiskās atšķirības.

KritērijsMCPServer (Python SDK)MCP SDK (TypeScript)
BriedumsĻoti nobriedisNobriedis
Dekoratori@app.tool()Metode server.tool()
HTTP transportsIebūvēts (FastAPI)Iebūvēts (Express)
KopienaLielaLiela

Ilgtspējīga projekta struktūra

Ieteicamā direktoriju struktūra nodala četras atbildības jomas: ko modelis redz (tools/), kas piekļūst datiem (services/), kas kontrolē piekļuvi (auth/) un kas apraksta vidi (config.py, .env).

my-mcp-server/
├── server.py              # FastAPI ieejas punkts + MCP montāža
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Projektu vadības rīki
│   ├── file_tools.py      # Failu pārvaldības rīki
│   └── search_tools.py    # Meklēšanas rīki
├── services/
│   ├── __init__.py
│   ├── database.py        # Datubāzes piekļuve
│   └── external_api.py    # Ārējo API izsaukumi
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Autentifikācijas starpprogrammatūra
├── config.py              # Konfigurācija (vides mainīgie)
├── Dockerfile             # Konteinerizācija
├── requirements.txt       # Python atkarības
├── .env                   # Vides mainīgie (netiek komitēti)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Šai nodalīšanai ir tiešas, konkrētas sekas: tavi rīki vairs nesatur SQL vai HTTP izsaukumus, tikai validāciju un deleģēšanu servisam. Tad tu vari testēt biznesa loģiku, neizejot caur MCP, un nomainīt datubāzi, nepieskaroties nevienam docstring, ko redz modelis.

Ieejas punkts: server.py

Galvenais fails nedara neko citu, kā tikai saliek kopā komponentes: tas izveido FastAPI lietojumprogrammu, sakrauj starpprogrammatūras un montē katru MCP serveri uz tā atsevišķā maršruta.

# server.py
"""MCP servera ieejas punkts."""

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

# Katram MCP serverim jāsāk savu sesiju pārvaldnieks
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

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

# CORS tīmekļa klientiem
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Autentifikācijas starpprogrammatūra
api.add_middleware(AuthMiddleware)

# Publiskais resursdatora nosaukums, zem kura tiek pasniegti serveri (pretējā gadījumā: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# MCP serveru montāža uz atšķirīgiem maršrutiem
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Sākumlapa (opcionāla, bet noderīga)
@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)

Montāža uz atšķirīgiem maršrutiem ļauj lietotājiem iespējot tikai nepieciešamo domēnu: kāds, kurš meklē dokumentāciju, pieslēdzas /search/mcp, un viņam netiek piedāvāti projektu vadības rīki. Kas attiecas uz sākumlapu, tā šķiet triviāla, līdz kolēģis pajautā precīzu galapunkta URL; tā atbild tavā vietā un kalpo kā veselības pārbaude.

Viens rīku modulis katrai domēnai

Katrs fails mapē tools/ deklarē savu MCPServer objektu un grupē rīkus no vienas funkcionālās domēnas. Lūk, kā izskatās projektu vadības modulis, ko iepriekš importēja server.py:

# tools/project_tools.py
"""MCP rīki projektu vadībai."""

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:
    """Izveido jaunu projektu.

    Args:
        name: Projekta nosaukums (2–100 rakstzīmes)
        description: Projekta apraksts (opcionāli)

    Returns:
        JSON ar izveidotā projekta detaļām
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Uzskaita projektus pēc statusa.

    Args:
        status: Filtrēt pēc statusa: active, archived, all (noklusējums: active)

    Returns:
        JSON ar projektu sarakstu
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Ievēro, cik īsi ir funkciju ķermeņi: tikai divas rindas katrai, jo datu piekļuve dzīvo failā services/database.py. Rīks vienkārši apraksta savu līgumu modelim un deleģē tālāk.

Centralizēta konfigurācija

Jebkurai vērtībai, kas mainās starp tavu datoru un ražošanas serveri, ir jānāk no vides, nekad no koda. Viens fails config.py apkopo šos mainīgos ar to noklusējuma vērtībām:

# config.py
"""MCP servera konfigurācija."""

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

Parametrs max_results ilustrē šīs pieejas priekšrocības: dienā, kad rīks atgriež pārāk daudz rezultātu un piesātina modeļa kontekstu, tu pielāgo vides mainīgo un restartē serveri, nepārizvieto kodu.

Kļūdas, ko modelis var lasīt

Python izņēmums, kas pēkšņi uzpeld augšup, modelim nepasaka neko: tas redz kļūmi, nesaprotot iemeslu, un bieži vien mēģina atkārtot to pašu. Tā vietā standartizē skaidru kļūdas atbildes formātu ar kodu un ziņojumu.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formatē standartizētu kļūdas ziņojumu."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Iegūst projekta detaļas pēc 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")

Atšķirība sarunā ir izšķiroša. Saskaroties ar not_found, modelis saprot, ka vispirms jāuzskaita projekti, lai atrastu pareizo ID; saskaroties ar klusu izņēmumu, tas padodas vai iekļūst cilpā.

Ar stāvokli vai bez stāvokļa

Ar stāvokli (stateful) serveris saglabā informāciju starp izsaukumiem: atmiņā esoša datubāze, lietotāju sesijas, darba konteksts. Tas ir izplatīts vadības serveriem, piemēram, uzdevumu pārvaldniekam no iepriekšējās nodarbības. Bezstāvokļa (stateless) serveris apstrādā katru pieprasījumu neatkarīgi, neko neatceroties — ieteicams tīriem aprēķiniem vai transformācijām, un tas ļauj horizontālu mērogošanu, jo jebkurš instances eksemplārs var apstrādāt jebkuru pieprasījumu. SDK v2 to ļauj ar HTTP lietojumprogrammas parametru (vairs netiek nodots konstruktoram). Ņem vērā, ka kopš 2026. gada 28. jūlija specifikācijas pats protokols vairs nezina sesijas: šis iestatījums attiecas tikai uz klientiem, kas vienojas par agrāku protokola versiju.

app = MCPServer("Stateless Server")

# Iestatījums tiek nodots, veidojot HTTP lietojumprogrammu
mcp_app = app.streamable_http_app(stateless_http=True)

Izlem šo jautājumu pirms rīku rakstīšanas, nevis pēc tam: pāreja no servera ar stāvokli uz bezstāvokļa serveri nozīmē visa stāvokļa pārvietošanu uz ārēju datubāzi, kas pārraksta lielu daļu koda.

Galvenās atziņas

  • Nodali savus rīkus tematiskos moduļos mapē tools/
  • Izmanto FastAPI kā HTTP bāzi, montē MCP serverus uz veltītiem maršrutiem un nodod to lifespan
  • Centralizē konfigurāciju, izmantojot vides mainīgos
  • Standartizē kļūdu atbilžu formātus, lai modelis tos varētu izmantot
  • Izvēlies starp ar stāvokli (datu pārvaldība) un bezstāvokļa (tīri aprēķini)
  • Pievieno sākumlapu /, lai dokumentētu savus MCP galapunktus