MCP-India-Stack

Servidor MCP para APIs indianas — GSTIN, IFSC, PAN, UPI, CEP, HSN/SAC. Sem autenticação. Prioridade offline. Para agentes de IA.

GitHub
58
Experimente este MCPPatrocinado

Documentação

🇮🇳 MCP India Stack

Um servidor de Model Context Protocol (MCP) de alta performance e offline-first que equipa agentes de IA com APIs financeiras, fiscais e governamentais indianas. Nenhuma autenticação necessária.

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

📑 Sumário

📌 Declaração do Problema

  • Acesso Fragmentado: As APIs indianas de fintech, identidade e impostos são fortemente isoladas, exigindo múltiplas integrações desconexas.
  • Barreiras de Entrada Altas: As soluções existentes são prejudicadas por assinaturas pagas, limites de taxa rigorosos e gerenciamento complexo de chaves de API.
  • Sem Integração Nativa de IA: Não existe um padrão nativo de MCP projetado especificamente para agentes de IA autônomos validarem GSTIN, PAN, IFSC ou calcularem dados fiscais.
  • Problemas de Latência e Confiabilidade: Depender de APIs remotas de terceiros para conjuntos de dados estáticos ou de baixa variação introduz atrasos de rede desnecessários e possíveis pontos de falha para fluxos de trabalho de IA.

🛠️ Stack de Tecnologia

CamadaTecnologia
ProtocoloMCP (FastMCP)
RuntimePython
DistribuiçãoPyPI / Smithery
HospedagemRender
Conjuntos de DadosIncluídos offline (sincronização via CDN jsDelivr)

🏗️ Diagrama de Arquitetura

Architecture Cliente MCP ↔ Servidor MCP ↔ 76 módulos de ferramentas offline-first

🔗 Links

✨ Principais Recursos

  • Arquitetura Offline-First: Inclui conjuntos de dados compactados para consultas de latência zero (IFSC, CEPs, HSN/SAC). Sem limites de taxa de API.
  • Autenticação Zero: Sem chaves de API, segredos ou assinaturas necessárias. Toda a lógica é executada localmente.
  • Atualizações Automáticas em Segundo Plano: Busca não bloqueante via CDN garante que seus conjuntos de dados nunca fiquem desatualizados sem impactar a latência das solicitações.
  • Cobertura Abrangente: 76 ferramentas dedicadas para validação de identidade (PAN, Aadhaar, GSTIN, TAN, PRAN), cálculo de impostos (Imposto de Renda, TDS, GST), calculadoras de poupança (EPF, PPF, SIP) e consultas de dados mestre.
  • Pronto para Empresas: Ferramentas de validação em lote aceleradas por pool de threads para processar grandes lotes de dados de fornecedores ou clientes.

🚀 Início Rápido

Instalação

pip install mcp-india-stack

Configuração do Claude Desktop

Adicione o seguinte ao seu arquivo claude_desktop_config.json para habilitar o India Stack no 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 ou ~/.config/Claude/claude_desktop_config.json):

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

🛠️ Catálogo de Ferramentas

🔍 Ferramentas de Consulta

✅ Ferramentas de Validação

📱 Identidade e Contato

⚡ Operações em Lote

🧮 Calculadoras Fiscais e Financeiras (AF2025-26)

💰 Calculadoras de Poupança e Investimento

🏠 Imóveis

💼 RH e Folha de Pagamento

🏦 Bancos e Pagamentos

📈 Mercado de Ações

  • get_stock_quote — Buscar cotações e resumos de ações indianas em tempo real/com atraso (NSE/BSE) usando yfinance.
  • get_stock_history — Buscar dados históricos de fechamento para ações indianas usando yfinance.

⚖️ Referência Jurídica

📋 Kit RTI

🔐 Agregador de Contas (Offline)

🔄 Fluxos de Trabalho e Recursos do Agente

Fluxos de Trabalho de Prompt (Visão Geral)

Modelos de prompt integrados para orientar agentes de IA em tarefas complexas de múltiplas etapas:

  • vendor_kyc — Sequência de verificação GSTIN, PAN e IFSC.
  • salary_planner — Planejamento de renda, HRA e salário líquido otimizado.
  • invoice_audit — Referência cruzada de GSTINs, códigos HSN e alíquotas GST aplicáveis.

Recursos do Servidor (Visão Geral)

Recursos JSON dinâmicos fornecidos diretamente ao contexto do LLM:

  • india://status — Versão, conectividade do banco de dados e sinalizadores de runtime
  • india://changelog — Recurso de changelog estruturado
  • india://schema/* — Esquemas JSON para todas as saídas das ferramentas

📡 Arquitetura de Dados e Atualização

Este pacote inclui conjuntos de dados estáticos para fluxos de trabalho offline-first (aproximadamente 10-11MB de tamanho compactado), cobrindo IFSCs, CEPs, cadastros mestre HSN/SAC e handles UPI selecionados.

Um mecanismo opcional de atualização automática busca as versões mais recentes do CDN jsDelivr em segundo plano:

  • Não bloqueante: Dados desatualizados acionam uma atualização em segundo plano; a solicitação atual usa imediatamente os dados em cache existentes para garantir latência zero.
  • Desativar: Defina a variável de ambiente MCP_INDIA_STACK_NO_AUTO_UPDATE=1 para desabilitar todas as verificações de atualização.
  • Atualização manual: Execute mcp-india-stack --refresh-all para atualizar sincronamente todos os conjuntos de dados do CDN.
  • Local do cache: Específico da plataforma via platformdirs (por exemplo, ~/.cache/mcp-india-stack no Linux).

