MCP Especialista eSocial

MCP Especialista eSocial

Servidor MCP com conhecimento profundo do eSocial S-1.3 — leiaute completo, regras de validação, MOS e Notas Técnicas indexados.

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

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

Eventos e Estrutura

Documentação

Busca e Contexto

Versões Suportadas

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

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.

_{Conhecimento profundo do eSocial para agentes de IA}