Cargando

Implementando un cliente

Lección 5310 min
Cargando

Ahora que tenemos nuestro servidor MCP funcionando, es hora de construir el lado del cliente. El cliente es lo que permite que nuestra aplicación se comunique con el servidor MCP y acceda a su funcionalidad.

Comprendiendo la Arquitectura del Cliente

Antes de sumergirnos en el código, aclaremos un punto importante sobre los proyectos MCP. Normalmente, implementarías un cliente MCP o un servidor MCP, no ambos. Estamos construyendo ambos en este proyecto solo para que puedas ver cómo funcionan juntos.

Diagrama de nuestro servidor que contiene el cliente MCP, el cual se conecta en ambas direcciones a un servidor MCP separado.

El cliente MCP consta de dos componentes principales que trabajan juntos:

Diagrama de mcp_client.py que contiene el MCP Client y la Client Session, la cual se conecta a un servidor MCP separado.

  • MCP Client - Una clase personalizada que creamos para facilitar el uso de la sesión
  • Client Session - La conexión real con el servidor (parte del SDK de Python de MCP)

La client session maneja la comunicación de bajo nivel, pero requiere una limpieza cuidadosa de recursos cuando tu programa se cierra. Por eso la envolvemos en nuestra propia clase, para gestionar esa limpieza automáticamente.

Cómo Encaja el Cliente en Nuestra Aplicación

¿Recuerdas nuestro diagrama de flujo de la aplicación? El cliente juega un papel crucial en dos momentos clave:

Diagrama de secuencia del flujo de la aplicación, destacando dónde nuestro código CLI usa el cliente para listar herramientas y para llamar a una herramienta.

Nuestro código CLI usa el cliente para:

  • Obtener una lista de herramientas disponibles para enviar a Claude
  • Ejecutar herramientas cuando Claude las solicita

Implementando las Funciones Principales del Cliente

Implementemos las dos funciones esenciales: list_tools y call_tool.

Para list_tools, necesitamos conectarnos a nuestra sesión y solicitar las herramientas disponibles:

python
async def list_tools(self) -> list[types.Tool]:
    result = await self.session().list_tools()
    return result.tools

Para call_tool, pasamos el nombre de la herramienta y los parámetros de entrada al servidor:

python
async def call_tool(
    self, tool_name: str, tool_input: dict
) -> types.CallToolResult | None:
    return await self.session().call_tool(tool_name, tool_input)

¡Eso es todo! La sesión maneja todos los detalles complejos de comunicación por nosotros.

Probando el Cliente

El archivo del cliente incluye un sencillo arnés de pruebas al final. Puedes ejecutarlo directamente para verificar que todo funciona:

bash
uv run mcp_client.py

Esto se conectará a tu servidor MCP e imprimirá las herramientas disponibles. Deberías ver una salida que muestra las definiciones de tus herramientas, incluyendo nombres, descripciones y esquemas de entrada.

Diferencias Importantes de Esquema

Aquí hay un detalle que debes conocer: las definiciones de herramientas MCP no coinciden exactamente con lo que Claude espera. La especificación MCP tiene su propio formato para los esquemas de herramientas, que es ligeramente diferente de lo que requiere Bedrock.

No te preocupes: ya hay código en el proyecto que maneja esta conversión automáticamente. La función to_bedrock_tools en core/bedrock.py traduce las definiciones de herramientas MCP al formato que Claude entiende.

Probando con Claude

Ahora que tanto el servidor como el cliente funcionan, puedes probar el flujo completo. Intenta ejecutar tu aplicación principal y pedirle a Claude que lea un documento:

bash
uv run main.py

Luego pregunta: "¿Cuál es el contenido del documento report.pdf?"

Claude:

  1. Recibirá la lista de herramientas disponibles de tu cliente
  2. Decidirá usar la herramienta read_doc_contents
  3. Tu cliente ejecutará esa herramienta en el servidor MCP
  4. Claude recibirá el contenido del documento y responderá

El cliente actúa como el puente entre el código de tu aplicación y el servidor MCP, facilitando la exposición de la funcionalidad del servidor a Claude y a otras partes de tu sistema.