geolens-mcp

geolens-mcp

Servidor Model Context Protocol somente leitura, licenciado sob Apache-2.0, para GeoLens.

Aponte um agente de codificação (Claude Code, Cursor, Codex, …) para uma instância do GeoLens para que ele possa descobrir conjuntos de dados, inspecionar esquemas, ler feições e mapas e executar SQL somente leitura dentro de uma sessão de desenvolvimento.

Somente leitura por design. Sem gravações, ingestão ou administração. As ferramentas de descoberta são GETs contra endpoints de API existentes; query é um POST mecanicamente, mas é executado dentro do sandbox SQL READ ONLY do servidor, portanto não pode modificar nada. As chamadas são limitadas ao acesso do chamador: com uma chave de API, o agente vê os conjuntos de dados que o usuário daquela chave pode ver; sem credencial, ele vê apenas dados públicos/publicados (query adicionalmente exige uma credencial cujo usuário tenha a permissão de chat de IA — chaves de API read_only funcionam, por meio de uma exceção específica da rota no lado do servidor).

Instalação

pip install geolens-mcp        # or: uvx geolens-mcp

Configuração

O servidor lê a instância de destino e as credenciais do ambiente (mesmos nomes da CLI geolens):

Variável	Obrigatória	Significado
GEOLENS_INSTANCE	sim	URL da instância, ex.: https://geolens.example.com. O sufixo /api é acrescentado automaticamente se você o omitir.
GEOLENS_API_KEY	recomendada	Chave de API, enviada como X-Api-Key. Crie uma em Configurações → Chaves de API. Omita para acesso somente público.
GEOLENS_TOKEN	—	Token de portador JWT, usado somente se GEOLENS_API_KEY não estiver definido.

Registrar em um cliente MCP

Claude Code:

claude mcp add geolens -e GEOLENS_INSTANCE=https://geolens.example.com -e GEOLENS_API_KEY=... -- uvx geolens-mcp

Cursor / Codex / qualquer cliente que leia um bloco mcpServers:

{
  "mcpServers": {
    "geolens": {
      "command": "uvx",
      "args": ["geolens-mcp"],
      "env": {
        "GEOLENS_INSTANCE": "https://geolens.example.com",
        "GEOLENS_API_KEY": "your-api-key"
      }
    }
  }
}

Ferramentas

Ferramenta	O que faz
search_datasets	Busca no catálogo por texto livre (ranqueamento semântico quando a instância o habilita). Retorna registros de conjuntos de dados como feições GeoJSON com estado de origem e frescor seguros; chaves de saúde/verificação/atualização são nulas quando indisponíveis no resumo da busca.
get_dataset_schema	Colunas de um conjunto de dados, tipo de geometria, CRS/SRID, contagem de feições, extensão e metadados de confiança da fonte.
get_features	Feições GeoJSON limitadas para um conjunto de dados (OGC API — Features), com bbox opcional.
list_maps	Mapas salvos (id, nome, visibilidade, contagem de camadas).
get_map	Metadados completos de um mapa salvo, incluindo camadas e estado de visualização.
query	Um SQL SELECT somente leitura por meio do sandbox reforçado do servidor (#565): instrução única sobre tabelas data.*, funções na lista de permissões, um escopo restrict_tables obrigatório e um orçamento estrito no lado do servidor (timeout de instrução, limite de auto-junção, limite de linhas, limites de taxa). Exige uma credencial cujo usuário tenha a permissão de chat de IA; requer GeoLens ≥ a versão que inclui POST /api/query/.

Desenvolvimento

cd mcp
uv run --extra dev python -m pytest -v