MCP-India-Stack

Servidor MCP para APIs de India — GSTIN, IFSC, PAN, UPI, código postal, HSN/SAC. Sin autenticación. Prioridad offline. Para agentes de IA.

GitHub
33

Documentación

🇮🇳 MCP India Stack

Un servidor de Model Context Protocol (MCP) de alto rendimiento y prioridad offline que dota a los agentes de IA con APIs financieras, fiscales y gubernamentales de la India. Sin autenticación requerida.

PyPI version License: MIT MCP Compatible CI Verified on MseeP MseeP.ai Security Assessment Badge

📑 Tabla de Contenidos

📌 Planteamiento del Problema

  • Acceso Fragmentado: Las APIs financieras, de identidad y fiscales de la India están fuertemente aisladas, lo que requiere múltiples integraciones desconectadas entre sí.
  • Barreras de Entrada Elevadas: Las soluciones existentes adolecen de suscripciones de pago, límites de frecuencia estrictos y una gestión compleja de claves de API.
  • Sin Integración Nativa de IA: No existe un estándar nativo MCP diseñado específicamente para que agentes de IA autónomos validen GSTIN, PAN, IFSC o calculen datos fiscales.
  • Problemas de Latencia y Fiabilidad: Depender de APIs de terceros remotas para conjuntos de datos estáticos o de lento cambio introduce retrasos de red innecesarios y posibles puntos de fallo en los flujos de trabajo de IA.

🛠️ Stack Tecnológico

CapaTecnología
ProtocoloMCP (FastMCP)
RuntimePython
DistribuciónPyPI / Smithery
AlojamientoRender
Conjuntos de DatosIncluidos offline (sincronización CDN jsDelivr)

🏗️ Diagrama de Arquitectura

Architecture Cliente MCP ↔ Servidor MCP ↔ 58 módulos de herramientas con prioridad offline

🧠 Equipo

Nombre del Equipo: Solo Wizard

NombreNombre de Usuario NAMESPACERol
Rehan ShashiRehan ShashiDesarrollador

🏆 Categoría del Hackathon

Categoría: Trabajo, Finanzas y Economía Digital

🔗 Demo y Enlaces

✨ Características Clave

  • Arquitectura con Prioridad Offline: Incluye conjuntos de datos comprimidos para consultas de latencia cero (IFSC, códigos postales, HSN/SAC). Sin límites de frecuencia de API.
  • Autenticación Cero: No requiere claves de API, secretos ni suscripciones. Toda la lógica se ejecuta localmente.
  • Actualizaciones Automáticas en Segundo Plano: La obtención no bloqueante desde CDN garantiza que sus conjuntos de datos nunca queden desactualizados sin afectar la latencia de las solicitudes.
  • Cobertura Integral: 58 herramientas dedicadas para validación de identidad (PAN, Aadhaar, GSTIN, TAN, PRAN), cálculo de impuestos (Impuesto sobre la Renta, TDS, GST), calculadoras de ahorro (EPF, PPF, SIP) y consultas de datos maestros.
  • Listo para Empresas: Herramientas de validación masiva aceleradas con grupo de subprocesos para procesar grandes lotes de datos de proveedores o clientes.

🚀 Inicio Rápido

Instalación

pip install mcp-india-stack

Configuración de Claude Desktop

Añada lo siguiente a su archivo claude_desktop_config.json para habilitar India Stack en Claude Desktop:

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-india-stack": {
      "command": "python",
      "args": ["-m", "mcp_india_stack"]
    }
  }
}

macOS/Linux (~/Library/Application Support/Claude/claude_desktop_config.json o ~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-india-stack": {
      "command": "python3",
      "args": ["-m", "mcp_india_stack"]
    }
  }
}

🛠️ Catálogo de Herramientas

🔍 Herramientas de Consulta

  • lookup_ifsc — Detalles de sucursal bancaria a partir del código IFSC
  • lookup_pincode — Detalles de códigos postales de la India y oficinas de correos
  • lookup_hsn_code — Consulta de código HSN/SAC por código o palabra clave
  • decode_state_code — Metadatos de códigos estatales GST
  • lookup_bbps_biller — Consulta del directorio de facturadores BBPS
  • lookup_bank — Consulta básica del maestro bancario por nombre o código

✅ Herramientas de Validación

📱 Identidad y Contacto

⚡ Operaciones Masivas

🧮 Calculadoras Fiscales y Financieras (AF2025-26)

💰 Calculadoras de Ahorro e Inversión

🏠 Bienes Raíces

💼 RR. HH. y Nómina

🏦 Banca y Pagos

🔐 Agregador de Cuentas (Offline)

🔄 Flujos de Trabajo y Recursos para Agentes

Flujos de Trabajo con Prompts (Resumen)

Plantillas de prompt integradas para guiar a los agentes de IA en tareas complejas de varios pasos:

  • vendor_kyc — Secuencia de verificación de GSTIN, PAN e IFSC.
  • salary_planner — Planificación de ingresos, HRA y salario neto optimizado.
  • invoice_audit — Referencia cruzada de GSTIN, códigos HSN y tasas GST aplicables.

Recursos del Servidor (Resumen)

Recursos JSON dinámicos proporcionados directamente al contexto del LLM:

  • india://status — Versión, conectividad de base de datos y marcas de runtime
  • india://changelog — Recurso estructurado de registro de cambios
  • india://schema/* — Esquemas JSON para todas las salidas de herramientas

