MapBiomas Soil MCP

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

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.

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.

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

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 e as etapas locais que vieram de R:

poetry install --with soildata

Esse é o caminho recomendado porque instala a API Earth Engine e as bibliotecas usadas nas tabelas e modelos locais.

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

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/<run_id>/, 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.

Prévia estática versus visualizador interativo

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 diretamente para as camadas C03 catalogadas: para elas, a ferramenta atual entrega métricas numéricas. 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

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

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

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

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.