GS Robot MCP Server

Servidor MCP Gausium OpenAPI

Este proyecto implementa un servidor MCP (Protocolo de Control de Modelos) que actúa como un puente hacia Gausium OpenAPI, permitiendo que los modelos de IA u otros clientes interactúen con los robots Gausium a través de una interfaz estandarizada.

Repositorio: https://github.com/cfrs2005/mcp-gs-robot

Arquitectura

El servidor sigue una arquitectura en capas que separa las preocupaciones y promueve la facilidad de mantenimiento:

Flujo del protocolo MCP

El siguiente diagrama muestra cómo los modelos de IA interactúan con los robots Gausium a través del protocolo MCP:

Características

Actualmente, el servidor admite las siguientes funcionalidades como herramientas MCP:

• list_robots : Lista los robots accesibles mediante la clave API. (Basado en: API de List Robots )
• get_robot_status : Obtiene el estado detallado de un robot específico mediante su número de serie. (Basado en la API Get Robot Status )
• list_robot_task_reports : Obtiene informes de tareas de limpieza de un robot específico, con filtro de tiempo opcional. (Basado en la API de informes de tareas de List Robot )
• list_robot_maps : Enumera los mapas asociados a un robot específico. (Basado en la API List Robot Maps )

Estructura del proyecto

El proyecto sigue un diseño estructurado basado en las mejores prácticas de Python:

• src/gs_openapi/config.py : contiene URL base, rutas de API y nombres de variables de entorno.
• src/gs_openapi/auth/token_manager.py : administra la adquisición y actualización de tokens OAuth.
• src/gs_openapi/api/ : Contiene módulos ( robots.py , maps.py ) con funciones que llaman directamente a los puntos finales de Gausium OpenAPI mediante httpx .
• src/gs_openapi/mcp/gausium_mcp.py : define la clase GausiumMCP que integra las llamadas API y la gestión de tokens.
• main.py : inicializa GausiumMCP , registra las funcionalidades de API como herramientas MCP usando @mcp.tool() , configura el registro básico e inicia el servidor usando mcp.run() .

Configuración y ejecución

1. Clonar el repositorio:
   git clone https://github.com/cfrs2005/mcp-gs-robot.git cd mcp-gs-robot
2. Crear y activar un entorno virtual usando uv :
   uv venv source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
3. Instalar dependencias usando uv :
   uv pip install -r requirements.txt # Or, if you prefer adding specific core packages: # uv add httpx "mcp[cli]"
4. Configurar credenciales: la aplicación espera que las credenciales de la API de Gausium se configuren como variables de entorno:
   • GS_CLIENT_ID : Su ID de cliente de la aplicación Gausium.
   • GS_CLIENT_SECRET : Su secreto de cliente de la aplicación Gausium.
   • GS_OPEN_ACCESS_KEY : Su clave de acceso a Gausium OpenAPI.

   Puedes configurarlos directamente en tu shell:

   export GS_CLIENT_ID="your_client_id" export GS_CLIENT_SECRET="your_client_secret" export GS_OPEN_ACCESS_KEY="your_access_key"

   (Alternativamente, modifique src/gs_openapi/config.py para el desarrollo, pero no confirme las credenciales ).

5. Ejecutar el servidor:
   python main.py
   De forma predeterminada, esto inicia el servidor usando el transporte SSE en http://0.0.0.0:8000 . Puede modificar main.py para usar el transporte stdio si es necesario.

Conexión de un cliente MCP

Una vez que el servidor está en funcionamiento, un cliente MCP (como Cursor u otra herramienta compatible) puede conectarse a él a través del transporte apropiado (SSE o stdio) para utilizar las herramientas definidas.

Uso con cursor

A continuación se muestra un ejemplo de cómo Cursor interactúa con este servidor MCP:

Depuración

Puede supervisar los registros del servidor para obtener información de depuración. La configuración básica de registro en main.py proporciona marcas de tiempo, niveles e información de origen.

A continuación se muestra un ejemplo de la salida del registro del servidor durante el funcionamiento: