EconomizAPP MCP Server

Um servidor MCP (Model Context Protocol) para integração com o sistema de controle de custos EconomizAPP. Este servidor permite que assistentes de IA como Claude Desktop e VS Code acessem e manipulem dados de transações financeiras através do protocolo MCP.

🚀 Instalação Rápida via NPX

npx economizapp-mcp-server

📋 Funcionalidades

• Gerenciamento de Bancos: Criar, listar, atualizar e excluir bancos
• Tipos de Despesa: Gerenciar categorias de despesas
• Métodos de Pagamento: Configurar diferentes formas de pagamento
• Transações: Criar e consultar transações financeiras
• Integração Azure: Suporte ao Azure Key Vault para variáveis sensíveis
• Fallback Local: Funcionamento com variáveis de ambiente locais

🛠️ Configuração

Variáveis de Ambiente

Crie um arquivo .env baseado no .env.example:

# API Configuration
CUSTOS_API_BASE_URL=https://sua-api.azurewebsites.net

# Azure Key Vault (opcional)
AZURE_KEY_VAULT_URL=https://seu-keyvault.vault.azure.net/
AZURE_CLIENT_ID=seu-client-id
AZURE_CLIENT_SECRET=seu-client-secret
AZURE_TENANT_ID=seu-tenant-id

# Fallback options (para desenvolvimento/teste)
FORCE_LOCAL_SECRETS=false
ALLOW_ENV_FALLBACK=true

Configuração no Claude Desktop

Adicione no seu claude_desktop_config.json:

{
  "mcpServers": {
    "economizapp": {
      "command": "npx",
      "args": ["economizapp-mcp-server"],
      "env": {
        "CUSTOS_API_BASE_URL": "https://sua-api.azurewebsites.net"
      }
    }
  }
}

Configuração no VS Code

Instale uma extensão MCP e configure no .vscode/mcp.json:

{
  "mcpServers": {
    "economizapp": {
      "command": "npx",
      "args": ["economizapp-mcp-server"]
    }
  }
}

🔧 Desenvolvimento

Pré-requisitos

• Node.js 18+
• NPM ou Yarn
• TypeScript

Instalação Local

git clone <repository-url>
cd backend/mcp-server
npm install

Scripts Disponíveis

# Desenvolvimento
npm run dev          # Executa em modo desenvolvimento
npm run build        # Compila TypeScript
npm run start        # Executa versão compilada

# Deploy e Publicação
npm run package      # Cria pacote de deploy
npm run prepare-npm  # Prepara para publicação no NPM
npm run publish-pkg  # Publica no NPM

# Testes
npm run test-mcp     # Testa comunicação MCP via STDIO

Estrutura do Projeto

src/
├── server.ts           # Servidor MCP principal
├── index.ts           # Entry point para execução
├── dev.ts             # Entry point para desenvolvimento
├── handlers/
│   └── validation.ts  # Validação de schemas
├── services/
│   ├── azure-client.ts    # Cliente Azure Key Vault
│   └── custos-api.ts      # API do sistema de custos
└── types/
    └── custos.ts          # Tipos TypeScript

�️ Ferramentas MCP Disponíveis

Bancos

• get_banks - Lista todos os bancos
• get_bank - Obtém detalhes de um banco específico
• create_bank - Cria um novo banco
• update_bank - Atualiza um banco existente
• delete_bank - Exclui um banco

Tipos de Despesa

• get_expensive_types - Lista tipos de despesa
• get_expensive_type - Obtém detalhes de um tipo
• create_expensive_type - Cria novo tipo de despesa
• update_expensive_type - Atualiza tipo existente
• delete_expensive_type - Exclui tipo de despesa

Métodos de Pagamento

• get_payment_methods - Lista métodos de pagamento
• get_payment_method - Obtém detalhes de um método
• create_payment_method - Cria novo método
• update_payment_method - Atualiza método existente
• delete_payment_method - Exclui método

Transações

• get_transactions - Lista transações (com filtros opcionais)
• get_transaction - Obtém detalhes de uma transação
• create_transaction - Cria nova transação

🔐 Segurança

Azure Key Vault

O servidor suporta carregamento seguro de variáveis através do Azure Key Vault:

1. Configure as credenciais do Azure no .env
2. As variáveis serão carregadas automaticamente do Key Vault
3. Em caso de falha, o sistema usa fallback para variáveis locais (se habilitado)

Variáveis de Fallback

• FORCE_LOCAL_SECRETS=true - Força uso de variáveis locais
• ALLOW_ENV_FALLBACK=true - Permite fallback para .env em caso de erro no Key Vault

🐛 Troubleshooting

Problemas Comuns

1. Erro de conexão com API

   • Verifique se CUSTOS_API_BASE_URL está correto
   • Teste a conectividade com a API

2. Falha no Azure Key Vault

   • Verifique as credenciais do Azure
   • Certifique-se que o Key Vault existe e tem as permissões corretas
   • Use FORCE_LOCAL_SECRETS=true para testes locais

3. Claude Desktop não conecta

   • Verifique se o claude_desktop_config.json está na localização correta
   • Reinicie o Claude Desktop após mudanças na configuração
   • Verifique os logs do Claude para erros

4. VS Code não reconhece o servidor

   • Instale uma extensão MCP compatível
   • Verifique a configuração em .vscode/mcp.json
   • Reinicie o VS Code

Debug Mode

Para executar com logs detalhados:

# Desenvolvimento local
npm run dev

# Via NPX com debug
DEBUG=true npx economizapp-mcp-server

Teste de Comunicação

Para testar a comunicação MCP diretamente:

npm run test-mcp

Ou teste manual via STDIO:

npx economizapp-mcp-server
# Digite: {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}}}

📖 Exemplos de Uso

Criar uma Nova Transação

// Através do MCP, você pode solicitar ao assistente:
// "Crie uma nova transação de R$ 50,00 para 'Almoço' no banco Nubank"

// O assistente usará a ferramenta create_transaction com:
{
  "valor": 50.00,
  "descricao": "Almoço",
  "idBanco": 1,
  "idTipoDespesa": 2,
  "idMetodoPagamento": 1,
  "data": "2024-01-15"
}

Consultar Transações

// "Mostre todas as transações do mês atual"
// O assistente usará get_transactions com filtros apropriados

🤝 Contribuindo

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
4. Push para a branch (git push origin feature/nova-feature)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.

🆘 Suporte

Para suporte ou dúvidas:

1. Abra uma issue no GitHub
2. Consulte a documentação do MCP: Model Context Protocol
3. Verifique os logs de erro para diagnóstico

📈 Roadmap

• [ ] Suporte a mais tipos de autenticação
• [ ] Interface web para configuração
• [ ] Métricas e monitoramento
• [ ] Suporte a múltiplas instâncias da API
• [ ] Cache inteligente de dados
• [ ] Exportação de relatórios

EconomizAPP MCP Server - Facilitando a integração entre IA e controle financeiro! 🚀💰