⚠️ Limitações

  • Validação Sem Estado: Os validadores de GSTIN, Aadhaar, Título de Eleitor, CNH, Passaporte, CIN e DIN verificam apenas formatação estrutural e somas de verificação. Eles não verificam o status de registro ativo junto às autoridades governamentais emissoras.
  • Restrições Algorítmicas: A validação PAN é estrutural; a lógica do caractere de verificação PAN não é publicamente verificável.
  • Estimativas Fiscais: Todos os cálculos fiscais são estimativas algorítmicas baseadas nas regras de AF2025-26. A obrigação real pode diferir. Consulte sempre um Contador.
  • Alíquotas Estáticas: As alíquotas HSN/SAC são referências estáticas e podem variar com base em condições específicas ou novas notificações governamentais.

⚖️ Avisos Legais e Atribuições

Consulte NOTICES para atribuição detalhada de conjuntos de dados, detalhes de licenciamento e reconhecimentos de terceiros.

Consulte LEGAL_NOTICE.md para avisos legais importantes, incluindo:

  • Sem Afiliação Governamental — Este projeto não é afiliado ao NIC, eCourts, MeitY ou qualquer órgão governamental.
  • Não é Aconselhamento Jurídico — Todas as saídas (consultas de leis, cálculos de prazos, estimativas de custas processuais, estimativas de imposto de selo, cálculos de prazos/penalidades da RTI) são estimativas algorítmicas, não aconselhamento jurídico.
  • Precisão dos Dados — Dados de competência estadual (custas processuais, imposto de selo) possuem campos as_of / last_verified e não são verificados em tempo real junto às autoridades emissoras.
  • Dados Pessoais — A validação de identidade (Aadhaar, PAN, etc.) é apenas estrutural/checksum. Os usuários são responsáveis pela conformidade com a Lei DPDP.

🚀 Notas de Lançamento

Este repositório está pronto para lançamento no GitHub com:

  • Metadados de pacote 0.6.0 e cobertura de changelog.
  • Um card completo de servidor MCP em docs/.well-known/mcp/server-card.json.
  • Etapas de configuração local e publicação em SETUP.md.
  • Guia de contribuição e política de versionamento em CONTRIBUTING.md.

Novidades na v0.6.0 — Kit de Referência Jurídica e RTI

  • Referência Jurídica: Decodificador CNR, consulta de tribunais, consultas de seções de leis (IPC/BNS/CrPC/BNSS/IEA/BSA), tabela de correspondência IPC↔BNS, calculadora de prazos de prescrição, calculadora de custas processuais (10 estados), calculadora de imposto de selo (10 estados).
  • Kit RTI: Calculadora de taxas RTI, rastreador de prazos, estimador de penalidades, geradores de modelos de solicitação/recurso.
  • Ganhos de Capital: Isenção LTCG atualizada de ₹1L para ₹1.25L (Orçamento 2024).
  • Mercado de Ações: Adicionadas ferramentas get_stock_quote e get_stock_history baseadas em yfinance.

Correções de bugs na v0.4.2 (Rodada 2 — Auditoria Profunda de Código)

  • Ganhos de Capital: Limites LTCG específicos por tipo de ativo — imóveis 24 meses, ouro/debêntures 36 meses, cripto sempre 30% fixo.
  • EPF/ESIC: EPF do funcionário corretamente limitado ao teto salarial de ₹15 mil. Adicionado voluntary_pf_on_actual para VPF.
  • HRA: Removidas Bangalore/Hyderabad/Pune das cidades metropolitanas. Apenas Delhi/Mumbai/Chennai/Kolkata recebem 50%.
  • Imposto Presumido: Cobertura completa do novo regime de 7 faixas com rebate 87A (antes truncado em 3 faixas).
  • Taxa de Atraso GST: Limite GSTR9 aplicado (0,25% do faturamento). Taxa de declaração nula corrigida para ₹20/dia.
  • Juros de Imposto de Renda: Seção 234C usa pagamento acumulado vs. exigido (não trimestre único).
  • Imposto Antecipado: Parcelas mostram installment_amount incremental (não acumulado confuso).
  • Reestruturação Salarial: Removida isenção obsoleta de transporte de ₹19.200. Dedução padrão (₹75 mil) exibida.

Correções de bugs na v0.4.1

  • Segurança: Mascarado vazamento de número Aadhaar em campos de resposta.
  • Validação: Corrigido problema de contagem excessiva de dígitos em números de celular.
  • Regras Fiscais: Corrigidos limites do Imposto Presumido (44AD/44ADA) para as regras do FY25-26.
  • Financeiro: Corrigido cálculo de retorno composto de SIP com aumento progressivo.
  • Dados: Adicionados códigos HSN ausentes (8517, 9401, 2523, 3004, 8708) com taxas GST corretas.
  • Imposto Profissional: Corrigidos totais anuais com base nas faixas mensais corretas.
  • Imposto de Renda: Corrigido limite de dedução 80D para idosos.
  • ISIN: Corrigida lógica de expansão multidiígito do checksum Luhn.
  • Calculadora EMI: Melhoradas respostas de erro para não vazar campos de fallback em entradas inválidas.
  • Imposto Antecipado: Adicionado suporte para substituir cálculos internos com tax_liability fornecido pelo usuário.

Garantia Offline-Primeiro: Todas as ferramentas deste pacote funcionam sem conexão com a internet. Nenhuma chave de API é necessária. Nenhum dado é enviado a servidores externos. Todos os conjuntos de dados são incluídos no pacote no momento da instalação.