MCP SQL Server - Sistema de Cotizaciones

Servidor MCP (Model Context Protocol) para integración con SQL Server que permite gestionar un sistema completo de cotizaciones, ventas y facturación.

Características

• 🏢 Gestión de Clientes: Registro y consulta de clientes con datos de facturación
• 📦 Catálogo de Artículos: Múltiples unidades y listas de precios por artículo
• 📋 Cotizaciones: Generación de cotizaciones con cálculo automático de impuestos
• 🔄 Progresión de Movimientos: Cotización → Venta → Factura
• 🔍 Búsquedas Avanzadas: Por clave, descripción, código de barras, RFC
• 🛡️ Seguridad: Conexión segura con SQL Server y validación de datos

Instalación

Prerrequisitos

• Node.js 18+
• SQL Server 2019+
• npm o yarn
• Claude Desktop (para integración MCP)

Pasos de Instalación

1. Clonar el repositorio

   cd "D:\PROYECTOS CON IA\MCP-SQL-SERVER"

2. Instalar dependencias

   npm install

3. Configurar variables de entorno

   cp .env.example .env
   # Editar .env con tus credenciales de SQL Server

4. Configurar base de datos

   npm run setup-db

5. Construir el proyecto

   npm run build

6. Configurar Claude Desktop (Opcional, para integración)

   # Copiar el archivo de configuración al directorio de Claude Desktop
   # Windows: %APPDATA%\Claude\claude_desktop_config.json
   # macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   # Linux: ~/.config/claude/claude_desktop_config.json

Configuración

Variables de Entorno (.env)

# SQL Server Configuration
DB_SERVER=
DB_DATABASE=CotizacionDB
DB_USER=sa
DB_PASSWORD=
DB_ENCRYPT=false

# MCP Server Configuration
MCP_SERVER_NAME=mcp-sql-server
MCP_SERVER_VERSION=1.0.0
PORT=3000

Uso

Iniciar el Servidor

# Desarrollo
npm run dev

# Producción
npm start

# Ejecutar como servidor MCP (para Claude Desktop)
npm run mcp

Integración con Claude Desktop

1. Configurar Claude Desktop

Copia el contenido del archivo claude_desktop_config.json a tu configuración de Claude Desktop:

Windows:

copy claude_desktop_config.json "%APPDATA%\Claude\claude_desktop_config.json"

macOS:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Linux:

cp claude_desktop_config.json ~/.config/claude/claude_desktop_config.json

2. Actualizar la configuración

Edita el archivo claude_desktop_config.json y actualiza las rutas y credenciales:

{
  "mcpServers": {
    "mcp-sql-server": {
      "command": "node",
      "args": ["D:\\PROYECTOS CON IA\\MCP-SQL-SERVER\\dist\\index.js"],
      "env": {
        "DB_SERVER": "TU_SERVIDOR\\INSTANCIA_SQL",
        "DB_DATABASE": "CotizacionDB",
        "DB_USER": "sa",
        "DB_PASSWORD": "TU_CONTRASEÑA",
        "DB_ENCRYPT": "false"
      }
    }
  }
}

3. Reiniciar Claude Desktop

Reinicia Claude Desktop para que cargue la nueva configuración del servidor MCP.

4. Verificar la conexión

En Claude Desktop, deberías ver las herramientas disponibles del MCP SQL Server:

• buscar_articulos
• obtener_articulo
• buscar_clientes
• crear_cliente
• crear_cotizacion
• autorizar_cotizacion
• facturar_venta
• buscar_movimientos

Herramientas MCP Disponibles

📦 Gestión de Artículos

buscar_articulos

{
  "criterio": "Laptop" // Búsqueda por clave, descripción, código de barras
}

obtener_articulo

{
  "id": 1 // ID del artículo
}

👥 Gestión de Clientes

buscar_clientes

{
  "criterio": "Empresa ABC" // Búsqueda por nombre, RFC o email
}

crear_cliente

{
  "nombre": "Nuevo Cliente SA",
  "rfc": "NEW123456XYZ",
  "telefono": "55-0000-0000",
  "email": "[email protected]",
  "direccion": "Av. Nueva #123",
  "ciudad": "Ciudad de México",
  "estado": "CDMX",
  "codigo_postal": "06000",
  "limite_credito": 50000,
  "dias_credito": 30
}

📋 Gestión de Cotizaciones y Ventas

crear_cotizacion

{
  "cliente_id": 1,
  "items": [
    {
      "articulo_id": 1,
      "unidad_id": 1,
      "cantidad": 2,
      "precio_unitario": 8999.00
    }
  ],
  "notas": "Cotización para proyecto especial"
}

