fin-app-mcp 2.0.0 → 2.1.0

package/README.md

@@ -14,13 +14,31 @@ MCP server que expõe as operações do FIN (finanças pessoais) para qualquer L
 - Uma instância do FIN rodando (local ou na nuvem)
 - Service token configurado no FIN (endpoint `/api/genius/*`)
 
-## Setup
+## Setup (recomendado) — com API Key
 
-### Opção A: via npx (recomendado — zero instalação)
+Cada usuário gera sua própria chave no app FIN. Zero fricção, nada de tokens compartilhados.
 
-Não precisa clonar nem instalar nada. O `npx` baixa e executa automaticamente.
+### Passo 1: Gerar uma API Key
 
-#### Claude Code (settings.json)
+1. Acesse o app FIN (web ou mobile)
+2. Vá em **Configurações → Chaves de API**
+3. Clique em **"Nova chave"**
+4. Dê um nome (ex: "Claude Code", "Personal Genius")
+5. Copie a chave gerada (`fin_live_xxx`) — **ela só é mostrada uma vez**
+
+### Passo 2: Configurar o Claude Code
+
+Um único comando:
+
+```bash
+claude mcp add fin-app \
+  -s user \
+  -e FIN_BASE_URL=https://fin-app-wine.vercel.app \
+  -e FIN_API_KEY=fin_live_xxx \
+  -- npx -y fin-app-mcp
+```
+
+Ou edite manualmente o `settings.json` do Claude Code:
 
 ```json
 {
@@ -29,40 +47,74 @@ Não precisa clonar nem instalar nada. O `npx` baixa e executa automaticamente.
       "command": "npx",
       "args": ["-y", "fin-app-mcp"],
       "env": {
-        "FIN_BASE_URL": "https://fin.example.com",
-        "FIN_SERVICE_TOKEN": "seu-token-aqui",
-        "FIN_USER_ID": "seu-user-id-aqui"
+        "FIN_BASE_URL": "https://fin-app-wine.vercel.app",
+        "FIN_API_KEY": "fin_live_xxx"
       }
     }
   }
 }
 ```
 
-Reinicie o client MCP. O server deve aparecer com as tools disponíveis.
+### Passo 3: Testar
 
-### Opção B: instalação global
+Reinicie o Claude Code. Rode `claude mcp list` — o `fin-app` deve aparecer como conectado. As tools do FIN ficam disponíveis automaticamente.
 
-```bash
-npm install -g fin-app-mcp
-```
+### Variáveis de ambiente
+
+| Variável | Descrição |
+|----------|-----------|
+| `FIN_BASE_URL` | URL base da instância do FIN (ex: `https://fin-app-wine.vercel.app`) |
+| `FIN_API_KEY` | API key pessoal (`fin_live_xxx`) gerada em `/settings/api-keys` |
+
+---
+
+## Setup legado — com Service Token (backward-compat)
+
+Modo antigo, ainda suportado. Requer conhecer o `FIN_SERVICE_TOKEN` (env var do deploy) e o UUID do usuário no Supabase.
 
-Claude Code (settings.json):
 ```json
 {
   "mcpServers": {
     "fin-app": {
-      "command": "fin-app-mcp",
+      "command": "npx",
+      "args": ["-y", "fin-app-mcp"],
       "env": {
-        "FIN_BASE_URL": "https://fin.example.com",
-        "FIN_SERVICE_TOKEN": "seu-token-aqui",
-        "FIN_USER_ID": "seu-user-id-aqui"
+        "FIN_BASE_URL": "https://fin-app-wine.vercel.app",
+        "FIN_SERVICE_TOKEN": "shared-secret",
+        "FIN_USER_ID": "uuid-do-usuario"
       }
     }
   }
 }
 ```
 
-### Opção C: clone local (para desenvolvimento)
+Variáveis:
+
+| Variável | Descrição |
+|----------|-----------|
+| `FIN_BASE_URL` | URL base da instância do FIN |
+| `FIN_SERVICE_TOKEN` | Service token compartilhado |
+| `FIN_USER_ID` | UUID do usuário no Supabase |
+
+Se `FIN_API_KEY` e as variáveis legadas estiverem setadas juntas, `FIN_API_KEY` tem precedência.
+
+---
+
+## Opções de instalação
+
+### Via npx (padrão)
+
+O `npx -y fin-app-mcp` baixa e executa automaticamente. Updates automáticos na próxima invocação.
+
+### Instalação global
+
+```bash
+npm install -g fin-app-mcp
+```
+
+Depois use `"command": "fin-app-mcp"` na config (sem `npx`).
+
+### Clone local (desenvolvimento)
 
 ```bash
 git clone https://github.com/pe-menezes/fin-app.git
@@ -70,30 +122,7 @@ cd fin-app/mcp-server
 npm install
 ```
 
-Claude Code (settings.json):
-```json
-{
-  "mcpServers": {
-    "fin-app": {
-      "command": "node",
-      "args": ["/caminho/para/fin-app/mcp-server/index.mjs"],
-      "env": {
-        "FIN_BASE_URL": "https://fin.example.com",
-        "FIN_SERVICE_TOKEN": "seu-token-aqui",
-        "FIN_USER_ID": "seu-user-id-aqui"
-      }
-    }
-  }
-}
-```
-
-### Variáveis de ambiente
-
-| Variável | Descrição |
-|----------|-----------|
-| `FIN_BASE_URL` | URL base da instância do FIN (ex: `https://fin.example.com` ou `http://localhost:3000`) |
-| `FIN_SERVICE_TOKEN` | Service token para autenticação na API Genius |
-| `FIN_USER_ID` | UUID do usuário no FIN |
+Aponte o `command` pro `index.mjs` local.
 
 ## Resource: Guia do FIN
 

package/index.mjs

@@ -12,20 +12,47 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 
 // ── Config ──────────────────────────────────────────────────────────
+//
+// Auth modes (in order of preference):
+//
+// 1. Per-user API key (recommended):
+//    FIN_BASE_URL=https://fin-app-wine.vercel.app
+//    FIN_API_KEY=fin_live_xxx   ← gerada em /settings/api-keys no app
+//
+// 2. Legacy shared service token (backward-compat):
+//    FIN_BASE_URL=https://fin-app-wine.vercel.app
+//    FIN_SERVICE_TOKEN=<shared secret>
+//    FIN_USER_ID=<supabase uuid>
+//
 const BASE_URL = process.env.FIN_BASE_URL;
-const TOKEN = process.env.FIN_SERVICE_TOKEN;
-const USER_ID = process.env.FIN_USER_ID;
+const API_KEY = process.env.FIN_API_KEY;
+const LEGACY_TOKEN = process.env.FIN_SERVICE_TOKEN;
+const LEGACY_USER_ID = process.env.FIN_USER_ID;
 
-if (!BASE_URL || !TOKEN || !USER_ID) {
-  console.error("Missing env: FIN_BASE_URL, FIN_SERVICE_TOKEN, FIN_USER_ID");
+if (!BASE_URL) {
+  console.error("Missing env: FIN_BASE_URL");
   process.exit(1);
 }
 
-const headers = {
-  Authorization: `Bearer ${TOKEN}`,
-  "X-Genius-User-Id": USER_ID,
-  "Content-Type": "application/json",
-};
+if (!API_KEY && !(LEGACY_TOKEN && LEGACY_USER_ID)) {
+  console.error(
+    "Missing auth config. Set FIN_API_KEY (recomendado) ou " +
+      "FIN_SERVICE_TOKEN + FIN_USER_ID (legado).\n" +
+      "Gere uma API key em: " + BASE_URL + "/settings/api-keys"
+  );
+  process.exit(1);
+}
+
+const headers = API_KEY
+  ? {
+      Authorization: `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+    }
+  : {
+      Authorization: `Bearer ${LEGACY_TOKEN}`,
+      "X-Genius-User-Id": LEGACY_USER_ID,
+      "Content-Type": "application/json",
+    };
 
 // ── Resource content ────────────────────────────────────────────────
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fin-app-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MCP server para o FIN App — finanças pessoais. Expõe tools para agents LLM operarem contas, despesas, faturas de cartão, bills recorrentes e mais.",
   "type": "module",
   "main": "index.mjs",