MCP 服务器

mcp-especialista-esocial

MCP server providing deep knowledge of Brazilian eSocial S-1.3, including validation rules, XSD fields, and official documentation, enabling AI agents to answer questions about eSocial events and compliance.

README

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

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