# Angelthebestone/Normativa-colombiana-MCP [Health: Active]

**Category:** ⚖️ Legal  
**Repository:** https://github.com/Angelthebestone/Normativa-colombiana-MCP  
**GitHub Stars:** 3  
**npm Downloads (last month):** 990  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/angelthebestone-normativa-colombiana-mcp

## Description
Colombian law and jurisprudence: Gestor Normativo (laws, decrees, resolutions), Corte Constitucional (49,000+ rulings), SUIN-Juriscol with validity status, Corte Suprema de Justicia, Consejo de Estado, and DIAN Normograma (tax, customs, forex). Install: npx -y normativa-colombia-mcp.

## Tools
Capabilities this server exposes over MCP:

- **resolver_cita** — Ruta rápida y exacta para citas de leyes, decretos, sentencias, artículos y códigos citados por su nombre ("art. 191 del Código de Comercio"). Úsala SIEMPRE que la pregunta mencione una norma concreta: buscar_normas y buscar_por_tema son para cuando no la hay. Devuelve la identificación oficial con su enlace, la vigencia y el texto pedido, y dice contra qué norma resolvió. Solo consulta, no guarda nada. Tres modos: cita sola; citas, un lote de 1 a 20 que se agrupa por norma (cita o citas, nunca las dos); o articulos con cita apuntando a UNA norma, que se descarga una vez (con citas, articulos se ignora). validar=true cambia la respuesta a un VEREDICTO sobre la cita (validada, parcialmente validada o no validable), sin texto ni vigencia; url y formato solo valen con validar. Para las reformas de una norma usa historial_norma; para quién cita una sentencia, linea_jurisprudencial.
- **buscar_normas** — Busca leyes, decretos, resoluciones, conceptos y sentencias del sector público colombiano. IMPORTANTE: el buscador del portal indexa solo los resúmenes temáticos, NO el articulado completo, y une los términos con OR. Usa pocas palabras y muy distintivas. Para buscar dentro del texto de una norma concreta, usa obtener_documento con fuente="gestor" y buscar_en_texto. Para una cita exacta, usa resolver_cita.
- **buscar_por_tema** — Consulta temática oficial: devuelve tema, subtema y las normas, sentencias y conceptos asociados (hasta 8 por fila). Responde desde un índice empaquetado, instantáneo y sin red; solo si el índice no tiene el término consulta el portal del Gestor. limite cuenta filas de tema/subtema, no documentos. Cada fila trae temsubid ("ts-38872") y normid: pásalos juntos, de la MISMA fila, a explicar_relacion_tema. El prefijo "ts-" es parte del id: pégalo tal cual y no lo cruces con el "sub-" ni el "tema-" de listar_catalogos, que son otras dos taxonomías del portal con los mismos números. Para una norma concreta usa resolver_cita; para buscar palabras en los resúmenes, buscar_normas.
- **listar_catalogos** — Valores válidos para los filtros de buscar_normas: tipos de documento, años, entidades y temas, más los subtemas de un tema (subtemas con tema_id), los conceptos de Función Pública (conceptos_fp con numero/anio) y el listado curado del DAFP (normas_fp). En temas el filtro es obligatorio por volumen, y sus ids llevan prefijo ("tema-24457") porque el portal tiene tres taxonomías que reutilizan los mismos números. OJO CON EL ALCANCE: estos catálogos son SOLO del Gestor Normativo de Función Pública y solo sirven en buscar_normas; no cubren la DIAN (su normograma está en buscar_normativa_tributaria), ni SUIN-Juriscol, ni las tres altas cortes. Que "DIAN" no aparezca entre las entidades no significa que no haya normativa suya: significa que el Gestor no la cataloga como entidad emisora.
- **buscar_jurisprudencia** — Sentencias y autos de la relatoría de la Corte Constitucional (44.839 providencias, con fallos de 2026 publicados el mismo año). Es la vía para jurisprudencia constitucional: el Gestor tiene muy poca. Devuelve sentencia, tipo, fecha, síntesis y la ruta para obtener_documento con fuente="corte". La relatoría no indexa frases largas: con varias palabras se reintenta con la más distintiva y la respuesta lo anuncia ("se buscó con el núcleo «X»"). Es la CORTE CONSTITUCIONAL: para la Suprema usa buscar_jurisprudencia_suprema; para el Consejo de Estado, buscar_jurisprudencia_consejo_estado.
- **buscar_normativa_tributaria** — Normograma de la DIAN: decretos, resoluciones, conceptos y circulares en materia tributaria, aduanera y cambiaria, que ninguna otra herramienta cubre. Devuelve el extracto y el enlace; para leer el documento usa obtener_documento con fuente="dian". Para una ley o un decreto que ya tienes citado, también el Estatuto Tributario y sus artículos, usa resolver_cita; buscar_normas no mira este normograma. AVISO: la primera búsqueda de cada término tarda ~20 s (el portal devuelve el resultado completo y no admite tope), pero las páginas siguientes del MISMO término son instantáneas: pagina con desde en vez de lanzar búsquedas nuevas.
- **buscar_jurisprudencia_suprema** — Providencias de la Corte Suprema por sala (Tutelas, Civil, Laboral o Penal), desde 1991. NO es la Corte CONSTITUCIONAL (usa buscar_jurisprudencia) ni el Consejo de Estado (buscar_jurisprudencia_consejo_estado). Cada resultado trae las NORMAS QUE CITA (resolubles con resolver_cita) y una RUTA con la que obtener_documento con fuente="suprema" devuelve el texto. Cada llamada mira UNA sala y, si no la indicas, solo Tutelas: una pregunta civil, laboral o penal tiene que nombrar su sala; anio y magistrado acotan dentro de ella. Si la frase exacta no da nada, se repite sola con OR y la respuesta lo avisa: no pases exacto=false para eso. Busca en el texto completo sin descartar palabras comunes: usa términos distintivos.
- **buscar_jurisprudencia_consejo_estado** — Providencias tituladas del Consejo de Estado, el supremo de lo contencioso administrativo (nulidad y restablecimiento, contratación estatal, nulidad electoral, reparación directa, conceptos de la Sala de Consulta). Para la Corte Constitucional usa buscar_jurisprudencia; para la Suprema, buscar_jurisprudencia_suprema; con un radicado concreto, resolver_cita. Cada resultado trae el problema jurídico y su respuesta, el enlace a la ficha en SAMAI y el token con el que obtener_documento (fuente="consejo") devuelve el texto. CÓMO BUSCA: con exacto=true (activado) busca la FRASE EXACTA y, si no aparece, se amplía solo a OR avisándolo; en modo OR el número de páginas mide el corpus, no la pertinencia. Avanza con pagina; limite recorta DENTRO de la página y lo que deja fuera no sale en la siguiente.
- **buscar_en_suin** — Busca en el índice del buscador de SUIN-Juriscol (MinJusticia, unos 103.000 documentos hasta 2026) por tipo, número, año, título, epígrafe, materia, sector o entidad. coleccion elige qué se busca: "normas" (por defecto: leyes, decretos, resoluciones, circulares, directivas… desde 1844), o la jurisprudencia que SUIN registra porque afectó la vigencia de alguna norma: "corte-constitucional", "consejo-estado" o "corte-suprema". Los reglamentos técnicos se buscan por materia (ej. "Bebidas alcohólicas"). Cada resultado trae el estado de vigencia de su ficha, el enlace y el id con el que obtener_documento (fuente="suin") lee el texto. NO busca dentro del articulado. vigencia, sector y materia acotan la búsqueda; para el tramo siguiente repite la misma llamada con desde = desde + limite. Ante un vacío, NO concluyas que no existe: prueba buscar_por_tema.
- **explicar_relacion_tema** — Devuelve el "restrictor": el extracto que explica por qué esa norma es pertinente para ESE subtema en concreto. Ambos identificadores deben salir de la MISMA fila de buscar_por_tema, y el temsubid va con su prefijo ("ts-38872"): un id de listar_catalogos (catalogo="subtemas") o de otros catálogos se rechaza aquí. Para ver todos los restrictores de una norma de una vez, usa obtener_documento con fuente="gestor" y mira su bloque "Temas asociados".
- **buscar_normativa_anh** — Resoluciones, acuerdos y circulares de la Agencia Nacional de Hidrocarburos (785 documentos): contratos de exploración y producción, regalías, fiscalización y reservas. ÚSALA para hidrocarburos y regalías; NO devuelve el texto (publica en PDF), solo el epígrafe, el PDF y la ficha. Para leyes o decretos nacionales de cualquier sector usa resolver_cita. Por defecto OCULTA los actos de personal, que son dos de cada tres; pídelos con incluir_administrativos=true si de verdad los buscas.
- **buscar_normativa_upme** — Circulares y resoluciones de la Unidad de Planeación Minero Energética: convocatorias de transmisión y de gas, planes de expansión y actos administrativos. Devuelve título, resumen, fecha de publicación y enlace al PDF; NO el texto. Para la CREG usa buscar_resoluciones_creg; para leyes y decretos, resolver_cita. pagina cuenta en bloques de limite: no cambies limite mientras paginas. Los actos de personal se quitan DESPUÉS de traer la página, así que una página puede mostrar menos de limite sin ser la última. OJO CON LAS FECHAS: la fecha que publica su portal es la de PUBLICACIÓN EN LA WEB, no la de la norma — la "Resolución 1163 de 2024" figura publicada en 2025. El número y el año reales están en el título.
- **buscar_resoluciones_creg** — Resoluciones de la Comisión de Regulación de Energía y Gas: tarifas, conexión, comercialización, plantas solares y gas natural. Devuelve número, año, epígrafe, el estado según la compilación y la ruta para leer el texto con obtener_documento (fuente="creg"): es la ÚNICA fuente sectorial con texto legible aquí. Cada consulta recorre UNA compilación de UN año: texto filtra dentro de ese año (por número, año o epígrafe, nunca por el contenido), así que para una resolución antigua pasa anio aunque ya pongas su número en texto; "todas" junta vigentes y derogadas de ese mismo año. La señal de vigencia se traslada literal, no la conviertas en un sí o un no. Para la UPME usa buscar_normativa_upme; para leyes o decretos nacionales, resolver_cita.
- **listar_normativa_ambiental_anla** — La ANLA mantiene en su sistema "Eureka" una CURADURÍA de la normativa nacional que aplica al licenciamiento ambiental, agrupada por tema. Lo que aporta es la CLASIFICACIÓN, no documentos nuevos: casi todo lo que lista son leyes y decretos que resolver_cita ya resuelve mejor, con texto completo y con vigencia. Devuelve título, resumen y enlace de cada entrada, y avisa cuando el número del título no cuadra con el resumen. seccion elige el tema (por defecto, "leyes"); texto filtra SOLO la página que trae desde, no la sección entera, así que un vacío no es definitivo: repite sin texto para ver la página y el desde siguiente. Úsala para descubrir QUÉ normas aplican a un tema ambiental y resuelve cada una con resolver_cita; para filtrar de una vez la primera página de todas las secciones, consultar_perfil con perfil="ambiental".
- **buscar_normativa_sectorial** — Actos administrativos —resoluciones, circulares, acuerdos— de los reguladores y ministerios sectoriales que el Gestor Normativo NO cataloga; elige cuál en `entidad`. CUÁNDO NO USARLA: para leyes y decretos nacionales de cualquier sector usa resolver_cita o buscar_por_tema, que dan texto completo y vigencia; el Decreto Único Reglamentario de cada sector (1071, 1072, 1074, 1076, 1079…) ya está en el Gestor.
Casi todas entregan PDF sin texto extraíble, y la mayoría no publica estado de vigencia; donde aparece (ANM, Supersociedades) es la fila del propio portal, no una verificación: para el estado real de una ley o un decreto, resolver_cita.
LOS FILTROS NO SE COMPORTAN IGUAL EN TODAS: el Invima y el Ministerio de Educación exigen texto o año; la Superfinanciera y la Supertransporte se quedan en el año en curso si no indicas otro; el Ministerio de Transporte solo busca su catálogo de 2016–2024 si indicas el año (sin año, solo los actos de 2025 en adelante); la ANM no aplica el año a las circulares. Cada respuesta dice qué hizo, pero no lo adivines: indica el año si lo esperabas.
- **describir_fuentes** — Declara el alcance real: qué fuente responde cada pregunta, qué NO está cubierto y con qué fecha se generaron los índices que viajan empaquetados. Úsala ANTES de concluir que algo "no existe" a partir de una búsqueda vacía, y para saber si el índice de vigencia sigue fresco. No consulta la red. Con el parámetro `fuente` devuelve SOLO el alcance de esa fuente, que es lo que suele hacer falta; sin él, el cuadro completo, que es largo.
- **consultar_por_jerarquia** — Busca normativa colombiana de UN nivel de autoridad y explica su carácter: vinculante, orientador o informativo. Devuelve los documentos de ese nivel con título y enlace, y el carácter del nivel. nivel decide la fuente: "jurisprudencia" busca solo en la relatoría de la Corte Constitucional (para la Suprema usa buscar_jurisprudencia_suprema; para el Consejo de Estado, buscar_jurisprudencia_consejo_estado); los demás, en el Gestor filtrado por tipo, donde texto se busca en los resúmenes, no en el articulado. ÚSALA cuando la pregunta pida un nivel concreto (p. ej. "¿qué leyes hay sobre X?"); para buscar sin nivel usa buscar_normas o buscar_por_tema, y para el texto de un artículo de la Constitución, resolver_cita. No es asesoría jurídica: verifica en el enlace.
- **analizar_conflicto** — Reúne para dos normas la EVIDENCIA de un posible conflicto. Por cada una: identificación en el Gestor, vigencia según SUIN cuando consta, nivel en la jerarquía y su carácter, y notas de reforma de cualquier artículo. Con sobre añade los pasajes de ambas que mencionan ese tema. NO detecta contradicciones semánticas: el resultado es un conflicto POTENCIAL, no una conclusión jurídica; verifica en los enlaces antes de actuar. Para confrontar el texto de dos artículos concretos usa comparar_articulos. Con formato="json" devuelve un objeto con fecha_consulta, alcance, sobre (si se pidió), evidencias (una por norma, con los mismos campos del texto) y avisos.
- **cambios_desde** — Resume los cambios (modificación, derogación, adición) que el Gestor anota sobre LAS NORMAS QUE SE LISTAN: por norma, la acción, la norma modificadora, el artículo y la nota literal. De desde solo cuenta el año, así que "2019-12-31" incluye todo 2019, y las notas sin año se descartan. Cada cita necesita su año y se resuelve por separado: una que falla se anota y no frena a las demás. NO rastrea novedades ni descubre normas nuevas: para lo recién publicado usa buscar_diario_oficial; para la historia completa de una sola norma, incluidas las notas sin año, historial_norma.
- **comparar_articulos** — Compara el texto de un artículo entre dos normas y marca lo añadido y lo eliminado. Clasifica cada diferencia por patrones de texto (plazo, sanción, excepción, sujeto obligado, prohibición u obligación) y detecta cambios editoriales por similitud léxica (Dice bigramas, ≥0,92); lo que no encaja se marca «revisar manualmente». Sin modelo semántico. Con con_reforma=true no hace falta la segunda norma: busca la última reforma que el portal anota al artículo, extrae el artículo de la norma modificadora y lo contrasta con el texto vigente, porque la página consolida y no publica la redacción anterior. Para ver todas las reformas de la norma usa historial_norma; para reunir evidencia de un conflicto entre dos normas enteras, analizar_conflicto.
- **consultar_perfil** — Ejecuta la consulta en la ÚNICA fuente que fija cada perfil sectorial: laboral → Gestor Normativo, tributario → DIAN, ambiental → ANLA, contratación estatal → Consejo de Estado, energía → CREG (solo el año en curso). Devuelve una línea por resultado, con el sector y la advertencia del perfil, que declara sus límites. El perfil no admite año, página ni otros filtros: para eso usa la herramienta propia de la fuente (p. ej. buscar_resoluciones_creg con anio). Solo consulta, no guarda nada. NO uses un perfil para lo que no cubre: si la materia es otra, usa buscar_normas o resolver_cita.
- **consultar_vigencia** — Devuelve el estado de vigencia de una ley o un decreto tal como lo publica la ficha de SUIN: "Vigente", "Derogado", "Vigencia en Estudio", "Compilado" u otro. Añade un nivel de confianza. Alta: la ficha respondió. Baja: no consta, o la fuente no respondió. Nunca inventa el estado. Una sentencia como "C-337/11" no tiene vigencia: se comprueba en la relatoría de la Corte Constitucional si existe. El estado es el de la norma entera, aunque la cita nombre un artículo. Para las reformas de un artículo usa historial_norma; para su texto, resolver_cita. Si la cita no trae año y hay varias candidatas, las lista en vez de elegir. La respuesta empieza con la línea de alcance: qué fuente se consultó y cuál no.
- **historial_norma** — Devuelve la cadena de reformas que el Gestor anota sobre una norma: qué norma la modificó, adicionó, derogó, sustituyó... y qué artículo afectó cada cambio, con la nota literal citable. Las ordena por el año de la norma que introduce cada cambio (las notas sin año van al final, sin ordenar) y señala la última reforma ANOTADA, que no es necesariamente la que rige: el portal no siempre anota todas. articulo filtra primero; desde y limite recortan después esa lista ya ordenada, y la última reforma se calcula sobre todo lo filtrado, no sobre el tramo mostrado. Para la vigencia usa resolver_cita; para los cambios de varias normas a partir de un año, cambios_desde; para comparar el texto antes y después, comparar_articulos. Con formato="json" el objeto trae titulo, url, total, cambios, ultima_reforma y avisos.
- **buscar_unificado** — Busca en paralelo en Gestor Normativo, Corte Constitucional, SUIN-Juriscol y DIAN, y agrega los resultados con su fuente y su enlace. Úsala cuando la consulta es abierta o por materia y no hay herramienta obvia; para una cita exacta sigue siendo mejor resolver_cita y para un tribunal concreto, su buscador propio. perfil elige las fuentes ("salud" añade INVIMA y Supersalud; "mineria", la ANM) y el orden; si pasas fuentes, esa lista manda y el perfil solo ordena. limite es POR fuente, así que el total puede multiplicarse. El estado de SUIN es el de su ficha, copiado tal cual. Cuando la fuente sirve su texto, cada resultado trae "Para leer", la llamada lista a obtener_documento. Una fuente caída se declara como fallo, no como vacío.
- **linea_jurisprudencial** — Devuelve las providencias que la relatoría registra como CITANTES de una sentencia de la Corte Constitucional (el bloque "citaciones" de su ficha oficial), con tipo, fecha, tema, la ruta para obtener_documento y el enlace. Son citas, no una línea verificada: mencionar no es reiterar y la relación puede estar incompleta. Se ordenan con las SU y las C en cabeza ANTES de aplicar limite, así que un limite bajo deja fuera primero las T y los autos; el portal no registra más de 100 y no hay paginación. Úsala cuando ya tienes la sentencia y quieres saber quién la cita. Para encontrar sentencias sobre un tema usa buscar_jurisprudencia; para leer o verificar la propia sentencia citada, resolver_cita. Solo cubre la Corte Constitucional.
- **buscar_diario_oficial** — Diarios Oficiales publicados: número, tipo de edición (Ordinaria, Extraordinaria, Especial, Oficio o Tributario) y fecha de publicación. Sirve para saber qué salió publicado y cuándo, incluso el mismo día, antes de que el Gestor Normativo lo catalogue. Filtra por número de diario, por rango de fechas y por el tipo y el número de una norma (encuentra el diario que la publicó: tipo="LEY" y numero_norma="2466" devuelve el 53.160). NO dice qué normas contiene cada diario ni trae su texto, y el PDF del diario no tiene enlace estable: para el texto de una norma usa resolver_cita; para buscarla por materia, buscar_normas.
- **obtener_documento** — Devuelve el texto (troceado, nunca entero) de una de las ocho fuentes con texto. CADA FUENTE EXIGE LO SUYO y los parámetros de otra no valen con ella: gestor necesita id; suin, id; corte, ruta; suprema, ruta y sala; consejo, token; dian, link; creg, ruta; sectorial, entidad y url. Una combinación que no encaje se rechaza antes de salir a la red, diciendo qué falta y el ejemplo mínimo que funciona. Qué parte sale: historial (gestor) da los cambios anotados en vez del texto, del artículo si va con articulo; articulo (gestor y suin) o seccion (cortes) acotan y entonces buscar_en_texto no se aplica; desde solo avanza el troceo, no los pasajes de buscar_en_texto. Informa total/mostrado/omitido y el "desde" del trozo siguiente. ESCRIBE EN DISCO solo con entero o ruta_destino, que se imponen a todo lo anterior: dian y sectorial guardan el archivo original; las demás, texto-<fuente>.txt (sin ruta_destino, en una carpeta temporal); consejo no lo admite. Nunca sobrescribe: un nombre repetido lleva sufijo. Para encontrar el documento usa antes resolver_cita o el buscador de su fuente.
- **expediente** — Crea, agrega, lee o exporta un expediente para agrupar consultas, citas y observaciones de una investigación. No consulta ninguna fuente: guarda lo que le pasas. Se activa con EXPEDIENTES=1 (DESACTIVADO por defecto). En memoria es TEMPORAL (expira según EXPEDIENTES_TTL_MS; por defecto no expira); con EXPEDIENTES_DIR persiste en disco y sobrevive a reinicios. El flujo empieza siempre en "crear", SIN id: devuelve el id que piden las demás; "agregar" exige campo y texto juntos; "leer" lo devuelve agrupado por sección. "exportar" escribe markdown: si ruta es un directorio crea <id>.md dentro, el directorio padre tiene que existir, y un archivo que ya existe no se sobrescribe: se escribe al lado con sufijo numérico y la respuesta da la ruta final. Para guardar el texto de una norma usa obtener_documento.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "normativa-colombiana-mcp": {
    "command": "npx",
    "args": ["-y","normativa-colombia-mcp@latest"]
  }
}
```

## Documentation & README

# Normativa Colombia — servidor MCP

[![npm](https://img.shields.io/npm/v/normativa-colombia-mcp.svg)](https://www.npmjs.com/package/normativa-colombia-mcp)
[![Licencia: MIT](https://img.shields.io/badge/licencia-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-servidor-black.svg)](https://modelcontextprotocol.io)

Consulta la normativa y la jurisprudencia colombiana desde cualquier asistente de IA que hable [Model Context Protocol](https://modelcontextprotocol.io), sin abrir el navegador ni pelear con formularios.

Conecta seis fuentes oficiales:

- **Gestor Normativo** del Departamento Administrativo de la Función Pública — leyes, decretos, resoluciones, circulares y conceptos del sector público, con la consulta temática y los *restrictores* que explican por qué cada norma aplica a un tema.
- **Relatoría de la Corte Constitucional** — 44.839 providencias según su propio índice, con fallos recientes publicados el mismo año.
- **SUIN-Juriscol** del Ministerio de Justicia — **el estado de vigencia**, que ninguna otra fuente del país publica, y su buscador nuevo: unos 103.000 documentos de 1844 a 2026 (leyes, decretos, resoluciones, circulares, reglamentos técnicos y la jurisprudencia que afectó la vigencia de alguna norma), con su texto, muchos de los cuales el Gestor no tiene.
- **Corte Suprema de Justicia** — providencias de las salas de Tutelas, Civil, Laboral y Penal, cada una con las normas que cita.
- **Consejo de Estado** — providencias tituladas de lo contencioso administrativo, con el problema jurídico que la Sala se planteó, su respuesta y el texto completo. Con esta se completan las tres altas cortes, y las tres entregan texto.
- **Normograma de la DIAN** — normativa tributaria, aduanera y cambiaria.

Es un servidor MCP estándar que se comunica por **stdio**, así que sirve en Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Continue, LM Studio, agentes propios hechos con los SDK de MCP y cualquier cliente que aparezca después.

---

## Instalación

### Opción A — Claude Desktop, con un clic

La más sencilla si usas Claude Desktop: no requiere Node ni tocar archivos de configuración.

1. Descarga `normativa-colombia.mcpb` desde [Releases](https://github.com/Angelthebestone/Normativa-colombiana-MCP/releases).
2. Abre Claude Desktop → **Configuración → Extensiones**.
3. Arrastra el archivo a esa ventana y confirma.
4. *(Opcional: instalar sin ciertas fuentes)* En Claude Desktop, abre la configuración de la extensión **Normativa Colombia**. En el campo **Fuentes** puedes indicar qué fuentes desactivar (p. ej. `-creg,-anh,-upme,-anla,-sectorial` para instalar sin fuentes sectoriales y ahorrar contexto) o cuáles conservar (`corte,suin`). Si lo dejas vacío, incluye todas.

Claude Desktop trae su propio Node, así que no hace falta instalar nada más.

**Actualizaciones:** una extensión `.mcpb` no se actualiza sola. Cuando npm tenga una versión más nueva que la instalada, la primera respuesta de la sesión lo avisa una vez, con el enlace al último release; descárgalo y arrástralo igual que la primera vez. Si prefieres no volver a hacerlo, usa la Opción B: con `@latest` se actualiza sola.

### Opción B — cualquier otro cliente MCP, desde npm (recomendada)

La forma más sencilla y la que evita errores de rutas: no hay que clonar nada ni apuntar a archivos locales. Requiere **Node 18 o superior**.

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

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

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

El sufijo `@latest` importa: sin él, `npx` reutiliza la copia que ya tiene en su caché y no vuelve a mirar el registro, así que te quedas con la versión del primer día. Con `@latest` consulta npm en cada arranque y trae la versión más reciente. Si ya tenías configurado el servidor sin `@latest`, añádelo al argumento. Además, el servidor avisa una vez por sesión cuando hay una versión más nueva que la que corre.

Casi todos los clientes comparten este formato:

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

Para instalar **sin ciertas fuentes** (por ejemplo, sin los reguladores sectoriales para reducir consumo de contexto), añade la variable `FUENTES` en `env`:

```json
{
  "mcpServers": {
    "normativa-colombia": {
      "command": "npx",
      "args": ["-y", "normativa-colombia-mcp@latest"],
      "env": {
        "FUENTES": "-creg,-anh,-upme,-anla,-sectorial"
      }
    }
  }
}
```

| Cliente | Dónde va esa configuración |
| --- | --- |
| **Claude Desktop** (manual) | `claude_desktop_config.json` — en Configuración → Desarrollador → Editar configuración |
| **Cursor** | `.cursor/mcp.json` en el proyecto, o `~/.cursor/mcp.json` para todos |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |
| **Continue** | El bloque `mcpServers` de su configuración |
| **LM Studio** | Program → Install → Edit mcp.json |
| **Agente propio** | Como `StdioServerParameters` del SDK de MCP, en Python o TypeScript |

**Claude Code** no usa archivo; se registra por línea de comandos:

```bash
# con todas las fuentes
claude mcp add normativa-colombia -- npx -y normativa-colombia-mcp@latest

