Temario Lección 139 de 250 · Salidas estructuradas y llamadas a funciones y herramientas
Salidas estructuradas y llamadas a funciones y herramientas

Herramientas sobre MCP (Model Context Protocol)

En cuanto tu aplicación tiene más de una herramienta, cada proveedor de modelos se inventa su propia forma JSON para llamarlas, y acabas escribiendo un adaptador por proveedor. El Model Context Protocol (MCP) es el estándar abierto que lo resuelve. Es un protocolo de transporte JSON-RPC 2.0 para exponer herramientas (funciones que el modelo puede llamar), recursos (datos que puede leer) y prompts a cualquier cliente de modelos. Escribe un servidor MCP una vez y cualquier cliente compatible con MCP (un asistente de IDE, una aplicación de escritorio, un agente) podrá usarlo.

Cada mensaje es JSON-RPC 2.0, un sobre diminuto y fijo. Una petición siempre lleva cuatro claves:

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

El id vincula una respuesta con su petición. El servidor contesta con una respuesta que repite el mismo id y lleva o bien un result o bien un objeto error, nunca ambos:

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

Los códigos negativos son los estándar de JSON-RPC: -32601 es "método no encontrado", -32602 es "parámetros no válidos", etcétera. Un resultado de tools/call siempre tiene esa forma: una lista content de bloques (texto, imágenes, etcétera) más isError. Una herramienta que se ejecutó pero falló (un nombre de ciudad erróneo, por ejemplo) responde con isError: true en un resultado normal, para que el modelo pueda leer el fallo; el objeto error de JSON-RPC es para problemas de protocolo, como un método desconocido.

Una sesión empieza con un saludo inicial: el cliente envía una petición initialize (su versión del protocolo, sus capacidades y su nombre), el servidor responde con sus propias capacidades, y el cliente lo confirma con una notificación notifications/initialized (un mensaje sin id, porque nadie le responde). Solo entonces el cliente descubre las herramientas llamando a tools/list con parámetros vacíos; el servidor devuelve la lista de descriptores de herramientas.

Un servidor MCP real funciona sobre stdio o HTTP y conecta todo esto con el SDK; aquí construimos y analizamos los mensajes con el módulo json de la biblioteca estándar para que el formato de transporte sea concreto. Vas a escribir tres funciones.

  • build_request(id, method, params) -> una cadena JSON para el sobre {"jsonrpc": "2.0", "id": id, "method": method, "params": params}. Usa json.dumps.
  • parse_response(text) -> pasa el texto por json.loads y exige jsonrpc == "2.0" (si no, lanza ValueError). Si tiene un result, devuelve {"id": ..., "ok": True, "result": ...}. Si tiene un error, devuelve {"id": ..., "ok": False, "error": {"code": ..., "message": ...}}. Si no tiene ninguno de los dos, lanza ValueError.
  • list_tools_request(id) -> la petición de descubrimiento de herramientas: un build_request con el método "tools/list" y params vacíos {}.

Como build_request devuelve una cadena, las pruebas la vuelven a analizar con json.loads y comparan el dict, así que el orden de las claves no importa. Asegúrate de que tanto un resultado como un error hagan el viaje de ida y vuelta, de que la petición de descubrimiento tenga el método correcto, y de que un mensaje sin jsonrpc o sin result ni error lance una excepción.

Tu turno

Construye y analiza mensajes JSON-RPC 2.0 al estilo de MCP con el módulo json. build_request(id, method, params) devuelve la cadena JSON de {"jsonrpc": "2.0", "id", "method", "params"}. parse_response(text) carga el texto, exige jsonrpc == "2.0" (si no, lanza ValueError) y devuelve {"id", "ok": True, "result"} para un resultado o {"id", "ok": False, "error": {"code", "message"}} para un error, y lanza una excepción si no tiene ninguno de los dos. list_tools_request(id) devuelve la petición de descubrimiento tools/list (enviada tras el saludo inicial) con parámetros vacíos.

¿Has visto un problema en esta lección? Avísanos · Preguntar sobre esta lección

Este ejercicio se abre pronto

Termina la lección anterior y esta se desbloquea. Todo el curso es gratis, no hace falta cuenta, y puedes leer esta lección ahora mismo.