# MCP Especialista eSocial

<p align="center">
  <strong>Servidor MCP com conhecimento profundo do eSocial S-1.3 — leiaute completo, regras de validação, MOS e Notas Técnicas indexados.</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/leiaute-S--1.3-009c3b" alt="Leiaute S-1.3">
  <img src="https://img.shields.io/badge/eventos-50-002776" alt="50 eventos">
  <img src="https://img.shields.io/badge/regras-118-FFDF00?labelColor=002776" alt="118 regras">
  <img src="https://img.shields.io/badge/campos_XSD-~10k-009c3b" alt="~10k campos">
  <img src="https://img.shields.io/badge/MCP-compatível-7c3aed" alt="MCP Compatible">
  <a href="LICENSE"><img src="https://img.shields.io/badge/licença-MIT-FFDF00?labelColor=002776" alt="License MIT"></a>
</p>

---

## Por que este projeto?

O eSocial é o sistema mais complexo da obrigação acessória brasileira — 50 eventos, milhares de campos, 118 regras de validação interconectadas, manual de 300+ páginas e notas técnicas que mudam o comportamento silenciosamente.

**Este MCP transforma toda essa documentação em conhecimento consultável por IA.**

```text
Você:  "Quais campos são obrigatórios no S-2200 para trabalhador estrangeiro?"

IA:    Segundo o XSD do S-2200, para estrangeiro (paisNac ≠ 105):
       - dtChegada: obrigatório
       - classTrabEstworking: obrigatório  
       - casadoBr: obrigatório
       - filhosBr: obrigatório
       
       Regra REGRA_ESTRANG_BRASIL valida consistência.
```

```text
Você:  "Qual a ordem de envio para admitir um funcionário?"

IA:    Cadeia de dependências:
       1. S-1000 (empregador) — pré-requisito de tudo
       2. S-1005 (estabelecimento) — opcional se já existe
       3. S-2200 (admissão) — requer S-1000 ativo
       
       Fonte: relações do evento S-2200.
```

---

## Início Rápido

```json
{
  "mcpServers": {
    "especialista-esocial": {
      "url": "https://mcp-especialista-esocial.fly.dev/sse"
    }
  }
}
```

Adicione ao arquivo de configuração MCP do seu cliente (Claude Desktop, Cursor, VS Code, etc.). Reinicie. Pronto.

---

## O que tem dentro

| Módulo | Conteúdo |
| ------ | -------- |
| **Eventos** | 50 fichas completas com campos, regras associadas e dependências |
| **XSD** | ~10.148 campos parseados com tipos, tamanhos, obrigatoriedade |
| **Regras** | 118 regras de validação com condições e mensagens de erro |
| **MOS** | Manual de Orientação do eSocial indexado por seção |
| **NTs** | Notas Técnicas com alterações de leiaute |
| **Tabelas** | 29 tabelas de domínio (categorias, países, naturezas, etc.) |
| **Enums** | 146 enumerações do XSD |
| **Relações** | Grafo de dependências entre eventos |

---

## Arquitetura

```mermaid
flowchart TB
    subgraph Fontes["📚 Fontes Oficiais"]
        XSD[XSDs eSocial S-1.3]
        MOS[Manual de Orientação]
        NT[Notas Técnicas]
        TAB[Tabelas de Domínio]
    end

    subgraph Ingestão["⚙️ Ingestão"]
        Parser[XSD Parser]
        Indexer[Indexador FTS]
        Embed[Embeddings]
    end

    subgraph Storage["🗄️ PostgreSQL"]
        DB[(eventos, campos,<br/>regras, mos, nts,<br/>tabelas, enums)]
    end

    subgraph MCP["🤖 MCP Server"]
        Tools[17 Tools]
        SSE[SSE Endpoint]
    end

    subgraph Clients["💻 Clientes"]
        Claude[Claude Desktop]
        Cursor[Cursor]
        VSCode[VS Code]
        API[Qualquer MCP Client]
    end

    XSD --> Parser
    MOS --> Indexer
    NT --> Indexer
    TAB --> Indexer
    Parser --> DB
    Indexer --> DB
    Embed --> DB
    DB --> Tools
    Tools --> SSE
    SSE --> Claude
    SSE --> Cursor
    SSE --> VSCode
    SSE --> API
```