autorizar_cotizacion

{
  "cotizacion_id": 1,
  "usuario_autorizo": "Juan Pérez"
}

facturar_venta

{
  "venta_id": 1,
  "usuario_autorizo": "María López"
}

buscar_movimientos

{
  "tipo_movimiento": "COTIZACION", // Opcional: COTIZACION, VENTA, FACTURA
  "cliente_id": 1 // Opcional
}

Flujo de Trabajo

1. Crear Cotización

# Buscar cliente
buscar_clientes { "criterio": "Empresa ABC" }

# Buscar artículos
buscar_articulos { "criterio": "Laptop" }

# Crear cotización
crear_cotizacion {
  "cliente_id": 1,
  "items": [
    {
      "articulo_id": 1,
      "unidad_id": 1,
      "cantidad": 2
    }
  ]
}

2. Autorizar Cotización (Convertir a Venta)

autorizar_cotizacion {
  "cotizacion_id": 1,
  "usuario_autorizo": "Vendedor"
}

3. Facturar Venta

facturar_venta {
  "venta_id": 1,
  "usuario_autorizo": "Contador"
}

Estructura de la Base de Datos

Tablas Principales

• Articulos: Catálogo de productos
• Unidades: Unidades de medida (PZA, CAJ, KG, etc.)
• ArticuloUnidades: Relación artículo-unidad con factores de conversión
• ListasPrecios: Diferentes listas de precios
• ArticuloPrecios: Precios por artículo y lista
• Clientes: Datos de clientes y facturación
• Ventas: Movimientos (cotización, venta, factura)
• VentaDetalles: Detalles de cada movimiento

API Response Format

Todas las respuestas siguen el formato:

{
  "success": true,
  "data": [...],
  "count": 10,
  "message": "Operación exitosa"
}

En caso de error:

{
  "success": false,
  "error": "Mensaje descriptivo del error"
}

Desarrollo

Scripts Disponibles

npm run dev        # Modo desarrollo
npm run build      # Compilar TypeScript
npm start          # Producción
npm test           # Ejecutar tests
npm run setup-db   # Configurar base de datos

Estructura del Proyecto

src/
├── config/          # Configuración de base de datos
├── models/          # Tipos de datos
├── services/        # Lógica de negocio
├── handlers/        # Handlers MCP
├── utils/           # Utilidades (logger)
└── index.ts         # Punto de entrada

scripts/             # Scripts SQL de base de datos
tests/               # Tests unitarios

Troubleshooting

Problemas Comunes

Error de conexión a SQL Server

• Verificar que el servicio de SQL Server esté corriendo
• Confirmar credenciales en .env
• Verificar firewall y puertos

Error de compilación TypeScript

• Ejecutar npm install para instalar dependencias
• Verificar versión de Node.js (18+)

Base de datos no existe

• Ejecutar npm run setup-db
• Verificar permisos de usuario en SQL Server

Demostración con Claude Desktop

Flujo Completo de Demostración

1. Búsqueda de Clientes

Por favor, busca clientes con el criterio "Empresa ABC"

2. Búsqueda de Artículos

Busca artículos con la palabra "Laptop"

3. Crear Cotización

Crea una cotización para el cliente ID 1 con los siguientes artículos:
- 2 unidades del artículo ID 1 (Laptop Pro)
- 5 unidades del artículo ID 2 (Mouse Inalámbrico)

4. Autorizar Cotización

Autoriza la cotización ID 1 con el usuario "Vendedor Demo"

5. Facturar Venta

Factura la venta ID 1 con el usuario "Contador Demo"

6. Consultar Movimientos

Busca todos los movimientos del cliente ID 1

Ejemplos de Comandos para Claude Desktop

Gestión de Clientes:

• "Crea un nuevo cliente llamado 'Tech Solutions SA' con RFC 'TECH123456XYZ'"
• "Busca clientes por el nombre 'Tech'"
• "Encuentra clientes con RFC que contenga 'XYZ'"

Gestión de Artículos:

• "Busca artículos con la palabra 'laptop'"
• "Muestra el artículo con ID 5"
• "Encuentra productos por código de barras '1234567890'"

Gestión de Ventas:

• "Crea una cotización para el cliente 3 con 2 laptops"
• "Convierte la cotización 5 a venta"
• "Factura la venta 10"

Contribución

1. Fork del proyecto
2. Crear feature branch
3. Commit de cambios
4. Push al branch
5. Crear Pull Request

Licencia

MIT License - Ver archivo LICENSE para detalles