📡 Arquitectura de Datos y Actualización

Este paquete incluye conjuntos de datos estáticos para flujos de trabajo con prioridad offline (aproximadamente 10-11 MB de huella comprimida), que cubren IFSC, códigos postales, maestros HSN/SAC y manejadores UPI seleccionados.

Un mecanismo opcional de actualización automática obtiene las últimas versiones del CDN jsDelivr en segundo plano:

  • Sin bloqueo: Los datos obsoletos activan una actualización en segundo plano; la solicitud actual utiliza inmediatamente los datos en caché existentes para garantizar latencia cero.
  • Exclusión voluntaria: Establezca la variable de entorno MCP_INDIA_STACK_NO_AUTO_UPDATE=1 para deshabilitar todas las comprobaciones de actualización.
  • Actualización manual: Ejecute mcp-india-stack --refresh-all para actualizar sincrónicamente todos los conjuntos de datos desde el CDN.
  • Ubicación de la caché: Específica de la plataforma mediante platformdirs (p. ej., ~/.cache/mcp-india-stack en Linux).

⚠️ Limitaciones

  • Validación sin Estado: Los validadores GSTIN, Aadhaar, identificación de votante, licencia de conducir, pasaporte, CIN y DIN comprueban únicamente el formato estructural y las sumas de verificación. No verifican el estado de registro activo ante las autoridades gubernamentales emisoras.
  • Restricciones Algorítmicas: La validación PAN es estructural; la lógica del carácter de comprobación PAN no es verificable públicamente.
  • Estimaciones Fiscales: Todos los cálculos fiscales son estimaciones algorítmicas basadas en las reglas del AF2025-26. La obligación real puede diferir. Consulte siempre a un Contador Público Colegiado.
  • Tasas Estáticas: Las tasas HSN/SAC son referencias estáticas y pueden variar según condiciones específicas o nuevas notificaciones gubernamentales.

⚖️ Legal y Atribución

Consulte NOTICES para obtener información detallada sobre la atribución de conjuntos de datos, detalles de licencia y reconocimientos de terceros.

🚀 Notas de Lanzamiento

Este repositorio está listo para su lanzamiento en GitHub e incluye:

  • Metadatos de paquete 0.4.2 y cobertura del registro de cambios.
  • Una tarjeta completa del servidor MCP en docs/.well-known/mcp/server-card.json.
  • Pasos de configuración local y publicación en SETUP.md.
  • Guía de contribuciones y política de versionado en CONTRIBUTING.md.

Correcciones de errores en v0.4.2 (Ronda 2 — Auditoría profunda de código)

  • Ganancias de Capital: Umbrales LTCG específicos por tipo de activo — bienes raíces 24 meses, oro/bonos 36 meses, cripto siempre 30% fijo.
  • EPF/ESIC: EPF del empleado correctamente limitado al tope salarial de ₹15.000. Se añadió voluntary_pf_on_actual para VPF.
  • HRA: Se eliminaron Bangalore/Hyderabad/Pune de las ciudades metropolitanas. Solo Delhi/Mumbai/Chennai/Kolkata reciben el 50%.
  • Impuesto Presunto: Cobertura completa del nuevo régimen de 7 tramos con rebaja 87A (antes truncado en 3 tramos).
  • Tasa por Retraso GST: Límite GSTR9 aplicado (0,25% de la facturación). Tasa de declaración nula corregida a ₹20/día.
  • Intereses del Impuesto sobre la Renta: La Sección 234C utiliza el acumulado pagado frente al requerido (no por trimestre individual).
  • Impuesto Anticipado: Las cuotas muestran installment_amount incremental (no el confuso acumulado).
  • Reestructuración Salarial: Se eliminó la exención obsoleta de transporte de ₹19.200. Se muestra la deducción estándar (₹75.000).

Corrección de errores en v0.4.1

  • Seguridad: Se corrigió la fuga del número Aadhaar enmascarado en los campos de respuesta.
  • Validación: Se corrigió el problema de conteo excesivo de dígitos en números móviles.
  • Reglas fiscales: Se corrigieron los umbrales del Impuesto Presuntivo (44AD/44ADA) según las reglas del año fiscal 25-26.
  • Financiero: Se corrigió el cálculo del rendimiento compuesto de SIP escalonado (Step-up SIP).
  • Datos: Se agregaron códigos HSN faltantes (8517, 9401, 2523, 3004, 8708) con las tasas de GST correctas.
  • Impuesto profesional: Se corrigieron los cálculos totales anuales según las escalas mensuales correctas.
  • Impuesto sobre la renta: Se corrigió el límite de deducción de la sección 80D para ciudadanos de la tercera edad.
  • ISIN: Se corrigió la lógica de expansión de múltiples dígitos del checksum Luhn.
  • Calculadora EMI: Se mejoraron las respuestas de error para no filtrar campos de respaldo en entradas inválidas.
  • Impuesto anticipado: Se agregó soporte para sobrescribir los cálculos internos con el tax_liability proporcionado por el usuario.

Garantía de funcionamiento sin conexión: Todas las herramientas de este paquete funcionan sin conexión a Internet. No se requieren claves de API. No se envía ningún dato a ningún servidor externo. Todos los conjuntos de datos están incluidos en el paquete al momento de la instalación.