Saltar al contenido principal

Endpoint MCP

Descripción general​

Agradecimientos especiales a XiaoZhi AI Chatbot por sus contribuciones de código abierto que hicieron posible este proyecto.

MCP (Model Context Protocol) es un potente framework que amplía las capacidades de la IA al permitir control remoto, cómputo, operaciones de correo electrónico, búsquedas de conocimiento y más.

MCP permite que los servidores expongan herramientas invocables a los modelos de lenguaje mediante un protocolo bien definido. Estas herramientas permiten que el modelo interactúe con sistemas externos, como consultar bases de datos, invocar APIs o realizar cálculos complejos. Cada herramienta se identifica de forma única por un nombre y se describe mediante metadatos que definen su funcionalidad.

El Endpoint MCP sirve como puente entre tu servicio MCP local y el modelo Xiaozhi AI. Proporciona una interfaz para que los dispositivos con voz y otros terminales aprovechen estas capacidades externas sin interrupciones.

Obtener Endpoint MCP​

  1. Accede al panel de control de Watcher Agent a través de SenseCraft AI > Models > Workspace > SenseCAP Watcher > Watcher Agent, o utiliza el enlace directo al espacio de trabajo y luego haz clic en Watcher Agent en la barra lateral izquierda.
  1. Abre la configuración del agente
  1. Haz clic en MCP Setting y Get MCP Endpoint
  1. Obtén la dirección del Endpoint y el estado de la conexión

Ejemplo de MCP​

Agradecimientos especiales a XiaoZhi AI Chatbot por sus contribuciones de código abierto que hicieron posible este proyecto.

Puedes obtener el siguiente código desde MCP Example Code Github

Ejemplo de código de servidor MCP​

  # server.py
  from mcp.server.fastmcp import FastMCP
  import logging
  logger = logging.getLogger('test_mcp')

  import math
  import random

  # Create an MCP server
  mcp = FastMCP("Calculator")

  # Add an addition tool
  @mcp.tool()
  def calculator(python_expression: str) -> dict:
      """For mathamatical calculation, always use this tool to calculate the result of a python expression. `math` and `random` are available."""
      result = eval(python_expression)
      logger.info(f"Calculating formula: {python_expression}, result: {result}")
      return {"success": True, "result": result}

  # Start the server
  if __name__ == "__main__":
      mcp.run(transport="stdio")

Explicación del código​

A continuación se muestra una explicación detallada de algunas partes clave del ejemplo de servidor MCP:

  • @mcp.tool() : Registra la siguiente función como una herramienta MCP que puede ser llamada de forma remota por el modelo de IA.

  • def calculator(python_expression: str) -> dict: Define una herramienta que recibe una expresión matemática del modelo.

  • result = eval(python_expression) : Usa la función eval() de Python para evaluar la expresión. Se pueden usar bibliotecas como math y random porque se importaron anteriormente.

  • mcp.run(transport="stdio") : Inicia el servidor. El transporte stdio le permite comunicarse con Watcher Agent o con tu cliente MCP.

Inicio rápido​

  • Requisitos

    • MCP Example Code Github
    • Python 3.7+
    • websockets>=11.0.3
    • python-dotenv>=1.0.0
    • mcp>=1.8.1
    • pydantic>=2.11.4
    • mcp-proxy>=0.8.2

  • Paso 1. Clona el repositorio y navega a la carpeta del proyecto

    git clone https://github.com/78/mcp-calculator.git
    cd mcp-calculator

  • Paso 2. Instala las dependencias

    pip install -r requirements.txt

  • Paso 3. Configura las variables de entorno

    • Para Linux/macOS 
      export MCP_ENDPOINT=<your_mcp_endpoint>
    • Para Windows (PowerShell) 
      $env:MCP_ENDPOINT="<your_mcp_endpoint>"
    • Para Windows (CMD) 
      set MCP_ENDPOINT=<your_mcp_endpoint>

  • Paso 4. Ejecuta el ejemplo de calculadora

    python mcp_pipe.py calculator.py

  • O ejecuta todos los servidores configurados

    python mcp_pipe.py
    nota

    Esto requiere un archivo de configuración mcp_config.json que defina los ajustes del servidor.

Resultado de la ejecución​

export MCP_ENDPOINT=<mcp_endpoint_address_get_from_your_agent_configuration>
python mcp_pipe.py calculator.py
2025-05-16 09:07:09,009 - MCP_PIPE - INFO - Connecting to WebSocket server...
2025-05-16 09:07:09,096 - MCP_PIPE - INFO - Successfully connected to WebSocket server
2025-05-16 09:07:09,097 - MCP_PIPE - INFO - Started test.py process
Processing request of type ListToolsRequest
Processing request of type CallToolRequest
Calculating formula: 3.14159 * (8 / 2) ** 2, result: 50.26544
Processing request of type CallToolRequest
Calculating formula: math.comb(10, 3), result: 120

Estado del Endpoint MCP​

  • Estado de la conexión: Muestra si tu conexión MCP está funcionando correctamente.
  • Icono de actualización: Actualiza el estado de tu conexión MCP.
  • Servicios habilitados: Enumera todos los servicios MCP que tu Watcher puede usar.
  • Dirección del Endpoint: Tu mcp_endpoint_address (no lo compartas con nadie a menos que sea requerido por el soporte técnico oficial)

Registro de conversación​

Precauciones​

1. Nombres de herramientas y parámetros en MCP​

Los nombres de las herramientas y de sus parámetros deben ser claros para que el modelo grande entienda su propósito. Evita usar abreviaturas siempre que sea posible y proporciona un comentario que explique la función de la herramienta y cuándo debe utilizarse.

Por ejemplo, una herramienta llamada calculator permite al modelo saber que es una calculadora, y el parámetro python_expression indica que el modelo debe introducir una expresión de Python.

Si estás escribiendo una herramienta bing_search, el nombre del parámetro debe ser keywords.

2. Guía mediante docstring de la función​

El docstring (usando """...""") guía al modelo sobre cuándo usar la herramienta.

También puede mencionar que en la expresión se pueden usar funciones de las bibliotecas math y random.

Estas dos bibliotecas ya se han importado en el código de ejemplo.

3. Registro en lugar de impresión​

Dado que la entrada/salida estándar en este ejemplo de servidor MCP se utiliza para la transmisión de datos, no puedes usar print para mostrar información.

Utiliza logger para depuración y registro en su lugar.

4. Valores de retorno​

Los valores de retorno de MCP suelen ser una cadena o JSON. En el ejemplo, el resultado del cálculo se devuelve en un campo JSON llamado result.

La longitud de los valores de retorno suele estar limitada, similar a los comandos de dispositivos IoT, normalmente dentro de 1024 bytes.

5. Límite de la lista de herramientas​

La lista de herramientas MCP tiene un límite máximo.

Más adelante se mostrará en la página de configuración, calculado en función del recuento de tokens.

Nota: Tener demasiadas herramientas puede afectar la eficiencia de programación del dispositivo.

6. Límite de conexiones​

Cada endpoint MCP tiene un número máximo de conexiones simultáneas.

Nota: Superar este límite o tener demasiadas conexiones simultáneas puede reducir el rendimiento del dispositivo.

Seleccionar servicios MCP preproporcionados​

Los siguientes cuatro servicios MCP están disponibles para que los elijas en MCP Setting mencionado anteriormente.

Después de guardar la configuración y reiniciar el dispositivo, los servicios seleccionados se activarán automáticamente.

Puedes eliminar el servicio haciendo clic en ×

Soporte técnico​

Loading Comments...