Agente Financeiro

Aplicativo de finanças pessoais com interface mobile, API própria e integração com agentes de IA. O projeto nasceu como laboratório de estudos sobre FastAPI, React Native, OpenWebUI e Model Context Protocol (MCP), mas também busca resolver um problema real: registrar gastos em linguagem natural e acompanhar o orçamento mensal.

Status: em desenvolvimento. O fluxo local funciona, mas autenticação multiusuário e RLS ainda estão em implementação. Não use em produção nem armazene dados financeiros sensíveis antes de concluir os itens de segurança.

Funcionalidades

• Registro, consulta, busca e exclusão de gastos.

• Salário fixo, meta de economia e saldo mensal disponível.

• Relatório e limite de gastos por categoria.

• Alertas quando uma categoria se aproxima ou ultrapassa seu orçamento.

• Conversa em linguagem natural por meio do OpenWebUI.

• Servidor MCP Streamable HTTP com nove ferramentas financeiras.

• Persistência no PostgreSQL do Supabase.

Related MCP server: Expense Tracker MCP Server

Arquitetura

Expo / React Native
        |
        v
FastAPI REST  <------  servidor MCP  <------  cliente de IA
        |
        v
Supabase PostgreSQL + Auth + RLS

A arquitetura final manterá o OpenWebUI invisível atrás da FastAPI. Dessa forma, a chave do OpenWebUI permanece no servidor e o aplicativo envia apenas o access token do usuário autenticado no Supabase.

Leia a explicação do MCP para entender o protocolo e o caminho de uma chamada de ferramenta.

Tecnologias

Estrutura do repositório

.
├── backend/                 # API FastAPI, MCP, testes e migrações SQL
│   ├── app/
│   ├── migrations/
│   └── tests/
├── frontend/                # Aplicativo Expo/React Native
├── docs/                    # Arquitetura, MCP e roadmap
├── docker-compose.yml       # API
└── docker-compose.mcp.yml   # Extensão do Compose para o MCP

Pré-requisitos

• Docker com Docker Compose; ou

• Python 3.12 e Node.js 20.19 ou superior dentro da versão 20.

• Um projeto Supabase.

• OpenWebUI somente para testar o chat com IA.

Configuração local

1. Backend

cp backend/.env.example backend/.env

Preencha no arquivo local:

SUPABASE_URL=https://SEU_PROJETO.supabase.co
SUPABASE_KEY=SUA_CHAVE_ANON_OU_PUBLISHABLE

Nunca envie .env, access tokens, JWT secrets ou chaves administrativas para o GitHub.

Para executar API e MCP juntos:

docker compose -f docker-compose.yml -f docker-compose.mcp.yml up --build

• Documentação da API: http://localhost:8000/docs

• Healthcheck da API: http://localhost:8000/health

• Endpoint MCP: http://localhost:8001/mcp

• Healthcheck do MCP: http://localhost:8001/health

2. Frontend

cp frontend/.env.example frontend/.env
cd frontend
npm ci
npm start

Troque EXPO_PUBLIC_LOCAL_IP pelo IP da máquina que executa a API. Variáveis EXPO_PUBLIC_* são incluídas no aplicativo compilado e nunca devem conter segredos.

O chat atual ainda usa a integração direta de desenvolvimento com o OpenWebUI. Antes de uma distribuição real, ele será substituído pela rota protegida /agent da FastAPI.

Testes

Backend:

cd backend
python -m pip install -r requirements-mcp.txt
pytest

Frontend:

cd frontend
npm ci
npx tsc --noEmit
npx expo-doctor

Cada pull request executa verificações automáticas no GitHub Actions.

Banco de dados e RLS

As migrações ficam em backend/migrations/. A migração 002_multi_user_rls.sql contém um placeholder proposital e não deve ser executada até que o backend encaminhe corretamente o JWT Supabase ao PostgREST.

Ordem planejada:

1. Implementar login pelo Supabase Auth.

2. Criar um cliente Supabase isolado por requisição.

3. Migrar os registros existentes para o UUID do proprietário.

4. Ativar e testar as políticas RLS com dois usuários diferentes.

Contribuição

Consulte CONTRIBUTING.md para convenções de branches, commits, testes e pull requests.

Segurança

Este projeto manipula informações financeiras. Não publique dados reais em issues, logs, screenshots ou fixtures. Leia SECURITY.md antes de relatar uma vulnerabilidade.

Roadmap

O planejamento técnico está em docs/ROADMAP.md.

Licença

Nenhuma licença de código aberto foi escolhida ainda. Até que um arquivo LICENSE seja adicionado, todos os direitos permanecem reservados ao autor.