GigAPI Timeseries Lake

Um servidor MCP para GigAPI Timeseries Lake, permitindo integração perfeita com clientes compatíveis com MCP.

Documentação

Servidor MCP GigAPI

Um servidor MCP para GigAPI Timeseries Lake que fornece integração perfeita com Claude Desktop e outros clientes compatíveis com MCP.

Recursos

Ferramentas GigAPI

run_select_query
- Execute consultas SQL no seu cluster GigAPI.
- Entrada: sql (string): A consulta SQL a ser executada, database (string): O banco de dados no qual executar.
- Todas as consultas são executadas com segurança através da API HTTP do GigAPI com formato NDJSON.
list_databases
- Liste todos os bancos de dados no seu cluster GigAPI.
- Entrada: database (string): O banco de dados a ser usado para a consulta SHOW DATABASES (padrão: "mydb").
list_tables
- Liste todas as tabelas em um banco de dados.
- Entrada: database (string): O nome do banco de dados.
get_table_schema
- Obtenha informações de esquema para uma tabela específica.
- Entrada: database (string): O nome do banco de dados, table (string): O nome da tabela.
write_data
- Escreva dados usando o formato InfluxDB Line Protocol.
- Entrada: database (string): O banco de dados para escrita, data (string): Dados no formato InfluxDB Line Protocol.
health_check
- Verifique o status de saúde do servidor GigAPI.
ping
- Envie um ping ao servidor GigAPI para verificar a conectividade.

Início Rápido

1. Instale o Servidor MCP

Opção A: Do 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

Opção B: Do Código-Fonte

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

# Install dependencies
uv sync

2. Configure o Claude Desktop

Abra o arquivo de configuração do Claude Desktop localizado em:
- No macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- No Windows: %APPDATA%/Claude/claude_desktop_config.json
Adicione a seguinte configuração:

Para a Demonstração Pública (Recomendado para Testes)

{
  "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 Desenvolvimento 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"
      }
    }
  }
}

Com Autenticação

{
  "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: Substitua o comando uv pelo caminho absoluto do seu executável uv:
```
which uv  # Find the path
```
Reinicie o Claude Desktop para aplicar as alterações.

Compatibilidade de API

Este servidor MCP foi projetado para funcionar com os endpoints da API HTTP do GigAPI:

Endpoints de Consulta

POST /query?db={database}&format=ndjson - Execute consultas SQL com formato de resposta NDJSON
Todas as consultas retornam no formato NDJSON (Newline Delimited JSON) para streaming eficiente

Endpoints de Escrita

POST /write?db={database} - Escreva dados usando InfluxDB Line Protocol

Endpoints Administrativos

GET /health - Verificação de saúde
GET /ping - Ping simples

Exemplo de Uso

Escrevendo Dados

Use o 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

Lendo Dados

Execute consultas SQL via JSON POST com 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 Bancos de Dados/Tabelas

# 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"}'

Variáveis de Ambiente

Variáveis Obrigatórias

GIGAPI_HOST: O hostname do seu servidor GigAPI
GIGAPI_PORT: O número da porta do seu servidor GigAPI (padrão: 7971)

Variáveis Opcionais

GIGAPI_USERNAME ou GIGAPI_USER: O nome de usuário para autenticação (se necessário)
GIGAPI_PASSWORD ou GIGAPI_PASS: A senha para autenticação (se necessário)
GIGAPI_TIMEOUT: Tempo limite de solicitação em segundos (padrão: 30)
GIGAPI_VERIFY_SSL: Ativar/desativar verificação de certificado SSL (padrão: true)
GIGAPI_DEFAULT_DATABASE: Banco de dados padrão para consultas (padrão: mydb)
GIGAPI_MCP_SERVER_TRANSPORT: Define o método de transporte para o servidor MCP (padrão: stdio)
GIGAPI_ENABLED: Ativar/desativar funcionalidade GigAPI (padrão: true)

Exemplos de Configuração

Para Desenvolvimento 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 Produção com Autenticação

# 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 Demonstração Pública

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

Formato de Dados

O GigAPI usa particionamento Hive com a estrutura:

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

Desenvolvimento

Configurar Ambiente de Desenvolvimento

Instale as dependências:

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

Crie um arquivo .env na raiz do repositório:

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 testar com o MCP Inspector:
```
fastmcp dev mcp_gigapi/mcp_server.py
```

Executando Testes

# 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

Testando com a Demonstração Pública

O repositório inclui um script de teste que valida o servidor MCP contra a demonstração pública do GigAPI:

python test_demo.py

Isso testará:

✅ Verificação de saúde e conectividade
✅ Listagem de bancos de dados (SHOW DATABASES)
✅ Listagem de tabelas (SHOW TABLES)
✅ Consultas de dados (SELECT count(*) FROM table)
✅ Recuperação de dados de exemplo

Publicação no PyPI

Este pacote é publicado automaticamente no PyPI a cada release do GitHub. O processo de publicação é gerenciado pelos workflows do GitHub Actions:

Workflow de CI (.github/workflows/ci.yml): Executa testes em pull requests e pushes para a main
Workflow de Publicação (.github/workflows/publish.yml): Publica no PyPI quando uma release é criada

Para Usuários

Uma vez publicado, os usuários podem instalar o pacote diretamente do PyPI:

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

Para Mantenedores

Para publicar uma nova versão:

Atualize a versão em pyproject.toml
Crie uma release no GitHub
O workflow publicará automaticamente no PyPI

Consulte RELEASING.md para instruções detalhadas de release.

Solução de Problemas

Problemas Comuns

Conexão recusada: Verifique se o GigAPI está em execução e se o host/porta estão corretos
Falha na autenticação: Verifique se o nome de usuário e a senha estão corretos
Erros de certificado SSL: Defina GIGAPI_VERIFY_SSL=false para certificados autoassinados
Nenhum banco de dados encontrado: Certifique-se de estar usando o banco de dados padrão correto (geralmente "mydb")

Modo de Depuração

Ative o registro de depuração definindo o nível de log:

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

Licença

Licença Apache-2.0

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações
Adicione testes
Envie um pull request

Suporte

Problemas: GitHub Issues
Documentação: Documentação GigAPI