leis-mcp 0.1.0

Busque e cite o texto oficial de mais de 1,2 milhão de normas brasileiras sem sair do seu assistente.

Início rápido · Ferramentas · Clientes · Como funciona · Limitações

_{Clique na imagem para ver a demonstração (25 s, com música).}

leis-mcp é um servidor MCP que dá ao Claude Code, ao Claude Desktop e a qualquer cliente MCP acesso à legislação brasileira do repositório público ctresb/leis. Em vez de parafrasear de memória, o assistente busca a norma, lê o dispositivo e cita o texto exato, com a fonte oficial e os avisos de revogação.

ler_artigo("8245/1991", "23", inciso="III")
→ "III - restituir o imóvel, finda a locação, no estado em que o recebeu, salvo as deteriorações decorrentes do seu uso normal;"

Destaques

• 📜 Texto exato. Artigo, parágrafo, inciso e alínea, com o caput como contexto e a citação pronta (art. 23, III).
• 🔗 Sempre com fonte. Cada resposta traz o link oficial (normas.leg.br, LexML) e o caminho no acervo.
• ⚠️ Avisos automáticos. Norma revogada, texto não compilado, dispositivo revogado ou vetado, trecho tachado.
• 🗂️ Acervo inteiro. Normas federais, estaduais, municipais e de reguladores, com mais de 40 apelidos (CLT, CDC, LGPD, lei do inquilinato…).
• ⚡ Rápido e local. Índice SQLite em ~6 s, conteúdo baixado sob demanda e conferido pelo hash do blob. O que está em cache funciona offline.
• 🔒 Só leitura. O repositório de origem nunca é alterado.

Início rápido

Requisitos: uv e git. O ripgrep (rg) é recomendado.

uvx leis-mcp index                          # clone leve + índice (~1 min na primeira vez)
claude mcp add leis -- uvx leis-mcp serve

Pronto. Pergunte ao Claude: "O inquilino é obrigado a devolver o imóvel como recebeu? Cite a lei."

git clone https://github.com/mazulo/leis-mcp && cd leis-mcp
uv sync
uv run leis-mcp index
claude mcp add leis -- uv --directory "$PWD" run leis-mcp serve

Ferramentas

{
  "norma": {"titulo": "Lei nº 8.245 de 18/10/1991", "ementa": "Dispõe sobre as locações dos imóveis urbanos…",
            "revogada": false, "versao_texto": "compilada (texto vigente)",
            "caminho": "federal/leis-ordinarias/1991/lei-8245-1991-10-18.md"},
  "dispositivo": {"citacao": "art. 23, III",
                  "texto": "III - restituir o imóvel, finda a locação, no estado em que o recebeu, salvo as deteriorações decorrentes do seu uso normal;",
                  "caput": "**Art. 23.** O locatário é obrigado a:"},
  "avisos": [],
  "fonte": "https://normas.leg.br/?urn=urn:lex:br:federal:lei:1991-10-18;8245",
  "aviso_legal": "Texto convertido automaticamente das fontes oficiais (…). Não substitui a publicação no Diário Oficial."
}

Exemplos de perguntas

Clientes

Claude Code

claude mcp add leis -- uvx leis-mcp serve

Use -s user para disponibilizar em todos os projetos e -s project para gravar em .mcp.json.

Claude Desktop

Em claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "leis": {
      "command": "uvx",
      "args": ["leis-mcp", "serve"]
    }
  }
}

Se o Desktop não achar o uvx, use o caminho absoluto (which uvx).

Docker

docker compose build
docker compose run --rm leis-mcp index
docker compose run --rm leis-mcp warm
docker compose run --rm -i leis-mcp serve                 # stdio
docker compose --profile http up leis-mcp-http            # HTTP: http://localhost:8000/mcp

Os dados ficam no volume leis-data. Para registrar no Claude Code:

claude mcp add leis -- docker compose -f /caminho/para/leis-mcp/docker-compose.yml run --rm -i leis-mcp serve

No Claude Desktop, troque o comando por "command": "docker", "args": ["compose", "-f", "/caminho/para/leis-mcp/docker-compose.yml", "run", "--rm", "-i", "leis-mcp", "serve"].

HTTP

