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.

Related MCP server: onpe-mcp

🛠️ 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.