treasy-mcp 0.0.0.dev0__tar.gz

treasy_mcp-0.0.0.dev0/INSTALAR.md

@@ -0,0 +1,78 @@
+# treasy-mcp: o seu Treasy dentro do Claude Code
+
+O `treasy-mcp` liga o Claude Code à sua conta do Treasy FP&A. Depois de instalado, você pede ao
+Claude, em português, o que hoje faz no Treasy, e ele consulta os seus dados com o seu usuário.
+
+Em produção o pacote é **somente leitura**: ele consulta, nunca altera.
+
+## 1. Instale o `uv` (uma vez por computador)
+
+O `uv` é o programa que baixa e roda o `treasy-mcp`. Se o comando `uv --version` já responde,
+pule para o passo 2.
+
+**Windows** (no PowerShell):
+
+```powershell
+winget install --id astral-sh.uv -e
+```
+
+**macOS** (no Terminal):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Linux** (no terminal):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Feche e abra o terminal depois de instalar.
+
+## 2. Ligue o Treasy ao Claude Code (a linha da instalação)
+
+```bash
+claude mcp add treasy -- uvx treasy-mcp
+```
+
+## 3. Entre com o seu usuário do Treasy (a linha do login)
+
+```bash
+uvx treasy-mcp login
+```
+
+O navegador abre na página de login do Treasy. Entre com o seu e-mail e a sua senha de sempre.
+A senha fica só no navegador: o `treasy-mcp` guarda uma sessão no seu computador, na pasta
+`.treasy` da sua pasta de usuário, e nunca vê a senha.
+
+## 4. Pronto: peça ao Claude
+
+Abra o Claude Code e peça, por exemplo: "liste as minhas empresas no Treasy".
+
+## Quando algo não funciona
+
+Rode o diagnóstico e mande as seis linhas ao suporte da Treasy (elas não têm segredo):
+
+```bash
+uvx treasy-mcp doctor
+```
+
+| O que aparece | O que fazer |
+|---|---|
+| `sem sessão de prod` | Rode `uvx treasy-mcp login`. |
+| `a sessão de prod venceu` | Rode `uvx treasy-mcp login` de novo. |
+| `porta 47650 ocupada` | Feche o programa que usa a porta 47650 e rode o login de novo. |
+| `não respondeu` no SSO ou na API | Confira a internet, o proxy ou o firewall da empresa para `*.treasy.com.br`. |
+
+Outros comandos:
+
+```bash
+uvx treasy-mcp status     # mostra a sessão gravada (nunca o token)
+uvx treasy-mcp sair       # apaga a sessão deste computador
+uvx treasy-mcp --version  # a versão instalada
+```
+
+Para usar outro ambiente que a Treasy lhe indicar (`qa` ou `sandbox`), acrescente o nome ao
+login (`uvx treasy-mcp login sandbox`) e ligue o Claude com a variável do ambiente:
+`claude mcp add treasy -e TREASY_AMBIENTE=sandbox -- uvx treasy-mcp`.

treasy_mcp-0.0.0.dev0/LICENSE

@@ -0,0 +1,28 @@
+Licença de uso do treasy-mcp
+
+Copyright (c) 2026 Treasy. Todos os direitos reservados.
+
+Este software (o pacote "treasy-mcp", com o código, o catálogo de operações e a documentação que o
+acompanham) é propriedade da Treasy e é licenciado, não vendido.
+
+1. Permissão de uso. Quem tem um usuário ativo do Treasy pode instalar e executar este software,
+   sem custo, em qualquer número de computadores próprios ou da sua empresa, com o único fim de
+   acessar a própria conta do Treasy por um cliente compatível com o Model Context Protocol (MCP),
+   como o Claude Code.
+
+2. O que não é permitido. Sem autorização por escrito da Treasy, não é permitido: (a) vender,
+   sublicenciar, alugar ou redistribuir este software, no todo ou em parte, fora do índice oficial
+   onde a Treasy o publica; (b) modificar o software e distribuir a versão modificada; (c) usá-lo
+   para acessar conta, empresa ou dado de terceiro sem a permissão dele; (d) remover este aviso.
+
+3. Uso interno nas empresas. Copiar o pacote para o espelho interno de pacotes da empresa, sem
+   modificação, para instalar nos computadores dela, é permitido.
+
+4. Sem garantia. O software é fornecido "no estado em que se encontra", sem garantia de qualquer
+   tipo. O uso do Treasy segue os termos de uso do serviço contratado.
+
+5. Responsabilidade. Na máxima extensão permitida pela lei, a Treasy não responde por dano
+   indireto decorrente do uso deste software. Nada aqui limita direito que a lei brasileira
+   garanta ao consumidor.
+
+Dúvidas sobre esta licença: fale com o suporte da Treasy.

treasy_mcp-0.0.0.dev0/MANIFEST.in

@@ -0,0 +1,6 @@
+# O sdist leva só o que o wheel precisa para ser reconstruído (003968): nada de testes nem de _data_ vivo.
+prune tests
+prune _data_/runtime
+prune _data_/build
+prune helm
+global-exclude *.py[cod] __pycache__ .env .env.*

treasy_mcp-0.0.0.dev0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: treasy-mcp
+Version: 0.0.0.dev0
+Summary: Servidor MCP do Treasy: o seu Treasy FP&A dentro do Claude Code, com login pelo navegador
+Author: Treasy
+License-Expression: LicenseRef-Treasy-Proprietaria
+Keywords: treasy,mcp,claude,fpa,orcamento
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<1.27,>=1.5.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: openpyxl>=3.1
+Dynamic: license-file
+
+# treasy-mcp: o seu Treasy dentro do Claude Code
+
+O `treasy-mcp` liga o Claude Code à sua conta do Treasy FP&A. Depois de instalado, você pede ao
+Claude, em português, o que hoje faz no Treasy, e ele consulta os seus dados com o seu usuário.
+
+Em produção o pacote é **somente leitura**: ele consulta, nunca altera.
+
+## 1. Instale o `uv` (uma vez por computador)
+
+O `uv` é o programa que baixa e roda o `treasy-mcp`. Se o comando `uv --version` já responde,
+pule para o passo 2.
+
+**Windows** (no PowerShell):
+
+```powershell
+winget install --id astral-sh.uv -e
+```
+
+**macOS** (no Terminal):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+**Linux** (no terminal):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Feche e abra o terminal depois de instalar.
+
+## 2. Ligue o Treasy ao Claude Code (a linha da instalação)
+
+```bash
+claude mcp add treasy -- uvx treasy-mcp
+```
+
+## 3. Entre com o seu usuário do Treasy (a linha do login)
+
+```bash
+uvx treasy-mcp login
+```
+
+O navegador abre na página de login do Treasy. Entre com o seu e-mail e a sua senha de sempre.
+A senha fica só no navegador: o `treasy-mcp` guarda uma sessão no seu computador, na pasta
+`.treasy` da sua pasta de usuário, e nunca vê a senha.
+
+## 4. Pronto: peça ao Claude
+
+Abra o Claude Code e peça, por exemplo: "liste as minhas empresas no Treasy".
+
+## Quando algo não funciona
+
+Rode o diagnóstico e mande as seis linhas ao suporte da Treasy (elas não têm segredo):
+
+```bash
+uvx treasy-mcp doctor
+```
+
+| O que aparece | O que fazer |
+|---|---|
+| `sem sessão de prod` | Rode `uvx treasy-mcp login`. |
+| `a sessão de prod venceu` | Rode `uvx treasy-mcp login` de novo. |
+| `porta 47650 ocupada` | Feche o programa que usa a porta 47650 e rode o login de novo. |
+| `não respondeu` no SSO ou na API | Confira a internet, o proxy ou o firewall da empresa para `*.treasy.com.br`. |
+
+Outros comandos:
+
+```bash
+uvx treasy-mcp status     # mostra a sessão gravada (nunca o token)
+uvx treasy-mcp sair       # apaga a sessão deste computador
+uvx treasy-mcp --version  # a versão instalada
+```
+
+Para usar outro ambiente que a Treasy lhe indicar (`qa` ou `sandbox`), acrescente o nome ao
+login (`uvx treasy-mcp login sandbox`) e ligue o Claude com a variável do ambiente:
+`claude mcp add treasy -e TREASY_AMBIENTE=sandbox -- uvx treasy-mcp`.

treasy_mcp-0.0.0.dev0/README.md

@@ -0,0 +1,448 @@
+# treasy-copilot-mcp
+Treasy Copilot MCP
+
+> **Para instalar no Claude Code como cliente** (sem clonar este repositório), siga o
+> [`INSTALAR.md`](INSTALAR.md): é a fonte única das instruções do pacote `treasy-mcp`. Para construir e
+> conferir o pacote: `python -m build` e depois `python scripts/verificar_wheel.py dist` (sai 0 limpo,
+> 1 achou segredo ou lixo, 2 não mediu).
+
+## Pré-requisitos
+
+- Python 3.11 gerenciado pelo **pyenv**
+- **pyenv-virtualenv** para criar o ambiente virtual do projeto
+> Instale o **pyenv** antes de continuar: [linux](https://github.com/pyenv/pyenv) ou [windows](https://github.com/pyenv-win/pyenv-win). Para gerenciar ambientes virtuais pelo pyenv, instale também o [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv).
+
+## Primeira execução do projeto
+
+Siga os passos abaixo após baixar ou clonar o projeto pela primeira vez.
+
+### 1. Instalar o Python e criar o virtualenv com pyenv
+
+```bash
+pyenv install 3.11
+pyenv virtualenv 3.11 treasy-copilot-mcp
+pyenv local treasy-copilot-mcp
+python --version
+```
+
+O comando `pyenv local treasy-copilot-mcp` cria o arquivo `.python-version` na raiz do projeto. Assim, sempre que você estiver nesta pasta, o `pyenv` selecionará automaticamente o ambiente virtual `treasy-copilot-mcp`.
+
+Se a versão `3.11` não estiver disponível no seu ambiente, instale uma versão específica do Python 3.11, por exemplo:
+
+```bash
+pyenv install 3.11.9
+pyenv virtualenv 3.11.9 treasy-copilot-mcp
+pyenv local treasy-copilot-mcp
+python --version
+```
+
+Para confirmar que o virtualenv do pyenv está ativo:
+
+```bash
+pyenv version
+pyenv which python
+```
+
+### 2. Instalar as dependências
+
+Para instalar o projeto em modo editável com as dependências de execução:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e .
+```
+
+Se também for rodar testes localmente, instale as dependências de desenvolvimento:
+
+```bash
+python -m pip install -r requirements-dev.txt
+```
+
+### 3. Configurar variáveis de ambiente
+
+Crie o arquivo `.env` a partir do exemplo:
+
+```bash
+cp .env.example .env
+```
+
+No Windows PowerShell:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Depois, preencha no `.env` os valores necessários:
+
+```env
+TREASY_CLIENT_SECRET=
+TREASY_CLIENT_SECRET_QA=
+TREASY_API_BASE_URL_SANDBOX=
+```
+
+### 4. Inicializar o servidor MCP
+
+Com o ambiente virtual do pyenv ativo, execute:
+
+```bash
+python -m treasy_mcp
+```
+
+Após instalar o projeto com `python -m pip install -e .`, também é possível iniciar pelo script:
+
+```bash
+treasy-mcp
+```
+
+Por padrão, a execução local usa transporte stdio. Para rodar o MCP como serviço HTTP separado, use:
+
+```bash
+MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=7000 python -m treasy_mcp
+```
+
+Nesse modo, o endpoint MCP fica disponível em:
+
+```text
+http://localhost:7000/mcp
+```
+
+No Docker Compose da raiz do projeto agregador, esse serviço é chamado pelo backend em:
+
+```text
+http://treasy-copilot-mcp:7000/mcp
+```
+
+### 5. Rodar os testes
+
+```bash
+pytest
+```
+
+### 6. Login pelo navegador (opcional, sem guardar senha)
+
+Para usar o Treasy MCP no Claude Code sem deixar a senha num arquivo, a pessoa entra pelo navegador
+com um comando que ela mesma roda no terminal. O comando abre a tela do Keycloak (Authorization Code
+com PKCE, client público, sem segredo), confere que a API aceita o token e grava só o `refresh_token`
+em `%USERPROFILE%\.treasy\sessao-<ambiente>.json`, o arquivo que o modo claude-code já lê. O MCP nunca
+abre navegador sozinho, e este módulo não é importado por nenhum outro (o Copilot não o sente).
+
+Não há nada a configurar: o client público `treasy-mcp-navegador` (esforço `002677`, nos três
+ambientes) já vem no programa. A variável `TREASY_CLIENT_ID_NAVEGADOR_<AMBIENTE>` só existe para
+trocá-lo, se a Treasy pedir; o `ambassador` nunca serve. Na pasta do projeto:
+
+```powershell
+python -m treasy_mcp.login_navegador login sandbox   # prod | qa | sandbox
+python -m treasy_mcp.login_navegador status          # o que está gravado (nunca o token)
+python -m treasy_mcp.login_navegador sair sandbox    # apaga a sessão deste computador
+```
+
+- O `login` diz o ambiente e o host antes de abrir o navegador, e no fim com que e-mail entrou.
+- A volta usa `http://127.0.0.1:47650/callback`; essa é a `redirect_uri` cadastrada no client. Outra
+  porta só serve se estiver cadastrada (`TREASY_NAVEGADOR_PORTA` ou `--porta`).
+- Escopos pedidos: `openid email profile` (`TREASY_NAVEGADOR_ESCOPOS` troca; `offline_access` faz o
+  refresh durar dias em disco).
+- Sem navegador (`--sem-abrir` ou o navegador não abre): o comando imprime o endereço; abra-o no
+  MESMO computador em que o comando roda. Em terminal SSH ou WSL o comando avisa isso antes de
+  esperar. Sessão remota (nuvem, Remote Control) não é suportada.
+- Códigos de saída: `0` fez; `1` o SSO ou a API recusou; `2` não fez (ambiente sem login liberado,
+  porta ocupada, tempo esgotado de 180 s, rede, ambiente `local`, que não usa SSO).
+- A sessão dura no máximo 10 h (o teto do Keycloak): depois disso, um novo `login`.
+- Qualquer falha deixa o arquivo de sessão anterior como estava. A senha do `.env` não é apagada:
+  se ela existir, o comando só avisa qual linha remover.
+- O `sair` apaga a sessão deste computador e deixa a marca `sair-<ambiente>.json`: um servidor MCP já
+  aberto larga a sessão no pedido seguinte e passa a pedir login. Ele não encerra a sessão no
+  Keycloak: a versão da Treasy não revoga só o acesso do MCP, e encerrar a sessão derrubaria também o
+  T30 web. O refresh já emitido segue válido lá até vencer, mas não fica guardado em lugar nenhum.
+- Sem o segredo do `ambassador` (quem não é da casa), o MCP nunca tenta a senha: o único caminho é
+  este login.
+
+## Modo claude-code (login sozinho, só por stdio)
+
+Para usar o Treasy MCP dentro do Claude Code com o seu usuário, sem a senha passar pelo chat.
+O modo liga só com as **duas** variáveis juntas, no processo que o Claude Code lança:
+
+```env
+TREASY_MCP_MODO=claude-code
+TREASY_AMBIENTE=sandbox        # prod | qa | sandbox | local
+```
+
+- Sem `TREASY_MCP_MODO`, nada muda: é o modo do backend do Copilot (`treasy_set_token`).
+- Valor inválido em qualquer uma das duas, ou `MCP_TRANSPORT=http`, e o processo não sobe.
+- `treasy_login` e `treasy_set_token` somem da lista e são recusados.
+- **Prod escreve com confirmação a cada chamada** (seção "Escrita em produção", abaixo); só o operador desliga,
+  com `TREASY_MCP_ESCRITA_PROD=off`. qa, sandbox e local escrevem com a mesma confirmação.
+- Em sandbox, qa e local a escrita pelo gateway exige `TREASY_GATEWAY_WRITES` no ambiente do processo que lança o
+  MCP, porque o `.env` do modo só carrega `TREASY_CLIENT_SECRET*`, `TREASY_API_BASE_URL_*` e `TREASY_SSO_URL_*`.
+- `treasy_listar_empresas` lê todas as páginas e aceita `filtro` (parte do nome ou do CNPJ);
+  `treasy_selecionar_empresa` só aceita id que veio dessa lista e passa a mandar `XXX-LITE-EMPRESA`.
+
+**Onde mora o seu login.** Num arquivo fora de qualquer repositório, que só você edita:
+`%USERPROFILE%\.treasy\treasy-mcp.env` (ou o caminho em `TREASY_CREDENCIAIS_FILE`), com
+`TREASY_LOGIN_<AMBIENTE>` e `TREASY_SENHA_<AMBIENTE>` (`PROD`, `QA`, `SANDBOX`). Os segredos do
+client `ambassador` continuam no `.env` deste repositório (ou no arquivo de `TREASY_ENV_FILE`).
+
+```powershell
+python -m treasy_mcp.credenciais modelo           # cria o arquivo com as chaves vazias (nunca sobrescreve)
+python -m treasy_mcp.credenciais status           # diz por ambiente se há login e senha, sem mostrar valor
+python -m treasy_mcp.credenciais medir sandbox    # UM login: ok ou negado, e os prazos dos tokens
+python -m treasy_mcp.modo listar escrita          # as ferramentas de uma classe, uma por linha
+```
+
+**A sessão.** O `refresh_token` fica em `%USERPROFILE%\.treasy\sessao-<ambiente>.json` e é tentado
+antes da senha. Se o SSO recusar a senha, o MCP não tenta de novo até o arquivo de credenciais
+mudar (`senha-negada-<ambiente>.json`), para não bloquear a sua conta. Nunca cole a senha no chat.
+
+### Escrita em produção
+
+No modo `claude-code` com `TREASY_AMBIENTE=prod`, o MCP faz CRUD completo (criar, alterar, excluir, pelas
+ferramentas dedicadas e pelo `treasy_api_executar`), **sempre com o humano no meio**:
+
+1. **Confirmação a cada escrita.** Se o cliente MCP atende `elicitation`, o servidor pergunta ao humano, com o
+   resumo (verbo, alvo, empresa com id e nome, ambiente; excluir diz "NÃO se desfaz"), e só grava com "aceitar".
+   Senão, a 1ª chamada devolve `requer_confirmacao` com o resumo e um `confirmacao_id` de uso único, que vale 60 s
+   e só com os mesmos argumentos e a mesma empresa ativa. `confirmar_escrita=true` sozinho não grava.
+2. **Auditoria antes.** Cada escrita grava duas linhas (`pedido` e `resultado`, ligadas por `id_do_evento`, esquema
+   `v1`) em `~/.treasy/auditoria/AAAA-MM.jsonl` (`TREASY_MCP_AUDITORIA_DIR` troca a pasta; arquivos com mais de
+   180 dias saem). `senha`, `token`, CPF e e-mail saem mascarados. Se a linha `pedido` não grava, nada é enviado.
+3. **Teto.** 10 escritas por minuto e 50 por sessão (`TREASY_MCP_TETO_POR_MINUTO`, `TREASY_MCP_TETO_POR_SESSAO`).
+4. **Resposta incerta.** Timeout, 5xx ou corpo ilegível depois do envio: "a gravação pode ter acontecido: confira com
+   a leitura antes de repetir".
+
+**Como o operador desliga:** `TREASY_MCP_ESCRITA_PROD=off` no ambiente do processo que lança o MCP. Com ela, prod volta
+a ser somente leitura (as escritas somem da lista e são recusadas). Só `off` e vazio são aceitos; outro valor e o
+processo não sobe. A variável não vale fora de prod, nem fora do modo.
+
+**Códigos de `motivo`** (estáveis; a recusa volta como `{"recusado": true, "motivo": ..., "mensagem": ...}`):
+
+| `motivo` | Quando |
+|---|---|
+| `desligada_pelo_operador` | `TREASY_MCP_ESCRITA_PROD=off` em prod |
+| `segredo_ou_plataforma` | operação de segredo ou de plataforma pelo `treasy_api_executar`, recusada em prod |
+| `teto` | 10 por minuto ou 50 por sessão atingidos |
+| `auditoria` | a linha `pedido` não pôde ser gravada; nada foi enviado |
+| `autenticacao` | `treasy_login` e `treasy_set_token` no modo |
+| `sem_classe` | ferramenta fora das classes leitura, escrita e autenticação |
+| `negada_pelo_humano` | o humano recusou a pergunta do cliente MCP |
+| `confirmacao_desconhecida` | `confirmacao_id` que o servidor não emitiu |
+| `confirmacao_ja_usada` | `confirmacao_id` reusado |
+| `confirmacao_expirada` | `confirmacao_id` com mais de 60 s |
+| `confirmacao_divergente` | argumentos ou empresa ativa diferentes dos do pedido |
+
+**Risco residual, no caminho por id.** O `confirmacao_id` volta ao modelo, que pode repeti-lo sem mostrar o resumo
+ao usuário: nesse caminho a barreira contra uma instrução maliciosa é fraca. O caminho por `elicitation` não tem
+esse furo, porque a pergunta vai direto ao humano. Não há desfazer: o que o T30 gravou só se corrige gravando de novo.
+
+**Fora de prod.** Dentro do modo, qa, sandbox e local têm a mesma confirmação, auditoria e teto. Só a recusa de
+segredo e plataforma (`segredo_ou_plataforma`) e o interruptor do operador valem apenas em prod. Antes de pedir,
+o servidor lê o alvo (GET do mesmo caminho, só se liberado) e mostra nome, valor e antes e depois; sem leitura
+prévia, o resumo diz "sem leitura prévia". Fora do modo (Copilot) nada muda.
+
+<br>
+<br>
+
+----
+
+## Enviar e baixar arquivo pelo gateway (003966)
+
+- **Enviar** (anexo de fato, causa, ação ou comentário; logo; foto): peça ao Claude passando o **caminho completo** do arquivo, por exemplo `C:/Users/ana/Documents/nota.pdf`. O `treasy_api_executar` recebe isso em `arquivos` (`{"file": "<caminho>"}`) e os demais campos em `campos`. Antes de enviar, ele mostra ambiente, schema, empresa, nome, bytes e sha256 e pede a sua confirmação; se o arquivo mudar entre o resumo e a confirmação, nada sobe.
+- **Baixar**: o arquivo vai para `~/treasy-exportacoes/<ambiente>/<schema>/arquivos/` (ou `TREASY_EXPORTACAO_DIR`), e o Claude recebe só o caminho, o tamanho e o sha256. Conteúdo executável ganha a extensão `.bin`.
+- **Limites**: 50 MB nos dois sentidos (`TREASY_ARQUIVO_TETO_ENVIO_MB`, `TREASY_ARQUIVO_TETO_DOWNLOAD_MB`); o servidor do T30 corta o pedido entre 45 e 50 MB (medido no sandbox em 2026-11-01). Tipos que sobem: pdf, png, jpg, jpeg, xlsx, csv, txt, docx. `TREASY_ENVIO_DIR` restringe o envio a uma pasta. Pastas sensíveis (`.treasy`, `.ssh`, `.git`, `.env*`, chaves) nunca sobem. Envio em produção está desligado; o servidor por HTTP remoto não vê o seu disco e recusa.
+- **Troca de logo**: o MCP baixa o logo atual para a pasta acima antes de trocar; se não conseguir, não troca.
+
+## Exportar o resultado de uma consulta para arquivo
+
+A ferramenta `treasy_exportar` roda por dentro uma ferramenta de **leitura** e grava o resultado em
+arquivo. Ao modelo volta só o caminho, o formato e as contagens de linhas e colunas: nenhuma célula
+entra na conversa. Ela só existe no **modo claude-code** (`TREASY_MCP_MODO=claude-code`); fora dele
+não aparece na lista e, se for chamada, é recusada sem tocar em rede nem em disco.
+
+| Argumento | O que é |
+|---|---|
+| `ferramenta` | nome da leitura a consultar (ex.: `treasy_listar_contas`) |
+| `argumentos` | os argumentos dessa leitura (opcional) |
+| `formato` | `csv`, `xlsx` ou `json` (obrigatório) |
+
+- **Pasta:** `%USERPROFILE%\treasy-exportacoes\<ambiente>\<schema>\`. `TREASY_EXPORTACAO_DIR` (caminho
+  absoluto) troca a pasta base. O MCP recusa destino dentro de um repositório git ou de uma pasta do
+  OneDrive. O nome do arquivo é gerado pelo MCP (`<ferramenta>_AAAAMMDD-HHMMSS.<formato>`) e nunca
+  sobrescreve outro.
+- **CSV:** `utf-8-sig`, separador `;`, vírgula decimal (o formato que o Excel em português abre). A origem
+  (ambiente, empresa, CNPJ, ferramenta, hora) vai no arquivo irmão `.origem.json`; no Excel, na aba
+  `Origem`; no JSON, em `_origem`.
+- **Excel:** precisa do pacote `openpyxl`, que **não** é dependência declarada do MCP. Sem ele, o
+  `xlsx` recusa com a instrução `pip install openpyxl` e o CSV e o JSON seguem funcionando.
+- **O que é recusado:** escrita, login, `treasy_selecionar_empresa`, a própria exportadora, empresa não
+  selecionada, `schema` diferente do selecionado, mais de 200 mil linhas e ferramenta que devolve texto
+  de tela em vez de tabela.
+- **Gateway:** `treasy_exportar` não exporta resposta do gateway, porque `treasy_api_executar` é de escrita.
+- **Cuidado:** o arquivo fica em texto puro no disco. O Claude Code não deve lê-lo (`Read`, `Bash`):
+  a negação de leitura dessa pasta é configurada no esforço `002676`.
+
+----
+
+# SANDBOX
+
+## Build
+
+```bash
+docker build -t treasy/sandbox/treasy-copilot-mcp . -f Dockerfile
+```
+
+## Scripts Helm
+
+### install
+
+```bash
+helm install treasy-copilot-mcp helm/sandbox/. --debug
+```
+
+### install test
+
+```bash
+helm install treasy-copilot-mcp helm/sandbox/. --dry-run --debug
+```
+
+### upgrade
+
+```bash
+helm upgrade treasy-copilot-mcp helm/sandbox/. --debug
+```
+
+### upgrade test
+
+```bash
+helm upgrade treasy-copilot-mcp helm/sandbox/. --dry-run --debug
+```
+
+### rollback
+
+```bash
+helm rollback treasy-copilot-mcp --debug
+```
+
+### delete
+
+```bash
+helm delete treasy-copilot-mcp --debug
+```
+
+### package
+
+```bash
+helm package treasy-copilot-mcp helm/sandbox/. --debug
+```
+
+<br>
+<br>
+
+----
+
+# QA
+
+## Build
+
+```bash
+docker build -t treasy/qa/treasy-copilot-mcp . -f Dockerfile
+```
+
+## Scripts Helm
+
+### install
+
+```bash
+helm install treasy-copilot-mcp-qa helm/qa/. --debug
+```
+
+### install test
+
+```bash
+helm install treasy-copilot-mcp-qa helm/qa/. --dry-run --debug
+```
+
+### upgrade
+
+```bash
+helm upgrade treasy-copilot-mcp-qa helm/qa/. --debug
+```
+
+### upgrade test
+
+```bash
+helm upgrade treasy-copilot-mcp-qa helm/qa/. --dry-run --debug
+```
+
+### rollback
+
+```bash
+helm rollback treasy-copilot-mcp-qa --debug
+```
+
+### delete
+
+```bash
+helm delete treasy-copilot-mcp-qa --debug
+```
+
+### package
+
+```bash
+helm package treasy-copilot-mcp-qa helm/qa/. --debug
+```
+
+
+<br>
+<br>
+
+----
+
+# MASTER (PROD)
+
+## Build
+
+```bash
+docker build -t treasy/master/treasy-copilot-mcp . -f Dockerfile
+```
+
+## Scripts Helm
+
+### install
+
+```bash
+helm install treasy-copilot-mcp helm/master/. --debug
+```
+
+### install test
+
+```bash
+helm install treasy-copilot-mcp helm/master/. --dry-run --debug
+```
+
+### upgrade
+
+```bash
+helm upgrade treasy-copilot-mcp helm/master/. --debug
+```
+
+### upgrade test
+
+```bash
+helm upgrade treasy-copilot-mcp helm/master/. --dry-run --debug
+```
+
+### rollback
+
+```bash
+helm rollback treasy-copilot-mcp --debug
+```
+
+### delete
+
+```bash
+helm delete treasy-copilot-mcp --debug
+```
+
+### package
+
+```bash
+helm package treasy-copilot-mcp helm/master/. --debug
+```