uvx leis-mcp serve --transport streamable-http --port 8000      # servido em /mcp
claude mcp add --transport http leis http://localhost:8000/mcp

Como funciona

flowchart LR
    client["Assistente<br>cliente MCP"] -- "stdio ou HTTP" --> server["leis-mcp"]
    server --> index[("Índice SQLite<br>1,2 M normas")]
    server --> cache[("Cache por blob")]
    cache -. "sob demanda,<br>fixado no commit" .-> raw["raw.githubusercontent.com<br>ctresb/leis"]
    index -. "git ls-tree" .-> clone["Clone leve<br>só árvores"]

Os dados ficam em ~/.cache/leis-mcp, configurável com LEIS_MCP_HOME.

src/leis_mcp/
  config.py, models.py, errors.py, text.py
  messages.py        todo texto devolvido ao usuário (pt-BR)
  catalog/           GitRepository, PathParser, IndexBuilder / NormIndex (SQLite)
  references/        ReferenceParser + tabelas de apelidos
  content/           FrontMatterParser, ContentStore (cache por blob)
  legal_text/        labels (Art., §, inciso, alínea), DocumentParser, ProvisionExtractor, notices
  search/            AccentInsensitivePattern, RipgrepEngine / PythonEngine, TextSearch
  services/          NormResolver, NormLoader, NormPresenter, LegislationService (fachada)
  server/            LeisServer: adaptador MCP (nomes de ferramentas e parâmetros em pt-BR)
  cli.py             Cli: serve, index, update, status, warm, read

CLI

Rode com uvx leis-mcp <comando> ou, no código-fonte, com uv run leis-mcp <comando>:

leis-mcp index                         # clone leve + índice
leis-mcp update                        # git fetch + reindexação
leis-mcp status                        # commit indexado, total, itens em cache
leis-mcp warm                          # pré-carrega as leis dos apelidos
leis-mcp warm --no-aliases --sphere federal --kind leis-complementares
leis-mcp read "Lei 8.245/91" 23 -c III # testa sem cliente MCP (-p parágrafo, -c inciso, -s alínea, -b bloco)
leis-mcp serve                         # stdio (padrão)

Se o índice não existir, serve gera o índice antes de iniciar. Ainda assim, rode index antes para o cliente não esperar.

Testes

uv run pytest -m "not integration"   # unitários, sem rede (fixtures pequenas)
uv run pytest                        # tudo, incluindo integração com conteúdo real e e2e MCP via stdio

Os testes de integração usam o índice de LEIS_MCP_HOME e são pulados se ele não existir. Eles cobrem a Lei 8.245/91 (art. 23, III e art. 38, § 2º), o CDC (art. 20, I), o CC (arts. 422 e 1.000), a Lei 9.099/95 (art. 9º), a CLT, a CF e o ADCT, e todos os apelidos. O teste e2e sobe o servidor por stdio com o cliente MCP oficial e chama todas as ferramentas.

Limitações

• Busca textual sem o acervo inteiro: buscar_texto sem norma procura só nas normas já em cache. Baixar as 1,2 M normas não é viável. Use warm para ampliar o cache. Não há busca semântica nem embeddings.
• Ementas e títulos: só aparecem para normas já baixadas. O índice tem apenas o que se deduz do caminho.
• Referências ambíguas: sem ano (por exemplo, "decreto 5452"), o servidor pede o ano. buscar_norma lista as opções.
• Qualidade do texto: a conversão automática e o OCR podem ter erros (por exemplo, servir - se). O texto é devolvido como está e o parser não o corrige.
• Revogação: o aviso depende do cabeçalho (revogada, versao_texto) e das notas no próprio texto. Não há verificação independente de vigência.
• Metadados de normas não federais: o número e a data de normas estaduais, municipais e de reguladores vêm de heurísticas sobre o nome do arquivo.
• Rede: o conteúdo vem do raw.githubusercontent.com, que pode impor limite de requisições. O que já está em cache funciona offline.

Créditos

O acervo é o ctresb/leis, que converte as normas das fontes oficiais para Markdown. O leis-mcp só lê esse repositório. A trilha do vídeo é Intergalactic, de Alex Jones / Xander Jones, da Biblioteca de áudio do YouTube.