GigAPI Timeseries Lake

Un servidor MCP para GigAPI Timeseries Lake, que permite una integración perfecta con clientes compatibles con MCP.

Documentación

Servidor MCP de GigAPI

Un servidor MCP para GigAPI Timeseries Lake que proporciona una integración perfecta con Claude Desktop y otros clientes compatibles con MCP.

Características

Herramientas de GigAPI

run_select_query
- Ejecuta consultas SQL en tu clúster de GigAPI.
- Entrada: sql (string): La consulta SQL a ejecutar, database (string): La base de datos contra la que se ejecutará.
- Todas las consultas se ejecutan de forma segura a través de la API HTTP de GigAPI con formato NDJSON.
list_databases
- Lista todas las bases de datos de tu clúster de GigAPI.
- Entrada: database (string): La base de datos a usar para la consulta SHOW DATABASES (por defecto, "mydb").
list_tables
- Lista todas las tablas de una base de datos.
- Entrada: database (string): El nombre de la base de datos.
get_table_schema
- Obtiene la información de esquema de una tabla específica.
- Entrada: database (string): El nombre de la base de datos, table (string): El nombre de la tabla.
write_data
- Escribe datos usando el formato InfluxDB Line Protocol.
- Entrada: database (string): La base de datos a la que se escribirá, data (string): Datos en formato InfluxDB Line Protocol.
health_check
- Comprueba el estado de salud del servidor GigAPI.
ping
- Hace ping al servidor GigAPI para comprobar la conectividad.

Inicio rápido

1. Instalar el servidor MCP

Opción A: Desde PyPI (recomendado)

# The package will be available on PyPI after the first release
# Users can install it directly with uv
uv run --with mcp-gigapi --python 3.11 mcp-gigapi --help

Opción B: Desde el código fuente

# Clone the repository
git clone https://github.com/gigapi/mcp-gigapi.git
cd mcp-gigapi

# Install dependencies
uv sync

2. Configurar Claude Desktop

Abre el archivo de configuración de Claude Desktop ubicado en:
- En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- En Windows: %APPDATA%/Claude/claude_desktop_config.json
Añade la siguiente configuración:

Para la demo pública (recomendado para pruebas)

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "gigapi.fly.dev",
        "GIGAPI_PORT": "443",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

Para desarrollo local

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "localhost",
        "GIGAPI_PORT": "7971",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "false",
        "GIGAPI_DEFAULT_DATABASE": "mydb"
      }
    }
  }
}

Con autenticación

{
  "mcpServers": {
    "mcp-gigapi": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp-gigapi",
        "--python",
        "3.13",
        "mcp-gigapi"
      ],
      "env": {
        "GIGAPI_HOST": "your-gigapi-server",
        "GIGAPI_PORT": "7971",
        "GIGAPI_USERNAME": "your_username",
        "GIGAPI_PASSWORD": "your_password",
        "GIGAPI_TIMEOUT": "30",
        "GIGAPI_VERIFY_SSL": "true",
        "GIGAPI_DEFAULT_DATABASE": "your_database"
      }
    }
  }
}

Importante: Reemplaza el comando uv por la ruta absoluta a tu ejecutable de uv:
```
which uv  # Find the path
```
Reinicia Claude Desktop para aplicar los cambios.

Compatibilidad de API

Este servidor MCP está diseñado para funcionar con los endpoints de la API HTTP de GigAPI:

Endpoints de consulta

POST /query?db={database}&format=ndjson - Ejecuta consultas SQL con formato de respuesta NDJSON
Todas las consultas devuelven formato NDJSON (Newline Delimited JSON) para un streaming eficiente

Endpoints de escritura

POST /write?db={database} - Escribe datos usando InfluxDB Line Protocol

Endpoints administrativos

GET /health - Comprobación de salud
GET /ping - Ping simple

Ejemplo de uso

Escribir datos

Usa el formato InfluxDB Line Protocol:

curl -X POST "http://localhost:7971/write?db=mydb" --data-binary @/dev/stdin << EOF
weather,location=us-midwest,season=summer temperature=82
weather,location=us-east,season=summer temperature=80
weather,location=us-west,season=summer temperature=99
EOF

Leer datos

Ejecuta consultas SQL mediante POST JSON con formato NDJSON:

curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT time, temperature FROM weather WHERE time >= epoch_ns('\''2025-04-24T00:00:00'\''::TIMESTAMP)"}'

Mostrar bases de datos/tablas

# Show databases
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW DATABASES"}'

# Show tables  
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SHOW TABLES"}'

# Count records
curl -X POST "http://localhost:7971/query?db=mydb&format=ndjson" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT count(*), avg(temperature) FROM weather"}'

Variables de entorno

Variables requeridas

GIGAPI_HOST: El nombre de host de tu servidor GigAPI
GIGAPI_PORT: El número de puerto de tu servidor GigAPI (por defecto: 7971)

Variables opcionales

