Lleva la IA de Voz a tu Sistema Empresarial (MCP)

Descripción General

Esta guía demuestra cómo usar el Protocolo de Contexto de Modelo (MCP) para conectar la IA de Voz con tu ecosistema de software existente. Al envolver tus APIs REST como herramientas MCP, permites que SenseCAP Watcher interactúe directamente con tu lógica empresarial —ya sea un Sistema de Gestión de Almacén (WMS), CRM, ERP, o un panel de TI personalizado.

Interacción Espacial Inteligente

Paquete de Solución 🖱️

Interacción Espacial Inteligente

Voz a API: Transforma la Intención en Acción. No construyas una nueva aplicación desde cero. Simplemente expone tus endpoints WMS existentes al Watcher para habilitar control de voz inmediato para tu fuerza laboral.

Verdadera Productividad Manos Libres
Los operadores pueden consultar inventario o registrar envíos mientras usan guantes o conducen montacargas. Mantén los ojos en la tarea y las manos en el volante para máxima seguridad y eficiencia.
Sincronización de Datos de Latencia Cero
Elimina el retraso de los registros en papel. Los comandos de voz activan llamadas API directas a tu ERP, asegurando que los datos de inventario se sincronicen al instante que un artículo se mueve.
Interoperabilidad Universal de Sistemas
Ya sea que ejecutes SAP, Oracle, o un backend SQL personalizado, si tu sistema tiene una API, Watcher lo controla. No necesitas migrar sistemas heredados para adoptar IA.

Arquitectura

Entender el flujo de datos es esencial antes de escribir código. La integración sigue un patrón de puente donde el Servidor MCP actúa como una puerta de enlace segura entre la IA y tu red interna.

Componentes Clave:

Dispositivo Watcher: Captura la intención en lenguaje natural (ej., "Verificar inventario") y la envía a la nube.
Endpoint MCP (Nube): Un túnel seguro proporcionado por SenseCraft que reenvía la intención a tu entorno local.
Servidor MCP (Puente Local): Un script Python ligero ejecutándose en tu máquina. Traduce la intención de la IA en funciones de código específicas.
API Backend: Tu aplicación empresarial existente (FastAPI, Flask, etc.) que ejecuta la lógica real.
Infraestructura: Base de datos u otros servicios de los que depende tu backend.

Escenarios de Integración Universal:

Aunque esta guía usa un Sistema de Almacén como implementación de referencia, la arquitectura se aplica universalmente:

Industria	Comando de Voz	Acción del Sistema Subyacente
Logística	"Ingresar 50 unidades."	`POST /api/inventory/add`
Ventas (CRM)	"Actualizar estado del trato a Cerrado."	`PUT /api/deals/{id}/status`
Ops de TI	"Reiniciar el servidor de staging."	`POST /api/servers/restart`

Demo 1: Almacén Controlado por Voz

Simularemos un entorno empresarial ejecutando un Backend de Almacén simulado y un Puente MCP en tu máquina local. Esta demo habilita:

🗣️ Verificación de Inventario: "¿Cuántas unidades Xiaozhi Standard tenemos?"
🗣️ Entrada de Datos: "Ingresar 5 unidades de Watcher Xiaozhi."
🗣️ Información Empresarial: "¿Cuál es el resumen de inventario de hoy?"

Prerrequisitos

Hardware: SenseCAP Watcher, Computadora con soporte Docker
Software: Docker o Docker Desktop (incluye Docker Compose), Git
Cuenta: Cuenta de SenseCraft AI Platform

Configuración del Watcher

Asegúrate de que tu SenseCAP Watcher esté configurado con Xiaozhi AI a través del SenseCraft AI Device Center.

Paso 1: Desplegar el Sistema de Almacén

Usamos Docker para el despliegue para asegurar un entorno consistente en todas las plataformas (Windows, macOS, Linux).

1. Clonar el repositorio:

git clone https://github.com/suharvest/warehouse_system.git
cd warehouse_system

2. Iniciar con Docker Compose:

docker-compose -f docker-compose.prod.yml up -d

Este único comando:

Construye e inicia el servidor API backend (puerto 2124)
Construye e inicia la interfaz web frontend (puerto 2125)
Crea un volumen persistente para tu base de datos

3. Verificar el despliegue:

Espera unos 30 segundos para que los contenedores inicien, luego verifica:

docker-compose -f docker-compose.prod.yml ps

Deberías ver ambos contenedores warehouse-backend-prod y warehouse-frontend-prod ejecutándose.

UI Frontend: Abre http://localhost:2125 en tu navegador
Documentación API: Abre http://localhost:2124/docs para ver la UI de Swagger

Paso 2: Configuración Inicial del Sistema

