sienge-ecbiesek-mcp 3.0.0

🏗️ Model Context Protocol (MCP) server for Sienge API integration - Brazilian construction ERP system. Connect Claude AI to Sienge with 60+ powerful tools including smart validation, error parsing, complete invoice pipeline, and advanced caching for comprehensive business management.

🏗️ SIENGE MCP Server

Model Context Protocol (MCP) server para integração com a API do Sienge, o principal sistema ERP de gestão de construção do Brasil. Conecte Claude AI ao Sienge com 60+ ferramentas poderosas incluindo validação inteligente, parser de erros, pipeline completo de notas fiscais e cache avançado.

📋 Índice

• Sobre o Projeto
• Características Principais
• Instalação
• Configuração
• Uso
• Ferramentas Disponíveis
• Arquitetura
• Deploy
• Contribuindo
• Licença

🎯 Sobre o Projeto

O SIENGE MCP Server é um servidor Model Context Protocol que permite integração completa entre Claude AI e o sistema Sienge ERP, facilitando a gestão de dados de construção através de inteligência artificial.

Público-Alvo

• ✅ Empresas de construção que utilizam Sienge ERP
• ✅ Desenvolvedores construindo integrações com IA
• ✅ Usuários do Claude Desktop buscando conectividade com Sienge
• ✅ Profissionais da indústria da construção brasileira

Foco Regional

Especificamente projetado para empresas brasileiras de construção que utilizam o sistema ERP Sienge, com documentação em português e funcionalidades localizadas.

🚀 Características Principais

✨ Funcionalidades Core

• 🔌 60+ Ferramentas - Acesso completo à API do Sienge
• 🔐 Autenticação Flexível - Suporta Bearer Token e Basic Auth
• 🧠 Parser de Erros Inteligente - Identifica e sugere correções para 14+ tipos de erros
• ⚡ Cache Avançado - Sistema de cache in-memory com TTL configurável
• 🔄 Retry Automático - Retry com backoff exponencial para requisições
• 📊 Pipeline Completo - Processamento completo de notas fiscais de compra
• 🔍 Busca Universal - Busca em múltiplas entidades simultaneamente
• 💾 Integração Supabase - Acesso direto a dados sincronizados

📦 Módulos Disponíveis

• Utilities - Testes de conexão e busca universal
• Master Data - Clientes, fornecedores, projetos, centros de custo
• Purchases - Pedidos de compra, requisições, notas fiscais
• Accounts Payable - Títulos a pagar, parcelas, anexos
• Financial - Contas a receber, títulos, análises financeiras
• Inventory - Estoque, inventário, reservas
• Supabase Tools - Queries diretas no banco sincronizado

📥 Instalação

Pré-requisitos

• Python 3.10 ou superior
• Conta Sienge com acesso à API
• Claude Desktop (para uso com Claude AI)

Instalação via PyPI (Recomendado)

pip install sienge-ecbiesek-mcp

Instalação via pipx (Isolada)

pipx install sienge-ecbiesek-mcp

Instalação do Código Fonte

# Clonar repositório
git clone https://github.com/INOTECH-ecbiesek/Sienge-MCP.git
cd Sienge-MCP

# Criar ambiente virtual
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# ou
.venv\Scripts\activate  # Windows

# Instalar dependências
pip install -r requirements.txt

# Instalar em modo desenvolvimento
pip install -e .

⚙️ Configuração

1. Variáveis de Ambiente

Crie um arquivo .env na raiz do projeto ou configure as variáveis de ambiente:

# Obrigatórias (escolha uma opção de autenticação)

# Opção 1: Bearer Token (Recomendado)
SIENGE_API_KEY=sua_api_key_aqui

# Opção 2: Basic Auth
SIENGE_USERNAME=seu_usuario
SIENGE_PASSWORD=sua_senha
SIENGE_SUBDOMAIN=sua_empresa

# Opcionais
SIENGE_BASE_URL=https://api.sienge.com.br
REQUEST_TIMEOUT=30

# Integração Supabase (Opcional)
SUPABASE_URL=https://seu-projeto.supabase.co
SUPABASE_SERVICE_ROLE_KEY=sua_service_role_key

2. Configuração Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop (claude_desktop_config.json):

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sienge": {
      "command": "sienge-ecbiesek-mcp",
      "env": {
        "SIENGE_API_KEY": "sua_api_key_aqui",
        "SIENGE_SUBDOMAIN": "sua_empresa",
        "SIENGE_USERNAME": "seu_usuario",
        "SIENGE_PASSWORD": "sua_senha"
      }
    }
  }
}

3. Testar Conexão

Após configurar, reinicie o Claude Desktop e teste a conexão:

Teste a conexão com a API do Sienge

💻 Uso

Uso Básico

Uma vez configurado, você pode usar as ferramentas diretamente no Claude:

Busque todos os clientes cadastrados no Sienge

Crie uma nota fiscal de compra para o pedido de compra 12345

Liste todos os projetos/empreendimentos ativos

Exemplos de Uso

Buscar Clientes

Busque clientes com nome contendo "Construtora"

Criar Nota Fiscal

Crie uma nota fiscal de compra:
- Número: 123456
- Fornecedor: ID 100
- Empresa: ID 1
- Data de movimento: 2025-01-15
- Data de emissão: 2025-01-15

Buscar Títulos a Pagar

Liste todos os títulos a pagar do mês de janeiro de 2025

🛠️ Ferramentas Disponíveis

🔧 Utilities

