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

Имплементиране на инструменти: JSON Schema и обработчици

Урок 11 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Анатомия на един MCP инструмент
  2. Какво изгражда декораторът за Вас
  3. Именуване и след това описване
  4. Типове, асинхронни обработчици и валидация
  5. Прецизиране на върнатата стойност
  6. Ключови изводи

Обновено на 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 инструмент

Един MCP инструмент прилича на Python функция, но от гледна точка на модела той не е такава. Той представлява договор от четири части: име, описание, JSON схема за входните данни и обработчик, който изпълнява логиката. Моделът никога не вижда Вашия код – той вижда само този договор. Един перфектно имплементиран инструмент, който е описан лошо, никога няма да бъде извикан или ще бъде извикан в грешния момент. Следователно качеството на договора определя ефективността на сървъра много повече от качеството на имплементацията.

Какво изгражда декораторът за Вас

MCPServer изгражда този договор автоматично въз основа на подписа на Вашата функция и нейния docstring. Вие пишете стандартен Python:

from mcp.server.mcpserver import MCPServer

app = MCPServer("My Server")

@app.tool()
def search_documents(
    query: str,
    max_results: int = 10,
    language: str = "fr",
    include_archived: bool = False,
) -> str:
    """Searches for documents in the knowledge base.

    Args:
        query: Search terms (2-500 characters)
        max_results: Maximum number of results (1-100, default: 10)
        language: ISO 639-1 language code (default: fr)
        include_archived: Include archived documents (default: false)

    Returns:
        JSON with the list of found documents and the total count
    """
    # Search logic
    ...

А моделът получава следното:

{
  "name": "search_documents",
  "description": "Searches for documents in the knowledge base.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search terms (2-500 characters)"
      },
      "max_results": {
        "type": "integer",
        "description": "Maximum number of results (1-100, default: 10)",
        "default": 10
      },
      "language": {
        "type": "string",
        "description": "ISO 639-1 language code (default: fr)",
        "default": "fr"
      },
      "include_archived": {
        "type": "boolean",
        "description": "Include archived documents (default: false)",
        "default": false
      }
    },
    "required": ["query"]
  }
}

Сравнете двата блока ред по ред: всяка анотация на тип се превръща в JSON тип, всяка стойност по подразбиране става поле default, всеки ред в секцията Args се превръща в описание на параметър, а единственият аргумент без стойност по подразбиране попада в required. С други думи, всичко, което пропуснете в docstring, изчезва напълно от договора.

Именуване и след това описване

Името на инструмента е името на функцията и моделът го използва като първа подсказка. Глагол за действие, последван от ясен обект, не оставя място за двусмислие, докато общо или техническо име кара модела да гадае:

# Добре: глагол за действие + ясен обект
@app.tool()
def create_issue(title: str, body: str) -> str: ...

@app.tool()
def search_repositories(query: str) -> str: ...

@app.tool()
def get_user_profile(username: str) -> str: ...

# Лошо: неясно, двусмислено, техническо
@app.tool()
def process(data: str) -> str: ...        # Твърде неясно

@app.tool()
def handle_request(req: str) -> str: ...   # Неразбираемо за LLM

@app.tool()
def db_query(sql: str) -> str: ...         # Твърде технически

След това docstring поема щафетата и представлява най-критичната част от целия Ви сървър. Той трябва да отговори на три въпроса в следния ред: кога да се използва този инструмент, кои параметри да се предоставят с техния формат и ограничения и какво да се очаква в отговор. Следващият пример показва как изглежда това в реален случай:

@app.tool()
def book_restaurant(
    restaurant_name: str,
    date: str,
    party_size: int,
    special_requests: str = "",
) -> str:
    """Books a table at a restaurant.

    Performs a complete reservation including email
    confirmation. Use this tool when the user wants
    to book a specific restaurant.

    Args:
        restaurant_name: Exact name of the restaurant
        date: Date and time in ISO 8601 format (e.g., 2026-04-15T19:30:00)
        party_size: Number of guests (1-20)
        special_requests: Special requests (allergies, occasion, etc.)

    Returns:
        JSON with the reservation number, confirmation,
        and restaurant details
    """
    ...

