Skip to main content
Glama

MapBiomas Soil MCP

Em resumo: este projeto permite consultar dados de solo, planejar receitas, executar processamentos autorizados no Google Earth Engine (GEE), acompanhar tarefas e fazer perguntas sobre os resultados — sem baixar os mapas nacionais para o computador.

📘 Para uma explicação visual, sem pressupor conhecimento técnico, veja arquitetura-gee-mcp.html.

O que você pode fazer

Objetivo

Primeiro passo

Altera dados?

Perguntar sobre um produto de solo já publicado

Consultar pelo MCP

Não

Entender a ordem de uma modelagem

Planejar uma receita

Não

Prever textura ou carbono

Rodar um teste pequeno e autorizado

Sim, cria tarefas no GEE

Preparar tabelas que antes usavam R

Planejar uma etapa Python local

Não no planejamento

Consultar um resultado que você já produziu

Informar o run_id e a camada

Não

Regra de ouro: consultar e planejar são operações de leitura. Executar uma receita cria tarefas no GEE e só deve acontecer após revisar os assets, a área, a pasta de saída e os custos esperados.


Related MCP server: GeoSight MCP Server

O problema que esta arquitetura resolve

Mapas nacionais de solo têm muitos pixels, profundidades, anos, imagens de satélite e tabelas de amostras. Guardar e recalcular tudo em um computador comum seria lento, caro e difícil de manter.

Por isso o projeto usa uma arquitetura híbrida:

Dados tabulares locais
        ↓
Python local: preparação e validação
        ↓
GEE: modelos, mapas e tarefas pesadas
        ↓
Assets versionados por execução
        ↓
MCP: perguntas, métricas, mapas e monitoramento

Em linguagem simples:

  • Google Earth Engine (GEE): plataforma em nuvem onde ficam imagens, coleções e processamento espacial em grande escala. É onde o cálculo pesado acontece.

  • Python local: código que roda no computador para organizar tabelas, preparar dados e validar resultados.

  • MCP: ponte controlada entre a conversa e as ferramentas. Ele permite que o assistente planeje, execute quando autorizado, acompanhe tasks e consulte resultados.

  • run_id: nome único de uma execução. Ele separa os resultados de um teste dos resultados de outro.

O projeto não tenta copiar os rasters do Brasil, nem recriar o banco do GEE no computador. Dados espaciais grandes continuam no GEE; localmente ficam código, tabelas, configurações, validações e resultados compactos quando necessários.


De onde veio a lógica do projeto

A pasta soil_30m_landsat foi preservada como referência científica e de auditoria. Ela contém scripts, notebooks e a sequência de etapas do fluxo original de solo.

Pense nela como uma receita: ela informa ingredientes, ordem de preparo, filtros, fórmulas, modelos e verificações. Este projeto adapta essa lógica para Python e MCP.

Referência original

O que foi adaptado

Por que

Scripts/notebooks de textura no GEE

Receitas Python que montam planos e tasks no GEE

Rodar o cálculo perto dos dados espaciais

Scripts/notebooks de carbono no GEE

Receitas Python para matriz, réplicas e previsão anual

Permitir previsões controladas e monitoráveis