El sistema de almacén incluye autenticación de usuario y gestión de claves API para seguridad. Necesitas configurar esto antes de conectar MCP.

1. Crear Cuenta de Administrador:

Abre http://localhost:2125 en tu navegador. En la primera visita, verás un formulario de registro:

Ingresa tu nombre de usuario deseado (ej., admin)
Ingresa una contraseña (ej., admin123)
Haz clic en Register

El Primer Usuario es Administrador

El primer usuario registrado automáticamente se convierte en administrador.

2. Iniciar Sesión y Navegar a Gestión de Usuarios:

Después del registro, inicia sesión con tus credenciales. Haz clic en la pestaña User Management en la navegación.

3. Crear una Clave API:

En la sección de Gestión de Usuarios, encuentra el área API Key Management:

Ingresa un nombre descriptivo para la clave (ej., MCP Bridge)
Haz clic en Create API Key
Importante: ¡Copia la clave API generada inmediatamente! Solo se mostrará una vez.

La clave API se ve como: wh_xxxxxxxxxxxxxxxxxxxx

Guarda tu Clave API

La clave API solo se muestra una vez cuando se crea. Guárdala de forma segura - la necesitarás en el siguiente paso.

Paso 3: Configurar Puente MCP

Ahora, conectamos el backend a la IA. El código del puente reside en el directorio mcp/.

Instalar uv

El puente MCP usa uv como su gestor de entorno Python. Instálalo con:

Linux/macOS
Windows (PowerShell)

curl -LsSf https://astral.sh/uv/install.sh | sh

irm https://astral.sh/uv/install.ps1 | iex

1. Obtener Endpoint MCP:

