normativa-colombia-mcp

Um mcp para obter todas as informações legais colombianas.

Documentação

Normativa Colombia — servidor MCP

Consulte a normativa e a jurisprudência colombiana a partir de qualquer assistente de IA que fale Model Context Protocol, sem abrir o navegador nem brigar com formulários.

Conecta seis fontes oficiais:

Gestor Normativo do Departamento Administrativo da Função Pública — leis, decretos, resoluções, circulares e conceitos do setor público, com a consulta temática e os restritores que explicam por que cada norma se aplica a um tema.
Relatoria da Corte Constitucional — 44.839 decisões segundo seu próprio índice, com julgados recentes publicados no mesmo ano.
SUIN-Juriscol do Ministério da Justiça — o estado de vigência, que nenhuma outra fonte do país publica, e 11.599 leis de 1844 a 2026, muitas das quais o Gestor não possui.
Corte Suprema de Justiça — decisões das salas de Tutelas, Civil, Trabalhista e Penal, cada uma com as normas que cita.
Conselho de Estado — decisões tituladas do contencioso administrativo, com o problema jurídico que a Sala se colocou, sua resposta e o texto completo. Com esta se completam as três altas cortes, e as três entregam texto.
Normograma da DIAN — normativa tributária, aduaneira e cambial.

É um servidor MCP padrão que se comunica por stdio, então serve no Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, LM Studio, agentes próprios feitos com os SDKs de MCP e qualquer cliente que aparecer depois.

Instalação

Opção A — Claude Desktop, com um clique

A mais simples se você usa Claude Desktop: não requer Node nem mexer em arquivos de configuração.

Baixe normativa-colombia.mcpb de Releases.
Abra o Claude Desktop → Configurações → Extensões.
Arraste o arquivo para essa janela e confirme.

O Claude Desktop traz seu próprio Node, então não é preciso instalar mais nada.

Opção B — qualquer outro cliente MCP, via npm (recomendada)

A forma mais simples e que evita erros de caminhos: não é preciso clonar nada nem apontar para arquivos locais. Requer Node 18 ou superior.

# sin instalar nada, la forma habitual en clientes MCP
npx -y normativa-colombia-mcp

# o instalado en el proyecto
npm install normativa-colombia-mcp

# o disponible en todo el sistema
npm install -g normativa-colombia-mcp

Quase todos os clientes compartilham este formato:

{
  "mcpServers": {
    "normativa-colombia": {
      "command": "npx",
      "args": ["-y", "normativa-colombia-mcp"]
    }
  }
}

Cliente	Onde vai essa configuração
Claude Desktop (manual)	`claude_desktop_config.json` — em Configurações → Desenvolvedor → Editar configuração
Cursor	`.cursor/mcp.json` no projeto, ou `~/.cursor/mcp.json` para todos
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Continue	O bloco `mcpServers` da sua configuração
LM Studio	Program → Install → Edit mcp.json
Agente próprio	Como `StdioServerParameters` do SDK de MCP, em Python ou TypeScript

Claude Code não usa arquivo; registra-se por linha de comando:

claude mcp add normativa-colombia -- npx -y normativa-colombia-mcp

VS Code usa a chave servers em vez de mcpServers, em .mcp.json do projeto ou na configuração de usuário:

{
  "servers": {
    "normativa-colombia": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "normativa-colombia-mcp"]
    }
  }
}

Se você instalou com npm install -g, o comando é normativa-colombia-mcp puro, sem argumentos.

Se o seu cliente não está na lista, procure onde ele declara servidores MCP por stdio: o comando e os argumentos são sempre os mesmos.

Verificar se ficou correto

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"prueba","version":"1"}}}' \
  | npx -y normativa-colombia-mcp

Deve responder um JSON com "name":"normativa-colombia" e um campo instructions.

Opção C — a partir do código

Para desenvolver ou para fixar uma versão própria. Requer Node 22 ou superior:

