# Conectar sua IA ao Acácia

Sua IA faz a pesquisa e a modelagem com suas ferramentas GIS/Python. O Acácia recebe estudos e camadas, preserva fontes e método e devolve links de visualização.

## Conexão pelo botão Vincular (OAuth)

1. No ChatGPT, Claude ou outro cliente MCP, adicione um conector com a URL `https://acacia.ligacolaborativa.com.br/api/mcp`.
2. Selecione OAuth. Deixe Client ID e Client Secret vazios para usar o cadastro automático.
3. Clique em **Vincular**, entre na sua conta do Acácia e confira o consentimento.
4. Autorize as permissões desejadas. `acacia:read` permite ler indicadores, fontes e estudos autorizados; `acacia:write` permite criar/editar seus rascunhos e enviá-los à revisão. Nenhuma delas permite aprovar ou publicar.

O login usa a mesma conta do site. Seus estudos privados continuam pertencendo a você.
O cliente renova o acesso pelo OAuth quando necessário. Para remover a autorização, gerencie as aplicações conectadas na sua conta do Clerk/Acácia; desvincule também o conector no cliente.

Se uma conexão criada antes da implantação do OAuth continuar falhando, remova-a e adicione-a novamente para atualizar a descoberta de autenticação.

## Conexão manual com chave pessoal

1. Entre em https://acacia.ligacolaborativa.com.br/conectar.
2. Crie uma chave pessoal com leitura e rascunhos, ou somente leitura.
3. Copie a chave uma vez. Ela expira em 30 dias e pode ser revogada na mesma tela.
4. Configure um cliente MCP Streamable HTTP com `https://acacia.ligacolaborativa.com.br/api/mcp` e o cabeçalho `Authorization: Bearer SUA_CHAVE`.

O endpoint implementa [Streamable HTTP do MCP](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports), com respostas JSON e sem sessão persistente no servidor. Clientes anteriores negociam sua versão ao inicializar.

Para Claude Desktop, use o adaptador [mcp-remote](https://github.com/geelen/mcp-remote):

```json
{
  "mcpServers": {
    "acacia": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://acacia.ligacolaborativa.com.br/api/mcp",
        "--header",
        "Authorization: Bearer ${ACACIA_TOKEN}"
      ],
      "env": { "ACACIA_TOKEN": "SUA_CHAVE" }
    }
  }
}
```

Reinicie o cliente após editar a configuração. Não inclua a chave em prompts, commits ou estudos.

## Ferramentas

| Ferramenta          | Uso                                                                                                |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `search_indicators` | Busca os indicadores públicos com pergunta `q`, `limit` de 1 a 50 e modo `fast`, `auto` ou `deep`. |
| `get_search_map`    | Monta o mapa usando o `mapSnapshotId` retornado pela busca e devolve o link de visualização.       |
| `source_catalog`    | Lista referências aprovadas, suas fontes sugeridas e os provedores integrados.                     |
| `list_studies`      | Lista seus estudos e os estudos publicados.                                                        |
| `get_study`         | Lê um estudo autorizado, camadas e links de visualização.                                          |
| `create_study`      | Cria rascunho privado com título, resumo, método, território e indicação de simulação.             |
| `save_study`        | Atualiza os metadados de seu rascunho ou estudo devolvido para ajustes.                            |
| `add_layer`         | Recebe GeoJSON em uma string, cor, crédito, URL da fonte e referência espacial.                    |
| `submit_study`      | Envia o rascunho para revisão da Liga. Não publica automaticamente.                                |

Não há uma ferramenta para aprovar ou publicar pelo MCP. Chaves de leitura não podem criar, alterar ou submeter estudos.

## Formato cartográfico

Use `FeatureCollection` WGS84 (EPSG:4326), com geometria e tabela `properties`. Limites: 700 KB e 5.000 feições por camada; 20 camadas e 4 MB por estudo. Inclua a origem, versão e limitações de cada camada.

No site, também é possível importar KML ou um ZIP de shapefiles contendo `.shp`, `.dbf` e `.prj` no mesmo diretório por camada; `.shx` e `.cpg` são preservados quando disponíveis. O [shpjs](https://github.com/calvinmetcalf/shapefile-js) usa a projeção do `.prj` para converter as coordenadas para WGS84. Limites de ZIP: 10 MB compactado e 20 MB expandido. Para dados maiores, simplifique ou divida as camadas no GIS.

## Prova de conceito Python

No repositório `hub-indicadores`:

```sh
python3 scripts/modelar-territorio.py examples/lagoa-real-simulado.csv --simulated --output output/acacia
```

Gera quatro camadas e um relatório de correlações de Pearson. Os dados de exemplo são fictícios. Uma correlação não demonstra causalidade.

Para enviar o resultado a um rascunho privado, forneça `ACACIA_API_URL` (URL HTTP do Convex, terminada em `.convex.site`) e `ACACIA_TOKEN` no ambiente e acrescente `--publish`. Nesse script, `--publish` significa enviar ao Acácia: o estudo continua privado. Nunca imprime a chave e não submete à revisão automaticamente.

```sh
python3 scripts/modelar-territorio.py examples/lagoa-real-simulado.csv --simulated --publish
```

Dados próprios podem ser combinados com geometrias usando `--geometry arquivo.geojson`, com a junção pelo campo `properties.id`. Confira período, escala, qualidade e coordenadas antes de interpretar a análise.

## Revisão

O autor prepara e testa o rascunho. Ao submeter, a equipe autorizada da Liga pode ler o estudo, aprovar, solicitar ajustes ou rejeitar. Um rascunho ainda não submetido permanece privado, inclusive para o revisor. Após aprovação, o link fica público e o conteúdo não pode mais ser alterado pelo autor; uma nova versão exige outro rascunho.