ptn-mcp

# Argentina PTN - MCP Server Suite [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://ptn-mcp.vercel.app) [](https://www.npmjs.com/package/ptn-mcp) MCP Server Oficial para buscar y extraer dictámenes de la Procuración del Tesoro de la Nación (PTN). Conector para consultar dictámenes, opiniones técnicas y asesoramientos desde busquedadictamenes.ptn.gob.ar. Paquete npm: [`ptn-mcp`](https://www.npmjs.com/package/ptn-mcp) · Repositorio: [github.com/voftec/ptn-mcp](https://github.com/voftec/ptn-mcp) --- ## Novedades v1.3.0 * **Insights del portal PTN**: Aplicación de análisis detallado del portal de búsqueda y Novedades para nuevas funcionalidades. * **+4 herramientas nuevas basadas en investigación del portal**: * `buscar_por_doctrina` - Búsqueda restringida al campo doctrina (evita ruido de boilerplate procedimental) * `obtener_facetas_completas` - Facetas de navegación combinadas (organismos + voces) con conteos * `buscar_por_ley_enriquecido` - Búsqueda de leyes con contexto de citación (integración Infoleg) * `localizar_por_coordenadas_archivisticas` - Búsqueda por Tomo + Página exacta (útil para OCR deficiente) * **Mejora en `obtener_novedades`**: Ahora incluye facetas con conteos como el portal Novedades * **Mejora en `buscar_dictamenes`**: Parámetro `soloDoctrina` para búsqueda específica en doctrina ## Novedades v1.2.0 * **Patrones de implementación mejorados**: Aplicación de patrones arquitectónicos de InfoLeg, JUBA, BORA y NormativaPBA para mayor robustez. * **+2 herramientas de agregación concurrente**: `obtener_resumen_multiple_organismos` y `obtener_resumen_multiple_voces` (BORA pattern: Promise.all). * **Parsing de fechas sofisticado**: Soporte para fechas en lenguaje natural español ("15 de febrero de 2026"), DD/MM/YYYY, ISO YYYY-MM-DD, y compacto YYYYMMDD (BORA pattern). * **Auto-resolución de dictámenes**: `localizar_dictamen_automatico` permite buscar con información parcial y devuelve el dictamen más probable (NormativaPBA pattern). * **Detección de plazos mejorada**: `detector_plazos_dictamenes` con +70 patrones legales/administrativos adicionales (InfoLeg pattern). * **Validadores Zod personalizados**: Helpers reutilizables para validación de fechas, arrays y números (common pattern). * **Mejoras en herramientas existentes**: Integración de nuevas funciones de parsing y validación en todas las herramientas de búsqueda. ## Novedades v1.1.0 * **+6 herramientas nuevas** pensadas para flujos de abogados: shortcuts por **organismo**, **voz temática**, **ley citada**, y **localización por cita** (Tomo / Página / Nº / Año). * **Catálogos descubribles**: `listar_organismos` y `listar_voces` exponen los facets oficiales con conteo (basados en agregaciones de Elasticsearch). * **`obtener_novedades` con filtros** por organismo y voz. * **2 nuevos prompts**: `comparar_dictamenes` y `resumen_por_organismo`. * **+5 herramientas cognitivas y forenses**: detección de plazos, certificación forense, búsqueda semántica, relación de dictámenes, exportación estructurada. * Diseño "una tool por eje" para mejorar la precisión cuando lo usa una IA. --- ## Características principales * **Búsquedas especializadas** (la IA elige la tool por nombre): * `buscar_por_organismo` — `"¿qué dictó CONICET / AFIP / Ministerio X?"` * `buscar_por_voz` — por materia (`designación transitoria`, `apoderamiento`, `contratación`, ...). * `buscar_por_ley` — dictámenes que citan una ley. * `localizar_por_cita` — lookup directo por Tomo + Página o N° + Año. * `localizar_dictamen_automatico` — auto-resolución con información parcial (NormativaPBA pattern). * `buscar_dictamenes` — búsqueda avanzada multi-filtro (power user). * **Agregación Concurrente** (BORA pattern: Promise.all): * `obtener_resumen_multiple_organismos` — resumen comparativo de múltiples organismos en paralelo. * `obtener_resumen_multiple_voces` — resumen comparativo de múltiples voces temáticas en paralelo. * **Texto íntegro** (`obtener_dictamen_texto`): cuerpo completo por `_id`. * **Novedades** (`obtener_novedades`): últimos dictámenes, filtrables por organismo y voz. * **Catálogos** (`listar_organismos`, `listar_voces`): facets oficiales con conteo. * **Análisis y Relación**: * `detector_plazos_dictamenes` — detecta plazos y fechas límite con +70 patrones legales (InfoLeg pattern). * `relacionar_dictamenes` — busca dictámenes relacionados. * `buscar_por_semantica` — búsqueda con expansión de términos. * **Exportación y Certificación**: * `generar_certificacion_forense` — certificación con hash SHA-256. * `exportar_dictamen` — exportación a Markdown con frontmatter YAML. * **Alcance** (`alcance_fuente`): metadatos y disclaimer. * **Prompts asistidos**: `auditar_dictamen`, `comparar_dictamenes`, `resumen_por_organismo`. > La PTN no expone HTML scrapeable: este MCP usa `POST /search` y `POST /search_news` contra `https://api.ptn.gob.ar`, no Cheerio ni Playwright. **TLS:** por defecto verifica certificados. Si tu red/OS no puede validar la cadena de `api.ptn.gob.ar`, el servidor reintenta una vez sin verificación y avisa por stderr. Para forzar ese modo desde el inicio: `PTN_TLS_INSECURE=1`. --- ## Instalación y configuración rápida Requiere [Node.js](https://nodejs.org/) 18 o superior. ### 1. Cursor IDE / Windsurf 1. Abre **Settings** → **MCP** → **Add New MCP Server**. 2. Completa: * **Name:** `ptn-mcp` * **Type:** `command` * **Command:** `npx -y ptn-mcp` ### 2. Claude Desktop Edita `claude_desktop_config.json` (en Windows suele estar en `C:\Users\<TuUsuario>\AppData\Roaming\Claude\claude_desktop_config.json`): ```json { "mcpServers": { "ptn-mcp": { "command": "npx", "args": ["-y", "ptn-mcp"] } } } ``` ### 3. Antigravity / Codex (stdio local) En `mcp_config.json`: ```json { "mcpServers": { "ptn-mcp": { "command": "npx", "args": ["-y", "ptn-mcp"] } } } ``` > Para conexión **SSE remota** (Claude Web, sin Node.js local), usa el despliegue **PTN-MCP** en Vercel. --- ## Instalación manual (desarrolladores) ```bash git clone https://github.com/voftec/ptn-mcp.git cd ptn-mcp npm install npm run build npm test # unit tests (sin red) npm run test:smoke # humo contra api.ptn.gob.ar (requiere red) ``` Ejecutar el servidor compilado: ```bash node build/index.js ``` Configuración local en Cursor o Claude Desktop apuntando a la build: ```json "ptn-mcp": { "command": "node", "args": ["D:/ruta-a-tu-carpeta/ptn-mcp/build/index.js"] } ``` --- ## Catálogo de herramientas (Tools) | Herramienta | Descripción | Parámetro principal | |---|---|---| | `buscar_dictamenes` | Búsqueda avanzada multi-filtro (power user). | combinación libre | | `buscar_por_organismo` | Dictámenes de un organismo. | `organismo` | | `buscar_por_voz` | Dictámenes por voz temática / materia. | `voz` | | `buscar_por_ley` | Dictámenes que citan una ley. | `ley` | | `localizar_por_cita` | Lookup por Tomo+Página o Nº+Año. | `tomo`/`paginaRef`/`numero`/`anio` | | `localizar_dictamen_automatico` | Auto-resolución con información parcial (NormativaPBA pattern). | combinación libre | | `obtener_dictamen_texto` | Texto íntegro por `_id`. | `idDictamen` | | `obtener_novedades` | Últimas publicaciones, con filtros opcionales. | `cantidad`, `organismo`, `voz` | | `listar_organismos` | Catálogo de organismos con conteo (facets). | `top`, `criterio` | | `listar_voces` | Catálogo de voces temáticas con conteo (facets). | `top`, `criterio` | | `obtener_facetas_completas` | Facetas de navegación combinadas (organismos + voces) con conteos. | `top`, `criterio` | | `detector_plazos_dictamenes` | Detecta plazos y fechas límite en dictámenes. | `texto_dictamen` | | `relacionar_dictamenes` | Busca dictámenes relacionados. | `criterio_base`, `terminos_relacionados` | | `buscar_por_semantica` | Búsqueda con expansión de términos. | `concepto`, `terminos_equivalentes` | | `generar_certificacion_forense` | Certificación forense con hash SHA-256. | `idDictamen` | | `exportar_dictamen` | Exportación a Markdown con frontmatter YAML. | `idDictamen` | | `alcance_fuente` | Alcance, fuentes y disclaimer. | *(ninguno)* | | `buscar_por_doctrina` | Búsqueda restringida al campo doctrina (evita ruido procedimental). | `criterio` | | `buscar_por_ley_enriquecido` | Búsqueda de leyes con contexto de citación (integración Infoleg). | `ley` | | `localizar_por_coordenadas_archivisticas` | Búsqueda por Tomo + Página exacta (útil para OCR deficiente). | `tomo`, `pagina` | | `obtener_resumen_multiple_organismos` | Resumen comparativo de múltiples organismos en paralelo. | `organismos` | | `obtener_resumen_multiple_voces` | Resumen comparativo de múltiples voces temáticas en paralelo. | `voces` | Parámetros detallados: [TOOLS.md](./TOOLS.md). --- ## Diseño "una tool por eje" La base PTN tiene 3 ejes naturales de búsqueda (los que el portal expone como filtros): **organismo**, **voz temática** y **ley citada**, más la **cita bibliográfica** (Tomo + Página). En vez de obligar al LLM a combinar 13 parámetros opcionales en una sola tool, ofrecemos una tool especializada por eje. Esto mejora dramáticamente la precisión cuando una IA decide qué llamar. Cuando la pregunta mezcla ejes (ej. `"dictámenes de CONICET sobre contratación en 2025"`), la IA puede: 1. Usar `buscar_dictamenes` con `dependencia="CONICET"`, `materia="contratación"`, `anio="2025"`, o 2. Usar `buscar_por_organismo` y luego refinar con `buscar_por_voz`. --- ## Licencia Este proyecto se distribuye bajo la **Licencia MIT**. Consulta el archivo [LICENSE](./LICENSE).