git clone https://github.com/Angelthebestone/Normativa-colombiana-MCP.git
cd Normativa-colombiana-MCP
npm install
npm run generar-indice   # índice temático, ~20 MB de descarga, una sola vez
npm run build            # genera server/index.js

Depois, aponte o cliente para node /ruta/absoluta/a/Normativa-colombiana-MCP/server/index.js, com o mesmo formato acima. Funciona a partir de qualquer diretório de trabalho.

Pasta sem espaços: se o caminho local contiver espaços (p. ex. C:\Users\…\normativa mcp\server\index.js), alguns clientes lançam o comando sem aspas e o Node só vê a primeira parte (C:\Users\…\normativa) e sai com código 1. Para instalação local, clone em uma pasta sem espaços ou use a Opção B (npx), que não tem esse problema.

O que o cliente recebe

Ao conectar, o servidor entrega 26 ferramentas, 5 prompts e suas próprias instruções de uso: a que tipo de pergunta corresponde cada ferramenta, que a fonte deve ser sempre citada e que nunca se deve afirmar por conta própria que uma norma está vigente. Os clientes que respeitam o campo instructions do protocolo aproveitam isso sem configurar nada.

Fonte	Ferramentas
Qualquer uma (ponto de entrada)	`resolver_cita` — citação exata → norma ou sentença, com sua vigência se constar; aceita lote com `citas` e validação com `validar: true`. `consultar_vigencia` — o estado de vigência com um nível de confiança (alta/média/baixa). `historial_norma` — a cadeia de reformas que o Gestor anota sobre uma norma (o que a modificou, adicionou ou revogou e qual artigo cada mudança afetou), filtrável por `articulo` e paginável com `desde` / `limite`
Gestor Normativo	`buscar_normas` (com marca de pertinência por linha: quais termos cada trecho menciona), `buscar_por_tema`, `obtener_documento` (fonte `gestor`, com `sin_temas` para omitir o bloco de temas), `listar_catalogos`, `explicar_relacion_tema`
Corte Constitucional	`buscar_jurisprudencia`, `obtener_documento` (fonte `corte`)
Corte Suprema	`buscar_jurisprudencia_suprema`, `obtener_documento` (fonte `suprema`)
Conselho de Estado	`buscar_jurisprudencia_consejo_estado`, `obtener_documento` (fonte `consejo`)
SUIN-Juriscol	`buscar_en_suin` (e vigência via `resolver_cita`)
DIAN	`buscar_normativa_tributaria`, `obtener_documento` (fonte `dian`)
CREG	`buscar_resoluciones_creg`, `obtener_documento` (fonte `creg`)
ANH / UPME / ANLA	`buscar_normativa_anh`, `buscar_normativa_upme`, `listar_normativa_ambiental_anla`
14 reguladores setoriais	`buscar_normativa_sectorial` (entidade: `sic`, `superfinanciera`, `supersalud`, `ant`, `unidadvictimas` …) + `obtener_documento` (fonte `sectorial`)
V2 — hierarquia e conflitos	`consultar_por_jerarquia`, `analizar_conflicto` (reúne EVIDÊNCIA; a busca de tema testa singular e plural e declara a variante), `comparar_articulos`, `cambios_desde`
V2 — perfis e expedientes	`consultar_perfil`, `expediente` (ação `crear\|agregar\|leer\|exportar`)
Escopo	`describir_fuentes` — o que cada fonte cobre e o que não cobre, sem consultar a rede

O que você pode perguntar

