zaratine/conta-azul-mcp-server

MCP Server para Conta Azul ✅

Este é um servidor Model Context Protocol (MCP) que integra com a API da Conta Azul usando OAuth2.

✅ Status do Projeto

O servidor está funcionando corretamente!

📋 Testes Realizados:

• ✅ Inicialização MCP com capabilities OAuth2
• ✅ Detecção correta de requisições não autenticadas
• ✅ Resposta adequada no formato JSON-RPC MCP
• ✅ Headers de OAuth configurados corretamente

🔧 Configuração

1. Variáveis de Ambiente

Configure o arquivo .env com suas credenciais da Conta Azul:

# URL base do seu servidor MCP
BASE_URL=http://localhost:3000

# Configurações OAuth da Conta Azul (substitua pelos seus valores reais)
CONTAAZUL_CLIENT_ID=seu_client_id_da_conta_azul
CONTAAZUL_CLIENT_SECRET=seu_client_secret_da_conta_azul
CONTAAZUL_REDIRECT_URI=http://localhost:3000/oauth/callback

# Porta do servidor
PORT=3000

# Tokens de autenticação
CONTA_AZUL_ACCESS_TOKEN=your_initial_access_token
CONTA_AZUL_REFRESH_TOKEN=your_initial_refresh_token

2. Instalação e Execução

# Instalar dependências
npm install

# Compilar o projeto
npm run build

# Executar o servidor
npm start

3. Testando o Servidor

# Testar o fluxo completo
node test-full-flow.js

Resultado esperado:

✅ OAuth requerido corretamente detectado
✅ OAuth requerido corretamente detectado para ferramenta

🔗 Configuração no Cursor

Para Cursor/Claude Desktop

Adicione esta configuração ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "conta-azul": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Localização do arquivo de configuração:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

🔄 Fluxo de Autenticação

1. Inicialização: O servidor MCP inicia com capabilities OAuth2
2. Primeiro acesso: Cursor detecta que precisa de autenticação
3. Login OAuth: Cursor deve mostrar "needs login" ao invés de "loading tools"
4. Autorização: Usuário completa o fluxo OAuth com a Conta Azul
5. Uso das ferramentas: Após autenticação, ferramentas ficam disponíveis

🛠️ Ferramentas Disponíveis

list_customers

Lista clientes da Conta Azul (requer autenticação)

{
  "name": "list_customers",
  "description": "Lista clientes da Conta Azul",
  "inputSchema": {}
}

🐛 Solução de Problemas

Problema: Cursor fica "loading tools"

Solução verificada:

1. ✅ Servidor configurado corretamente - Responde adequadamente às requisições OAuth
2. ✅ Formato JSON-RPC correto - Retorna erros no formato esperado pelo MCP
3. ✅ Capabilities OAuth - Servidor anuncia corretamente suporte a OAuth2

Se ainda não funcionar:

1. Reinicie o Cursor/Claude Desktop completamente
2. Verifique se o arquivo de configuração está na localização correta
3. Confirme que o servidor está rodando em http://localhost:3000
4. Teste usando node test-full-flow.js para validar o comportamento

Verificando Logs do Servidor

O servidor produz logs detalhados:

🔓 Requisição de inicialização - pulando autenticação
✅ Sessão MCP inicializada: [session-id]
🔐 Aplicando middleware de autenticação
❌ Token de autorização não encontrado - retornando erro MCP

Testando Manualmente

# Teste de inicialização
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}'

📚 Estrutura do Projeto

.
├── src/
│   ├── index.ts              # Servidor principal MCP
│   └── auth/
│       └── provider.ts       # Provider OAuth para Conta Azul
├── test-full-flow.js         # Script de teste completo
├── package.json              # Dependências do projeto
├── .env                      # Configurações (não commitado)
└── README.md                 # Este arquivo

🔧 Desenvolvimento

Para desenvolvimento, você pode modificar as ferramentas em src/index.ts na função createMcpServer().

Adicionando Novas Ferramentas

mcpServer.tool(
  "nova_ferramenta",
  { /* schema de entrada */ },
  async (input, context) => {
    // Verificar autenticação
    if (!context.authorization) {
      return {
        isError: true,
        content: [{ type: "text", text: "Erro: Autenticação necessária." }],
      };
    }
    
    // Lógica da ferramenta aqui
    return {
      content: [{ type: "text", text: "Resultado da ferramenta" }],
    };
  }
);

🎯 Próximos Passos

1. Implementar validação real de tokens (atualmente aceita qualquer token para testes)
2. Adicionar mais ferramentas da API Conta Azul
3. Implementar cache de tokens
4. Adicionar testes unitários

Status: ✅ Funcionando - Servidor MCP com OAuth2 implementado corretamente

Authentication

The system uses OAuth 2.0 with access tokens and refresh tokens. Tokens are automatically managed and refreshed when they expire.

When Authentication Fails

If your refresh token expires, you'll see an error like:

Authentication required: Refresh token expired. Please obtain new tokens through OAuth flow.

To fix this:

1. Get OAuth URL: Run npm run auth-url to get the authorization URL
2. Authorize: Open the URL in your browser and authorize the application
3. Exchange Code: Copy the authorization code from the callback URL and run:

   npm run auth-code <authorization_code>
   

Manual Token Update

Alternatively, you can manually update tokens in your .env file and delete the token-storage.json file to force reloading.

Available Tools

• list_customers - Lists customers from Conta Azul
• listar-contas-pagar - Lists accounts payable with filters

Usage

npm start

Error Handling

The system automatically:

• Refreshes access tokens when they expire
• Clears invalid tokens from storage
• Provides OAuth instructions when re-authentication is needed
• Handles specific API errors gracefully