🏢 Company Database AI Manager

📖 Visión general

Company Database AI Manager es una interfaz de lenguaje natural para una base de datos corporativa. En lugar de escribir consultas SQL complejas para insertar, actualizar o recuperar datos, los usuarios pueden simplemente escribir comandos en lenguaje natural (por ejemplo, «Añade un departamento de TI y asigna 5 empleados a él»).

El sistema utiliza el Model Context Protocol (MCP) para conectar de forma segura un agente LangGraph impulsado por Groq a un servidor de base de datos Python local. La IA razona de manera autónoma sobre la consulta del usuario, selecciona las herramientas de base de datos correctas, ejecuta las operaciones SQL y devuelve el resultado en una interfaz web limpia de Streamlit.

Related MCP server: PySqlitMCP

⚙️ Arquitectura y cómo funciona

Este proyecto separa la lógica de la base de datos de la lógica de IA mediante una auténtica arquitectura servidor/cliente:

1. El servidor (server.py y models.py): Ejecuta un servidor FastMCP independiente que aloja herramientas de base de datos SQLite (setup_database, add_record, search_database).

2. El cliente (client.py y app.py): Ejecuta un agente LangGraph impulsado por llama-3.3-70b-versatile de Groq o openai/gpt-oss-120b.

3. El protocolo (MCP): El cliente se conecta al servidor de forma segura mediante la entrada/salida estándar (stdio). Solicita al servidor las herramientas disponibles, se las pasa al agente LangGraph y activa las funciones de Python sin importarlas directamente.

📂 Estructura de carpetas

📦 llm-db-mcp
 ┣ 📜 .env                # Stores secure API keys (Do NOT commit to GitHub)
 ┣ 📜 .gitignore          # Prevents sensitive files from being pushed to Git
 ┣ 📜 app.py              # The Streamlit web UI for interacting with the AI
 ┣ 📜 client.py           # The terminal-based LangGraph agent script
 ┣ 📜 company.db          # The automatically generated SQLite database file
 ┣ 📜 models.py           # SQLAlchemy schemas (Departments, Roles, Employees, Projects)
 ┣ 📜 requirements.txt    # Project dependencies and version numbers
 ┗ 📜 server.py           # The FastMCP server hosting the database tools

🚀 Configuración e instalación

1. Requisitos previos

Python 3.10 o superior.

Una clave de API de Groq gratuita.

2. Configuración del entorno

Crea y activa un entorno virtual (se recomienda Conda):

conda create -n db_mcp python=3.11
conda activate db_mcp

3. Instalación de dependencias

Instala todos los paquetes necesarios desde el archivo requirements.txt:

pip install -r requirements.txt

4. Configuración de claves de API

Crea un archivo .env en el directorio raíz y añade tu clave de API de Groq:

GROQ_API_KEY=gsk_your_api_key_here

🖥️ Uso

Opción 1: Ejecutar la interfaz web (recomendada)

Para iniciar la interfaz de chat interactiva, ejecuta:

streamlit run app.py

Opción 2: Ejecutar el cliente de terminal

Para ejecutar el agente estrictamente a través de la línea de comandos:

🛠️ Ejemplos de indicaciones para probar

Una vez que la aplicación esté en funcionamiento, prueba a escribir estas indicaciones en el chat:

"Configura las tablas de la base de datos." (¡Ejecuta esto primero!)

"Añade un departamento de TI."

"Añade un nuevo empleado llamado John Doe con un salario de 75000 en el departamento de TI."

"Muéstrame todos los empleados que ganan más de 50000."

🔒 Notas de seguridad

Nunca incluyas tu archivo .env ni tus claves de API en el control de versiones.

El archivo .gitignore está preconfigurado para evitar que .env y company.db se suban a GitHub.