«O que diz a Lei 1221 de 2008 sobre o auxílio de conectividade?»
«Quais normas regulam o teletrabalho no setor público e por que se aplicam?»
«O que diz o Decreto 1083 sobre designações?»
«Busque jurisprudência recente da Corte Constitucional sobre estabilidade laboral reforçada.»
«A Lei 909 de 2004 continua vigente?»
«O que diz a DIAN sobre a retenção na fonte por serviços?»
«Busque tutelas da Corte Suprema sobre teletrabalho e diga quais normas elas citam.»
«Existe a Lei 74 de 1923 e ela continua vigente?» — está revogada, e nem o Gestor a possui.
«Quais leis existem sobre teletrabalho?» — consultar_por_jerarquia com nível "lei".
«Compare o art. 2 da Lei 909 com o art. 2.2.5.3.1 do Decreto 1083.» — comparar_articulos.
«Há conflito entre a Lei 909 de 2004 e o Decreto 1083 de 2015 em matéria de designações?» — analizar_conflicto (reúne evidência, não conclui).
«O que mudou na Lei 909 de 2004 desde 2020?» — cambios_desde.
«Normativa trabalhista sobre teletrabalho» — consultar_perfil com perfil "trabalhista".

O servidor inclui ainda cinco prompts prontos, que os clientes que os suportam mostram como comandos: Quais normas se aplicam a um tema?, Esta norma continua vigente?, Explique esta norma em linguagem simples, Compare duas normas e Esclarecer uma consulta ambígua.

Ferramentas V2

Sobre a camada comum de metadados, evidência e normalização:

consultar_por_jerarquia filtra por nível (constituição, lei, decreto, resolução, conceito, jurisprudência) e explica o caráter de cada um. O Gestor não cataloga a Constituição como tipo: para esse nível, orienta-se.
resolver_cita com validar: true verifica se uma citação e seu link são verdadeiros: número/ano contra o título, domínio do link, id da norma e existência do artigo. Classifica em "validada", "parcialmente validada" ou "não foi possível validar"; nunca afirma vigência.
analizar_conflicto reúne EVIDÊNCIA de um possível conflito entre duas normas (identificação, vigência segundo SUIN se constar, hierarquia, reformas anotadas, trechos sobre um tema). Não detecta contradições semânticas e o resultado é um conflito POTENCIAL, não uma conclusão jurídica.
cambios_desde resume as mudanças (modificação, revogação, adição) que o Gestor anota sobre as normas que são listadas, filtradas pelo ano da norma modificadora. Não rastreia novidades por conta própria.
comparar_articulos compara o texto de um artigo entre duas normas, marca o que foi adicionado/removido, classifica cada diferença por padrões (prazo, sanção, exceção, sujeito obrigado) e agrupa as mudanças editoriais por similaridade lexical (Dice sobre bigramas ≥0,92): «uma linha» → «uma única linha» sai como mudança menor, não como adicionado+removido. O que não for classificado é marcado "revisar manualmente". Sem modelo semântico.
consultar_perfil executa uma consulta com as fontes e filtros pré-configurados de um perfil: laboral, tributario, ambiental, contratacion_estatal, energia. Cada perfil declara seu aviso na resposta.
expediente com accion="crear|agregar|leer|exportar" agrupa consultas, citações e observações de uma investigação. Desativado por padrão: ativa-se com a variável de ambiente EXPEDIENTES=1; a persistência em disco, com EXPEDIENTES_DIR.

Uma regra de ouro das V2: se uma citação vier sem ano e o número for ambíguo ("Decreto 1072" são quatro), a ferramenta não escolhe por você: lista os candidatos e pede o ano.

O que você deve saber antes de confiar em uma resposta

Isto não é assessoria jurídica. É um buscador que dá a um assistente de IA acesso a fontes oficiais. Verifique sempre no link que acompanha cada resposta.

A vigência vem da SUIN, e somente da SUIN. Nem o Gestor nem a relatoria têm um campo que diga «esta norma está revogada»: as revogações vão escritas dentro do texto, e o servidor se limita a avisar quando detecta marcas de «Revogado» ou «Modificado por» (o Decreto 1083 de 2015 contém 155 notas de modificação). SUIN-Juriscol, do Ministério da Justiça, publica o estado como dado, e é a única fonte do país que o faz: quando a norma está no índice empacotado, resolver_cita devolve esse estado com seu link.

Três avisos sobre esse dado, todos comprovados:

