Saltar al contenido principal

Referencia de herramientas MCP

MCP ofrece cinco herramientas: tool_list, tool_info, tool_call, skill_list y skill_read, para nombres de herramientas de negocio, definiciones, llamadas de negocio, catálogo de Skills y lectura de sus documentos. El directorio es una ayuda opcional. Consultas de negocio, cambios y acciones sobre dispositivos usan tool_call, con tool obligatorio. Llama directamente a operaciones conocidas; lee los Skills y sus referencias cuando sea necesario. args es un objeto opcional de parámetros de negocio.

HerramientaDescripciónEfecto
tool_listDevuelve nombres de herramientas de negocio, con filtro opcional por categoría.Solo lectura
tool_infoDevuelve descripciones, esquemas de parámetros y efectos de herramientas seleccionadas sin ejecutar operaciones.Solo lectura
tool_callInvoca una herramienta de negocio para consultar, modificar u operar dispositivos.Depende de la herramienta
skill_listDevuelve nombres y descripciones de Skills integrados con indicaciones de lectura y descarga.Solo lectura
skill_readLee el archivo principal o una referencia de un Skill, con paginación.Solo lectura

Ejemplos de llamadas​

  • tool_list({}): Devuelve version y la lista ordenada de nombres tools.
  • tool_list({category:"devices"}): Filtra los nombres de herramientas por category.
  • tool_info({tools:"backend_list_devices"}): Describe el uso de una herramienta sin ejecutarla.
  • tool_info({tools:["backend_list_devices","device_get_status"]}): Describe varias herramientas necesarias sin ejecutarlas. Devuelve un arreglo tools; cada elemento contiene el ID interno tool, description, inputSchema (para tool_call.args) y readOnly. tools acepta una cadena no vacía o un arreglo no vacío de cadenas, sin límite fijo de elementos por lote.
  • tool_call({tool:"backend_list_devices",args:{limit:10}}): Llama directamente a una herramienta conocida para leer la lista de dispositivos necesaria.
  • skill_list({}): Enumera los nombres, las descripciones y las sugerencias readCall de los Skills.
  • skill_read({skill:"xxtlancontrol"}): Lee directamente el Skill principal si conoces el nombre; path usa SKILL.md por defecto.
  • skill_read({skill:"xxtlancontrol",path:"references/tasks.md"}): Lee un flujo siguiendo un enlace relativo del Skill principal; cursor / maxBytes permiten paginar.

Las sugerencias de llamada de la aplicación readCall, infoCall y listCall usan {name,args}; name indica una herramienta MCP pública. Los ID de Skill se devuelven en skills[].skill en el catálogo y en data.skill en los resultados de lectura.

Cada entrada de skill_list ofrece downloadUrl, una URL completa del centro actual para descargar todo el Skill en ZIP. skill_read devuelve el texto del archivo seleccionado y también el enlace al paquete completo. El ZIP incluye el documento principal, referencias y los scripts, plantillas y recursos suministrados con el Skill. Para descargar basta con los metadatos del catálogo; usa directamente un enlace existente sin leer el texto ni volver a listar.

Si desconoces los nombres, consulta tool_list por categoría. Si desconoces los parámetros, obtén las definiciones necesarias juntas con tool_info y usa tool_call. Las herramientas conocidas se pueden llamar directamente, sin consultar antes el directorio ni las definiciones.

Cuando una operación por lotes devuelva un ID de tarea, consulta su estado y los elementos fallidos. Vuelve a conectar MCP después de actualizar el centro de control.

Ejecutar un comando de shell en el dispositivo​

En la configuración de MCP, activa Permitir la ejecución de comandos de shell en dispositivos y guarda para ejecutar comandos de shell en un dispositivo. La opción está desactivada de forma predeterminada. Al desactivarla y guardar, la herramienta se oculta en todas las sesiones MCP y se rechazan las nuevas llamadas.

command es una línea de comandos completa de hasta 16384 caracteres, ejecutada por la shell del dispositivo con -c. El resultado incluye el código de salida, stdout, stderr y una nota sobre las rutas cuando se usa una shell roothide.

El tiempo límite predeterminado es de 10 segundos. Para comandos largos, ajusta timeoutMs (por ejemplo, 300000 para 5 minutos) y el tiempo de espera del cliente MCP. El controlador renueva aux al inicio e intercambia señales de actividad con el dispositivo cada 30 segundos. Tras finalizar la última tarea, aux se cierra después de 180 segundos de inactividad.

{"tool":"device_run_shell_command","args":{"udid":"DEVICE_UDID","command":"df -h"}}