MCP Data Agent

Un servidor real del Model Context Protocol (MCP) que expone herramientas de analista de datos sobre una base de datos de ventas, además de un agente LLM (Gemini) que descubre esas herramientas en tiempo de ejecución y decide cuál llamar para responder a una pregunta — el verdadero propósito de MCP es que las definiciones de las herramientas residen en el servidor, no codificadas de forma fija en el agente.

Por qué esto es una implementación real de MCP, no un simulacro

• src/mcp_server.py es un servidor MCP genuino, construido sobre el SDK oficial de Python mcp, que expone 4 herramientas (list_tables, run_sql_query, get_column_stats, plot_bar_chart) a través del transporte estándar stdio.

• src/smoke_test_client.py es una prueba a nivel de protocolo sin ningún LLM involucrado — lanza el servidor como un subproceso real, se conecta a través de stdio, llama a list_tools() y llama a run_sql_query mediante el protocolo de red real de MCP. Esto es lo que demuestra que el servidor funciona, independientemente de si el agente que está encima funciona.

• src/mcp_client_agent.py es el agente: lista las herramientas del servidor, convierte sus esquemas JSON directamente en declaraciones de funciones de Gemini (parameters_json_schema=tool.input_schema — sin traducción manual de esquemas), y ejecuta el bucle estándar de llamada a herramientas: preguntar al modelo → ejecutar cualquier llamada a herramienta solicitada a través de la sesión MCP real → devolver el resultado → repetir hasta que el modelo dé una respuesta final.

Related MCP server: agente-ecommerce-mcp-memoria

Requiere Python 3.10+

El paquete mcp no es compatible con Python 3.9. Si tu python predeterminado es más antiguo, usa py -3.12 (o el intérprete 3.10+ que tengas) para todos los comandos siguientes.

Pipeline

pip install -r requirements.txt
python src/generate_data.py          # -> data/sales.db (3,000 synthetic orders)
python src/smoke_test_client.py      # protocol-only sanity check, no LLM
python src/mcp_client_agent.py "Which category has the highest revenue?"

Sin GEMINI_API_KEY configurada, mcp_client_agent.py ejecuta un respaldo manual: lista las herramientas descubiertas desde el servidor en vivo y llama a una directamente, de modo que la infraestructura de MCP se puede demostrar sin ninguna clave API. Con una clave (copia .env.example a .env), ejecuta el bucle completo del agente.

Pruebas

tests/test_pipeline.py llama directamente a las funciones de herramienta del servidor (introspección de esquemas, rechazo de sentencias SQL que no sean SELECT, estadísticas) y — la prueba real de que esta es una implementación MCP funcional — ejecuta smoke_test_client.py, que lanza el servidor como un subproceso real y se comunica con él a través del protocolo stdio real. No se necesita clave API, por lo que esto se ejecuta en CI en cada push, en Python 3.12.

pip install -r requirements.txt pytest
pytest tests/ -v

Herramientas expuestas por el servidor

Verificado vs. no verificado de forma independiente

• Verificado: el servidor MCP y el cableado del protocolo (descubrimiento de herramientas, ejecución de herramientas a través de stdio) — smoke_test_client.py lo ejecuta de principio a fin sin ningún LLM en el bucle, y la ruta de respaldo manual en mcp_client_agent.py ejercita el mismo protocolo real.

• Implementado contra el SDK actual google-genai, no ejecutado contra una clave real en este entorno: el propio bucle de llamada a herramientas de Gemini. Los tipos de declaración de función y respuesta de función se comprobaron directamente contra el SDK instalado, pero la llamada real de varios turnos requiere una clave API que este entorno no tiene. Ejecútalo con tu propia GEMINI_API_KEY para ejercitar esa ruta.

Estructura del proyecto

data/     generated sales.db
src/      mcp_server, smoke_test_client, mcp_client_agent, generate_data
reports/  charts saved by plot_bar_chart

Stack

Python 3.12 · mcp (SDK oficial del Model Context Protocol) · google-genai · SQLite · matplotlib

Licencia

MIT — consulta LICENSE.