Implementação de Ferramentas: Esquema JSON e Manipuladores
Nesta página
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):MCPServersubstituiFastMCP, as definições de transporte movem-se pararun()oustreamable_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 extramistralai[agents]requermcp>=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.
| Python | JSON Schema | Exemplo |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array de string | ["a", "b"] |
dict | object | {"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