Arnaud-Chafai/Agent-Database-Reader

graph TB
    subgraph "Cliente LLM                                    "
        A[Claude Desktop] 
        B[GPT-4]
        C[Otros LLMs]
    end
    
    subgraph "SQL LLM Agent                                                                      "
        D[Servidor MCP<br/>main.py] 
        E[Procesador de Consultas<br/>database.py]
        F[Contexto de Negocio<br/>glosario.json]
        G[Modelos de Datos<br/>models.py]
        H[Validador de Seguridad]
    end
    
    subgraph "Base de Datos                                  "
        I[(SQL Server)]
        J[(Azure SQL)]
        K[(SQL Express)]
    end
    
    subgraph "Herramientas MCP                                                    "
        L[ejecutar_consulta_sql]
        M[obtener_esquema_bd]
        N[probar_conexion]
        O[obtener_info_tabla]
    end
    
    A --> D
    B --> D
    C --> D
    
    D --> L
    D --> M
    D --> N
    D --> O
    
    L --> E
    M --> E
    N --> E
    O --> E
    
    E --> F
    E --> H
    E --> G
    
    E --> I
    E --> J
    E --> K
    
    style A fill:#ffffff,stroke:#333,stroke-width:2px,color:#000000
    style B fill:#ffffff,stroke:#333,stroke-width:2px,color:#000000
    style C fill:#ffffff,stroke:#333,stroke-width:2px,color:#000000
    style D fill:#e1f5fe,stroke:#333,stroke-width:2px,color:#000000
    style E fill:#f3e5f5,stroke:#333,stroke-width:2px,color:#000000
    style F fill:#fff3e0,stroke:#333,stroke-width:2px,color:#000000
    style G fill:#f1f8e9,stroke:#333,stroke-width:2px,color:#000000
    style H fill:#ffebee,stroke:#333,stroke-width:2px,color:#000000
    style I fill:#e3f2fd,stroke:#333,stroke-width:2px,color:#000000
    style J fill:#e3f2fd,stroke:#333,stroke-width:2px,color:#000000
    style K fill:#e3f2fd,stroke:#333,stroke-width:2px,color:#000000
    style L fill:#e8f5e8,stroke:#333,stroke-width:2px,color:#000000
    style M fill:#e8f5e8,stroke:#333,stroke-width:2px,color:#000000
    style N fill:#e8f5e8,stroke:#333,stroke-width:2px,color:#000000
    style O fill:#e8f5e8,stroke:#333,stroke-width:2px,color:#000000

git clone https://github.com/Arnaud-Chafai/Agent-Database-Reader.git
cd Agent-Database-Reader
cp .env.example .env
# Configurar .env con tu base de datos
docker-compose up -d

DB_SERVER=TU_SERVIDOR\INSTANCIA_SQL
DB_DATABASE=tu_base_datos
DB_USERNAME=tu_usuario
DB_PASSWORD=tu_contraseña
DB_DRIVER=ODBC Driver 17 for SQL Server

-- Explorar esquema
SELECT TABLE_NAME, COLUMN_NAME, DATA_TYPE 
FROM INFORMATION_SCHEMA.COLUMNS 
WHERE TABLE_CATALOG = 'tu_base_datos'

-- Análisis de datos
SELECT TOP 10 * FROM tu_tabla 
ORDER BY tu_columna_fecha DESC

-- Conteos y agregaciones
SELECT 
    columna_categoria,
    COUNT(*) as total,
    AVG(columna_numerica) as promedio
FROM tu_tabla
GROUP BY columna_categoria

-- Top productos por ventas
SELECT TOP 10 
    p.Name as Producto,
    COUNT(*) as Ventas
FROM Products p
JOIN OrderDetails od ON p.ProductId = od.ProductId
GROUP BY p.Name
ORDER BY Ventas DESC

{
  "conceptos_negocio": {
    "tu_dominio": {
      "descripcion": "Descripción de tu área de negocio",
      "tabla_principal": "tu_tabla_principal", 
      "metricas_clave": ["campo1", "campo2", "campo3"]
    }
  },
  "sinonimos": {
    "ventas": ["orders", "transactions", "sales"],
    "clientes": ["users", "customers", "clients"]
  }
}

# Construcción
build-docker.bat  # Windows
# o
docker build -t sql-llm-agent .

# Ejecución
docker-compose up -d

# Monitoreo
docker logs -f sql-llm-agent-mcp

{
  "mcpServers": {
    "sql-agent": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.sql_llm_agent.mcp_server.main"],
      "cwd": "/ruta/a/sql-llm-agent"
    }
  }
}

# Verificar conexión a tu base de datos
uv run python -c "from src.sql_llm_agent.mcp_server.database import DatabaseManager; print(DatabaseManager().test_connection())"

# Listar drivers ODBC disponibles
odbcinst -q -d

# Cambiar puerto si está ocupado
# En .env: MCP_PORT=8001

# Instalación local
pip install uv
uv sync

# Ejecutar servidor en desarrollo
uv run python -m src.sql_llm_agent.mcp_server.main

# Tests
uv run pytest

# Formateo de código
uv run black src/