Conteúdo do curso Lição 139 de 250 · Saídas estruturadas e chamada de funções/ferramentas
Saídas estruturadas e chamada de funções/ferramentas

Ferramentas via MCP (Model Context Protocol)

Quando seu app tem mais de uma ferramenta, cada fornecedor de modelos inventa seu próprio formato JSON para chamá-las, e você acaba escrevendo um adaptador por provedor. O Model Context Protocol (MCP) é o padrão aberto que resolve isso. É um protocolo de comunicação JSON-RPC 2.0 para expor ferramentas (funções que o modelo pode chamar), recursos (dados que ele pode ler) e prompts a qualquer cliente de modelo. Escreva um servidor MCP uma vez e qualquer cliente que entenda MCP (um assistente de IDE, um app de desktop, um agente) pode usá-lo.

Toda mensagem é JSON-RPC 2.0, um envelope pequeno e fixo. Uma requisição sempre carrega quatro chaves:

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "add", "arguments": {"a": 2, "b": 3}}}

O id liga uma resposta à sua requisição. O servidor responde com uma resposta que repete o mesmo id e carrega ou um result ou um objeto error, nunca os dois:

{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "5"}], "isError": false}}
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found"}}

Os códigos negativos são o padrão do JSON-RPC: -32601 é "method not found", -32602 é "invalid params", e assim por diante. Um resultado de tools/call sempre tem esse formato: uma lista content de blocos (texto, imagens etc.) mais isError. Uma ferramenta que rodou mas falhou (um nome de cidade inválido, por exemplo) responde com isError: true em um resultado normal, para que o modelo possa ler a falha; o objeto error do JSON-RPC é para problemas de protocolo, como um método desconhecido.

Uma sessão começa com um handshake: o cliente envia uma requisição initialize (sua versão do protocolo, suas capacidades e seu nome), o servidor responde com suas próprias capacidades e o cliente confirma com uma notificação notifications/initialized (uma mensagem sem id, porque ninguém responde a ela). Só então o cliente descobre as ferramentas chamando tools/list com params vazios; o servidor retorna a lista de descritores de ferramentas.

Um servidor MCP real roda por stdio ou HTTP e liga isso ao SDK; aqui montamos e interpretamos as mensagens com o módulo json da biblioteca padrão, para que o formato da comunicação fique concreto. Você vai escrever três funções.

  • build_request(id, method, params) -> uma string JSON para o envelope {"jsonrpc": "2.0", "id": id, "method": method, "params": params}. Use json.dumps.
  • parse_response(text) -> faça json.loads do texto, exija jsonrpc == "2.0" (senão levante ValueError). Se tiver um result, retorne {"id": ..., "ok": True, "result": ...}. Se tiver um error, retorne {"id": ..., "ok": False, "error": {"code": ..., "message": ...}}. Se não tiver nenhum dos dois, levante ValueError.
  • list_tools_request(id) -> a requisição de descoberta de ferramentas: um build_request com o método "tools/list" e params vazios {}.

Como build_request retorna uma string, os testes a interpretam de volta com json.loads e comparam o dict, então a ordem das chaves não importa. Garanta que um resultado e um erro façam a ida e volta, que a requisição de descoberta tenha o método certo e que uma mensagem sem jsonrpc ou sem result nem error levante exceção.

Sua vez

Monte e interprete mensagens JSON-RPC 2.0 no estilo MCP com o módulo json. build_request(id, method, params) retorna a string JSON para {"jsonrpc": "2.0", "id", "method", "params"}. parse_response(text) carrega o texto, exige jsonrpc == "2.0" (senão levante ValueError) e retorna {"id", "ok": True, "result"} para um resultado ou {"id", "ok": False, "error": {"code", "message"}} para um erro, levantando exceção se não tiver nenhum dos dois. list_tools_request(id) retorna a requisição de descoberta tools/list (enviada depois do handshake) com params vazios.

Viu um problema nesta lição? Reporte-o · Pergunte sobre esta lição

Este exercício abre em breve

Termine a lição anterior para que esta seja desbloqueada. O curso inteiro é gratuito, não precisa de conta, e você pode ler esta lição agora mesmo.