Obtén tu Dirección de Endpoint MCP (wss://...) desde la SenseCraft AI Platform -> Watcher Agent -> Configuration.

2. Configurar Clave API:

Abre una terminal y navega a la carpeta mcp:

cd mcp

# Copy the example config file
cp config.yml.example config.yml

Edita config.yml con tu clave API del Paso 2:

# Backend API address
api_base_url: "http://localhost:2124/api"

# API key (from User Management -> API Key Management)
api_key: "wh_your-api-key-here"

3. Iniciar el Puente MCP:

Linux/macOS
Windows (PowerShell)

# Set the MCP Endpoint (replace with your actual address)
export MCP_ENDPOINT="wss://your-endpoint-address"

# Start the Bridge
./start_mcp.sh

# Set the MCP Endpoint (replace with your actual address)
$env:MCP_ENDPOINT="wss://your-endpoint-address"

# Start the Bridge
./start_mcp.ps1

Si es exitoso, verás: MCP Service Started Successfully!

Paso 4: Verificación

Todo está conectado. Ahora, usa el SenseCAP Watcher para interactuar con tu sistema local.

¡Ahora podemos probar la integración usando tu dispositivo Watcher!

Comandos de Voz de Ejemplo

Comando de Voz	Acción Esperada
"Consultar el stock de Xiaozhi Versión Estándar"	Llama a la herramienta `query_xiaozhi_stock`
"¿Cuántos Xiaozhi Versión Profesional tenemos?"	Llama a `query_xiaozhi_stock` con versión profesional
"Ingresar 5 unidades de Watcher Xiaozhi Versión Estándar"	Llama a la herramienta `stock_in` con cantidad=5
"Sacar 3 unidades Xiaozhi para ventas"	Llama a la herramienta `stock_out` con cantidad=3
"¿Cuál es el resumen de inventario de hoy?"	Llama a la herramienta `get_today_statistics`
"Listar todos los productos Xiaozhi"	Llama a la herramienta `list_xiaozhi_products`

¿Qué sucede detrás de escena?

Componente	Acción
Watcher	Envía audio de voz a la nube.
Puente MCP	Recibe intención, determina que la herramienta es `query_stock`.
Sistema	Ejecuta `GET /materials/product-stats` con autenticación de clave API.
Resultado	Watcher habla: "El stock actual es de 150 unidades."

Respuestas Esperadas

Consultar Stock:

"La consulta de stock fue exitosa. Watcher Xiaozhi Versión Estándar actualmente tiene 150 unidades en stock en la ubicación A-01-01. El estado del stock es normal."

Ingreso de Stock:

"Se agregaron exitosamente 5 unidades de Watcher Xiaozhi Versión Estándar. La cantidad anterior era 150, la nueva cantidad es 155."

Personalización para Tu Sistema

La demostración del almacén es solo una plantilla. Para integrar tu propio Sistema de Gestión de Pedidos, CRM, o Panel de TI, sigue estos pasos para modificar el código del puente.

1. Apuntar a Tu Servidor Real

Abre mcp/warehouse_mcp.py. El primer paso es decirle al puente dónde vive tu API real.

# Change this line to point to your actual production server IP/Domain
# API_BASE_URL = "http://localhost:2124/api"
API_BASE_URL = "http://192.168.50.10:8080/api/v1"

O mejor, usa el archivo config.yml:

api_base_url: "http://192.168.50.10:8080/api/v1"
api_key: "your-production-api-key"

2. Definir Herramientas Personalizadas

Para agregar un nuevo comando de voz, no necesitas entrenar un modelo. Solo necesitas escribir una función de Python.

Usa el decorador @mcp.tool() para envolver tus llamadas API.

Flujo de trabajo:

Identificar Operaciones: ¿Qué acciones quieres controlar por voz? (ej., "Verificar Pedido", "Reiniciar Servidor").
Documentar API: Asegúrate de conocer la URL del endpoint y los parámetros (ej., GET /orders/{id}).
Escribir el Wrapper: Crea la función de Python usando el patrón de abajo.

Ejemplo: Adaptación para un Sistema de Gestión de Pedidos:

El "Docstring" es la Magia

La IA lee el docstring de Python (el texto dentro de """ ... """) para decidir cuándo llamar tu función. ¡Sé descriptivo!

@mcp.tool()
def check_order_status(order_id: str) -> dict:
    """
    Check the status of a customer order.
    Use this when the user asks about order tracking or delivery status.

    Args:
        order_id: The unique order identifier (e.g., "ORD-2024-001")

    Returns:
        Order status, estimated delivery date, and tracking information
    """
    # Call your real API
    return api_get(f"/orders/{order_id}/status")

Mejores Prácticas para Definir Herramientas Personalizadas

Escribir buenas herramientas MCP es diferente de escribir funciones estándar de Python. La IA depende mucho de la estructura de tu código para entender qué hacer.

1. Los Nombres Importan

Los nombres de herramientas y parámetros deben ser descriptivos. La IA lee estos para "adivinar" qué herramienta elegir.

# ✅ Good - Clear and descriptive
@mcp.tool()
def query_xiaozhi_stock(product_name: str) -> dict:
    ...

# ❌ Bad - Unclear abbreviations
@mcp.tool()
def qry_stk(pn: str) -> dict:
    ...

2. El Docstring es la Interfaz de Usuario

El docstring no es solo un comentario; es la Interfaz de Usuario para el modelo de IA. Guía a la IA sobre cuándo y cómo usar la herramienta.

@mcp.tool()
def stock_in(product_name: str, quantity: int) -> dict:
    """
    Record stock intake for watcher-xiaozhi products.
    Use this tool when the user wants to add inventory.  <-- Tells AI "When"

    Args:
        product_name: The exact product name             <-- Tells AI "How"
        quantity: Number of units (must be integer)
    """

3. Logger vs. Print (¡Crucial!)

Nunca uses print()

MCP usa entrada/salida estándar (stdio) para comunicación entre el puente y el agente de IA. Usar print() corromperá el flujo de datos del protocolo y causará que la conexión se rompa.

Siempre usa un logger para depuración:

import logging
logger = logging.getLogger(__name__)

# ✅ Good - Logs to file/stderr, safe for MCP
logger.info(f"Processing stock in: {product_name}")

# ❌ Bad - Breaks MCP communication
print(f"Processing stock in: {product_name}")

4. Optimizar Valores de Retorno

El valor de retorno es leído por la IA para generar una respuesta hablada. Manténlo conciso para reducir latencia y uso de tokens (típicamente bajo 1024 bytes).

# ✅ Good - Concise
return {
    "success": True,
    "quantity": 150,
    "message": "Stock query successful"
}

# ❌ Bad - Too verbose (AI doesn't need the full database history)
return {
    "success": True,
    "full_product_details": {...},
    "complete_history": [...]
}

5. Manejo de Errores

Tu API podría estar fuera de línea o devolver 404. Maneja estos casos con gracia para que la IA pueda explicar el problema al usuario en lugar de fallar.

try:
    result = api_post("/materials/stock-in", data)
    return result
except Exception as e:
    logger.error(f"Stock in failed: {str(e)}")
    return {
        "success": False,
        "error": str(e),
        "message": "Failed to record stock. Please try again."
    }

3. Desplegar para Producción

La demostración se ejecuta en tu terminal local. Para operación 24/7 a largo plazo:

Dockerizar: Empaqueta la carpeta mcp/ en un contenedor Docker para asegurar estabilidad del entorno.
Servicio en Segundo Plano: En lugar de ejecutar ./start_mcp.sh en una terminal abierta, usa systemd (Linux) o NSSM (Windows) para ejecutar el script como un servicio en segundo plano.
Red: Asegúrate de que la máquina que ejecuta el Puente MCP tenga acceso estable a internet para conectarse a SenseCraft Cloud (wss://...).

Solución de Problemas

❌ Contenedores Docker No Inician

Síntoma: docker-compose ps muestra contenedores en estado "Exited".
Solución:
1. Verifica que Docker Desktop esté ejecutándose
2. Ver logs: docker-compose -f docker-compose.prod.yml logs
3. Asegúrate de que los puertos 2124 y 2125 no estén en uso
4. Intenta reconstruir: docker-compose -f docker-compose.prod.yml up -d --build

❌ Clave API Inválida (401 No Autorizado)

Síntoma: Los logs del puente MCP muestran 401 Unauthorized o "Invalid API Key".
Solución:
1. Verifica que la clave API en mcp/config.yml sea correcta
2. Verifica que la clave API siga activa en User Management
3. Asegúrate de que no haya espacios extra o comillas alrededor de la clave
4. Intenta crear una nueva clave API

❌ Servicio Backend No Ejecutándose

Síntoma: La IA responde con "Cannot connect to backend service".
Solución:
1. Verifica que los contenedores Docker estén ejecutándose: docker-compose -f docker-compose.prod.yml ps
2. Verifica la salud del backend: curl http://localhost:2124/api/dashboard/stats
3. Verifica los logs del backend: docker-compose -f docker-compose.prod.yml logs backend

❌ Tiempo de Espera de Conexión MCP

Síntoma: El script se cuelga en "Connecting to WebSocket server..." indefinidamente.
Solución:
1. Verifica que tu MCP_ENDPOINT sea correcto (verifica errores tipográficos).
2. Asegúrate de que la URL comience con wss:// (WebSocket Seguro).
3. Verifica tu conexión a internet (tráfico saliente hacia SenseCraft Cloud).

❌ Herramienta No Reconocida

Síntoma: Hablas un comando, pero la IA dice "No sé cómo hacer eso" o no activa la herramienta.
Solución:
1. Verificar Nomenclatura: Usa nombres descriptivos claros en inglés para las funciones.
2. Verificar Docstrings: Asegúrate de que el docstring describa explícitamente la intención (ej., "Usar esto para verificar inventario").
3. Reiniciar: Debes reiniciar el script del servidor MCP después de cualquier cambio en el código.

❌ Límite de Conexión Excedido

Síntoma: El registro de errores muestra "Máximo de conexiones alcanzado".
Solución:
1. Cada Endpoint tiene un límite de conexión. Asegúrate de no tener múltiples terminales ejecutando el script simultáneamente.
2. Cierra otras conexiones y espera unos minutos antes de reintentar.

❌ Conexión Rechazada / WebSocket 443 Bloqueado

Síntoma: Ves [WinError 1225] Connection refused o el script se cuelga en Connecting to WebSocket server..., incluso con la URL del Endpoint correcta.

Causa: Firewall Corporativo Bloqueando. Muchas redes de oficina (o VPNs) bloquean estrictamente el tráfico WebSocket (wss://) o protocolos no estándar, incluso en el puerto 443.

Soluciones Rápidas:

📱 La "Prueba de Hotspot" (Recomendado) Desconéctate de la red de oficina/VPN y conecta tu computadora a un Hotspot Móvil (4G/5G).
- Si funciona: Tu red de oficina está bloqueando la conexión.
🔧 Configurar Proxy Si tu empresa requiere un proxy, configúralo antes de ejecutar:
- Windows: $env:HTTPS_PROXY="http://your-proxy:port"
- Mac/Linux: export HTTPS_PROXY="http://your-proxy:port"
🛡️ Lista Blanca Pide a IT que permita el tráfico WebSocket (WSS) para: *.seeed.cc.

Recursos

Guía de Configuración de MCP Endpoint - Aprende cómo crear y gestionar endpoints MCP.
Documentación de FastMCP - Profundiza en definiciones avanzadas de herramientas.

Descripción General​

Interacción Espacial Inteligente

Verdadera Productividad Manos Libres

Sincronización de Datos de Latencia Cero

Interoperabilidad Universal de Sistemas

Arquitectura​

Demo 1: Almacén Controlado por Voz​

Prerrequisitos​

Paso 1: Desplegar el Sistema de Almacén​

Paso 2: Configuración Inicial del Sistema​

Paso 3: Configurar Puente MCP​

Paso 4: Verificación​

Comandos de Voz de Ejemplo​

Respuestas Esperadas​

Personalización para Tu Sistema​

1. Apuntar a Tu Servidor Real​

2. Definir Herramientas Personalizadas​

1. Los Nombres Importan​

2. El Docstring es la Interfaz de Usuario​

3. Logger vs. Print (¡Crucial!)​

4. Optimizar Valores de Retorno​

5. Manejo de Errores​

3. Desplegar para Producción​

Solución de Problemas​

Recursos​

Soporte Técnico​