# o sin fuentes sectoriales
claude mcp add normativa-colombia -e FUENTES="-creg,-anh,-upme,-anla,-sectorial" -- npx -y normativa-colombia-mcp@latest
```

**VS Code** usa la clave `servers` en vez de `mcpServers`, en `.mcp.json` del proyecto o en la configuración de usuario:

```json
{
  "servers": {
    "normativa-colombia": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "normativa-colombia-mcp@latest"],
      "env": {
        "FUENTES": "-creg,-anh,-upme,-anla,-sectorial"
      }
    }
  }
}
```

Si lo instalaste con `npm install -g`, el comando es `normativa-colombia-mcp` a secas, sin argumentos.

Si tu cliente no está en la lista, busca dónde declara servidores MCP por stdio: el comando y los argumentos son siempre los mismos.

#### Comprobar que quedó bien

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

Debe responder un JSON con `"name":"normativa-colombia"` y un campo `instructions`.

### Opción C — desde el código

Para desarrollar o para fijar una versión propia. Requiere **Node 22 o superior**:

```bash
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/: el lanzador index.js, el bundle servidor.js y el trozo de unpdf que se carga al leer un PDF
```

Después se apunta el cliente a `node /ruta/absoluta/a/Normativa-colombiana-MCP/server/index.js`, con el mismo formato de arriba. Funciona desde cualquier directorio de trabajo.

> Carpeta sin espacios: si la ruta local contiene espacios (p. ej. `C:\Users\…\normativa mcp\server\index.js`), algunos clientes lanzan el comando sin comillas y Node solo ve la primera parte (`C:\Users\…\normativa`) y sale con código 1. Para instalación local, clona en una carpeta sin espacios o usa la Opción B (`npx`), que no tiene este problema.

### Opción D — con Bun (alternativa opcional)

Node sigue siendo el runtime de referencia: es el de las pruebas (`npm run check`) y el del `.mcpb`. El servidor construido en la Opción C también arranca con [Bun](https://bun.sh), y se ha probado **a mano con Bun 1.4.2**: mismo `tools/list`, mismas respuestas y TLS íntegro (Bun respeta la cadena de certificados propia del servidor). Arranca unos 40 ms antes y ocupa unos 19 MB menos de memoria; la latencia de cada consulta es la misma, porque la marca el portal. No se prueba en cada versión: si algo falla solo con Bun, reprodúcelo antes con Node.

El cliente se apunta a `bun /ruta/absoluta/a/Normativa-colombiana-MCP/server/index.js` (misma nota de la carpeta sin espacios). Construir sigue requiriendo Node.

### Qué recibe el cliente

Al conectarse, el servidor entrega **28 herramientas**, **5 prompts** y sus **propias instrucciones de uso**: a qué tipo de pregunta corresponde cada herramienta, que debe citarse siempre la fuente y que nunca debe afirmarse por cuenta propia que una norma está vigente. Los clientes que respetan el campo `instructions` del protocolo lo aprovechan sin configurar nada.

| Fuente | Herramientas |
| --- | --- |
| Cualquiera (punto de entrada) | `resolver_cita` — cita exacta → norma o sentencia, con su vigencia si consta; acepta lote con `citas` y validación con `validar: true`. `consultar_vigencia` — el estado de vigencia con un nivel de confianza (alta/media/baja). `historial_norma` — la cadena de reformas que el Gestor anota sobre una norma (qué la modificó, adicionó o derogó y qué artículo afectó cada cambio), ordenada por el año de la norma que la hizo y con la última reforma anotada señalada; filtrable por `articulo` y paginable con `desde`/`limite`. `buscar_unificado`, `analizar_conflicto`, `historial_norma` y `resolver_cita` (con `validar: true`) aceptan `formato: "json"` para devolver el objeto de datos sin pie de texto |
| Gestor Normativo | `buscar_normas` (con marca de pertinencia por fila: qué términos menciona cada extracto), `buscar_por_tema`, `obtener_documento` (fuente `gestor`, con `sin_temas` para omitir el bloque de temas), `listar_catalogos`, `explicar_relacion_tema` |
| Corte Constitucional | `buscar_jurisprudencia` (`tipos` acepta «tutela», «auto»…), `linea_jurisprudencial` (qué providencias citan una sentencia), `obtener_documento` (fuente `corte`) |
| Corte Suprema | `buscar_jurisprudencia_suprema`, `obtener_documento` (fuente `suprema`) |
| Consejo de Estado | `buscar_jurisprudencia_consejo_estado`, `obtener_documento` (fuente `consejo`) |
| SUIN-Juriscol | `buscar_en_suin` (`coleccion`: normas, corte-constitucional, consejo-estado o corte-suprema; `materia` para los reglamentos técnicos), `obtener_documento` (fuente `suin`, con el resumen de modificaciones y de jurisprudencia) y vigencia vía `resolver_cita` |
| Secretaría del Senado | el Código Civil, artículo por artículo, vía `resolver_cita` (solo HTTP sin cifrar) |
| Diario Oficial | `buscar_diario_oficial` — en qué diario salió una norma (tipo + número) o qué diarios salieron en unas fechas |
| DIAN | `buscar_normativa_tributaria`, `obtener_documento` (fuente `dian`) |
| CREG | `buscar_resoluciones_creg`, `obtener_documento` (fuente `creg`) |
| ANH / UPME / ANLA | `buscar_normativa_anh`, `buscar_normativa_upme`, `listar_normativa_ambiental_anla` |
| 15 reguladores y ministerios sectoriales | `buscar_normativa_sectorial` (entidad: `sic`, `superfinanciera`, `supersalud`, `ant`, `mineducacion`, `mintransporte`, `unidadvictimas`…) + `obtener_documento` (fuente `sectorial`) |
| V2 — jerarquía y conflictos | `consultar_por_jerarquia`, `analizar_conflicto` (reúne EVIDENCIA; la búsqueda de tema prueba singular y plural y declara la variante), `comparar_articulos`, `cambios_desde` |
| V2 — perfiles y expedientes | `consultar_perfil`, `expediente` (acción `crear\|agregar\|leer\|exportar`) |
| Alcance | `describir_fuentes` — qué cubre cada fuente y qué no, sin consultar la red |

### Elegir las fuentes al instalar

Cada herramienta se paga en contexto en cada conversación, se use o no. Si no necesitas algunas fuentes, apágalas con la variable de entorno `FUENTES` (en Claude Desktop, el campo **Fuentes** de la extensión): sus herramientas desaparecen de la lista y su valor sale de los parámetros de las herramientas compartidas (`obtener_documento.fuente`, `buscar_unificado.fuentes`, `consultar_perfil.perfil`, el nivel `jurisprudencia` de `consultar_por_jerarquia`), así que la llamada a una fuente apagada no se puede ni escribir.

| `FUENTES` | Efecto | Herramientas | `tools/list` |
| --- | --- | --- | --- |
| vacía (por defecto) | todas | 28 | 41.862 B |
| `-creg,-anh,-upme,-anla,-sectorial` | todas menos la regulación sectorial | 23 | 34.493 B |
| `corte` | Gestor Normativo y Corte Constitucional | 18 | 26.590 B |

Dos formas, sin mezclar: la lista de las que quieres (`corte,suin`) o la de las que quitas (`-creg,-anh`). Claves: `corte`, `suprema`, `consejo`, `dian`, `suin`, `senado`, `diario`, `creg`, `anh`, `upme`, `anla`, `sectorial`. El Gestor Normativo va siempre: es el corpus de `resolver_cita` y de las herramientas V2. Una clave mal escrita **impide arrancar** con el motivo en el log, en vez de dejarte sin una fuente sin avisar. Las respuestas declaran lo apagado aparte de lo no consultado (`Desactivadas en esta instalación, no consultadas: CREG, ANH…`), y `describir_fuentes` sigue describiendo las fuentes apagadas, marcadas como tales.

## Qué puedes preguntar

- «¿Qué dice la Ley 1221 de 2008 sobre el auxilio de conectividad?»
- «¿Qué normas regulan el teletrabajo en el sector público y por qué aplican?»
- «¿Qué dice el Decreto 1083 sobre encargos?»
- «Búscame jurisprudencia reciente de la Corte Constitucional sobre estabilidad laboral reforzada.»
- «¿La Ley 909 de 2004 sigue vigente?»
- «¿Qué dice la DIAN sobre la retención en la fuente por servicios?»
- «Búscame tutelas de la Corte Suprema sobre teletrabajo y dime qué normas citan.»
- «¿Existe la Ley 74 de 1923 y sigue vigente?» — está derogada, y ni el Gestor la tiene.
- «¿Qué leyes hay sobre teletrabajo?» — `consultar_por_jerarquia` con nivel "ley".
- «Compara el art. 2 de la Ley 909 con el art. 2.2.5.3.1 del Decreto 1083.» — `comparar_articulos`.
- «¿Hay conflicto entre la Ley 909 de 2004 y el Decreto 1083 de 2015 en materia de encargos?» — `analizar_conflicto` (reúne evidencia, no concluye).
- «¿Qué cambió la Ley 909 de 2004 desde 2020?» — `cambios_desde`.
- «Normativa laboral sobre teletrabajo» — `consultar_perfil` con perfil "laboral".

El servidor incluye además cinco prompts listos, que los clientes que los soportan muestran como comandos: *¿Qué normas aplican sobre un tema?*, *¿Esta norma sigue vigente?*, *Explícame esta norma en lenguaje sencillo*, *Compara dos normas* y *Aclarar una consulta ambigua*.

### Herramientas V2

Sobre la capa común de metadatos, evidencia y normalización:

- **`consultar_por_jerarquia`** filtra por nivel (constitución, ley, decreto, resolución, concepto, jurisprudencia) y explica el carácter de cada uno. El Gestor no cataloga la Constitución como tipo: para ese nivel se orienta.
- **`resolver_cita` con `validar: true`** comprueba que una cita y su enlace son de verdad: número/año contra el título, dominio del enlace, id de la norma y existencia del artículo. Clasifica en "validada", "parcialmente validada" o "no fue posible validar"; nunca afirma vigencia.
- **`analizar_conflicto`** reúne EVIDENCIA de un posible conflicto entre dos normas (identificación, vigencia según SUIN si consta, jerarquía, reformas anotadas, pasajes sobre un tema). **No detecta contradicciones semánticas** y el resultado es un conflicto POTENCIAL, no una conclusión jurídica.
- **`cambios_desde`** resume los cambios (modificación, derogación, adición) que el Gestor anota sobre **las normas que se le listan**, filtrados por el año de la norma modificadora. **No rastrea novedades** por su cuenta.
- **`comparar_articulos`** compara el texto de un artículo entre dos normas, marca lo añadido/eliminado, clasifica cada diferencia por patrones (plazo, sanción, excepción, sujeto obligado) y agrupa los cambios editoriales por similitud léxica (Dice sobre bigramas ≥0,92): «una línea» → «una sola línea» sale como cambio menor, no como añadido+eliminado. Lo no clasificado se marca "revisar manualmente". Sin modelo semántico.
- **`consultar_perfil`** ejecuta una consulta con las fuentes y filtros preconfigurados de un perfil: `laboral`, `tributario`, `ambiental`, `contratacion_estatal`, `energia`. Cada perfil declara su advertencia en la respuesta.
- **`expediente`** con `accion="crear|agregar|leer|exportar"` agrupa consultas, citas y observaciones de una investigación. **Desactivado por defecto**: se activa con la variable de entorno `EXPEDIENTES=1`; la persistencia en disco, con `EXPEDIENTES_DIR`.

Una regla de oro de las V2: si una cita viene sin año y el número es ambiguo ("Decreto 1072" son cuatro), la herramienta **no elige por ti**: lista los candidatos y pide el año.

## Lo que debes saber antes de confiar en una respuesta

**Esto no es asesoría jurídica.** Es un buscador que le da a un asistente de IA acceso a fuentes oficiales. Verifica siempre en el enlace que acompaña cada respuesta.

**La vigencia viene de SUIN, y solo de SUIN.** Ni el Gestor ni la relatoría tienen un campo que diga «esta norma está derogada»: las derogatorias van escritas dentro del texto, y el servidor se limita a avisar cuando detecta marcas de «Derogado» o «Modificado por» (el Decreto 1083 de 2015 contiene 155 notas de modificación). SUIN-Juriscol, del Ministerio de Justicia, sí publica el estado como dato, y es la única fuente del país que lo hace: `resolver_cita` y `consultar_vigencia` lo piden en vivo a su ficha por tipo, número y año, y lo devuelven con su enlace.

Tres advertencias sobre ese dato, todas comprobadas:

- **Se entrega literal, nunca traducido a un sí o un no.** SUIN distingue «Vigente», «DEROGADO», «Vigencia en Estudio», «Compilado», «Declarado Inexequible» y «Norma no vigente porque agotó su objeto». «Vigencia en Estudio» no significa vigente.
- **El estado se lee del registro del documento, no de su prosa.** Donde aparecen los dos se contradicen: la Ley 1541 de 2012 muestra «Vigente» en pantalla y «Vigencia en Estudio» en su campo.
- **El buscador de SUIN da el mismo dato que la ficha.** Desde octubre de 2026 `buscar_en_suin` consulta el índice del buscador nuevo, cuyo `estado` es el de la ficha (la Ley 74 de 1923 sale «Derogado»). El índice de Azure que usaba antes contradecía la ficha y ya no se consulta.

Y la regla de fondo no cambia: **verifica en el enlace antes de actuar.**

**El buscador del Gestor no busca en el texto completo**, solo en los resúmenes temáticos, y une los términos con OR. Su índice de palabras además es muy pobre: «teletrabajo» casa con 3 documentos en todo el portal, y con ninguno de los 43 conceptos que sí están clasificados bajo ese subtema. El servidor compensa de tres formas: quita las palabras vacías antes de consultar, reintenta por el subtema oficial cuando la búsqueda por palabras rinde poco, y busca dentro del articulado en tu computador cuando pides una norma concreta. Además, cada resultado de `buscar_normas` marca qué términos menciona su extracto y cuáles no, para que un resultado parcial no se lea como totalmente pertinente.

**Los códigos se citan por su nombre.** `resolver_cita` entiende "art. 191 del Código de Comercio" además de "art. 191 del Decreto 410 de 1971", y dice contra qué norma resolvió: Comercio (Decreto 410 de 1971), Sustantivo del Trabajo (Decreto 2663 de 1950), Procesal del Trabajo (Decreto 2158 de 1948), Penal (Ley 599 de 2000), Procedimiento Penal (Ley 906 de 2004), General del Proceso (Ley 1564 de 2012), CPACA (Ley 1437 de 2011), Infancia y Adolescencia (Ley 1098 de 2006) y Estatuto Tributario (Decreto 624 de 1989) salen del Gestor.

**El Código Civil (Ley 84 de 1873) sale de la Secretaría del Senado, con tres salvedades.** El Gestor no lo publica, así que `resolver_cita` con "art. 946 del Código Civil" lee el artículo de la página de la Secretaría del Senado (medido el 2026-09-28: 48 de 50 artículos de una muestra leídos bien; los otros dos, un «socket hang up» del portal, se declaran como «no respondió», nunca como «no existe»). (1) **Solo sirve HTTP sin cifrar** —su puerto 443 no abre—: el texto no se puede autenticar en tránsito, y cada respuesta lo dice; quien no lo quiera la apaga con `FUENTES=-senado`. (2) **Los apartes tachados** que el portal marca como inexequibles o derogados salen entre `~~ ~~` y la respuesta avisa: no se citan como vigentes. (3) **No se reproducen las notas de vigencia, concordancias ni jurisprudencia de cada artículo**: son del editor del portal (Avance Jurídico Casa Editorial), que reserva su copia; la respuesta remite al enlace, donde están, y hay que mirarlas antes de citar. El portal es lento e intermitente (una parte tardó 40 s en responder).

**Las leyes modificatorias traen el artículo que sustituyen.** Cuando una ley está redactada como "El artículo 217 del Código Civil quedará así:", el texto nuevo va debajo con su propia numeración; el extractor lo devuelve junto al artículo pedido en lugar de cortar en los dos puntos. El cuerpo del código modificado es otro documento, y se pide con su propia cita ("art. 217 del Código Civil").

**El texto que publica el Gestor es el consolidado.** Al comparar un artículo con su reforma (`comparar_articulos` con `con_reforma: true`) el «antes» no existe en esas páginas: se contrasta lo que dispuso la reforma con lo que el portal publica hoy, y la respuesta lo declara. Si la ley modificadora solo transcribe una parte, o el extractor no aísla su artículo, el modo lo dice y no calcula un diff que sería engañoso. El portal tampoco anota todas las reformas (medido: la Ley 2466 de 2025 modifica el art. 23 del Código Sustantivo del Trabajo y esa reforma no aparece anotada).

**La cita judicial sale compuesta, y lo que no consta se dice.** `resolver_cita` (sentencias de la Corte Constitucional) y `obtener_documento` (normas del Gestor) traen una línea «Cita oficial: …» armada solo con campos de la fuente. En la relatoría de la Corte, `prov_magistrados` es el **ponente** (238 de 240 aciertos medidos traen un solo nombre y el texto de la providencia lo declara). En SAMAI la fecha es la **del proceso**, no la del fallo, y la Corte Suprema publica la fecha de **carga**: por eso esas fechas no entran en la cita y se listan como «no consta». Tampoco se inventa la entidad expedidora de una norma: el Gestor no la publica de forma fiable.

**Vigencia diferida.** Cuando una norma no rige de inmediato —«regirá seis meses después de su promulgación», o por tramos, como la Ley 2277 de 2022—, la cabecera de `obtener_documento` lo dice a partir de su propio artículo de vigencia (medido sobre 20 normas reales). Solo calcula la fecha cuando el texto lo permite; si falta la fecha de publicación o hay varios tramos, lo declara en vez de suponer.

**Un radicado de 23 dígitos** (`11001-03-28-000-2022-00132-00`) se descompone en `resolver_cita` y se busca en las providencias tituladas del Consejo de Estado (SAMAI). Los dígitos identifican la corporación solo para el Consejo de Estado (`03xx`) y la Sala Civil de la Corte Suprema (`0203`); los de un juzgado o un tribunal (`31xx`, `23xx`…) no son de una alta corte y no se rotulan como tales. SAMAI solo titula una parte de sus providencias: no encontrar un radicado no dice nada sobre el proceso, y **el estado procesal no está en este servidor**. La Corte Suprema no permite buscar por radicado.

**El Diario Oficial** (`buscar_diario_oficial`) dice en qué diario salió una norma (tipo + número) o qué diarios salieron en unas fechas. No da el texto: el PDF del diario es de sesión (sin la cookie responde 404) y pesa hasta 15 MB. No sabe qué normas trae cada diario ni filtra por entidad.

**Línea jurisprudencial.** `linea_jurisprudencial` lista las providencias que, según la relatoría de la Corte Constitucional, citan una sentencia (su bloque «citaciones»; la premisa de que la relatoría publica «sentencias que reiteran» era falsa: sí publica quién cita a quién). Que una sentencia cite a otra **no** es que la reitere ni que la respete, la lista puede estar incompleta (medido: T-233/24 menciona la C-337/11 y no consta) y topa en 100. Que una SU posterior la haya superado no se deduce: hay que leer la providencia.

**Ritmo de consulta.** El servidor hace como máximo una petición por segundo sostenida a cada portal, con ráfagas de hasta cinco, y nunca dos a la vez al mismo sitio. Si un portal responde que está limitando las consultas, espera lo que él indique en vez de insistir. Son servicios públicos y conviene que un asistente automático les pese menos que una persona navegando.

**Caché en disco (opcional).** Con la variable de entorno `CACHE_DIR` apuntando a un directorio, las copias de documentos sobreviven a los reinicios del cliente: una providencia de 3,4 MB pasó de 2.278 ms a 26 ms en un proceso nuevo (medido el 2026-09-28) y, cuando la copia vence, se revalida con `If-Modified-Since` (304, cero bytes). Solo se guardan documentos, nunca buscadores ni APIs; el directorio se poda a 500 ficheros o 256 MB, lo más antiguo primero. Sin la variable no se toca el disco.

**Privacidad.** Cada consulta viaja a servidores del Estado colombiano, que registran las peticiones y tu dirección IP, igual que si navegaras el sitio. No se envía nada a ningún otro servidor, no hay analítica y no se recoge información tuya. Tenlo en cuenta si vas a consultar sobre un asunto propio.

**Datos empaquetados.** Se incluyen dos índices, cada uno con su fecha de generación:

- El **temático** (12.063 pares tema/subtema, 56.458 asociaciones norma–subtema, 2026-08-01) responde al instante y sigue sirviendo si el portal se cae. Si supera los tres meses, el servidor te lo advierte.
- El de **SUIN** (11.648 leyes, 2026-10-14) traduce una cita escrita como texto a su documento sin salir a la red. La vigencia **no** depende de él: se pide en vivo a la ficha de SUIN por tipo, número y año.

**SUIN-Juriscol volvió a cambiar (octubre de 2026).** El buscador nuevo (`lexis.minjusticia.gov.co/buscador/Detallado/3` normas, `/2` jurisprudencia, `/1` reglamentos técnicos) consulta ahora el índice `documents_pdn`: 103.326 documentos cargados el 2026-10-02 que llegan a 2026 —el anterior, `documents_stg`, se cortaba en 2020—, con colecciones de normas (89.879), Corte Constitucional (7.609), Consejo de Estado (3.483) y Corte Suprema (2.355). Los reglamentos técnicos no son una colección aparte: el portal los filtra por materia. Y el **texto** vuelve a leerse: el visor (`lexis.minjusticia.gov.co/minjusticia/viewDocument/{id}`, que es el enlace que se entrega) lo pide a `suin-search/api/documentos/{id}`, público, con el articulado, el resumen de modificaciones por artículo, el de jurisprudencia y las notas de vigencia (medido con un navegador el 2026-10-14). Entre el 2026-09-24 y esa fecha el visor apuntaba a direcciones privadas del Ministerio y el texto no se podía leer.

**Ministerio de Educación y Ministerio de Transporte.** El normograma del MEN (`normograma.info/men`) es un libro de Avance Jurídico con el mismo buscador JSON que el del INVIMA: indexa la compilación del sector educación (no solo actos del MEN) y corta en 10.000 resultados por consulta. El Ministerio de Transporte no concentra su normativa en un solo sitio: los actos desde 2025 están en la tabla de `mintransporte.gov.co/normatividad/actos/`, y los de 2016–2024 en su catálogo `/documentos/`, por año; el buscador de ese catálogo exige reCAPTCHA y el repositorio DSpace (`web.mintransporte.gov.co/jspui`) tiene fechas de relleno y llega a 2018, así que no se usan. Por eso, para un acto anterior a 2025, hay que indicar el año.

**Cobertura de la búsqueda tributaria.** La primera consulta de cada término a la DIAN tarda unos 20 segundos: su portal devuelve el resultado completo y no admite límite. Las páginas siguientes del mismo término son instantáneas, así que conviene paginar en lugar de repetir búsquedas.

**El enlace del Consejo de Estado caduca; el radicado no.** `buscar_jurisprudencia_consejo_estado` entrega, junto a cada providencia, un token firmado que emite el propio buscador y con el que `obtener_documento` con fuente `consejo` saca el texto del PDF. Ese token **vive una hora**: sirve para leer, no para citar. Para citar se usa el radicado. Si caducó, se repite la búsqueda y sale uno nuevo.

**El texto de la Corte Suprema se pide con su ruta y su sala.** `buscar_jurisprudencia_suprema` devuelve la referencia, el ponente, la fecha y las normas citadas; `obtener_documento` con fuente `suprema` devuelve el texto completo, pero exige la MISMA sala con la que apareció la providencia: el backend la busca dentro de esa sala y desde otra no la encuentra.

**La relatoría no indexa frases largas.** `buscar_jurisprudencia` con varias palabras («mora querella policiva») hace que el buscador de la Corte responda con un aviso de «búsquedas flexibles» y 0 resultados. El servidor lo detecta, reintenta con la palabra más distintiva del término («querella») y lo anuncia en la respuesta: «La relatoría no indexa la frase completa; se buscó con el núcleo «X»». Verifica la pertinencia del resultado contra lo que buscabas.

## Para desarrolladores

```bash
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 (unos segundos: pagina el índice del portal de SUIN)
npm run pack               # produce normativa-colombia.mcpb
npm run salud              # healthcheck interno: sondea en paralelo los portales que consulta el servidor (OK / LENTO / CAÍDO, con latencia)
```

`datos/` **sí está versionado**: sin él un clon limpio no pasa las pruebas. Regenéralo solo cuando quieras actualizarlo.

Las pruebas consultan los portales oficiales. `SIN_RED=1 npm test` corre solo la lógica pura, útil para iterar rápido o sin conexión.

No hay integración continua: `npm run check` se corre a mano antes de publicar. Conviene ejecutarlo cada tanto aunque no se haya tocado el código, porque es lo que detecta que un portal cambió su HTML.

El fichero `glama.json` de la raíz declara los metadatos del servidor en el [registro de Glama](https://glama.ai/mcp/servers/Angelthebestone/Normativa-colombiana-MCP) (schema oficial con `maintainers`); se empaqueta en el `.mcpb` y viaja en el paquete npm. El checklist de calidad y el diagnóstico de las descripciones de las herramientas viven en `CALIDAD_HERRAMIENTAS_GLAMA.md` (nota de trabajo, no se publica en npm).

Estructura:

| Archivo | Responsabilidad |
| --- | --- |
| `src/index.ts` | Herramientas y prompts MCP |
| `src/nucleo/` | Núcleo compartido: `parse.ts` (extracción y limpieza de HTML, troceado, canario anti-rotura), `citas.ts` (parser de citas), `codigos.ts` (los códigos por su nombre y su cobertura), `http.ts` (cliente HTTP con la cadena TLS completa), `ca.ts` (intermedios 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 herramientas MCP: `obtener_documento.ts`, `diff.ts` (comparación de artículos), V2 (`analizar_conflicto`, `cambios_desde`, `comparar_articulos`, `consultar_jerarquia`, `consultar_perfil`, `consultar_vigencia`, `expedientes`, `historial_norma`, `validar_cita`, `buscar_unificado`); `resolver_cita` está en `index.ts` |
| `src/fuentes/gestor.ts` | Gestor Normativo (HTML raspado, con canarios) |
| `src/fuentes/suin.ts` | SUIN-Juriscol: ficha, vigencia, búsqueda, texto e índice empaquetado |
| `src/fuentes/normograma.ts` | Normograma de la DIAN (JSON) |
| `src/fuentes/jurisprudencia/` | Tres tribunales: `corte.ts` (relatoría Constitucional, JSON), `cortesuprema.ts` (GraphQL), `consejoestado.ts` (WebForms, sin API) |
| `src/fuentes/sectorial/` | Reguladores sectoriales (CREG, ANH, UPME, ANLA y 15 más vía `buscar_normativa_sectorial`) |
| `scripts/medir.ts` | Banco de métricas, para que optimizar no sea a ojo |
| `scripts/verificar.ts` | `npm run verificar`: comando único de salud (build → typecheck → lint → unit → cobertura tool→caso → red → barridos) |
| `scripts/barrido-terminos.ts` | `npm run barrido-terminos`: detecta "término que antes rendía y ahora vacío" por fuente (regresión de portal) |
| `test/smoke.ts` | Pruebas de biblioteca contra las fuentes reales |
| `test/e2e.ts` | Arranca el servidor y le habla por stdio, como cualquier cliente MCP |
| `test/red*.ts` | Red de regresión: casos por dominio leyendo `content[0].text` crudo e `isError` |

Las instrucciones de uso que recibe el modelo están en `INSTRUCCIONES`, en `src/index.ts`: son el único mecanismo que orienta *qué* herramienta se elige, cosa que ninguna prueba puede verificar.

Dos notas para quien vaya a tocar esto:

- **Cuatro portales envían la cadena TLS incompleta.** `funcionpublica.gov.co` presenta un certificado de «Sectigo RSA Organization Validation» pero manda el intermedio de Domain Validation; `suin-juriscol.gov.co`, `sic.gov.co` y `www.corteconstitucional.gov.co` (intermedio «Go Daddy Secure Certificate Authority - G2») omiten directamente el suyo. `curl` lo tolera porque su bundle ya los trae; Node no. `src/nucleo/ca.ts` incluye los cuatro intermedios para completar la cadena **sin desactivar la verificación**: las raíces que los firman sí vienen con Node. No lo cambies por `rejectUnauthorized: false`.
- **Los códigos HTTP mienten en dos fuentes.** El backend de la Corte Suprema responde 200 con una página de mantenimiento ante rutas inventadas, y la relatoría de la Constitucional devuelve el armazón de su SPA en vez de un 404. Por eso los canarios validan la forma de la respuesta y nunca el código de estado.
- **El canario.** Si el HTML del portal cambia, los parsers lanzan `CanarioError` en vez de devolver listas vacías. Es deliberado: una lista vacía silenciosa se lee como «no existe esa norma», y en materia legal esa confusión es el peor fallo posible.
- **Un fallo de red nunca se presenta como un vacío.** `buscar_unificado` distingue "respondió sin nada" de "no se pudo consultar: <mensaje>" por fuente; una fuente caída no autoriza a concluir que no hay resultados ahí.
- **La SIC vive en la sede electrónica.** El repositorio viejo (`www.sic.gov.co/repositorio-de-normatividad`) responde 301 a `sedeelectronica.sic.gov.co/transparencia/normativa/busqueda-de-normas/entidad`; el adaptador apunta directo a la sede porque `pedir` no sigue redirecciones.

## Contribuir

Las guías están en [CONTRIBUTING.md](https://github.com/Angelthebestone/Normativa-colombiana-MCP/blob/HEAD/CONTRIBUTING.md), y hay cuatro reglas que no se negocian: el canario nunca devuelve vacío en silencio, no se desactiva la verificación TLS, no se sube el ritmo de peticiones a los portales y ninguna respuesta afirma vigencia.

Si el servidor te dio una respuesta incorrecta, ese es el reporte más valioso: hay una [plantilla de issue](https://github.com/Angelthebestone/Normativa-colombiana-MCP/issues/new/choose) para eso.

Para reportar una vulnerabilidad, mira [SECURITY.md](https://github.com/Angelthebestone/Normativa-colombiana-MCP/blob/HEAD/SECURITY.md); no abras un issue público.

## Licencia

Código bajo licencia MIT (ver [LICENSE](https://github.com/Angelthebestone/Normativa-colombiana-MCP/blob/HEAD/LICENSE)). Sobre los contenidos normativos y el acceso automatizado a los portales, mira [NOTICE.md](https://github.com/Angelthebestone/Normativa-colombiana-MCP/blob/HEAD/NOTICE.md).