É entregue literal, nunca traduzido para um sim ou um não. SUIN distingue «Vigente», «REVOGADO», «Vigência em Estudo», «Compilado», «Declarado Inexequível» e «Norma não vigente porque esgotou seu objeto». «Vigência em Estudo» não significa vigente.
O estado é lido do registro do documento, não de sua prosa. Onde os dois aparecem, contradizem-se: a Lei 1541 de 2012 mostra «Vigente» na tela e «Vigência em Estudo» em seu campo.
O buscador da SUIN não serve para isso. buscar_en_suin devolve um campo de vigência que vem de seu índice de busca e contradiz a ficha — a Lei 74 de 1923 figura ali como «Vigência em Estudo» e sua ficha diz REVOGADO —, então é marcado como não confiável em cada resposta.

E a regra de fundo não muda: verifique no link antes de agir. O buscador do Gestor não busca no texto completo, apenas nos resumos temáticos, e une os termos com OR. Seu índice de palavras também é muito pobre: "teletrabalho" casa com 3 documentos em todo o portal, e com nenhum dos 43 conceitos que estão classificados sob esse subtema. O servidor compensa de três formas: remove as palavras vazias antes de consultar, tenta novamente pelo subtema oficial quando a busca por palavras rende pouco, e busca dentro do articulado no seu computador quando você pede uma norma concreta. Além disso, cada resultado de buscar_normas marca quais termos seu extrato menciona e quais não, para que um resultado parcial não seja lido como totalmente pertinente.

Os códigos são citados pelo nome, e falta o Civil. resolver_cita entende "art. 191 do Código de Comércio" além de "art. 191 do Decreto 410 de 1971", e diz contra qual norma resolveu: Comércio (Decreto 410 de 1971), Substantivo do Trabalho (Decreto 2663 de 1950), Processual do Trabalho (Decreto 2158 de 1948), Penal (Lei 599 de 2000), Processo Penal (Lei 906 de 2004), Geral do Processo (Lei 1564 de 2012), CPACA (Lei 1437 de 2011), Infância e Adolescência (Lei 1098 de 2006) e Estatuto Tributário (Decreto 624 de 1989). O CÓDIGO CIVIL (Lei 84 de 1873) não está no corpus: nem o Gestor o publica nem o índice da SUIN o traz, então a ação reivindicatória, a responsabilidade civil, a filiação, o divórcio e a prescrição ordinária ficam fora do que aqui se pode verificar. O servidor diz isso com essas palavras em vez de responder "não encontrei a citação", que se lê como se a norma não existisse.

As leis modificadoras trazem o artigo que substituem. Quando uma lei está redigida como "O artigo 217 do Código Civil ficará assim:", o texto novo vai abaixo com sua própria numeração; o extrator o devolve junto ao artigo pedido em vez de cortar nos dois pontos. O corpo normativo modificado continua sendo outro documento: se for o Código Civil, não está aqui.

Ritmo de consulta. O servidor faz no máximo uma requisição por segundo sustentada a cada portal, com rajadas de até cinco, e nunca duas ao mesmo tempo ao mesmo site. Se um portal responder que está limitando as consultas, espera o que ele indicar em vez de insistir. São serviços públicos e convém que um assistente automático pese menos que uma pessoa navegando.

Privacidade. Cada consulta viaja para servidores do Estado colombiano, que registram as requisições e seu endereço IP, assim como se você navegasse no site. Nada é enviado a nenhum outro servidor, não há analytics e nenhuma informação sua é coletada. Tenha isso em mente se for consultar sobre um assunto próprio.

Dados empacotados. Incluem-se dois índices, ambos com data de geração (2026-08-01):

O temático (12.063 pares tema/subtema, 56.458 associações norma–subtema) responde na hora e continua servindo se o portal cair. Se passar de três meses, o servidor avisa você.
O da SUIN (11.599 leis, de 1844 a 2026) traduz uma citação para seu documento, porque a SUIN não tem buscador utilizável. A vigência é consultada ao vivo; o índice só diz onde olhar. Cobre leis, não decretos: os sitemaps de decretos do portal retornam 404, então para um decreto a vigência normalmente não consta — o que não significa nem que esteja vigente nem que esteja revogado.

