sienge-ecbiesek-mcp 3.1.3
🏗️ 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.
Requires Python: >=3.10
Keywords: sienge, mcp, model-context-protocol, claude, api, construction, erp, brazil, ecbiesek, fastmcp, ai-integration

# 🏗️ SIENGE MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/sienge-ecbiesek-mcp.svg)](https://badge.fury.io/py/sienge-ecbiesek-mcp)
[![Status: Production](https://img.shields.io/badge/status-production-green.svg)](https://pypi.org/project/sienge-ecbiesek-mcp/)

**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](#-sobre-o-projeto)
- [Características Principais](#-características-principais)
- [Instalação](#-instalação)
- [Configuração](#-configuração)
- [Uso](#-uso)
- [Ferramentas Disponíveis](#-ferramentas-disponíveis)
- [Arquitetura](#-arquitetura)
- [Deploy](#-deploy)
- [Contribuindo](#-contribuindo)
- [Licença](#-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)

```bash
pip install sienge-ecbiesek-mcp
```

### Instalação via pipx (Isolada)

```bash
pipx install sienge-ecbiesek-mcp
```

### Instalação do Código Fonte

```bash
# 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:

```env
# 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
```

```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:

```bash
# 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

```bash
# 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

```bash
# 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](LICENSE) para detalhes.

## 📞 Suporte

- **Issues:** [GitHub Issues](https://github.com/INOTECH-ecbiesek/Sienge-MCP/issues)
- **Email:** ti@ecbiesek.com
- **Documentação:** [GitHub Wiki](https://github.com/INOTECH-ecbiesek/Sienge-MCP/wiki)

## 🔗 Links Úteis

- [PyPI Package](https://pypi.org/project/sienge-ecbiesek-mcp/)
- [Sienge API Documentation](https://api.sienge.com.br)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Claude Desktop](https://claude.ai/download)

## 📈 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](https://github.com/INOTECH-ecbiesek)**