Consultas Perú - MCP & CLI

Una herramienta nativa y definitiva en TypeScript/Node.js para extraer y consultar información oficial de Perú de manera rápida y confiable. Está diseñada como un CLI interactivo, Servidor MCP para Inteligencia Artificial y un servidor unificado que ofrece una REST API y GraphQL API.

Características Principales

• 🚀 CLI Interactivo (consultdn): Una interfaz de terminal moderna y amigable.
• 🧑 Consultas DNI: Extrae nombres, apellidos y el código verificador. Además, cruza información tributaria si la persona cuenta con un RUC activo.
• 🏢 Consultas RUC (SUNAT): Extrae información detallada (estado, condición, dirección, sistema de emisión, actividades económicas, etc.).
• 💱 Tipo de Cambio Oficial (SUNAT): Obtiene el tipo de cambio del día (compra y venta).
• 🔐 Validación de Usuarios SOL: Permite verificar si un usuario secundario SOL se encuentra activo para un RUC dado.
• 🤖 Servidor MCP Integrado: Conecta tus herramientas de Inteligencia Artificial al CLI para delegar consultas.
• 🌐 APIs (REST y GraphQL): Levanta un servidor local (http://localhost:3000) para integrarlo fácilmente a cualquier frontend.

---

🛠️ Instalación y Uso

1. Clonar e Instalar

git clone https://github.com/AnderMC66/consultdn-mcp.git
cd consultdn-mcp
npm install
npm run build
npm link

2. Uso del CLI

Ejecuta el siguiente comando para iniciar la interfaz interactiva a pantalla completa:

consultdn

Alternativamente, puedes usarlo para scripts directamente:

• Consultar DNI: consultdn dni 12345678
• Consultar RUC: consultdn ruc 20123456789
• Tipo de Cambio: consultdn tc
• Validar Usuario SOL: consultdn user-sol 20123456789 USUARIO1

3. Ejecutar el Servidor API

Si deseas consumir los datos desde tu aplicación web (Frontend):

npm run start

Esto levantará el servidor en http://localhost:3000 con:

• REST API:
  • /api/citizens/:dni
  • /api/companies/:ruc
  • /api/exchange-rate
• GraphQL API: /graphql

4. Configurar Servidor MCP

Añade este proyecto a tu configuración de Cursor, Claude o tu IDE favorito con soporte MCP utilizando el ejecutable compilado:

{
  "mcpServers": {
    "consultas-peru": {
      "command": "node",
      "args": ["/ruta/absoluta/a/consultdn-mcp/dist/mcp.js"]
    }
  }
}

---

🏗️ Stack Tecnológico

• Lenguaje: TypeScript / Node.js
• Arquitectura: Clean Architecture
• Frameworks: Express.js, Apollo Server (GraphQL)
• Scraping: Cheerio, Axios
• CLI: Commander, Enquirer, Picocolors, Figlet

⚠️ Advertencia

Este proyecto realiza scraping de fuentes de información y debe ser utilizado de manera responsable de acuerdo a los términos y condiciones de las entidades involucradas.