GIGAPI_USERNAME o GIGAPI_USER: El nombre de usuario para autenticación (si es necesario)
GIGAPI_PASSWORD o GIGAPI_PASS: La contraseña para autenticación (si es necesaria)
GIGAPI_TIMEOUT: Tiempo de espera de la solicitud en segundos (por defecto: 30)
GIGAPI_VERIFY_SSL: Habilita/deshabilita la verificación del certificado SSL (por defecto: true)
GIGAPI_DEFAULT_DATABASE: Base de datos por defecto para las consultas (por defecto: mydb)
GIGAPI_MCP_SERVER_TRANSPORT: Establece el método de transporte para el servidor MCP (por defecto: stdio)
GIGAPI_ENABLED: Habilita/deshabilita la funcionalidad de GigAPI (por defecto: true)

Configuraciones de ejemplo

Para desarrollo local

# Required variables
GIGAPI_HOST=localhost
GIGAPI_PORT=7971

# Optional: Override defaults for local development
GIGAPI_VERIFY_SSL=false
GIGAPI_TIMEOUT=60
GIGAPI_DEFAULT_DATABASE=mydb

Para producción con autenticación

# Required variables
GIGAPI_HOST=your-gigapi-server
GIGAPI_PORT=7971
GIGAPI_USERNAME=your_username
GIGAPI_PASSWORD=your_password

# Optional: Production settings
GIGAPI_VERIFY_SSL=true
GIGAPI_TIMEOUT=30
GIGAPI_DEFAULT_DATABASE=your_database

Para demo pública

GIGAPI_HOST=gigapi.fly.dev
GIGAPI_PORT=443
GIGAPI_VERIFY_SSL=true
GIGAPI_DEFAULT_DATABASE=mydb

Formato de datos

GigAPI utiliza particionamiento Hive con la estructura:

/data
  /mydb
    /weather
      /date=2025-04-10
        /hour=14
          *.parquet
          metadata.json

Desarrollo

Configurar el entorno de desarrollo

Instala las dependencias:

uv sync --all-extras --dev
source .venv/bin/activate

Crea un archivo .env en la raíz del repositorio:

GIGAPI_HOST=localhost
GIGAPI_PORT=7971
GIGAPI_USERNAME=your_username
GIGAPI_PASSWORD=your_password
GIGAPI_TIMEOUT=30
GIGAPI_VERIFY_SSL=false
GIGAPI_DEFAULT_DATABASE=mydb

Para probar con el MCP Inspector:
```
fastmcp dev mcp_gigapi/mcp_server.py
```

Ejecutar pruebas

# Run all tests
uv run pytest -v

# Run only unit tests
uv run pytest -v -m "not integration"

# Run only integration tests
uv run pytest -v -m "integration"

# Run linting
uv run ruff check .

# Test with public demo
python test_demo.py

Probar con la demo pública

El repositorio incluye un script de prueba que valida el servidor MCP contra la demo pública de GigAPI:

python test_demo.py

Esto probará:

✅ Comprobación de salud y conectividad
✅ Listado de bases de datos (SHOW DATABASES)
✅ Listado de tablas (SHOW TABLES)
✅ Consultas de datos (SELECT count(*) FROM table)
✅ Recuperación de datos de muestra

Publicación en PyPI

Este paquete se publica automáticamente en PyPI en cada release de GitHub. El proceso de publicación lo gestionan los workflows de GitHub Actions:

Workflow de CI (.github/workflows/ci.yml): Ejecuta pruebas en pull requests y en pushes a main
Workflow de publicación (.github/workflows/publish.yml): Publica en PyPI cuando se crea un release

Para usuarios

Una vez publicado, los usuarios pueden instalar el paquete directamente desde PyPI:

# Install and run the MCP server
uv run --with mcp-gigapi --python 3.11 mcp-gigapi

Para mantenedores

Para publicar una nueva versión:

Actualiza la versión en pyproject.toml
Crea un release de GitHub
El workflow publicará automáticamente en PyPI

Consulta RELEASING.md para obtener instrucciones detalladas sobre el release.

Solución de problemas

Problemas comunes

Conexión rechazada: Comprueba que GigAPI está en ejecución y que el host/puerto son correctos
Autenticación fallida: Verifica que el nombre de usuario y la contraseña sean correctos
Errores de certificado SSL: Establece GIGAPI_VERIFY_SSL=false para certificados autofirmados
No se encuentran bases de datos: Asegúrate de usar la base de datos por defecto correcta (normalmente "mydb")

Modo de depuración

Habilita el registro de depuración estableciendo el nivel de log:

import logging
logging.basicConfig(level=logging.DEBUG)

Licencia

Licencia Apache-2.0

Contribuciones

Haz un fork del repositorio
Crea una rama de funcionalidad
Realiza tus cambios
Añade pruebas
Envía un pull request

Soporte

Problemas: GitHub Issues
Documentación: Documentación de GigAPI