Cobertura da busca tributária. A primeira consulta de cada termo à DIAN leva cerca de 20 segundos: o portal dela retorna o resultado completo e não aceita limite. As páginas seguintes do mesmo termo são instantâneas, então convém paginar em vez de repetir buscas.

O link do Conselho de Estado expira; o número do processo não. buscar_jurisprudencia_consejo_estado entrega, junto a cada provimento, um token assinado que o próprio buscador emite e com o qual obtener_documento com fonte consejo extrai o texto do PDF. Esse token dura uma hora: serve para ler, não para citar. Para citar, usa-se o número do processo. Se expirou, repete-se a busca e sai um novo.

O texto da Corte Suprema é pedido com sua turma e sua sala. buscar_jurisprudencia_suprema retorna a referência, o relator, a data e as normas citadas; obtener_documento com fonte suprema retorna o texto completo, mas exige a MESMA sala com a qual o provimento apareceu: o backend o busca dentro dessa sala e de outra não o encontra.

A relatoria não indexa frases longas. buscar_jurisprudencia com várias palavras ("mora querella policiva") faz o buscador da Corte responder com um aviso de "buscas flexíveis" e 0 resultados. O servidor detecta isso, tenta novamente com a palavra mais distintiva do termo ("querella") e anuncia na resposta: "A relatoria não indexa a frase completa; buscou-se com o núcleo «X»". Verifique a pertinência do resultado contra o que você buscava.

Para desenvolvedores

npm install
npm run check              # typecheck + lint + pruebas de biblioteca + de extremo a extremo
npm run medir              # métricas: bundle, arranque, índices y una fila por herramienta (p50/p95/peticiones/bytes)
npm run generar-indice     # regenera datos/indice-tematico.json (~20 MB de descarga)
npm run generar-indice-suin # regenera datos/indice-suin.json (~45 min; reanudable)
npm run pack               # produce normativa-colombia.mcpb

datos/ está versionado: sem ele, um clone limpo não passa nos testes, e o índice da SUIN custa 45 minutos de requisições a um serviço público. Regere-os apenas quando quiser atualizá-los.

Os testes consultam os portais oficiais. SIN_RED=1 npm test roda apenas a lógica pura, útil para iterar rápido ou sem conexão.

Não há integração contínua: npm run check é rodado manualmente antes de publicar. Convém executá-lo de vez em quando mesmo sem ter tocado no código, porque é o que detecta que um portal mudou seu HTML.

O arquivo glama.json da raiz declara os metadados do servidor no registro da Glama (schema oficial com maintainers); ele é empacotado no .mcpb e viaja no pacote npm. O checklist de qualidade e o diagnóstico das descrições das ferramentas vivem em CALIDAD_HERRAMIENTAS_GLAMA.md (nota de trabalho, não é publicado no npm).

Estrutura:

