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
58
Prueba este MCPPatrocinado

Documentación

🇮🇳 MCP India Stack

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

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 inconexas.
  • Altas Barreras de Entrada: Las soluciones existentes se ven afectadas por suscripciones de pago, límites de tasa estrictos y una gestión compleja de claves API.
  • Sin Integración Nativa de IA: No existe un estándar nativo de 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 remotas de terceros para conjuntos de datos estáticos o de lento cambio introduce retrasos de red innecesarios y posibles puntos de fallo para 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 ↔ 76 módulos de herramientas con prioridad offline

🔗 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 tasa de API.
  • Cero Autenticación: No se requieren claves 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 tus conjuntos de datos nunca queden desactualizados sin afectar la latencia de las solicitudes.
  • Cobertura Integral: 76 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

Agrega lo siguiente a tu 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 de estado GST
  • lookup_bbps_biller — Consulta del directorio de facturadores BBPS
  • lookup_bank — Consulta básica del banco maestro 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

💼 RRHH y Nómina

🏦 Banca y Pagos

📈 Mercado de Valores

  • get_stock_quote — Obtener cotizaciones de acciones indias en vivo/con retraso y resúmenes (NSE/BSE) usando yfinance.
  • get_stock_history — Obtener datos históricos de cierre para acciones indias usando yfinance.

⚖️ Referencia Legal

📋 Kit de Herramientas RTI

🔐 Agregador de Cuentas (Offline)

🔄 Flujos de Trabajo y Recursos para Agentes

Flujos de Trabajo de Prompts (Resumen)

Plantillas de prompts integradas para guiar a agentes de IA en tareas complejas de múltiples pasos:

  • vendor_kyc — Secuencia de verificación 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 banderas de runtime
  • india://changelog — Recurso de registro de cambios estructurado
  • 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 (aprox. 10-11 MB de huella comprimida), que cubren IFSC, códigos postales, maestros HSN/SAC y manejadores UPI seleccionados.

Un mecanismo opcional de autoactualización obtiene las últimas versiones desde el CDN jsDelivr en segundo plano:

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

⚠️ Limitaciones

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

⚖️ Aviso Legal y Atribuciones

Consulta NOTICES para obtener atribución detallada de conjuntos de datos, detalles de licencias y reconocimientos de terceros.

Consulte LEGAL_NOTICE.md para conocer los avisos legales importantes, incluidos:

  • Sin afiliación gubernamental — Este proyecto no está afiliado a NIC, eCourts, MeitY ni a ningún organismo gubernamental.
  • No es asesoramiento legal — Todos los resultados (consultas de leyes básicas, cálculos de plazos de prescripción, estimaciones de tasas judiciales, estimaciones de impuesto de timbre, cálculos de plazos/sanciones de RTI) son estimaciones algorítmicas, no asesoramiento legal.
  • Precisión de los datos — Los datos de competencia estatal (tasas judiciales, impuesto de timbre) incluyen campos as_of / last_verified y no se verifican en vivo contra las autoridades emisoras.
  • Datos personales — La validación de identidad (Aadhaar, PAN, etc.) es solo estructural/de suma de verificación. Los usuarios son responsables del cumplimiento de la Ley DPDP.

🚀 Notas de lanzamiento

Este repositorio está listo para su lanzamiento en GitHub con:

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

Novedades en v0.6.0 — Referencia legal y kit de herramientas RTI

  • Referencia legal: Decodificador CNR, consulta de establecimiento judicial, consultas de secciones de leyes básicas (IPC/BNS/CrPC/BNSS/IEA/BSA), tabla de correspondencia IPC↔BNS, calculadora de plazos de prescripción, calculadora de tasas judiciales (10 estados), calculadora de impuesto de timbre (10 estados).
  • Kit de herramientas RTI: Calculadora de tasas RTI, seguimiento de plazos, estimador de sanciones, redactores de plantillas de solicitud/apelación.
  • Ganancias de capital: Exención LTCG actualizada de ₹1L a ₹1.25L (Presupuesto 2024).
  • Mercado de valores: Se añadieron herramientas get_stock_quote y get_stock_history basadas en yfinance.

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, criptomonedas siempre 30% fijo.
  • EPF/ESIC: EPF del empleado correctamente limitado al tope salarial de ₹15K. Se añadió voluntary_pf_on_actual para VPF.
  • HRA: Se eliminaron Bangalore/Hyderabad/Pune de las ciudades metropolitanas. Solo Delhi/Mumbai/Chennai/Kolkata obtienen 50%.
  • Impuesto presuntivo: Cobertura completa del nuevo régimen de 7 tramos con deducción 87A (antes truncado en 3 tramos).
  • Tasa de GST por mora: 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 usa pagos acumulados vs. requeridos (no de un solo trimestre).
  • Impuesto anticipado: Las cuotas muestran installment_amount incremental (no acumulativo confuso).
  • Reestructuración salarial: Se eliminó la exención obsoleta de transporte de ₹19,200. Se muestra la deducción estándar (₹75K).

Correcciones de errores en v0.4.1

  • Seguridad: Se enmascaró la fuga del número Aadhaar en los campos de respuesta.
  • Validación: Se corrigió el problema de conteo excesivo de dígitos en números móviles.
  • Reglas fiscales: Umbrales de impuesto presuntivo (44AD/44ADA) corregidos a las reglas FY25-26.
  • Financiero: Se corrigió el cálculo de rendimiento compuesto de SIP con aumento escalonado.
  • Datos: Se añadieron códigos HSN faltantes (8517, 9401, 2523, 3004, 8708) con tasas GST correctas.
  • Impuesto profesional: Cálculos anuales totales corregidos según los tramos mensuales correctos.
  • Impuesto sobre la renta: Límite de deducción 80D corregido para personas mayores.
  • ISIN: Lógica de expansión de múltiples dígitos de la suma de verificación Luhn corregida.
  • Calculadora EMI: Respuestas de error mejoradas para no filtrar campos de respaldo en entradas inválidas.
  • Impuesto anticipado: Soporte añadido para anular cálculos internos con 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 API. No se envían datos a ningún servidor externo. Todos los conjuntos de datos se incluyen en el paquete al momento de la instalación.