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:

Related MCP server: ROS2 MCP Server

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:

. 
├── .venv/                # Virtual environment directory
├── src/
│   └── gs_openapi/
│       ├── __init__.py
│       ├── api/            # Modules for direct API interactions
│       │   ├── __init__.py
│       │   ├── maps.py
│       │   └── robots.py
│       ├── auth/           # Authentication related modules
│       │   ├── __init__.py
│       │   └── token_manager.py # Handles OAuth token lifecycle
│       ├── config.py       # Configuration (URLs, Env Vars)
│       └── mcp/            # MCP server specific implementations
│           ├── __init__.py
│           └── gausium_mcp.py # GausiumMCP class extending FastMCP
├── .gitignore
├── docs/
│   └── images/            # Documentation images
├── main.py               # Main application entry point, tool registration, server run
├── README.md             # This file
└── requirements.txt      # Project dependencies

• 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: