--- name: instalar-fin-mcp description: > Skill de FALLBACK pra configurar o MCP server do FIN App. A partir da v0.2.0, o plugin já declara o fin-app-mcp via .mcp.json e pede a API key automaticamente no install (userConfig sensitive). Essa skill só roda se o método automático falhar OU se a pessoa precisar atualizar/revogar a chave manualmente. Guia: gerar API key, editar config (Desktop) ou rodar claude mcp add (Code), troubleshooting de erros comuns. argument-hint: "(sem argumentos)" allowed-tools: Read Write Bash --- ## Como o plugin instala o MCP automaticamente (v0.2.0+) A partir da versão 0.2.0, o plugin **já declara** o `fin-app-mcp` via dois arquivos: 1. **`.mcp.json`** na raiz do plugin: declara `fin-app` com `command: npx`, `args: ["-y", "fin-app-mcp"]`, e env vars `FIN_BASE_URL` (fixa) + `FIN_API_KEY` (referenciando `${user_config.fin_api_key}`) 2. **`userConfig.fin_api_key`** no `plugin.json` com `sensitive: true` **Resultado:** quando a pessoa instala o plugin via `/plugin install`, o Claude pede a API key na hora, ela cola, e pronto. O MCP `fin-app` é registrado automaticamente. Sem editar `claude_desktop_config.json`. Sem `claude mcp add`. **Esta skill (`/financeiro:instalar-fin-mcp`) só é necessária se:** - O método automático falhou por algum bug do Claude (issue #16143 do `mcpServers` inline foi corrigido com `.mcp.json` separado, mas pode haver outros) - A pessoa pulou o prompt de userConfig sem colar a chave - A chave precisa ser revogada/regerada - A pessoa quer entender o que tá acontecendo "por baixo dos panos" ## Quando usar - **Detecção automática pelo agente principal:** o agente tentou `fin_listar_contas`, deu erro, e suspeita que o método automático não funcionou - **Pedido explícito:** "instala o FIN manualmente", "como configuro o MCP do FIN", "tô com erro de auth no FIN" - Erros: `Missing env: FIN_BASE_URL`, `unauthorized`, `auth_lookup_failed`, ou tool `fin_*` não disponível ## Quando NÃO usar - O método automático funcionou (`fin_listar_contas` retorna OK) → pular essa skill - A pessoa não tem conta no FIN App ainda → manda criar primeiro em https://fin-app-wine.vercel.app ## Pré-requisitos Antes de tudo, confirme com a pessoa: 1. **Tem conta no FIN App?** Se não, peça pra criar em https://fin-app-wine.vercel.app e pause aqui. 2. **Tem Node.js 18+ instalado?** Verificação obrigatória — ver Passo 0 abaixo. ## Passo 0 — Verificação de Node.js (OBRIGATÓRIO) O `fin-app-mcp` roda via `npx -y fin-app-mcp`, que precisa de **Node.js 18 ou superior**. Sem Node, nada funciona. Roda no terminal (via `Bash`): ```bash node --version ``` **Se retornar `v18.x.x` ou maior:** OK, segue pro Passo 1. **Se retornar versão menor que 18:** > Tu tem Node {versão} mas precisa de 18 ou maior. Atualiza assim: > > 1. Baixa a versão LTS em https://nodejs.org > 2. Roda o instalador (next-next-finish) > 3. Reinicia o terminal (e o Claude se for Desktop) > 4. Roda `node --version` de novo pra confirmar > 5. Volta aqui e me diz "atualizei" **Se retornar `command not found` / `'node' não é reconhecido como comando` / similar:** > Node.js não tá instalado no teu sistema. O `fin-app-mcp` precisa dele pra rodar. > > **Como instalar (rápido, ~5 min):** > > **Windows:** > 1. Vai em https://nodejs.org > 2. Clica no botão "LTS" (versão recomendada) > 3. Baixa o `.msi` de Windows Installer > 4. Abre o instalador, clica next-next-finish (deixa as opções padrão) > 5. **Reinicia o Claude completamente** (fecha tudo, incluindo a bandeja do sistema) > 6. Volta aqui e me diz "instalei o Node" > > **macOS:** > 1. Opção 1 (sem terminal): vai em https://nodejs.org, baixa o `.pkg` LTS, instala > 2. Opção 2 (com Homebrew): no Terminal, roda `brew install node` > 3. Reinicia o Claude > 4. Me diz "instalei" > > **Linux:** > 1. Recomendo instalar via `nvm`: https://github.com/nvm-sh/nvm > 2. Ou use o gerenciador de pacotes da tua distro (`apt`, `dnf`, etc.) pra instalar `nodejs >=18` > 3. Reinicia o Claude > 4. Me diz "instalei" > > Não consigo instalar Node sozinho — é software do sistema operacional, precisa privilégio de admin que eu não tenho. Pausa aqui. **Não segue pro Passo 1 até a pessoa confirmar que instalou e o `node --version` retornar uma versão válida.** Quando ela voltar dizendo que instalou, **roda `node --version` de novo** pra confirmar antes de seguir. ## Fluxo ### Passo 1 — Gerar a API key no FIN App Instrua a pessoa exatamente assim (não invente passos): > Você precisa gerar uma API key no FIN App. Faça o seguinte: > > 1. Acesse https://fin-app-wine.vercel.app/settings/api-keys > 2. Faça login se ainda não estiver logada > 3. Clique em **+ Nova chave** > 4. Dê um nome descritivo (ex: "Claude - {nome do computador}") > 5. Clique em **Criar chave** > 6. **Copie a chave imediatamente** (formato `fin_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`) > > ⚠️ A chave aparece **uma única vez**. Se perder, tem que revogar e gerar nova. > > Quando tiver a chave em mãos, me avisa. **IMPORTANTE:** quando a pessoa colar a chave na conversa, **avise pra ela não fazer isso** ("nunca cola chave aqui, ela fica gravada no histórico"). Peça pra ela ter a chave por perto mas não colar — você só precisa que ela cole no terminal ou no settings.json. Se ela já colou, siga adiante mas reforce que vai precisar revogar essa chave depois e gerar outra. ### Passo 2 — Detectar plataforma Pergunte ou detecte: a pessoa tá usando **Claude Code** (terminal) ou **Claude Desktop** (app)? Pra detectar via shell: `which claude` retorna caminho se Code estiver instalado. No Desktop, a config fica em `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). ### Passo 3a — Instalação no Claude Code (recomendado) Monte o comando exato e peça pra pessoa colar no terminal: ```bash claude mcp add fin-app \ -s user \ -e FIN_BASE_URL=https://fin-app-wine.vercel.app \ -e FIN_API_KEY=fin_live_SUA_CHAVE_AQUI \ -- npx -y fin-app-mcp ``` Substitua `fin_live_SUA_CHAVE_AQUI` pela chave dela. **NÃO peça pra ela colar a chave aqui na conversa pra você montar o comando.** Mostre o template, peça pra ela substituir no terminal dela mesma. A flag `-s user` instala globalmente (vale pra qualquer projeto). ### Passo 3b — Instalação no Claude Desktop A pessoa precisa editar `claude_desktop_config.json` manualmente. Localização: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Linux:** `~/.config/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Mostre o JSON pra adicionar: ```json { "mcpServers": { "fin-app": { "command": "npx", "args": ["-y", "fin-app-mcp"], "env": { "FIN_BASE_URL": "https://fin-app-wine.vercel.app", "FIN_API_KEY": "fin_live_SUA_CHAVE_AQUI" } } } } ``` **Avisos importantes:** - Se já existirem outros servers em `mcpServers`, **adicione `fin-app` como mais uma entrada**, não substitua o objeto inteiro - Substitua `fin_live_SUA_CHAVE_AQUI` pela chave real, no arquivo, fora da conversa - Não cole o JSON com a chave aqui ### Passo 4 — Reiniciar o Claude Peça pra pessoa fechar **completamente** o Claude (Code ou Desktop) e abrir de novo. A primeira invocação demora alguns segundos porque o `npx -y fin-app-mcp` baixa o pacote do npm na primeira vez. ### Passo 5 — Verificar instalação **No Claude Code:** peça pra rodar no terminal: ```bash claude mcp list ``` Procure por `fin-app` na lista. Deve aparecer como conectado. **No Claude Desktop:** peça pra ela voltar pra conversa e pedir pro Claude fazer um teste simples. Você pode rodar `fin_listar_contas` direto. Se retornar lista (mesmo vazia), tá funcionando. ### Passo 6 — Teste rápido Chame `fin_listar_contas`. Se retornar OK (lista vazia ou com contas), instalação concluída. Diga: > Pronto, MCP do FIN tá instalado e funcionando. Quer rodar o onboarding agora? (`/financeiro:onboarding`) ## Troubleshooting Quando der erro, identifique pelo sintoma e responda: | Sintoma | Causa | Solução | |---|---|---| | `claude mcp list` não mostra `fin-app` | Config não foi salva, ou Claude Code não foi reiniciado | Verifique `~/.claude/settings.json` (ou `claude_desktop_config.json`), reinicie Claude completamente | | `Missing env: FIN_BASE_URL` | Env var não foi setada na config | Reabra a config e confira que `env` tem `FIN_BASE_URL` E `FIN_API_KEY` | | `unauthorized` | API key errada, expirada ou revogada | Vá em https://fin-app-wine.vercel.app/settings/api-keys, gere nova chave, atualize a config | | `auth_lookup_failed` | Problema temporário no Supabase do FIN | Tente de novo em alguns segundos. Se persistir, verifique se o app tá no ar | | `npx` muito lento na 1ª invocação | Normal — baixando pacote (~16KB + deps) | Aguarde. Próximas invocações são instantâneas. Se >30s consistentemente, `npm cache clean --force` | | Tools `fin_*` ainda não aparecem após reiniciar | Cache do Claude, ou config em local errado | Confira que o JSON está válido (use `jq < ~/.claude/settings.json`), reinicie de novo | ## Como revogar uma chave (se vazar) Se a pessoa colou a chave em algum lugar público (incluindo essa conversa), avise: 1. Acesse https://fin-app-wine.vercel.app/settings/api-keys 2. Encontre a chave na lista de "Ativas" 3. Clique em **Revogar** e confirme 4. A revogação é instantânea 5. Gere uma nova chave e atualize a config do Claude ## Segurança - **NUNCA** peça pra pessoa colar a API key na conversa do Claude - **NUNCA** grave a API key em arquivo da pasta `Financeiro/` ou em config do plugin - A API key fica **só** no `settings.json` do Claude Code ou no `claude_desktop_config.json` do Desktop - Esses arquivos não são versionados nem sincronizados (a menos que a pessoa configure intencionalmente) ## Atualizações futuras O `npx -y fin-app-mcp` sempre baixa a última versão do pacote npm. Quando a Anthropic ou o time do FIN publicar uma nova versão, ela vai entrar automaticamente na próxima invocação. A pessoa não precisa fazer nada. Pra forçar uma versão específica, ela pode trocar `fin-app-mcp` por `fin-app-mcp@2.1.0` (ou outra versão) nos `args` da config. ## Após instalação concluída Diga pra pessoa o que fazer a seguir: > MCP do FIN instalado. Próximo passo: configurar suas contas e cartões no FIN. Rode `/financeiro:onboarding` ou só me diga "vamos configurar minhas finanças".