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.

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.

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

{
  "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

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

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

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:

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

Cursor

.cursor/mcp.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

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

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

---

Estrutura do Projeto

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"> _{Conhecimento profundo do eSocial para agentes de IA} </p>