Lleva la IA de voz a tu sistema empresarial (MCP)

Descripción general

Esta guía muestra cómo usar el Model Context Protocol (MCP) para conectar la IA de voz con tu ecosistema de software existente. Al envolver tus API REST como herramientas MCP, permites que SenseCAP Watcher interactúe directamente con tu lógica de negocio, ya sea un Sistema de Gestión de Almacenes (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 crees una nueva aplicación desde cero. Simplemente expón tus endpoints WMS existentes al Watcher para habilitar el control por voz inmediato para tu personal.

Productividad realmente manos libres
Los operarios pueden consultar existencias o registrar envíos mientras llevan guantes o conducen carretillas elevadoras. Mantén la vista en la tarea y las manos en el volante para lograr la máxima seguridad y eficiencia.
Sincronización de datos sin latencia
Elimina el retraso de los registros en papel. Los comandos de voz desencadenan llamadas API directas a tu ERP, garantizando que los datos de inventario se sincronicen en el instante en que un artículo se mueve.
Interoperabilidad universal de sistemas
Tanto si utilizas SAP, Oracle o un backend SQL personalizado, si tu sistema tiene una API, Watcher lo controla. No es necesario migrar sistemas heredados para adoptar IA.

Arquitectura

Comprender 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 (por ejemplo, "Check stock") 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 ligero de Python que se ejecuta en tu máquina. Traduce la intención de la IA en funciones de código específicas.
API de 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 utiliza un Sistema de almacén como implementación de referencia, la arquitectura se aplica de forma universal:

Industria	Comando de voz	Acción subyacente del sistema
Logística	"Stock in 50 units."	`POST /api/inventory/add`
Ventas (CRM)	"Update deal status to Closed."	`PUT /api/deals/{id}/status`
Operaciones de TI	"Restart the staging server."	`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 demostración permite:

🗣️ Consulta de inventario: "How many Xiaozhi Standard units do we have?"
🗣️ Entrada de datos: "Stock in 5 units of Watcher Xiaozhi."
🗣️ Información de negocio: "What's today's inventory summary?"

Requisitos previos

Hardware: SenseCAP Watcher, ordenador con compatibilidad con Docker
Software: Docker o Docker Desktop (incluye Docker Compose), Git
Cuenta: cuenta de la plataforma SenseCraft AI

Configuración de Watcher

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

Paso 1: Desplegar el sistema de almacén

Usamos Docker para el despliegue con el fin de garantizar un entorno coherente 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 hará lo siguiente:

Compilar y arrancar el servidor de la aplicación de almacén (puerto 2125)
Crear un volumen persistente para tu base de datos

3. Verificar el despliegue:

Espera unos 30 segundos a que el contenedor se inicie y luego comprueba:

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

Deberías ver el contenedor warehouse-prod en ejecución.

Interfaz web: Abre http://localhost:2125 en tu navegador
Documentación de la API: Abre http://localhost:2125/docs para ver la interfaz Swagger

Paso 2: Configuración inicial del sistema

El sistema de almacén incluye autenticación de usuarios y gestión de claves API para mayor seguridad. Debes configurarlo 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:

Introduce el nombre de usuario que desees (por ejemplo, admin)
Introduce una contraseña (por ejemplo, admin123)
Haz clic en Register

El primer usuario es administrador

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

2. Inicia sesión y navega 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, busca el área de API Key Management:

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

La clave API tiene este aspecto: 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 el puente MCP

Ahora conectamos el backend con la IA. El código del puente se encuentra en el directorio mcp/.

Instalar uv

El puente MCP utiliza uv como su gestor de entornos de 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 el endpoint MCP:

Obtén tu MCP Endpoint Address (wss://...) accediendo al panel de control de Watcher Agent a través de SenseCraft AI > Models > Workspace > SenseCAP Watcher > Watcher Agent > Configuration (o usa el enlace directo al espacio de trabajo y luego haz clic en Watcher Agent en la barra lateral izquierda).

2. Configurar la clave de 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 de API del Paso 2:

precaución

El api_base_url predeterminado en config.yml.example es http://localhost:2124/api (el puerto de desarrollo local). Como realizamos el despliegue con docker-compose.prod.yml, que usa el puerto 2125, debes actualizarlo en consecuencia.

# Backend API address (change from default 2124 to 2125 for Docker deployment)
api_base_url: "http://localhost:2125/api"

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

3. Iniciar el MCP Bridge:

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 todo va bien, verás: MCP 服务启动成功！ (Servicio MCP iniciado correctamente)

Paso 4: Verificación

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

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

Ejemplos de comandos de voz

Comando de voz	Acción esperada
"Consulta el stock de Xiaozhi Versión Estándar"	Llama a la herramienta `query_stock`
"¿Cuántas Xiaozhi Versión Profesional tenemos?"	Llama a `query_stock` con la versión profesional
"Entrada en stock de 5 unidades de Watcher Xiaozhi Versión Estándar"	Llama a la herramienta `stock_in` con quantity=5
"Salida de stock de 3 unidades de Xiaozhi para ventas"	Llama a la herramienta `stock_out` con quantity=3
"¿Cuál es el resumen de inventario de hoy?"	Llama a la herramienta `get_today_statistics`
"Lista todos los productos Xiaozhi"	Llama a la herramienta `search` con entity_type="material"

¿Qué ocurre entre bastidores?

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

Respuestas esperadas

Consulta de stock:

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

Entrada de stock:

"Se añadieron correctamente 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 demo de almacén es solo un punto de partida. El MCP bridge utiliza una arquitectura de plugins de Provider: no necesitas modificar ningún código existente. En su lugar, creas un nuevo Provider para adaptar el bridge a tu propio sistema backend.

Cómo funciona

El bridge tiene una clara separación de responsabilidades:

warehouse_mcp.py — Define 6 herramientas MCP fijas (query_stock, stock_in, stock_out, search, resolve_name, get_today_statistics). No necesitas modificar este archivo.
providers/base.py — Clase base abstracta que define la interfaz (6 métodos).
providers/default.py — Implementación predeterminada para el backend de almacén de la demo.
Tu provider personalizado — Un nuevo archivo .py en providers/ que adapta los 6 métodos al API de tu sistema.

1. Crear un Provider personalizado

Crea un nuevo archivo mcp/providers/my_erp.py:

from .base import BaseProvider

class MyERPProvider(BaseProvider):
    """Adapter for My ERP System."""

    PROVIDER_NAME = "my_erp"

    def query_stock(self, product_name, show_batches=False):
        # Call your ERP's inventory API
        return self.http_get(f"/inventory/query", params={"sku": product_name})

    def stock_in(self, product_name, quantity, reason, operator, fuzzy,
                 location=None, contact_id=None, variant=None):
        return self.http_post("/inventory/receive", {
            "sku": product_name, "qty": quantity, "note": reason
        })

    def stock_out(self, product_name, quantity, reason, operator, fuzzy,
                  variant=None):
        return self.http_post("/inventory/ship", {
            "sku": product_name, "qty": quantity, "note": reason
        })

    def search(self, query, entity_type, category, status, contact_type,
               fuzzy, include_batches=False, max_results=0):
        return self.http_get("/search", params={"q": query, "type": entity_type})

    def resolve_name(self, text, entity_type="all"):
        return self.http_get("/fuzzy-match", params={"q": text})

    def get_today_statistics(self):
        return self.http_get("/dashboard/today")

La clase base (BaseProvider) proporciona los helpers integrados http_get() y http_post() con inyección automática de cabeceras de autenticación y manejo de errores, de modo que el código de tu provider se mantiene mínimo.

Auto-Discovery

Simplemente coloca el archivo .py en mcp/providers/. El bridge descubre y registra automáticamente todas las subclases de BaseProvider, sin necesidad de registro manual.

2. Configurar mediante `config.yml`

Si aún no lo has hecho, crea primero config.yml a partir de la plantilla:

cd mcp
cp config.yml.example config.yml

Luego cambia a tu provider y apunta a tu servidor real — no se requieren cambios de código:

# Switch to your custom provider
provider: "my_erp"

# Your production API address
api_base_url: "http://192.168.50.10:8080/api/v1"

# Authentication (supports api_key, bearer, basic)
auth:
  type: api_key
  key: "your-production-api-key"

También puedes sobrescribir la configuración usando variables de entorno: WAREHOUSE_API_URL, WAREHOUSE_API_KEY y WAREHOUSE_PROVIDER.

Métodos de autenticación compatibles

La clase base admite varios tipos de autenticación de forma nativa a través de config.yml:

# API Key (default)
auth:
  type: api_key
  header: X-API-Key    # optional, defaults to X-API-Key
  key: "your-key"

# Bearer Token
auth:
  type: bearer
  token: "your-bearer-token"

# Basic Auth
auth:
  type: basic
  username: "admin"
  password: "secret"

Para autenticación personalizada (por ejemplo, firma HMAC), sobrescribe el método get_auth_headers() en tu provider.

Mejores prácticas para el desarrollo de Providers

Formato del valor de retorno

El valor de retorno es leído por la IA para generar una respuesta hablada. Mantenlo conciso (normalmente por debajo de 1024 bytes).

# Good — concise
return {
    "success": True,
    "quantity": 150,
    "message": "Stock query successful"
}

# Bad — too verbose
return {
    "success": True,
    "full_product_details": {...},
    "complete_history": [...]
}

Manejo de errores

Las funciones http_get() / http_post() de la clase base ya manejan errores de conexión y códigos de estado HTTP. Para errores adicionales de lógica de negocio, devuelve un diccionario de error estructurado:

return {
    "success": False,
    "error": "Product not found",
    "message": "No matching product in the ERP system."
}

Registro (Logging)

Nunca uses print()

MCP utiliza la entrada/salida estándar (stdio) para la comunicación. Usar print() corromperá el flujo de datos del protocolo. Utiliza siempre un logger:

import logging
logger = logging.getLogger("WarehouseMCP")
logger.info(f"Querying stock for: {product_name}")

3. Despliegue para producción

La demo se ejecuta en tu terminal local. Para una operación continua 24/7:

Dockerizar: Empaqueta la carpeta mcp/ en un contenedor Docker para garantizar la 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 MCP Bridge tenga acceso estable a Internet para conectarse a SenseCraft Cloud (wss://...).

Solución de problemas

❌ Los contenedores de Docker no se inician

Síntoma: docker-compose ps muestra los contenedores en estado "Exited".
Solución:
1. Comprueba que Docker Desktop se esté ejecutando
2. Revisa los registros: docker-compose -f docker-compose.prod.yml logs
3. Asegúrate de que el puerto 2125 no esté en uso
4. Intenta reconstruir: docker-compose -f docker-compose.prod.yml up -d --build

❌ Clave de API no válida (401 Unauthorized)

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

❌ Servicio backend no se está ejecutando

Síntoma: La IA responde con "Cannot connect to backend service".
Solución:
1. Comprueba que el contenedor se esté ejecutando: docker-compose -f docker-compose.prod.yml ps
2. Verifica el estado de salud del backend: curl http://localhost:2125/api/dashboard/stats
3. Revisa los registros: docker-compose -f docker-compose.prod.yml logs

❌ Tiempo de espera de conexión MCP agotado

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

❌ Herramienta no reconocida

Síntoma: Das un comando por voz, pero la IA dice "I don't know how to do that" o no activa la herramienta.
Solución:
1. Revisa los nombres: Usa nombres de funciones claros y descriptivos en inglés.
2. Revisa los docstrings: Asegúrate de que el docstring describa explícitamente la intención (por ejemplo, "Use this to check stock").
3. Reinicia: Debes reiniciar el script del servidor MCP después de cualquier cambio de código.

❌ Límite de conexión excedido

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

❌ Conexión rechazada / WebSocket 443 bloqueado

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

Causa: Cortafuegos corporativo bloqueando. Muchas redes de oficina (o VPN) bloquean estrictamente el tráfico de WebSocket (wss://) o protocolos no estándar, incluso en el puerto 443.

Soluciones rápidas:

📱 La "Prueba de hotspot" (recomendada) Desconéctate de la red de la 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 al departamento de TI que permita el tráfico de WebSocket (WSS) para: *.seeed.cc.

Recursos

Guía de configuración de Endpoint MCP - Aprende cómo crear y gestionar endpoints MCP.
Repositorio del sistema de almacén - Código fuente completo, incluidos ejemplos de Provider.
Documentación de FastMCP - Profundiza en definiciones avanzadas de herramientas.

Descripción general​

Interacción espacial inteligente

Productividad realmente manos libres

Sincronización de datos sin latencia

Interoperabilidad universal de sistemas

Arquitectura​

Demo 1: Almacén controlado por voz​

Requisitos previos​

Paso 1: Desplegar el sistema de almacén​

Paso 2: Configuración inicial del sistema​

Paso 3: Configurar el puente MCP​

Paso 4: Verificación​

Ejemplos de comandos de voz​

Respuestas esperadas​

Personalización para tu sistema​

Cómo funciona​

1. Crear un Provider personalizado​

2. Configurar mediante config.yml​

Formato del valor de retorno​

Manejo de errores​

Registro (Logging)​

3. Despliegue para producción​

Solución de problemas​

Recursos​

Soporte técnico​