• test_sienge_connection - Testa conexão com a API do Sienge
• list_sienge_entities - Lista entidades disponíveis
• search_sienge_data - Busca universal em múltiplas entidades

👥 Master Data

• get_sienge_customers - Busca clientes
• get_sienge_customer_types - Tipos de cliente
• get_sienge_creditors - Busca fornecedores/credores
• get_sienge_projects - Lista projetos/empreendimentos
• get_sienge_cost_centers - Centros de custo
• get_sienge_project_units - Unidades de empreendimento
• get_sienge_payment_categories - Categorias de plano financeiro

🛒 Purchases

• get_sienge_purchase_orders - Busca pedidos de compra
• get_sienge_purchase_order_items - Itens de pedido de compra
• get_sienge_purchase_requests - Requisições de compra
• get_sienge_purchase_invoices - Notas fiscais de compra
• create_sienge_purchase_invoice - Cria nota fiscal
• add_items_to_purchase_invoice - Adiciona itens à NF
• validate_purchase_order_company - Valida empresa do pedido
• process_purchase_invoice_pipeline - Pipeline completo de NF

💰 Accounts Payable

• get_sienge_bills - Busca títulos a pagar
• ap_list_installments - Lista parcelas de um título
• ap_update_installment - Atualiza uma parcela específica do título
• ap_update_auto_bill_installments - Atualiza parcelas automáticas
• ap_patch_bill - Atualiza campos do título
• ap_attach_bill - Anexa arquivo ao título
• ap_finalize_bill - Orquestrador: PATCH + anexo + auditoria
• ap_audit_bill_completeness - Audita completude do título

📊 Financial

• get_sienge_accounts_receivable - Contas a receber
• get_sienge_bills - Títulos a pagar
• search_sienge_financial_data - Busca avançada em dados financeiros
• get_sienge_dashboard_summary - Dashboard com resumo completo

📦 Inventory

• get_sienge_stock_inventory - Inventário de estoque
• get_sienge_stock_reservations - Reservas de estoque

🗄️ Supabase Tools

• query_supabase_database - Queries diretas no Supabase
• get_supabase_table_info - Informações de tabelas
• search_supabase_data - Busca universal no Supabase

🏛️ Arquitetura

Estrutura do Projeto

Sienge-MCP/
├── src/
│   └── sienge_mcp/
│       ├── server.py          # Core: FastMCP, autenticação, cache
│       ├── metadata.py        # Metadados do MCP
│       ├── tools/             # Módulos especializados
│       │   ├── utilities.py   # Testes e busca universal
│       │   ├── master_data.py # Dados mestres
│       │   ├── purchases.py   # Compras e notas fiscais
│       │   ├── accounts_payable.py  # Contas a pagar
│       │   ├── financial.py   # Financeiro
│       │   ├── inventory.py   # Estoque
│       │   └── supabase_tools.py  # Integração Supabase
│       └── utils/
│           └── logger.py      # Sistema de logging
├── app.py                     # Entry point para Railway
├── Dockerfile                 # Container para deploy
├── pyproject.toml            # Configuração do projeto
├── requirements.txt          # Dependências
└── README.md                 # Este arquivo

Características Técnicas

• Framework: FastMCP 2.12.3+
• HTTP Client: httpx (async)
• Validação: Pydantic 2.0+
• Cache: In-memory com TTL configurável
• Retry: Exponential backoff (5 tentativas)
• Error Handling: Parser inteligente com sugestões contextuais

🚢 Deploy

Railway

O projeto inclui configuração para deploy no Railway:

# O Railway detecta automaticamente o Dockerfile
# Configure as variáveis de ambiente no dashboard do Railway

Variáveis de Ambiente no Railway:

• SIENGE_API_KEY ou SIENGE_USERNAME + SIENGE_PASSWORD + SIENGE_SUBDOMAIN
• PORT (definido automaticamente pelo Railway)

Docker

# Build
docker build -t sienge-mcp .

# Run
docker run -p 8000:8000 \
  -e SIENGE_API_KEY=sua_key \
  -e SIENGE_SUBDOMAIN=sua_empresa \
  sienge-mcp

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

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

Padrões de Código

Este projeto segue padrões de qualidade de código:

• ✅ Flake8 para verificação de linting
• ✅ Black para formatação de código
• ✅ Pydantic para validação de dados
• ✅ Type hints em todas as funções

Desenvolvimento

# Instalar dependências de desenvolvimento
pip install -e ".[dev]"

# Executar testes
pytest

# Formatar código
black src/

# Verificar lint com flake8
flake8 src/ --config=.flake8

# Verificar lint com estatísticas
flake8 src/ --config=.flake8 --statistics

Configuração do Flake8

O projeto utiliza flake8 para verificação de qualidade de código. A configuração está em .flake8:

• Max line length: 127 caracteres
• Max complexity: 15
• Ignorados: E203, E501, W503, C901
• Excluídos: __pycache__, build, dist, .venv, *.egg-info

📝 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

📞 Suporte

• Issues: GitHub Issues
• Email: [e-mail]
• Documentação: GitHub Wiki

🔗 Links Úteis

• PyPI Package
• Sienge API Documentation
• Model Context Protocol
• Claude Desktop

📈 Status do Projeto

• ✅ Production Ready (v2.1.0)
• ✅ Active Development
• ✅ Published on PyPI
• ✅ Full Documentation
• ✅ 60+ Tools Available
• ✅ Supabase Integration
• ✅ Railway Deployment Ready

---

Desenvolvido com ❤️ por ECBIESEK