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

Descripción general

Esta guía muestra cómo utilizar el Protocolo de Contexto de Modelo (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

De voz a API: transforma la intención en acción. No construyas una nueva aplicación desde cero. Simplemente expón tus endpoints WMS existentes al Watcher para habilitar 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 disparan 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, "Comprobar existencias") 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 dependa 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	"Ingresar 50 unidades en stock."	`POST /api/inventory/add`
Ventas (CRM)	"Actualizar el estado de la oportunidad a Cerrado."	`PUT /api/deals/{id}/status`
Operaciones de TI	"Reinicia 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 demostración permite:

🗣️ Consulta de inventario: "¿Cuántas unidades Xiaozhi Standard tenemos?"
🗣️ Entrada de datos: "Ingresa en stock 5 unidades de Watcher Xiaozhi."
🗣️ Información de negocio: "¿Cuál es el resumen de inventario de hoy?"

Requisitos previos

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

Configuración de Watcher

Asegúrate de que tu SenseCAP Watcher esté configurado con Xiaozhi AI mediante el Centro de Dispositivos SenseCraft AI.

Paso 1: Desplegar el sistema de almacén

Utilizamos Docker para el despliegue a 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 para 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 usuario y gestión de claves API por motivos de 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 ve a la gestión de usuarios:

Después del registro, inicia sesión con tus credenciales. Haz clic en la pestaña User Management en la barra de 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 de inmediato! Solo se mostrará una vez.

La clave API tiene este formato: 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 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 dirección de endpoint MCP (wss://...) desde la plataforma SenseCraft AI -> Watcher Agent -> Configuration.

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 hicimos 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 tiene éxito, verás: MCP 服务启动成功！ (MCP Service Started Successfully)

Paso 4: Verificación

Todo está conectado. Ahora, utiliza el 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
"Query the stock of Xiaozhi Standard Version"	Llama a la herramienta `query_stock`
"How many Xiaozhi Professional Version do we have?"	Llama a `query_stock` con la versión profesional
"Stock in 5 units of Watcher Xiaozhi Standard Version"	Llama a la herramienta `stock_in` con quantity=5
"Stock out 3 Xiaozhi units for sales"	Llama a la herramienta `stock_out` con quantity=3
"What's today's inventory summary?"	Llama a la herramienta `get_today_statistics`
"List all Xiaozhi products"	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 y determina que la herramienta es `query_stock`.
Sistema	Ejecuta `GET /materials/product-stats` con autenticación por clave de API.
Resultado	Watcher dice: "Current stock is 150 units."

Respuestas esperadas

Consulta de stock:

"The stock query was successful. Watcher Xiaozhi Standard Version currently has 150 units in stock at location A-01-01. Stock status is normal."

Entrada de stock:

"Successfully added 5 units of Watcher Xiaozhi Standard Version. Previous quantity was 150, new quantity is 155."

Personalizar para tu sistema

La demostración del almacén es solo un punto de partida. El MCP bridge utiliza una arquitectura de plugins de proveedor — no necesitas modificar ningún código existente. En su lugar, creas un nuevo proveedor 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 proveedor personalizado — Un nuevo archivo .py en providers/ que adapta los 6 métodos al API de tu sistema.

1. Crear un proveedor 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 proveedor se mantiene mínimo.

Auto-Discovery

Simplemente deja el archivo .py en mcp/providers/. El bridge detecta 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, primero crea config.yml a partir de la plantilla:

cd mcp
cp config.yml.example config.yml

Luego cambia a tu proveedor 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 mediante 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 proveedor.

Mejores prácticas para el desarrollo de proveedores

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. Desplegar para producción

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

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, utiliza 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 esté en ejecución
2. Revisa los logs: 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 de MCP bridge 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 User Management
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 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 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: Dices un comando, pero la IA dice "I don't know how to do that" o no activa la herramienta.
Solución:
1. Comprueba el nombre: Utiliza nombres de funciones claros y descriptivos en inglés.
2. Comprueba 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 reintentar.

❌ 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: Firewall 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 zona Wi‑Fi" (recomendada) Desconéctate de la red de la oficina/VPN y conecta tu computadora a una zona Wi‑Fi 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​

Personalizar para tu sistema​

Cómo funciona​

1. Crear un proveedor personalizado​

2. Configurar mediante config.yml​

Formato del valor de retorno​

Manejo de errores​

Registro (logging)​

3. Desplegar para producción​

Solución de problemas​

Recursos​

Soporte técnico​