Scripts soildata/*.R

Etapas Python locais com entradas e saídas declaradas

Não depender de abrir scripts R manualmente

Passos manuais

Etapas nomeadas, planejáveis e auditáveis

Facilitar revisão e rastreabilidade

Saídas soltas

Caminhos abaixo de runs/<run_id>/...

Saber qual execução produziu cada mapa

O que não foi copiado:

  • dados privados, credenciais ou permissões de terceiros;

  • assets nacionais para o computador;

  • permissões da MapBiomas ou de qualquer outra organização;

  • o namespace oficial de saída de outra equipe.

O MCP usa as permissões da conta autenticada. Ele não cria acesso e não contorna bloqueios de dados privados.


O que já está disponível

Consultas, mapas e monitoramento

  • Produtos MapBiomas Solo Collection 3: areia, silte, argila, grupo/subgrupo/classe textural e profundidade até pedregosidade.

  • Estatísticas para uma área ou ponto: média, mediana, mínimo, máximo, desvio padrão e, para classes, moda.

  • Mapa nacional das camadas C03 publicadas, em PNG estático ou no visualizador interativo, recortado no limite do Brasil.

  • Consulta de uma banda produzida pelo seu próprio run_id.

  • URL de thumbnail/mapa para uma banda produzida.

  • Visualizador local interativo para uma a seis camadas produzidas pelo seu próprio run_id.

  • Listagem e consulta de status de tarefas Earth Engine.

Receitas GEE

Receita

Resultado principal

Precisa de

texture_training_matrix

Matriz de treinamento para textura

Pontos de solo e covariáveis autorizadas

texture_prediction

Areia, silte, argila e cascalho por profundidade

Matriz de treinamento

texture_classification

Grupo, subgrupo e classe textural

Predição de textura

texture_density

Densidade da terra fina e rocha

Textura e geologia

texture_stoniness

Pedregosidade e profundidades de 50%/90%

Textura e densidade

carbon_training_matrix

Matriz de treinamento SOC

Pontos de carbono autorizados

carbon_temporal_replication

Réplicas temporais de amostras estáveis

Pontos ou matriz SOC

carbon_prediction

Série anual de carbono, 1985–2024

Matriz de carbono

Etapas que eram R, agora em Python

A cadeia local possui etapas para juntar e limpar tabelas, preparar covariáveis, transformar composição PSD/ALR, estimar densidade e estoque de carbono, calcular estatísticas, treinar e validar modelos.

Use list_soildata_pipeline para ver a lista completa e o estado de cada etapa. Algumas portas são diretas; outras são aproximações que precisam ser validadas contra os dados reais.


Pré-requisitos

Antes de iniciar, confirme:

  1. Python 3.11 a 3.14 e Poetry instalados.

  2. Uma conta Google autorizada a usar Earth Engine.

  3. Um projeto Google Cloud registrado/configurado para Earth Engine.

  4. Permissão de leitura nos assets necessários para a receita desejada.

  5. Permissão de escrita em uma coleção GEE própria, se for exportar resultados.

  6. Para etapas locais, arquivos tabulares dentro de uma pasta permitida.

Ter autenticado no GEE não significa ter acesso automático a todos os assets. Coleções privadas precisam ser compartilhadas com a conta que executará o MCP.

Importante: o servidor inicializa o GEE ao iniciar. Portanto, mesmo se você pretende usar somente uma etapa local pelo MCP, configure GEE_PROJECT e a autenticação Earth Engine.


Instalação passo a passo

1. Abra o PowerShell na pasta do projeto

cd C:\caminho\para\gee-mcp

2. Instale as dependências

Para consultas, receitas GEE, as etapas locais que vieram de R e o desenho de mapas:

poetry install --with soildata,maps

Esse é o caminho recomendado porque instala a API Earth Engine, as bibliotecas usadas nas tabelas e modelos locais e o matplotlib usado pelos mapas nacionais.

3. Crie o arquivo de configuração

Se ainda não houver um arquivo .env:

Copy-Item .env.example .env

Abra o arquivo .env e comece com uma configuração segura:

GEE_PROJECT=seu-projeto-google-cloud
SOIL_MCP_ENABLE_EXPORTS=0
SOIL_MCP_ENABLE_LOCAL_RUNS=0

# Opcional: para etapas Python locais
# SOIL_MCP_DATA_ROOT=./data

# Obrigatório para exports e para consultar/visualizar outputs próprios
# SOIL_MCP_OUTPUT_ASSET_ROOT=projects/SEU_PROJETO/assets/soil-mcp

Variável

O que ela controla

Valor inicial recomendado

GEE_PROJECT

Projeto Google Cloud usado pelo GEE

ID do seu projeto

SOIL_MCP_ENABLE_EXPORTS

Criação de tasks/exportações GEE

0

SOIL_MCP_OUTPUT_ASSET_ROOT

Raiz própria de saída no GEE

Configure antes de exportar, consultar ou abrir outputs próprios

SOIL_MCP_ENABLE_LOCAL_RUNS

Escritas das etapas Python locais

0

SOIL_MCP_DATA_ROOT

Pasta permitida para arquivos locais

./data ou caminho absoluto

Os flags só são habilitados pelo valor literal 1. Valores como true, yes ou True não habilitam exports nem etapas locais.

Para clientes MCP que iniciam o processo em outra pasta, prefira um caminho absoluto em SOIL_MCP_DATA_ROOT.

4. Autentique a conta Earth Engine

Use a conta que possui as permissões necessárias:

poetry run earthengine authenticate --force --auth_mode=localhost
poetry run earthengine set_project seu-projeto-google-cloud

O navegador abrirá para autorizar a conta. Quando o terminal informar que o token foi salvo, a autenticação foi concluída.

O comando earthengine set_project configura o cliente de linha de comando; o servidor MCP usa especificamente o valor de GEE_PROJECT do arquivo .env.

5. Inicie o servidor MCP

poetry run python -m soil_mcp

O servidor usa transporte stdio: ele não abre uma página ou painel no terminal. O cliente MCP (por exemplo, Codex) deve iniciar esse comando, usando a raiz deste repositório como diretório de trabalho.

Não é necessário abrir o Code Editor do GEE para o fluxo normal do MCP. O Code Editor pode continuar útil para inspeção ou depuração visual feita por uma pessoa técnica.


Primeiro teste seguro

Comece com perguntas que apenas leem dados:

  • “Quais métricas de solo publicadas estão disponíveis?”

  • “Qual é a média de argila de 0–10 cm nesta área?”

  • “Mostre as etapas do pipeline de textura.”

  • “Liste as receitas GEE e suas dependências.”

Essas ações usam ferramentas como list_soil_metrics, query_soil_metric, list_soil_pipeline e list_pipeline_recipes. Elas não criam tasks.

Depois, peça um plano sem executar:

  • “Planeje texture_training_matrix, mas não execute nada.”

  • “Quais inputs e outputs serão usados em carbon_prediction?”

  • “O que precisa existir antes de classificar textura?”

plan_pipeline_recipe monta o plano e o grafo preguiçoso do GEE, mas não inicia uma task e não grava assets.


Fluxo de uma execução real

1. Escolha um run_id

Use um nome curto e explicativo, sem espaços:

textura-teste-pr-20260729

O formato aceito tem 3 a 80 caracteres e permite letras, números, hífen e sublinhado. Não use barras, espaços ou caracteres especiais.

As saídas ficam abaixo de:

<SOIL_MCP_OUTPUT_ASSET_ROOT>/runs/textura-teste-pr-20260729/...

2. Planeje a receita

Exemplo conceitual de argumentos para uma predição de textura depois que a matriz de treinamento já existe:

{
  "recipe_id": "texture_prediction",
  "run_id": "textura-teste-pr-20260729",
  "output_asset_root": "projects/SEU_PROJETO/assets/soil-mcp",
  "training_asset_id": "projects/SEU_PROJETO/assets/soil-mcp/runs/textura-teste-pr-20260729/texture/texture_training_matrix"
}

Peça ao MCP para chamar plan_pipeline_recipe com os argumentos. Antes de avançar, revise:

  • assets de entrada;

  • destino de cada export;

  • área de interesse;

  • escala, anos e profundidades;

  • se a conta consegue ler cada input;

  • se a saída pertence ao seu projeto.

Alguns roots padrão apontam para namespaces privados. Uma pessoa autorizada pode informar IDs reais e, quando necessário, asset_overrides no plano.

3. Habilite exports somente depois da revisão

No arquivo .env:

SOIL_MCP_ENABLE_EXPORTS=1
SOIL_MCP_OUTPUT_ASSET_ROOT=projects/SEU_PROJETO/assets/soil-mcp

Reinicie o servidor MCP depois de alterar o arquivo. O .env é a fonte de verdade das variáveis do servidor.

Agora faça uma solicitação explícita, por exemplo:

“Submeta o plano texture_prediction do run textura-teste-pr-20260729.”

A ferramenta submit_pipeline_recipe cria as tasks GEE. Algumas receitas podem gerar mais de uma task; revise a resposta e guarde cada task_id.

4. Acompanhe as tasks

Exemplos de pedidos:

  • “Liste as tarefas GEE.”

  • “Qual é o estado da task TASK_ID?”

  • “Esta task falhou? Qual foi a mensagem de erro?”

Use list_gee_tasks ou get_gee_task_status.

O MCP consulta o status quando você pergunta. Ele não permanece observando tasks sozinho nem envia alertas automáticos. Para isso, conecte um agendador ou serviço externo.

5. Veja dados e mapas sem abrir o Code Editor

Depois que uma exportação termina, o resultado continua no Earth Engine, mas pode ser consultado pelo MCP. Não é necessário baixar o raster nacional para o computador nem abrir o Code Editor.

Para ler um resultado produzido pelo pipeline, a task precisa ter concluído e o asset precisa existir abaixo de:

SOIL_MCP_OUTPUT_ASSET_ROOT/runs/<run_id>/...

Também é necessário configurar SOIL_MCP_OUTPUT_ASSET_ROOT no servidor e usar uma conta que possa ler esse asset. A flag SOIL_MCP_ENABLE_EXPORTS=1 é necessária para criar novas exports, mas não para visualizar um output já existente.

Pergunta sobre um dado: o que o MCP devolve

Pedido em linguagem natural:

“Qual é a média de argila de 0–10 cm nesta área para o run textura-demo?”

O MCP identifica o run, a camada, a banda, a área e a estatística. Para um output do próprio pipeline, ele usa query_pipeline_run_asset. Para uma camada C03 catalogada que a conta possa ler, usa query_soil_metric.

Exemplo ilustrativo — números fictícios, sem consultar assets privados:

{
  "run_id": "textura-demo",
  "band": "argila_000_010cm",
  "statistic": "mean",
  "value": 42.7,
  "unit": "%",
  "scale_m": 30,
  "source": "demonstracao_sintetica"
}

Essa é uma estatística resumida da área, e não uma medição direta de campo nem uma tabela de todos os pixels. Em áreas muito grandes, o GEE pode ajustar a escala efetiva para concluir o cálculo.

Pedido de mapa: o que o MCP devolve hoje

Pedido em linguagem natural:

“Mostre o mapa de argila de 0–10 cm produzido no run textura-demo nesta área.”

O MCP usa get_pipeline_run_asset_thumbnail. Ele seleciona a banda, aplica uma visualização (mínimo, máximo e paleta) e pede ao GEE uma prévia cartográfica em PNG. A resposta contém uma URL temporária que o cliente pode exibir ou abrir.

Exemplo ilustrativo — não corresponde a uma URL real:

{
  "run_id": "textura-demo",
  "band": "argila_000_010cm",
  "thumbnail_url": "<link temporario PNG do Earth Engine>",
  "visualization": {
    "min": 0,
    "max": 80,
    "palette": ["fff7bc", "fec44f", "d95f0e"],
    "dimensions": 768
  },
  "source": "demonstracao_sintetica"
}

Para a prévia, informe o run_id, asset_path, banda, área, mínimo, máximo, paleta e dimensão. A dimensão aceita de 128 a 2048 pixels e a paleta aceita de 2 a 12 cores. Mínimo, máximo e paleta mudam somente a aparência da imagem; não modificam os dados.

O link é temporário e não deve ser tratado como publicação permanente. A visualização também continua sujeita ao acesso da conta que pediu o mapa.

Visualizador interativo local: zoom, arrastar e camadas

Para abrir um mapa interativo real, peça ao MCP algo como:

“Abra o mapa interativo de argila e silte do run textura-demo nesta área.”

A ferramenta open_pipeline_run_asset_map valida de uma a seis camadas do mesmo run_id, cria uma sessão temporária e devolve um endereço semelhante a:

http://127.0.0.1:PORTA/viewer/SESSAO_ALEATORIA

Abra esse link no navegador do mesmo computador que está rodando o MCP. O visualizador permite:

  • aproximar/afastar;

  • arrastar o mapa;

  • navegar pelo teclado;

  • escolher entre as camadas autorizadas;

  • ver título, banda, legenda, mínimo, máximo e paleta.

Ele não abre o Code Editor e não precisa de uma API key no navegador. Os tiles vêm de um pequeno proxy local, limitado a 127.0.0.1, que usa a autenticação Earth Engine já configurada no MCP. A sessão fica somente em memória, expira em poucos minutos e deixa de funcionar quando o MCP é encerrado.

Esse recurso não cria exports nem tasks novas. Ele requer uma task já concluída, SOIL_MCP_OUTPUT_ASSET_ROOT configurado e permissão de leitura no output.

Quando o cliente MCP pedir os parâmetros técnicos, informe a área e pelo menos uma camada. Cada camada precisa apontar para um arquivo de imagem abaixo do run, uma banda, um nome para a legenda e a escala de cores. Exemplo de uma chamada que o assistente pode montar:

{
  "run_id": "textura-teste-pr-20260729",
  "layers": [
    {
      "asset_path": "texture/prediction/argila",
      "band": "argila_000_010cm",
      "label": "Argila 0–10 cm",
      "min_value": 0,
      "max_value": 80,
      "palette": ["fff7bc", "fec44f", "d95f0e"]
    }
  ],
  "bounding_box": [-48.0, -16.0, -47.8, -15.8]
}

asset_path é relativo a runs/&lt;run_id&gt;/, não um ID livre do GEE. O visualizador só aceita caminhos, bandas e paletas literais; isso impede que um pedido de mapa escape da pasta de resultados autorizada.

Mapa nacional estático (caminho recomendado)

As camadas do MapBiomas Solo C03 já são produtos nacionais. Para ver uma delas inteira, o caminho mais rápido é gerar um PNG:

python scripts/mapa_estatico.py
python scripts/mapa_estatico.py --metric clay --depth 000_030cm
python scripts/mapa_estatico.py --metric texture_class --scale 5000

Isso requer as dependências de desenho:

poetry install --with maps

O script baixa o país inteiro do GEE em uma única requisição, como uma grade de valores reais em resolução reduzida, e desenha localmente com matplotlib. Um mapa nacional sai em poucos segundos e o arquivo continua legível depois, sem sessão viva. Ele não cria export nem task.

Por que isso é muito mais rápido que o visualizador interativo: um mapa de tiles pede ao Earth Engine centenas de recortes independentes, recalculados a cada aproximação e deslocamento. A grade única troca essa conversa por um download só.

Opção

Tempo típico do Brasil inteiro

Interação

Quando usar

scripts/mapa_estatico.py

segundos

nenhuma

Ver, comparar, salvar e compartilhar o mapa

scripts/mapa_navegavel.py

segundos

zoom, pan, camadas, valor no cursor

Explorar o país sem esperar por tiles

open_soil_metric_map / scripts/mapa_brasil.py

minutos

zoom, pan, camadas

Só quando precisar dos tiles do próprio GEE

Argumentos úteis:

Argumento

Efeito

--metric

Métrica do catálogo; repita para um painel com vários mapas

--depth

Profundidade da métrica na mesma posição

--scale

Resolução da grade de exibição em metros (padrão 2500; valor maior baixa menos e desenha antes)

--bounding-box

Recorte em vez do país inteiro

--output

Arquivo de destino (padrão mapas/brasil_&lt;nome&gt;.png)

--dpi, --columns, --title

Aparência da figura

Sem argumentos, o script desenha argila, areia e silte de 0–10 cm mais o grupamento textural de 0–30 cm. Cada métrica tem uma faixa de cores revisada: para as frações granulométricas, as faixas correspondem aos percentis 2–98 nacionais, para que a paleta cubra os valores que de fato ocorrem no Brasil. Camadas categóricas ganham cores discretas e legenda com o nome de cada classe.

A grade de exibição é uma redução de resolução só para desenho: o produto continua sendo de 30 m e as estatísticas devem vir de query_soil_metric, não da leitura visual do PNG.

Mapa navegável, sem servidor e sem sessão

Se você quer aproximar, deslocar e ler valores, mas sem a lentidão do visualizador de tiles:

python scripts/mapa_navegavel.py
python scripts/mapa_navegavel.py --metric clay --metric texture_class
python scripts/mapa_navegavel.py --scale 1500 --bounding-box -55 -25 -45 -15

O script baixa a mesma grade única do mapa estático e a embute em um único arquivo HTML. Depois disso a página é autossuficiente: aproximar, deslocar, trocar de camada e ler o valor sob o cursor acontecem inteiramente no navegador. Não há requisição ao GEE, não há servidor local e não há sessão que expire — o arquivo continua funcionando amanhã.

Cada camada viaja como um PNG em tons de cinza cujo nível de cinza é a medição e cujo canal alfa carrega a máscara de validade. É por isso que a página consegue tanto colorir o raster quanto informar o valor do ponto.

O arquivo fica na ordem de alguns MB por camada. Use --scale para equilibrar detalhe e tamanho: 2000 m para o país inteiro, valores menores para um recorte.

O valor mostrado é o da grade de exibição, não o do pixel de 30 m. Para número com precisão de produto, use query_soil_metric.

Mapa nacional interativo por tiles

Se você precisa aproximar e navegar, peça algo como:

“Abra o mapa de argila e areia do Brasil.”

A ferramenta open_soil_metric_map usa o visualizador local, com duas diferenças em relação a open_pipeline_run_asset_map:

  • os assets vêm do catálogo fixo de list_soil_metrics, e não de um run_id próprio — portanto ela não exige SOIL_MCP_OUTPUT_ASSET_ROOT nem uma execução concluída;

  • a área padrão é o Brasil inteiro, e cada camada é recortada no limite nacional (USDOS/LSIB_SIMPLE/2017, um dataset público do GEE), de modo que apenas o país aparece desenhado.

Fora de um cliente MCP:

python scripts/mapa_brasil.py --minutes 60

O script imprime o endereço do visualizador, abre o navegador e mantém a sessão viva até você encerrar com Ctrl+C.

Em escala nacional esse caminho é lento: cada tile é recalculado pelo GEE sob demanda e a sessão não guarda cache entre deslocamentos. Para olhar o país inteiro, prefira o mapa estático; reserve o visualizador para aproximar uma área.

Prévia estática versus visualizador interativo

Formato

Situação atual

Para que serve

Mapa nacional em PNG

Disponível por scripts/mapa_estatico.py para as camadas C03 publicadas

Ver o país inteiro em segundos, com barra de cores e legenda, e guardar o arquivo

Mapa navegável em HTML

Disponível por scripts/mapa_navegavel.py para as camadas C03 publicadas

Aproximar, deslocar e ler valores sem servidor, sem sessão e sem consultar o GEE

Prévia cartográfica PNG

Disponível para assets concluídos do próprio run_id

Ver rapidamente cores, padrões espaciais e uma área específica, sem abrir o Code Editor

Visualizador local com zoom/pan/camadas

Disponível por open_pipeline_run_asset_map (run próprio) e open_soil_metric_map (camadas C03 publicadas)

Aproximar uma área no navegador local, sem expor credenciais Google

O arquivo arquitetura-gee-mcp.html mostra o contrato real da entrega: pergunta → resultado estruturado → viewer_url do mapa local. Ele não desenha um mapa fictício; as tiles verdadeiras só aparecem quando uma sessão autorizada é criada pelo MCP.

Hoje, o MCP não gera thumbnail PNG para as camadas C03 catalogadas: para elas existem métricas numéricas e o mapa interativo nacional. O thumbnail é destinado a outputs versionados do seu próprio pipeline, por segurança.


Etapas locais: portabilidade de R para Python

Várias etapas que eram executadas em R foram reorganizadas para Python local. Isso evita rodar scripts arbitrários e permite que o MCP conheça as entradas, saídas e dependências de cada etapa.

Habilite o fluxo local quando precisar

No .env:

SOIL_MCP_DATA_ROOT=./data
SOIL_MCP_ENABLE_LOCAL_RUNS=1

Todos os arquivos usados pelo MCP precisam ficar dentro de SOIL_MCP_DATA_ROOT. Essa limitação protege o restante do computador.

Fluxo recomendado

  1. Use list_soildata_pipeline para ver as etapas e seus estados.

  2. Use get_soildata_stage para entender entradas, saídas e dependências.

  3. Use plan_soildata_stage para conferir caminhos e opções sem criar uma saída.

  4. Use run_soildata_stage somente depois da revisão.

Exemplo conceitual:

{
  "stage_id": "export_psd_modeling_data",
  "input_paths": {
    "input": "15_soildata.parquet"
  },
  "output_path": "16_psd_modeling.parquet"
}

O planejamento local aceita caminhos de entrada ainda inexistentes para permitir organizar o fluxo. A execução verifica se os inputs existem. O MCP não roda R, Python ou comandos arbitrários; ele executa somente estágios previamente permitidos.


Permissões necessárias

Capacidade

Por que é necessária

Exemplo de falha

Usar Earth Engine no projeto GCP

Enviar consultas e tasks

Projeto não configurado ou conta não habilitada

Ler assets privados

Usar amostras, matrizes e covariáveis

Permission denied ao acessar um asset

Escrever na saída própria

Salvar resultados de um run

Raiz ausente ou sem permissão

Ler/escrever tabelas locais

Rodar Python local

Arquivo fora de SOIL_MCP_DATA_ROOT

Para exportações, duas regras são obrigatórias:

  1. SOIL_MCP_ENABLE_EXPORTS precisa valer 1.

  2. O destino precisa ser a raiz configurada em SOIL_MCP_OUTPUT_ASSET_ROOT ou uma subpasta dela.

A raiz de saída deve pertencer ao operador ou permitir a criação de filhos. As receitas não sobrescrevem assets existentes; para um novo teste, use outro run_id.


Ferramentas MCP por objetivo

Objetivo

Ferramentas

Exemplo de pedido

Ver métricas publicadas

list_soil_metrics

“Quais produtos posso consultar?”

Calcular uma métrica

query_soil_metric

“Qual é a média de argila nesta área?”

Gerar o mapa nacional em PNG

scripts/mapa_estatico.py

“Gere o mapa de argila do Brasil.”

Navegar pelo mapa nacional

scripts/mapa_navegavel.py

“Quero aproximar e ver os valores.”

Abrir o mapa por tiles do GEE

open_soil_metric_map

“Abra o mapa com tiles do Earth Engine.”

Exportar uma camada publicada

submit_soil_layer_export

“Exporte esta camada para minha pasta autorizada.”

Entender o fluxo de referência

list_soil_pipeline, get_soil_pipeline_stage, read_soil_pipeline_source

“Como esta etapa depende da anterior?”

Listar receitas GEE

list_pipeline_recipes

“Quais receitas existem para carbono?”

Planejar sem escrever

plan_pipeline_recipe

“Planeje, mas não execute.”

Submeter receita

submit_pipeline_recipe

“Agora pode enviar as tasks.”

Monitorar tasks

list_gee_tasks, get_gee_task_status

“A tarefa terminou?”

Consultar output próprio

query_pipeline_run_asset

“Qual a média da camada produzida?”

Gerar prévia de mapa de um run próprio

get_pipeline_run_asset_thumbnail

“Mostre um mapa deste resultado.”

Abrir mapa interativo de um run próprio

open_pipeline_run_asset_map

“Abra o mapa interativo desta camada nesta área.”

Trabalhar com tabela local

list_soildata_pipeline, get_soildata_stage, plan_soildata_stage, run_soildata_stage

“Planeje a limpeza desta tabela.”


O que validar antes de rodar uma área grande

A arquitetura permite executar grande parte da cadeia, mas reproduzir um produto científico exige mais do que código:

  • mesmos dados autorizados;

  • versões corretas de covariáveis e tabelas;

  • nomes de colunas, bandas, unidades e schemas esperados;

  • pseudoamostras, limites e correções manuais quando o fluxo original as usa;

  • comparação com uma linha de base autorizada;

  • aprovação do responsável científico antes de publicar.

Modelos/bibliotecas diferentes não garantem resultados idênticos pixel a pixel. Em especial, comportamentos de ranger, gbm, qmap e implementações Python/GEE podem variar.

Caminho seguro:

acesso autorizado
  → consulta de leitura
  → plano da receita
  → teste em área pequena
  → comparação com referência
  → validação de mapa e métricas
  → processamento maior

Limitações conhecidas

  • Alguns inputs privados não estão no repositório: SoilData-ctb, pseudoamostras, matrizes PSD/SOC, shapefiles auxiliares e certos assets MapBiomas.

  • Algumas portas de R para Python são aproximações e precisam ser verificadas com dados reais.

  • Rotinas antigas que dependiam de Google Drive/Insync não são a infraestrutura operacional deste projeto; se forem necessárias, precisam de destino institucional definido.

  • O MCP não envia alertas de task em segundo plano.

  • Planejar pode funcionar sem permissão total porque apenas monta referências; executar ou consultar falhará se a conta não puder ler o asset.

  • O MCP não toma decisões científicas nem substitui revisão humana.


Solução de problemas

“Este app está bloqueado” durante a autenticação

Tente novamente no modo local:

poetry run earthengine authenticate --force --auth_mode=localhost

Escolha a conta habilitada para Earth Engine. Se o terminal confirmar que o token foi salvo, a autenticação terminou. Se o bloqueio persistir, verifique o registro da conta/projeto no Earth Engine e políticas institucionais de login.

“Permission denied” ao acessar um asset

Autenticação não é permissão de leitura. Peça ao responsável que compartilhe a coleção, tabela ou imagem exata com a conta usada pelo MCP.

“Exports are disabled”

Isso é intencional. Revise o plano e configure:

SOIL_MCP_ENABLE_EXPORTS=1
SOIL_MCP_OUTPUT_ASSET_ROOT=projects/SEU_PROJETO/assets/soil-mcp

Reinicie o MCP depois da alteração.

Erro de raiz de saída

O destino informado deve ser a raiz configurada em SOIL_MCP_OUTPUT_ASSET_ROOT ou uma subpasta dela. Isso evita exports para coleções não autorizadas.

Arquivo local não encontrado ou caminho proibido

Coloque o arquivo dentro de SOIL_MCP_DATA_ROOT e informe um caminho relativo, por exemplo entrada/15_soildata.parquet. O MCP bloqueia caminhos que tentem sair dessa pasta.

A task falhou

Consulte o task_id. Verifique primeiro asset de entrada, permissões, nome de banda/coluna, escala, área e destino de saída. Corrija e teste em uma área pequena.


Estrutura do repositório

src/soil_mcp/
├── recipes/       # receitas Python para Google Earth Engine
├── soildata/      # substituições Python dos scripts R/notebooks
├── *_tools.py     # ferramentas expostas ao cliente MCP
└── pipeline.py    # ordem e contratos das etapas

scripts/                    # entradas de terminal, como o mapa nacional
soil_30m_landsat/          # fonte original preservada para comparação
tests/                      # testes de contrato e transformações
README.md                   # este manual operacional
arquitetura-gee-mcp.html   # guia visual e didático
mapa-interativo.html       # template do visualizador por tiles do GEE
mapa-navegavel.html        # template do mapa navegável autossuficiente

Desenvolvimento e validação

Para executar os testes:

poetry run pytest -q

Os testes verificam contratos do pipeline e transformações locais. Eles não substituem a validação científica com os assets privados reais.


Próximos passos recomendados

  1. Confirme a conta, o projeto GCP e as permissões de leitura.

  2. Faça uma consulta simples a um produto publicado.

  3. Peça o plano de uma receita, sem executar.

  4. Conecte IDs reais de tabelas, pontos e assets privados autorizados.

  5. Rode um teste pequeno.

  6. Compare métricas e mapa contra uma referência.

  7. Só então habilite uma exportação maior.


Atribuição e uso de dados

Os termos de uso, regras de atribuição e políticas de acesso da MapBiomas e das demais fontes continuam valendo. Este projeto organiza execução e rastreabilidade; ele não transfere propriedade, licença ou permissões sobre os dados.

F
license - not found
-
quality - not tested
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • -
    license
    -
    quality
    -
    maintenance
    Enables satellite imagery analysis through Google Earth Engine, allowing users to search datasets, calculate vegetation indices like NDVI, filter collections by location and date, and export imagery to cloud storage. Supports major satellite datasets including Sentinel-2, Landsat, and MODIS for applications like agriculture monitoring and deforestation tracking.
    Last updated
  • A
    license
    -
    quality
    D
    maintenance
    Production-ready satellite imagery analysis server that enables natural language queries for Earth observation data, including land cover classification, vegetation monitoring, water detection, change detection, and automated environmental reporting.
    Last updated
    MIT
  • A
    license
    B
    quality
    D
    maintenance
    Provides tools to search, download, and manage satellite imagery from all Copernicus Sentinel missions via the Copernicus Data Space ecosystem. It enables advanced geospatial queries, temporal coverage analysis, and automated data management for Earth observation tasks.
    Last updated
    13
    3
    LGPL 3.0

View all related MCP servers

Related MCP Connectors

  • OpenTopography global DEM rasters + point queries (free key)

  • Search and query government open-data portals (Socrata SODA API).

  • Query real-time and historical USGS water data from ~8,000 stream gages and groundwater wells.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/VitorEduardoLimaKenor/soil-pipeline-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server