TL;DR / Resumen
- Instala dependencias:
pip install -r requirements.txt - Crea
.envconGEMINI_API_KEY=TU_CLAVE_API_AQUI. - Ejecuta:
python mcp_gemini_client.py weather_tool_server.py
Proyecto Cliente MCP con Gemini y Servidor de Herramientas Meteorológicas
Este repositorio demuestra cómo usar el protocolo MCP (Model-Client-Protocol) para conectar un cliente de IA (usando Google Gemini) con un servidor que proporciona herramientas especializadas (en este caso, herramientas meteorológicas).
Cómo Funciona
El sistema actúa como un puente entre la IA de Gemini y las herramientas especializadas. Aquí está el flujo explicado de forma sencilla:
Roles de los Componentes
mcp_gemini_client.py- Este es el "intermediario" que:
* Habla con la IA de Gemini. * Se conecta al servidor de herramientas (weather_tool_server.py). * Maneja las entradas del usuario y muestra las respuestas.
weather_tool_server.py- Este es el "proveedor de herramientas" que:
* Ofrece herramientas específicas relacionadas con el clima (get_alerts, get_forecast). * Procesa las solicitudes de herramientas y devuelve los resultados.
- MCP (Model-Client-Protocol) - Este es el "sistema de comunicación" que:
* Proporciona formas estandarizadas para que los clientes descubran y llamen a las herramientas. * Maneja la mensajería entre clientes y servidores.
Flujo al Preguntar por el Clima
- Entrada del Usuario: Escribes una pregunta como "¿Cuál es el clima en Nueva York?" en el cliente.
- Procesamiento del Cliente:
* mcp_gemini_client.py envía esta pregunta a la IA de Gemini. * También le dice a Gemini qué herramientas están disponibles consultando al servidor weather_tool_server.py.
- Decisión de la IA de Gemini:
* Gemini reconoce que necesita usar una herramienta meteorológica (por ejemplo, get_forecast). * Formatea una respuesta indicando qué herramienta usar y con qué argumentos (por ejemplo, latitud y longitud para Nueva York).
- Ejecución de la Herramienta:
* El cliente analiza la solicitud de Gemini para usar la herramienta. * Envía la solicitud de herramienta al servidor weather_tool_server.py. * El servidor ejecuta la consulta meteorológica y devuelve los resultados.
- Respuesta Final:
* Los resultados de la herramienta regresan al cliente, que luego los envía de vuelta a Gemini. * Gemini formatea estos resultados en una respuesta fácil de entender para el usuario. * El cliente muestra esta respuesta final.
Configuración y Ejecución
- Instalar Dependencias:
pip install google-generativeai python-dotenv mcp-protocols # Asegúrate de que mcp-protocols sea el paquete correcto- Clave API:
* Obtén una clave API de Google AI Studio. * Crea un archivo .env en la raíz del proyecto. * Añade tu clave al archivo .env:
GEMINI_API_KEY=TU_CLAVE_API_AQUI- Ejecutar:
* Asegúrate de que mcp_gemini_client.py y weather_tool_server.py estén en el mismo directorio. * Ejecuta el cliente, diciéndole dónde encontrar el script del servidor:
python mcp_gemini_client.py weather_tool_server.py* Escribe tus consultas en la terminal cuando se te solicite.
Archivo de Log (mcp_log.txt)
- Consolidado y Detallado: Este archivo ahora contiene logs combinados tanto del cliente (
mcp_gemini_client.py) como del servidor (weather_tool_server.py). - Visibilidad del Flujo: Los logs son intencionalmente detallados para mostrar el flujo de datos completo:
* Mensajes enviados/recibidos de la API de Gemini (incluyendo los prompts). * Solicitudes/respuestas de herramientas enviadas/recibidas a través del protocolo MCP entre el cliente y el servidor.
- Identificación: Cada entrada de log incluye el nombre del módulo (
mcp_gemini_clientoweather_tool_server) para que puedas identificar qué componente generó el mensaje. - Depuración: Es la fuente principal para depurar problemas y entender las interacciones entre todos los componentes.
Flujo de Logs de Ejemplo (mcp_log.txt)
Aquí hay un ejemplo simplificado de cómo se ven los logs de una interacción completa, mostrando las comunicaciones clave:
- Cliente envía el prompt inicial a Gemini (con descripción de herramientas):
2025-04-21 12:31:54,519 - __main__ - INFO - === Prompt Sent to Gemini (Initial) ===
You are an assistant that helps users with weather information.
You have access to the following tools:
...
Tool: get_forecast
Description: Get weather forecast for a location...
Schema: {...}
...
When you need to use a tool, format your response like this:
TOOL_NAME: {the tool name}
TOOL_ARGS: {JSON formatted arguments for the tool}
...
The user message is: cual es el tiempo en nyc ?
======================================- Gemini responde solicitando una herramienta:
2025-04-21 12:31:56,049 - __main__ - INFO - === Raw Response Received from Gemini (Initial) ===
TOOL_NAME: get_forecast
TOOL_ARGS: {"latitude": 40.7128, "longitude": -74.0060}
===============================================- Cliente analiza la respuesta y envía la solicitud de herramienta MCP al servidor:
2025-04-21 12:31:56,050 - __main__ - INFO - Executing MCP tool: get_forecast with args: {'latitude': 40.7128, 'longitude': -74.006}- Servidor recibe la solicitud de herramienta MCP:
2025-04-21 12:31:56,052 - INFO - mcp.server.lowlevel.server - Processing request of type CallToolRequest
2025-04-21 12:31:56,052 - INFO - __main__ - MCP Request Received: get_forecast with latitude: 40.7128, longitude: -74.006- Servidor ejecuta la herramienta y envía la respuesta MCP al cliente:
2025-04-21 12:31:57,180 - INFO - __main__ - === MCP Response Sent (get_forecast) ===
Today:
Temperature: 56F
...
Forecast: Cloudy. High near 56...
---...
=======================================- Cliente recibe la respuesta de la herramienta MCP:
2025-04-21 12:31:57,182 - __main__ - INFO - Raw MCP Tool Result Object Received: meta=None content=[TextContent(type='text', text='\n Today:\n...)] isError=False
2025-04-21 12:31:57,182 - __main__ - INFO - MCP tool get_forecast executed. Extracted Result Content: [TextContent(type='text', text='\n Today:\n...)]...- Cliente envía el prompt final a Gemini (con resultado de la herramienta):
2025-04-21 12:31:57,182 - __main__ - INFO - === Prompt Sent to Gemini (Final) ===
I asked for information about the weather in response to: "cual es el tiempo en nyc ?"
I used the get_forecast tool with these arguments: {"latitude": 40.7128, "longitude": -74.006}
The tool returned this result: [TextContent(type='text', text='\n Today:\n...')]
Please provide a helpful, user-friendly response based on this information.
=======================================- Gemini responde con la respuesta final formateada para el usuario:
2025-04-21 12:31:59,000 - __main__ - INFO - === Raw Response Received from Gemini (Final) ===
The weather in NYC looks like this:
**Today:** Cloudy with a high of 56F...
...
===============================================