Параграфът след първия ред е това, което аматьорските сървъри най-често пропускат. Без него моделът знае какво прави инструментът, но не и в коя ситуация да го задейства. А примерът с датата във формат ISO 8601 ще Ви спести десетки обаждания с формата "15 април в 19:30 ч.".

Типове, асинхронни обработчици и валидация

MCPServer превежда обичайните Python анотации в техните еквиваленти в JSON Schema.

PythonJSON SchemaПример
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array от string["a", "b"]
dictobject{"key": "val"}
Optional[str]string (nullable)"text" или null

Веднага щом един инструмент излезе извън своя процес – мрежово обаждане, заявка към база данни, четене на отдалечен файл – declare го като async. Синхронен обработчик, чакащ HTTP отговор, блокира целия сървър, а заедно с него и всички останали потребители:

import httpx

@app.tool()
async def fetch_api_data(endpoint: str) -> str:
    """Retrieves data from an external API.

    Args:
        endpoint: The API endpoint path (e.g., /users/123)

    Returns:
        JSON data from the API
    """
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com{endpoint}")
        response.raise_for_status()
        return response.text

JSON схемата ограничава типовете, но никога стойностите: нищо не пречи на модела да изпрати име от 3000 символа или измислена роля. Затова винаги валидирайте в началната точка на обработчика и връщайте съобщение, указващо необходимата корекция:

import json

@app.tool()
def create_user(name: str, email: str, role: str = "viewer") -> str:
    """Creates a new user.

    Args:
        name: Full name (2-100 characters)
        email: Valid email address
        role: Role: viewer, editor, admin (default: viewer)

    Returns:
        JSON with the created user details
    """
    # Validation
    if len(name) < 2 or len(name) > 100:
        return json.dumps({"error": "Name must be between 2 and 100 characters"})

    if "@" not in email or "." not in email:
        return json.dumps({"error": "Invalid email address"})

    valid_roles = ("viewer", "editor", "admin")
    if role not in valid_roles:
        return json.dumps({"error": f"Invalid role. Choices: {', '.join(valid_roles)}"})

    # Creation...
    return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})

Третото съобщение изброява позволените стойности. Тогава моделът може да се коригира и да извика инструмента отново, вместо да се откаже пред грешка “Невалидна роля” без обяснение.

Прецизиране на върнатата стойност

Един MCP инструмент винаги връща текст, но този текст може да бъде структуриран JSON, който моделът интерпретира много добре. Контрастът между тези две връщания обобщава същественото:

# Добре: структуриран, четим JSON
return json.dumps({
    "success": True,
    "user": {
        "name": "Alice Dupont",
        "email": "[email protected]",
        "role": "editor",
    },
    "message": "User created successfully"
}, ensure_ascii=False)

# Лошо: сурови данни, трудни за използване
return "OK:user_id=abc123:status=created"

Винаги предпочитайте стойности, четими за човек, пред вътрешни идентификатори: моделът може веднага да използва "Alice Dupont" в своя отговор, докато UUID принуждава към допълнително обаждане, за да се разбере за кого става въпрос. Обратно, пазете се от прекалено обемни връщания – петдесет полета на запис запълват контекста, без да добавят стойност. Правилният рефлекс при писане на инструмент е да се запитате какво ще е необходимо на модела, за да каже на потребителя, и да върнете само това.

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

  • Декораторът @app.tool() автоматично генерира JSON Schema за параметрите
  • Името на функцията = име на инструмента (глагол + обект)
  • Docstring е от решаващо значение: той насочва модела кога и как да извика инструмента
  • Използвайте Python анотации на типове за схемата (str, int, float, bool, list, dict)
  • Винаги валидирайте входните данни и връщайте грешки, които позволяват действие
  • Връщайте структуриран JSON със стойности, четими за човек