@ssolis-ti/mcp-compra-agil 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssolis-ti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# MCP Server: Compra Ágil v2 — Mercado Público de Chile 🇨🇱
+
+[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue.svg)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Servidor [MCP (Model Context Protocol)](https://modelcontextprotocol.io) desarrollado en TypeScript que envuelve e integra de forma avanzada la API REST de **Compra Ágil v2** y la API de **Órdenes de Compra (OC)** de [Mercado Público](https://www.mercadopublico.cl). Permite a cualquier IA, agente autónomo o cliente compatible interrogar, filtrar, auditar y prospectar procesos de compra estatal del gobierno de Chile.
+
+El proyecto está diseñado bajo una arquitectura modular y cuenta con dos modos de operación principales:
+1. **Servidor Interactivo MCP:** Comunicación bidireccional vía Stdio para integrarse directamente con el chat y herramientas de tu IDE o cliente (Cursor, Claude Desktop, Windsurf, etc.).
+2. **Daemon de Alertas en Segundo Plano:** Servicio de consulta incremental autónomo que rastrea procesos de alto valor con **0 oferentes** y guarda alertas automatizadas en un registro local.
+
+---
+
+## 📋 Tabla de Contenidos
+* [¿Qué es Compra Ágil?](#qué-es-compra-ágil)
+* [Características Clave](#características-clave)
+* [Requisitos](#requisitos)
+* [Instalación](#instalación)
+* [Configuración de Variables de Entorno](#configuración-de-variables-de-entorno)
+* [Uso y Modos de Ejecución](#uso-y-modos-de-ejecución)
+  * [Desarrollo](#desarrollo)
+  * [Producción](#producción)
+  * [Monitoreo Autónomo](#monitoreo-autónomo)
+  * [Testing con MCP Inspector](#testing-con-mcp-inspector)
+* [Integración con Clientes MCP](#integración-con-clientes-mcp)
+  * [Claude Desktop](#claude-desktop)
+  * [OpenClaw](#openclaw)
+  * [Cursor / Windsurf](#cursor--windsurf)
+* [Catálogo del Servidor](#catálogo-del-servidor)
+  * [Herramientas Disponibles (Tools)](#herramientas-disponibles-tools)
+  * [Recursos Disponibles (Resources)](#recursos-disponibles-resources)
+  * [Prompts Disponibles](#prompts-disponibles)
+* [Ejemplos Prácticos de Interacción](#ejemplos-prácticos-de-interacción)
+* [Licencia](#licencia)
+
+---
+
+## 🔍 ¿Qué es Compra Ágil?
+
+Compra Ágil es el mecanismo de adquisición simplificado y directo del Estado de Chile para montos inferiores a 100 UTM. Permite a los organismos públicos convocar de forma abierta a cotizaciones rápidas a través de Mercado Público, promoviendo la participación de Empresas de Menor Tamaño (EMT).
+
+---
+
+## 🎯 ¿A quién está dirigido?
+
+Este servidor MCP maneja datos públicos de la API de Compra Ágil de Mercado Público, siendo de alto valor tanto para compradores del Estado como para proveedores privados:
+
+### 🏛️ Para Compradores Públicos (Organismos del Estado)
+* **Estudios de Mercado Eficientes:** Permite realizar análisis históricos rápidos de adjudicaciones y precios de referencia antes de publicar nuevas adquisiciones.
+* **Control y Auditoría Interna:** Facilita la fiscalización de procesos pasados, evaluando los motivos de adjudicación y comparando todas las ofertas recibidas para asegurar la probidad administrativa.
+* **Control de Órdenes de Compra (OC):** Monitoreo masivo de estados de aceptación y desgloses de productos facturados por los proveedores.
+
+### 💼 Para Proveedores (Empresas y Pymes)
+* **Inteligencia Competitiva:** Analizar ofertas ganadoras y perdedoras, precios de la competencia y spreads en procesos cerrados.
+* **Prospectar Oportunidades:** Monitorear llamados activos sin oferentes mediante filtros locales avanzados.
+* **Alertas Automatizadas:** El demonio en segundo plano notifica oportunidades que coincidan con tu presupuesto mínimo y rubro.
+
+---
+
+## ⚡ Características Clave
+* **Modernizado para SDK v1.12+:** Carga declarativa y robusta de herramientas, recursos y prompts bajo los nuevos estándares del protocolo.
+* **Carga de Entorno Autónoma:** El servidor detecta y carga de forma automática y manual el archivo `.env` del directorio de trabajo al iniciarse, facilitando la conexión en clientes MCP de escritorio sin necesidad de configurar variables de sistema globales.
+* **Lector de Documentación Integrado (Recursos):** Exposición nativa de guías, normativas y manuales en PDF (dentro de la carpeta `docs/`) como recursos del protocolo MCP (`compra-agil://documentacion/{filename}`). El servidor extrae el texto del PDF de manera local y lo inyecta en el LLM bajo demanda.
+* **Filtrado Inteligente Anti-Ruido:** Filtros locales en la herramienta `buscar_compras_agiles` (`palabras_clave_requeridas` y `palabras_clave_excluidas`) para afinar búsquedas amplias de la API y remover ofertas irrelevantes.
+* **Paginación Inteligente y Monitoreo Completo:** La herramienta de cambios recientes admite navegación de páginas (`numero_pagina`), y el demonio de monitoreo periódico procesa de forma recursiva todas las páginas de resultados (`client.buscarTodo()`) para evitar pérdidas de alertas.
+* **Integración del Detalle de OC:** Resuelve de forma dinámica el código alfanumérico o ID numérico de las Órdenes de Compra utilizando la API legada de Mercado Público.
+* **Enriquecimiento Inteligente de la OC:** Corrige las limitaciones de la API oficial donde el estado `oc_emitida` no funciona en producción. El servidor busca de forma recursiva a nivel raíz y anidado el `id_orden_compra` y enlaza el desglose de productos y datos del proveedor ganador.
+* **Rate Limiting Local:** Algoritmo *Token Bucket* integrado que limita el consumo (máximo 40 llamadas por minuto) y procesa el error 429 de forma transparente para evitar la inhabilitación temporal del ticket.
+* **Logs Nativos en el Protocolo:** Inyección de la notificación `sendLoggingMessage` de MCP para registrar y depurar la actividad del servidor directamente dentro de la interfaz del cliente.
+
+---
+
+## 📌 Requisitos y Obtención de Credenciales
+
+Para utilizar este servidor MCP necesitas:
+1. **Node.js v22+** (se utiliza la API nativa de `fetch` y soporte nativo para módulos ESM).
+2. **Ticket de acceso a la API** de Mercado Público de ChileCompra.
+
+### 🔑 Paso a Paso para obtener tu Ticket de Acceso
+El ticket es una credencial de acceso gratuita que identifica tus peticiones ante los servidores de Mercado Público y controla tu cuota diaria de consultas. Sigue este procedimiento oficial para obtenerlo en 2 minutos:
+
+1. **Acceder al portal de la API:** Abre tu navegador e ingresa a [chilecompra.cl/api/](https://www.chilecompra.cl/api/).
+2. **Solicitar ticket:** Haz clic en el botón destacado **«Pide tu ticket»**.
+3. **Autenticación con Clave Única:** Acepta los términos y condiciones de uso e inicia sesión con tu **Clave Única** del Estado de Chile.
+4. **Formulario de solicitud:** Completa los datos requeridos en el formulario y presiona el botón **«Solicitar ticket»**.
+5. **Recepción por correo:** Recibirás tu ticket alfanumérico (ej: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`) de forma inmediata en tu casilla de correo electrónico.
+   * *Consejo: Si no lo visualizas en tu bandeja de entrada en unos minutos, revisa la carpeta de Correo no deseado o Spam.*
+
+Una vez que tengas tu ticket alfanumérico copiado, puedes proceder a la instalación.
+
+---
+
+## 🚀 Instalación
+
+### Opción A: 🤖 Instalación Automatizada mediante tu Agente/Asistente de IA (Recomendado)
+Si estás utilizando un asistente o agente de IA en tu editor de código con permisos para ejecutar comandos (como Cursor Composer, Roo Code, Cline, Windsurf Agent o Claude Code), puedes delegar la configuración por completo. Simplemente copia y pega el siguiente prompt en el chat de tu IA:
+
+> "Por favor, inicializa y configura este servidor MCP en mi entorno local. Entra a la carpeta `mcp-compra-agil`, ejecuta `npm install` para instalar dependencias y compila el proyecto con `npm run build`. Una vez compilado con éxito, registra el servidor MCP en mis ajustes (Cursor, Roo Code, Cline, Continue o Claude Desktop según corresponda) configurando la herramienta para que se ejecute con `node` apuntando al archivo `dist/index.js` y vinculando el token `COMPRA_AGIL_TICKET` (búscalo en mi archivo `.env` o pídemelo)."
+
+---
+
+### Opción B: 💻 Instalación Manual clásica
+Si prefieres realizar la instalación tú mismo desde la terminal:
+```bash
+# Entrar al proyecto
+cd mcp-compra-agil
+
+# Instalar dependencias de desarrollo y producción
+npm install
+
+# Compilar el código fuente TypeScript (.ts -> .js en dist/)
+npm run build
+```
+
+---
+
+### Opción C: 📦 Ejecución directa vía NPX (Publicación en NPM)
+El servidor está configurado para empaquetarse de manera compacta. Si decides publicarlo en el registro de paquetes de NPM (ej: con `npm publish`), cualquier otra persona podrá ejecutarlo e integrarlo de forma instantánea **sin necesidad de descargar el código fuente ni compilarlo manualmente**:
+
+1. **Configuración directa en el cliente MCP:**
+   Se puede configurar el comando de inicio usando `npx`:
+   ```bash
+   npx @ssolis-ti/mcp-compra-agil
+   ```
+2. **Instalación global en el sistema:**
+   ```bash
+   npm install -g @ssolis-ti/mcp-compra-agil
+   # Ejecución directa del binario registrado
+   mcp-compra-agil
+   ```
+   *(Asegúrate de que el usuario defina la variable de entorno `COMPRA_AGIL_TICKET` en su cliente o entorno).*
+
+---
+
+## ⚙️ Configuración de Variables de Entorno
+
+Crea un archivo `.env` en la raíz del directorio `mcp-compra-agil/` para ingresar tus credenciales y ajustar las configuraciones por defecto:
+
+```env
+# Ticket oficial de acceso a la API (Obligatorio)
+COMPRA_AGIL_TICKET=tu_ticket_aqui
+
+# URL Base para las llamadas a la API v2 (por defecto api2.mercadopublico.cl)
+COMPRA_AGIL_BASE_URL=https://api2.mercadopublico.cl
+
+# --- Parámetros del Demonio de Monitoreo ---
+# Intervalo entre búsquedas en minutos (por defecto 1 hora)
+MONITOR_INTERVAL_MINUTES=60
+# Presupuesto mínimo en CLP para emitir alerta (ej: 5.000.000)
+MONITOR_MIN_BUDGET_CLP=5000000
+# Palabras clave a buscar separadas por coma
+MONITOR_KEYWORDS=software, desarrollo, licencias, plataforma, sistema, soporte, cloud
+```
+
+---
+
+## 🛠️ Uso y Modos de Ejecución
+
+### Desarrollo
+Para levantar el servidor en caliente observando cambios en el código:
+```bash
+npm run dev
+```
+
+### Producción
+Para iniciar el servidor compilado:
+```bash
+npm run build
+npm start
+```
+
+### Monitoreo Autónomo
+Para ejecutar el demonio de alertas en segundo plano (vigila oportunidades sin oferentes y escribe los reportes en `alerts.log`):
+```bash
+npm run monitor
+```
+
+### Testing con MCP Inspector
+Para probar las herramientas, recursos y prompts en una interfaz gráfica local:
+```bash
+npm run inspect
+```
+
+---
+
+## 🔌 Integración con Clientes MCP y Agentes
+
+Este servidor se comunica de manera estándar mediante Stdio. A continuación se detallan las instrucciones para integrarlo con los clientes y agentes más comunes del ecosistema:
+
+### 1. Claude Desktop
+Añade el servidor a tu archivo de configuración global editando `%APPDATA%\Claude\claude_desktop_config.json` (en Windows) o `~/Library/Application Support/Claude/claude_desktop_config.json` (en macOS):
+
+```json
+{
+  "mcpServers": {
+    "compra-agil": {
+      "command": "node",
+      "args": ["C:\\ruta\\completa\\mcp-compra-agil\\dist\\index.js"],
+      "env": {
+        "COMPRA_AGIL_TICKET": "tu_ticket_de_chilecompra_aqui"
+      }
+    }
+  }
+}
+```
+
+### 2. Claude Code (`claudecode`)
+Para registrar el servidor de forma global en Claude Code (el agente CLI de Anthropic), ejecuta el siguiente comando en tu terminal **antes** de iniciar tu sesión de `claude`:
+```bash
+claude mcp add compra-agil --env COMPRA_AGIL_TICKET=tu_ticket_de_chilecompra_aqui -- node C:\ruta\completa\mcp-compra-agil\dist\index.js
+```
+*Nota: Si estás en un proyecto local, puedes usar rutas relativas o el comando local.*
+Para comprobar que se cargó con éxito, inicia una sesión de `claude` y escribe el comando `/mcp` o ejecuta `claude mcp list` en tu terminal.
+
+### 3. OpenClaw
+Para registrar el servidor en OpenClaw (el cliente de terminal y automatización open source), puedes hacerlo de dos formas:
+
+#### A. Vía CLI (Recomendado)
+Ejecuta en tu consola:
+```bash
+openclaw mcp add compra-agil node "C:\\ruta\\completa\\mcp-compra-agil\\dist\\index.js"
+openclaw mcp set compra-agil env.COMPRA_AGIL_TICKET "tu_ticket_de_chilecompra_aqui"
+```
+#### B. Edición de Archivo de Configuración
+Abre tu archivo de configuración de OpenClaw (típicamente localizado en `~/.openclaw/openclaw.json` o `~/.openclaw/openclaw.json5`) e integra el servidor dentro de la sección `"mcpServers"`:
+```json5
+  "mcpServers": {
+    "compra-agil": {
+      "command": "node",
+      "args": ["C:/ruta/completa/mcp-compra-agil/dist/index.js"],
+      "env": {
+        "COMPRA_AGIL_TICKET": "tu_ticket_de_chilecompra_aqui"
+      }
+    }
+  }
+```
+*Asegúrate de ajustar los permisos de sandbox de herramientas (`tools.sandbox.tools` o `tools.sandbox.allowlist`) en tu config de OpenClaw para permitir la ejecución del comando `node`.*
+
+### 4. Open-Code / VSCodium / VS Code (Extensiones de Agentes)
+
+#### Con la extensión **Roo Code (Roo Cline / Cline)**:
+1. Abre los Ajustes de la extensión Roo Code/Cline (`Settings`).
+2. En la sección **MCP Servers Configuration**, haz clic en `Edit MCP Settings` (esto abrirá el archivo `cline_mcp_settings.json` o `roo_mcp_settings.json`).
+3. Añade el siguiente bloque:
+   ```json
+   {
+     "mcpServers": {
+       "compra-agil": {
+         "command": "node",
+         "args": ["C:/ruta/completa/mcp-compra-agil/dist/index.js"],
+         "env": {
+           "COMPRA_AGIL_TICKET": "tu_ticket_de_chilecompra_aqui"
+         },
+         "disabled": false
+       }
+     }
+   }
+   ```
+4. Guarda el archivo y la extensión refrescará automáticamente registrando las nuevas herramientas.
+
+#### Con la extensión **Continue**:
+Abre tu archivo `~/.continue/config.json` y añade la configuración en el bloque `"mcpServers"`:
+```json
+"mcpServers": [
+  {
+    "name": "compra-agil",
+    "command": "node",
+    "args": ["C:/ruta/completa/mcp-compra-agil/dist/index.js"],
+    "env": {
+      "COMPRA_AGIL_TICKET": "tu_ticket_de_chilecompra_aqui"
+    }
+  }
+]
+```
+
+### 5. Cursor / Windsurf
+* **Cursor:** Dirígete a `Settings` > `Features` > `MCP`. Haz clic en `+ Add New MCP Server`. Escribe el nombre `compra-agil`, selecciona el tipo `Stdio`, escribe en command `node` y en args `C:/ruta/completa/mcp-compra-agil/dist/index.js`. Añade la variable `COMPRA_AGIL_TICKET`.
+* **Windsurf:** Dirígete a la pestaña de MCP en Ajustes e ingresa la misma configuración Stdio.
+
+### 6. Agentes Personalizados (Node.js/Python SDK)
+Si estás construyendo tu propio agente o pipeline automatizado con el SDK oficial de MCP:
+```typescript
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const transport = new StdioClientTransport({
+  command: "node",
+  args: ["C:/ruta/completa/mcp-compra-agil/dist/index.js"],
+  env: {
+    COMPRA_AGIL_TICKET: "tu_ticket_de_chilecompra_aqui"
+  }
+});
+
+const client = new Client({ name: "mi-agente-cliente", version: "1.0.0" });
+await client.connect(transport);
+
+// Listar herramientas y recursos disponibles
+const tools = await client.listTools();
+const resources = await client.listResources();
+```
+
+---
+
+## 📖 Catálogo del Servidor
+
+### Herramientas Disponibles (Tools)
+
+| Nombre de la Herramienta | Descripción de Entrada / Salida |
+| :--- | :--- |
+| `buscar_compras_agiles` | Busca procesos utilizando palabras clave (con filtros inteligentes locales), región (1-16), estado y ventana temporal. Parámetros `q` e `id` son excluyentes. |
+| `obtener_detalle_compra` | Detalle exhaustivo de una cotización: descripción, ítems y cotizaciones recibidas (confidenciales hasta el estado *Cerrada*). |
+| `monitorear_cambios_recientes` | Sincronización reactiva e incremental en los últimos N minutos (ventana máxima de 1440 min / 24 horas), con soporte para paginación. |
+| `verificar_orden_compra` | Comprobación de emisión de OC resolviendo inconsistencias de la API pública. Retorna el ID de la OC y acopla dinámicamente los desgloses económicos y datos del adjudicado. |
+| `obtener_detalle_orden_compra` | Consulta detallada del desglose de productos y facturación de una OC utilizando su código alfanumérico o ID numérico. |
+| `obtener_estadisticas_uso` | Retorna las estadísticas del limitador de solicitudes local (`requestsToday`, `isLimited`) para optimizar el consumo de la cuota del ticket. |
+| `obtener_enlace_documento` | Genera el link público y oficial de descarga de un archivo adjunto del proceso de Mercado Público. |
+| `descargar_y_leer_documento` | Descarga y extrae el texto plano de un documento adjunto en PDF del proceso de compra de forma remota, permitiendo realizar búsquedas de palabras clave. |
+| `consultar_documentos_locales` | Busca y extrae fragmentos coincidentes dentro de los archivos PDF/TXT/MD de ayuda de Compra Ágil guardados en la carpeta local `docs/`. |
+| `recomendar_precio_ganador` | Analiza precios históricos unitarios y totales de proveedores ganadores en procesos cerrados y sugiere un precio competitivo ajustado (percentil 40). |
+| `auditar_compras_desiertas` | Analiza las causales de convocatorias sin ofertas (desiertas) cruzando presupuesto, duración del llamado y requisitos especiales contra históricos exitosos. |
+| `generar_borrador_cotizacion` | Auto-completa propuestas JSON de cotización bajo el esquema oficial, calculando impuestos (19% IVA), sumatorios y redactando cartas formales de presentación. |
+| `radar_oportunidades_calientes` | Califica y ordena convocatorias publicadas según un score ponderado (Hot Score) de competencia (sin oferentes), urgencia, presupuesto y simplicidad. |
+
+### Recursos Disponibles (Resources)
+
+| URI del Recurso | Tipo de Mime | Descripción de Contenido |
+| :--- | :--- | :--- |
+| `compra-agil://regiones` | `application/json` | Catálogo maestro de mapeo de las 16 regiones administrativas de Chile y sus identificadores numéricos. |
+| `compra-agil://estados` | `application/json` | Estados admitidos por la API y notas técnicas sobre su comportamiento real para optimizar las queries. |
+| `compra-agil://glosario` | `application/json` | Glosario de acrónimos del dominio de ChileCompra para contextualización semántica de la IA. |
+| `compra-agil://compras/{codigo}` | `application/json` | Recurso dinámico que resuelve el objeto JSON puro devuelto por la API v2 de una Compra Ágil usando su código único. |
+| `compra-agil://documentacion/{filename}` | `text/plain` | Recurso dinámico que lee y extrae todo el contenido de texto de un PDF/TXT/MD local en la carpeta `docs/` en tiempo real. |
+
+### Prompts Disponibles
+
+* **`buscar_oportunidades_proveedor`:** Plantilla estructurada para guiar a la IA a consultar la región del proveedor, buscar compras publicadas afines y filtrar las 5 mejores ofertas libres de competidores.
+* **`analizar_competencia`:** Plantilla de comandos para comparar precios unitarios y totales de los participantes de un proceso finalizado, identificando la brecha económica (spread) y el motivo de selección.
+
+---
+
+## 💡 Ejemplos Prácticos de Interacción
+
+* **Búsqueda Multi-Filtro:**
+  * *Usuario:* "¿Qué compras ágiles de materiales eléctricos están publicadas en Valparaíso?"
+  * *Acción del LLM:* Traduce "Valparaíso" al código de región `5` usando `compra-agil://regiones` y llama a `buscar_compras_agiles` con `q="materiales electricos"`, `estado="publicada"`, `region="5"`.
+* **Auditoría de Adjudicaciones:**
+  * *Usuario:* "¿Quién ganó la licitación de computadores con código `2376-331-COT26`?"
+  * *Acción del LLM:* Llama a `verificar_orden_compra` con `codigo="2376-331-COT26"` para identificar al proveedor seleccionado, y luego consulta el desglose de productos utilizando `obtener_detalle_orden_compra` con el ID de la OC devuelto.
+
+---
+
+## 📄 Licencia
+Este proyecto está bajo la Licencia MIT. Consulta el archivo [LICENSE](LICENSE) para obtener más información.

package/dist/api/compra-agil-client.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Cliente HTTP para la API REST de Compra Ágil v2 de Mercado Público.
+ *
+ * Centraliza autenticación, manejo de errores, rate limiting
+ * y paginación automática.
+ *
+ * Usa fetch nativo de Node.js 22+ (sin dependencias externas).
+ */
+export interface BuscarParams {
+    ttl_cambio_ms?: number;
+    cambio_desde?: string;
+    cambio_hasta?: string;
+    publicado_desde?: string;
+    publicado_hasta?: string;
+    estado?: string;
+    region?: string;
+    id?: string;
+    q?: string;
+    tamano_pagina?: number;
+    numero_pagina?: number;
+    ordenar_por?: string;
+}
+export interface Paginacion {
+    total_paginas: number;
+    numero_pagina: number;
+    tamano_pagina: number;
+    total_resultados: number;
+}
+export interface CompraAgilItem {
+    codigo: string;
+    nombre: string;
+    estado: {
+        id_estado: number;
+        codigo: string;
+        glosa: string;
+    };
+    convocatoria: {
+        estado_convocatoria: number;
+        descripcion: string;
+    };
+    documentos: Array<{
+        id: string;
+        nombre: string;
+    }>;
+    fechas: {
+        fecha_publicacion: string;
+        fecha_cierre: string;
+        fecha_ultimo_cambio: string;
+        fecha_cancelacion: string | null;
+    };
+    montos: {
+        moneda: string;
+        monto_disponible: number;
+        monto_disponible_clp: number;
+    };
+    institucion: {
+        organismo_comprador: string;
+        rut: string;
+        unidad_compra: string;
+        region: number | null;
+        nombre_region: string | null;
+    };
+    resumen: {
+        total_ofertas_recibidas: number;
+    };
+    motivos: {
+        motivo_cancelacion: string | null;
+        motivo_desierta: string | null;
+        motivo_seleccion: string | null;
+    };
+    links: {
+        detalle: string;
+    };
+}
+export interface BuscarResponse {
+    items: CompraAgilItem[];
+    paginacion: Paginacion;
+}
+export interface OrdenCompraDetalle {
+    Codigo: string;
+    Nombre: string;
+    CodigoEstado: number;
+    Estado: string;
+    CodigoLicitacion: string | null;
+    Descripcion: string | null;
+    FechaCreacion: string;
+    FechaAceptacion: string | null;
+    MontoNeto: number;
+    Impuestos: number;
+    Total: number;
+    Comprador: {
+        NombreOrganismo: string;
+        NombreUnidad: string;
+        RegionUsuario: string;
+    };
+    Proveedor: {
+        Nombre: string;
+        Rut: string;
+    };
+    Items: {
+        Listado: Array<{
+            Producto: string;
+            Cantidad: number;
+            PrecioNeto: number;
+            TotalLnea: number;
+        }>;
+    };
+}
+export interface OrdenCompraResponse {
+    Cantidad: number;
+    Listado: OrdenCompraDetalle[];
+}
+export interface ProductoSolicitado {
+    codigo_producto: number | string;
+    nombre: string;
+    descripcion: string | null;
+    cantidad: number;
+    unidad_medida: string;
+}
+export interface ProductoCotizado {
+    codigo_producto: number | string;
+    nombre_producto: string;
+    descripcion: string | null;
+    cantidad: number;
+    precio_unitario: number | null;
+    monto_total_producto: number | null;
+}
+export interface ProveedorCotizando {
+    rut_proveedor: string;
+    razon_social: string;
+    es_emt: boolean;
+    id_cotizacion?: number;
+    codigo_empresa?: string;
+    codigo_sucursal_empresa?: string;
+    estado_cotizacion?: {
+        id: number;
+        glosa: string;
+    };
+    estado_por_comprador?: string | null;
+    activo?: boolean;
+    fecha_creacion?: string;
+    fecha_vigencia?: string | null;
+    valor_neto?: number | null;
+    total_impuesto?: number | null;
+    monto_despacho?: number | null;
+    monto_total?: number | null;
+    nombre_impuesto?: string | null;
+    porcentaje_impuesto?: number | null;
+    descripcion_cotizacion?: string | null;
+    descripcion?: string | null;
+    justificacion_inadmisibilidad?: string | null;
+    proveedor_seleccionado?: number | boolean;
+    seleccion?: {
+        proveedor_seleccionado: boolean;
+        motivo_seleccion: string | null;
+        criterio_seleccion: string | null;
+    };
+    productos_cotizados?: ProductoCotizado[];
+}
+export interface CompraAgilDetalle {
+    codigo: string;
+    nombre: string;
+    descripcion: string;
+    id_orden_compra?: number | null;
+    estado: {
+        id_estado: number;
+        codigo: string;
+        glosa: string;
+    };
+    convocatoria: {
+        estado_convocatoria: number;
+        descripcion: string;
+        fecha_cierre_primer_llamado: string | null;
+        fecha_cierre_segundo_llamado: string | null;
+    };
+    fechas: {
+        fecha_publicacion: string;
+        fecha_cierre: string;
+        fecha_ultimo_cambio: string;
+        fecha_cancelacion: string | null;
+    };
+    entrega: {
+        direccion_entrega: string;
+        plazo_entrega_dias: number | null;
+    };
+    documentos: Array<{
+        id: string;
+        nombre: string;
+    }>;
+    presupuesto: {
+        tipo_presupuesto: string;
+        moneda: string;
+        presupuesto_estimado: number | null;
+        monto_disponible: number | null;
+        monto_disponible_clp: number | null;
+        valor_cambio_moneda: number | null;
+        fecha_cambio_moneda: string | null;
+    };
+    orden_compra?: {
+        id_orden_compra: number | null;
+        id_oc: number | null;
+        codigo_orden_compra: string | null;
+        estado_orden_compra: string | null;
+    };
+    institucion: {
+        organismo_comprador: string;
+        rut: string;
+        unidad_compra: string;
+        region: number | null;
+        nombre_region: string | null;
+    };
+    productos_solicitados: ProductoSolicitado[];
+    proveedores_cotizando: ProveedorCotizando[];
+    resumen: {
+        multa_sancion: number | null;
+        total_ofertas_recibidas: number;
+        total_demandas: number;
+    };
+    motivos: {
+        motivo_cancelacion: string | null;
+        motivo_desierta: string | null;
+    };
+    flags: {
+        considera_requisitos_medioambientales: boolean;
+        considera_requisitos_impacto_social_economico: boolean;
+    };
+}
+export declare class CompraAgilClient {
+    private readonly baseUrl;
+    private readonly ticket;
+    private readonly rateLimiter;
+    constructor(ticket: string, baseUrl?: string);
+    /**
+     * Realiza un GET autenticado a la API.
+     */
+    private request;
+    /**
+     * Buscar Compras Ágiles con filtros y paginación.
+     */
+    buscar(params: BuscarParams): Promise<BuscarResponse>;
+    /**
+     * Buscar todas las páginas de resultados (auto-paginación).
+     * Útil cuando la IA necesita todos los resultados sin gestionar páginas.
+     */
+    buscarTodo(params: BuscarParams, maxPages?: number): Promise<CompraAgilItem[]>;
+    /**
+     * Obtener el detalle completo de una Compra Ágil específica.
+     */
+    detalle(codigo: string): Promise<CompraAgilDetalle>;
+    /**
+     * Buscar cambios recientes en los últimos N milisegundos.
+     */
+    cambiosRecientes(ttlMs: number, filtros?: Partial<BuscarParams>): Promise<BuscarResponse>;
+    /**
+     * Obtener estadísticas del rate limiter.
+     */
+    getRateLimitStats(): {
+        requestsToday: number;
+        isLimited: boolean;
+        resetTime: string | null;
+    };
+    /**
+     * Obtener el detalle completo de una Orden de Compra (OC).
+     * Admite tanto el ID numérico interno como el código alfanumérico.
+     */
+    obtenerDetalleOC(idOC: string | number): Promise<OrdenCompraResponse>;
+}
+//# sourceMappingURL=compra-agil-client.d.ts.map

package/dist/api/compra-agil-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compra-agil-client.d.ts","sourceRoot":"","sources":["../../src/api/compra-agil-client.ts"],"names":[],"mappings":"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"}