Arquivo	Responsabilidade
`src/index.ts`	Ferramentas e prompts MCP
`src/nucleo/`	Núcleo compartilhado: `parse.ts` (extração e limpeza de HTML, fatiamento, canário anti-quebra), `citas.ts` (parser de citações), `codigos.ts` (os códigos pelo nome e sua cobertura), `http.ts` (cliente HTTP com a cadeia TLS completa), `ca.ts` (intermediários TLS), `evidencia.ts`, `compiladas.ts`, `alternativas.ts`, `entidades.ts`, `jerarquia.ts`, `perfiles.ts`, `indice.ts`, `expediente.ts`, `actualizacion.ts`, `deduplicar.ts`, `portal-roto.ts`, `snapshot.ts`
`src/herramientas/`	Handlers de ferramentas MCP: `obtener_documento.ts`, `diff.ts` (comparação de artigos), V2 (`analizar_conflicto`, `cambios_desde`, `comparar_articulos`, `consultar_jerarquia`, `consultar_perfil`, `consultar_vigencia`, `expedientes`, `historial_norma`, `validar_cita`, `buscar_unificado`); `resolver_cita` está em `index.ts`
`src/fuentes/gestor.ts`	Gestor Normativo (HTML raspado, com canários)
`src/fuentes/suin.ts`	SUIN-Juriscol: ficha, vigência e índice empacotado
`src/fuentes/normograma.ts`	Normograma da DIAN (JSON)
`src/fuentes/jurisprudencia/`	Três tribunais: `corte.ts` (relatoria Constitucional, JSON), `cortesuprema.ts` (GraphQL), `consejoestado.ts` (WebForms, sem API)
`src/fuentes/sectorial/`	Reguladores setoriais (CREG, ANH, UPME, ANLA e mais 11 via `buscar_normativa_sectorial`)
`scripts/medir.ts`	Banco de métricas, para que otimizar não seja no olho
`scripts/verificar.ts`	`npm run verificar`: comando único de saúde (build → typecheck → lint → unit → cobertura tool→caso → rede → varreduras)
`scripts/barrido-terminos.ts`	`npm run barrido-terminos`: detecta "termo que antes rendia e agora vazio" por fonte (regressão de portal)
`test/smoke.ts`	Testes de biblioteca contra as fontes reais
`test/e2e.ts`	Inicia o servidor e fala com ele por stdio, como qualquer cliente MCP
`test/red*.ts`	Rede de regressão: casos por domínio lendo `content[0].text` cru e `isError`

As instruções de uso que o modelo recebe estão em INSTRUCCIONES, em src/index.ts: são o único mecanismo que orienta qual ferramenta é escolhida, coisa que nenhum teste pode verificar.

Duas notas para quem for mexer nisso:

Quatro portais enviam a cadeia TLS incompleta. funcionpublica.gov.co apresenta um certificado de "Sectigo RSA Organization Validation" mas envia o intermediário de Domain Validation; suin-juriscol.gov.co, sic.gov.co e www.corteconstitucional.gov.co (intermediário "Go Daddy Secure Certificate Authority - G2") omitem diretamente o deles. curl tolera isso porque seu bundle já os traz; Node não. src/nucleo/ca.ts inclui os quatro intermediários para completar a cadeia sem desativar a verificação: as raízes que os assinam vêm com Node. Não troque por rejectUnauthorized: false.
Os códigos HTTP mentem em duas fontes. O backend da Corte Suprema responde 200 com uma página de manutenção para rotas inventadas, e a relatoria da Constitucional retorna o esqueleto de sua SPA em vez de um 404. Por isso os canários validam a forma da resposta e nunca o código de status.
O canário. Se o HTML do portal mudar, os parsers lançam CanarioError em vez de retornar listas vazias. É deliberado: uma lista vazia silenciosa se lê como "essa norma não existe", e em matéria legal essa confusão é o pior erro possível.
Uma falha de rede nunca se apresenta como um vazio. buscar_unificado distingue "respondeu sem nada" de "não foi possível consultar: " por fonte; uma fonte caída não autoriza concluir que não há resultados ali.
A SIC vive na sede eletrônica. O repositório antigo (www.sic.gov.co/repositorio-de-normatividad) responde 301 para sedeelectronica.sic.gov.co/transparencia/normativa/busqueda-de-normas/entidad; o adaptador aponta direto para a sede porque pedir não segue redirecionamentos.

Contribuir

Os guias estão em CONTRIBUTING.md, e há quatro regras que não se negociam: o canário nunca retorna vazio em silêncio, não se desativa a verificação TLS, não se aumenta o ritmo de requisições aos portais e nenhuma resposta afirma vigência.

Se o servidor deu uma resposta incorreta, esse é o relato mais valioso: há um modelo de issue para isso.

Para relatar uma vulnerabilidade, veja SECURITY.md; não abra um issue público.

Licença

Código sob licença MIT (ver LICENSE). Sobre os conteúdos normativos e o acesso automatizado aos portais, veja NOTICE.md.