Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Implementação de Ferramentas: Esquema JSON e Manipuladores

Aula 11 de 14 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. A Anatomia de uma Ferramenta MCP
  2. O Que o Decorador Constrói por Si
  3. Nomear e, em Seguida, Descrever
  4. Tipos, Manipuladores Assíncronos e Validação
  5. Polir o Valor de Retorno
  6. Pontos-chave

Atualizado em 2 de novembro de 2026 — MCP Python SDK v2. Este curso segue agora a versão 2 do SDK mcp (2.3.0 em 2 de outubro de 2026): MCPServer substitui FastMCP, as definições de transporte movem-se para run() ou streamable_http_app(), e uma aplicação exposta sob um nome de anfitrião real deve declarar esse nome de anfitrião (transport_security). Esta é também a versão exigida pelo Mistral SDK: o extra mistralai[agents] requer mcp>=2.2.0,<3.0. Fontes: Novidades na v2 · Guia de Migração · Implementar e escalar.

A Anatomia de uma Ferramenta MCP

Uma ferramenta MCP assemelha-se a uma função Python, mas, da perspetiva do modelo, não o é. Trata-se de um contrato de quatro partes: um nome, uma descrição, um esquema de entrada JSON e um manipulador que executa a lógica. O modelo nunca vê o seu código; vê apenas este contrato. Uma ferramenta perfeitamente implementada, mas mal descrita, nunca será chamada ou será invocada no momento errado. Por conseguinte, a qualidade do contrato determina a eficácia do servidor muito mais do que a qualidade da implementação.

O Que o Decorador Constrói por Si

MCPServer constrói este contrato automaticamente a partir da assinatura da sua função e da sua docstring. Escreve Python standard:

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
    ...

E o modelo recebe isto:

{
  "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"]
  }
}

Compare os dois blocos linha por linha: cada anotação de tipo torna-se um tipo JSON, cada valor predefinido torna-se um campo default, cada linha na secção Args torna-se uma descrição de parâmetro, e o único argumento sem valor predefinido acaba em required. Por outras palavras, tudo o que omitir na docstring desaparece completamente do contrato.

Nomear e, em Seguida, Descrever

O nome da ferramenta é o nome da função, e o modelo utiliza-o como sua primeira pista. Um verbo de ação seguido de um objeto claro não deixa ambiguidade, ao passo que um nome genérico ou técnico força o modelo a adivinhar:

# Bom: verbo de ação + objeto claro
@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: ...

# Mau: vago, ambíguo, técnico
@app.tool()
def process(data: str) -> str: ...        # Demasiado vago

@app.tool()
def handle_request(req: str) -> str: ...   # Incompreensível para o LLM

@app.tool()
def db_query(sql: str) -> str: ...         # Demasiado técnico

A docstring assume então o controlo e constitui a peça mais crítica de todo o seu servidor. Deve responder a três perguntas, nesta ordem: quando utilizar esta ferramenta, quais parâmetros fornecer com o seu formato e restrições, e o que esperar em retorno. O exemplo seguinte mostra como isto se apresenta num caso real:

@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
    """
    ...

O parágrafo seguinte à primeira linha é aquilo de que os servidores amadores mais frequentemente carecem. Sem ele, o modelo sabe o que a ferramenta faz, mas não em que situação a deve acionar. E o exemplo de data ISO 8601 poupar-lhe-á dezenas de chamadas com "April 15 at 7:30 PM".

Tipos, Manipuladores Assíncronos e Validação

MCPServer traduz anotações Python comuns nos seus equivalentes JSON Schema.

PythonJSON SchemaExemplo
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array de string["a", "b"]
dictobject{"key": "val"}
Optional[str]string (anulável)"text" ou null

Assim que uma ferramenta sai do seu processo — chamada de rede, consulta à base de dados, leitura de ficheiro remoto — declare-a como async. Um manipulador síncrono à espera de uma resposta HTTP bloqueia todo o servidor e, consequentemente, os seus outros utilizadores:

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

O esquema JSON restringe tipos, nunca valores: nada impede o modelo de enviar um nome de 3.000 caracteres ou uma função inventada. Portanto, valide sempre no ponto de entrada do manipulador e devolva uma mensagem indicando a correção necessária:

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

A terceira mensagem lista os valores permitidos. O modelo pode então autocorrigir-se e chamar novamente a ferramenta, em vez de desistir perante um erro “Invalid role” sem explicação.

Polir o Valor de Retorno

Uma ferramenta MCP devolve sempre texto, mas esse texto pode ser JSON estruturado, que o modelo interpreta muito bem. O contraste entre estes dois retornos resume o essencial:

# Bom: JSON estruturado e legível
return json.dumps({
    "success": True,
    "user": {
        "name": "Alice Dupont",
        "email": "[email protected]",
        "role": "editor",
    },
    "message": "User created successfully"
}, ensure_ascii=False)

# Mau: dados brutos difíceis de utilizar
return "OK:user_id=abc123:status=created"

Prefira sempre valores legíveis por um humano em vez de identificadores internos: o modelo pode utilizar imediatamente "Alice Dupont" na sua resposta, ao passo que um UUID obriga a uma chamada adicional para descobrir de quem se está a falar. Por outro lado, cuidado com retornos inchados — cinquenta campos por registo enchem o contexto sem acrescentar valor. O reflexo correto ao escrever uma ferramenta é perguntar-se do que o modelo necessitará para informar o utilizador e devolver apenas isso.

Pontos-chave

  • O decorador @app.tool() gera automaticamente o Esquema JSON para os parâmetros
  • O nome da função = nome da ferramenta (verbo + objeto)
  • A docstring é crucial: guia o modelo sobre quando e como chamar a ferramenta
  • Utilize anotações de tipo Python para o esquema (str, int, float, bool, list, dict)
  • Valide sempre as entradas e devolva erros acionáveis
  • Devolva JSON estruturado com valores legíveis por humanos