---

## Tools Disponíveis

### Descoberta

| Tool | Uso |
| ---- | --- |
| `how_to_use` | Lista tools ou documentação detalhada de uma tool específica |
| `sumario` | Estatísticas gerais: eventos, regras, tabelas, campos |

### Eventos e Estrutura

| Tool | Uso |
| ---- | --- |
| `eventos` | Fichas dos eventos (list, get) |
| `xsd` | Campos XSD por evento ou busca por nome de campo |
| `tipos` | Tipos XSD (patterns, lengths) |
| `enums` | Enumerações e valores válidos |
| `relacoes` | Dependências e cadeia de eventos |

### Documentação

| Tool | Uso |
| ---- | --- |
| `mos` | Seções do Manual de Orientação |
| `nts` | Notas Técnicas |
| `tabelas` | Tabelas de domínio (categorias, países, etc.) |
| `regras` | Regras de validação com condições |

### Busca e Contexto

| Tool | Uso |
| ---- | --- |
| `busca` | Busca textual cross-módulo (FTS + semântica) |
| `contexto` | Contexto completo de um evento (XSD + regras + código) |
| `versoes` | Histórico de versões e diffs entre leiautes |

---

## Versões Suportadas

| Versão | Status | Vigência |
| ------ | ------ | -------- |
| **S-1.3** | ✅ Atual | Abril/2025 em diante |
| S-1.2 | ⏳ Legado | Jan/2024 - Mar/2025 |
| S-1.1 | 📦 Histórico | 2022 - 2023 |

### Linha do Tempo das Versões

```text
2019 ────── 2022 ────── 2024 ────── 2025 ──────▶
  │          │           │           │
S-1.0      S-1.1       S-1.2       S-1.3
(inicial)  (simplif.)  (ajustes)   (atual)
```

### O que muda entre versões

| Mudança Típica | Exemplo |
| -------------- | ------- |
| **Novos campos** | `infoMV` no S-1200 (S-1.2+) |
| **Campos removidos** | `ideADC` simplificado (S-1.1+) |
| **Regras alteradas** | REGRA_EVENTO_EXT revisada |
| **Novos eventos** | S-2405 (Alteração cadastral) |
| **Tabelas atualizadas** | Novos códigos Tabela-06 |

### Consultar Versões

```text
Você:  versoes(mode="atual")
IA:    Versão ativa: S-1.3 (vigente desde 01/04/2025)

Você:  versoes(mode="diff", de="S-1.2", para="S-1.3")
IA:    Changelog S-1.2 → S-1.3:
       - Novo campo infoRetif no S-1200
       - Regra REGRA_VALID_DT alterada
       - Tabela-29 com novos códigos...
```

---

## Configuração por Cliente

### Claude Desktop

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "especialista-esocial": {
      "url": "https://mcp-especialista-esocial.fly.dev/sse"
    }
  }
}
```

### Cursor

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "especialista-esocial": {
      "url": "https://mcp-especialista-esocial.fly.dev/sse"
    }
  }
}
```

---

## Self-hosting

Se preferir hospedar sua própria instância:

### Requisitos

- Python 3.11+
- PostgreSQL 15+
- uv (gerenciador de pacotes)

### Deploy local

```bash
git clone https://github.com/seu-usuario/mcp-especialista-esocial.git
cd mcp-especialista-esocial

# Subir banco
docker-compose up -d

# Ingerir dados
uv sync
uv run python scripts/ingest.py

# Rodar servidor
uv run python -m especialista_esocial
```

### Deploy Fly.io

```bash
fly launch --no-deploy
fly postgres create --name especialista-esocial-db
fly postgres attach especialista-esocial-db
fly deploy
```

---

## Estrutura do Projeto

```text
src/especialista_esocial/
├── server.py          # FastMCP entrypoint
├── core/              # repository, watcher, xsd_parser
├── infra/             # postgres, embeddings, schema_cache
├── models/            # DTOs Pydantic
└── tools/             # 17 MCP tools
```

---

## Licença

MIT — use como quiser.

---

<p align="center">
  <sub>Conhecimento profundo do eSocial para agentes de IA</sub>
</p>