From a870af91978c26fa9c5dfb6494702cad74f26702 Mon Sep 17 00:00:00 2001 From: rehan1020 <30rehanshashivic@gmail.com> Date: Thu, 30 Apr 2026 20:54:57 +0530 Subject: [PATCH] docs: refresh launch documentation --- README.md | 149 +++++++++++++++++++++++++++----------------- docs/prompts.md | 25 ++++++++ docs/resources.md | 61 ++++++++++++++++++ docs/tools/gstin.md | 15 ++++- docs/tools/ifsc.md | 15 ++++- docs/tools/pan.md | 27 +++++++- 6 files changed, 231 insertions(+), 61 deletions(-) create mode 100644 docs/prompts.md create mode 100644 docs/resources.md diff --git a/README.md b/README.md index 1aeff9a..79dde8a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# mcp-india-stack +# 🇮🇳 MCP India Stack [![PyPI version](https://img.shields.io/pypi/v/mcp-india-stack.svg)](https://pypi.org/project/mcp-india-stack/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) @@ -6,35 +6,67 @@ [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/137943ec-5cee-4de7-a22d-e55a7ac699bd) [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/rehan1020-mcp-india-stack-badge.png)](https://mseep.ai/app/rehan1020-mcp-india-stack) -MCP server exposing Indian financial and government APIs for AI agents. Zero auth. Offline-first. +> A high-performance, offline-first Model Context Protocol (MCP) server equipping AI agents with Indian financial, tax, and government APIs. Zero authentication required. -## Install +## ✨ Key Features + +- **Offline-First Architecture**: Bundles compressed datasets for zero-latency lookups (IFSC, Pincodes, HSN/SAC). No API rate limits. +- **Zero Authentication**: No API keys, secrets, or subscriptions required. All logic runs locally. +- **Background Auto-Updates**: Non-blocking CDN fetching ensures your datasets never go stale without impacting request latency. +- **Comprehensive Coverage**: 30 dedicated tools for identity validation (PAN, Aadhaar, GSTIN), tax calculation (Income Tax, TDS, GST), and master data lookups. +- **Enterprise-Ready**: Thread-pool accelerated bulk validation tools for processing large batches of vendor or customer data. + +--- + +## 🚀 Quick Start + +### Installation ```bash pip install mcp-india-stack ``` -## Run +### Claude Desktop Configuration -```bash -mcp-india-stack -``` +Add the following to your `claude_desktop_config.json` file to enable the India Stack in Claude Desktop: -or +**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`): +```json +{ + "mcpServers": { + "mcp-india-stack": { + "command": "python", + "args": ["-m", "mcp_india_stack"] + } + } +} +``` -```bash -python -m mcp_india_stack +**macOS/Linux** (`~/Library/Application Support/Claude/claude_desktop_config.json` or `~/.config/Claude/claude_desktop_config.json`): +```json +{ + "mcpServers": { + "mcp-india-stack": { + "command": "python3", + "args": ["-m", "mcp_india_stack"] + } + } +} ``` -## Tools +--- + +## 🛠️ Tool Catalog -### Lookup Tools +### 🔍 Lookup Tools - [`lookup_ifsc`](docs/tools/ifsc.md) — Bank branch details from IFSC code - [`lookup_pincode`](docs/tools/pincode.md) — India pincode details and post offices - [`lookup_hsn_code`](docs/tools/hsn.md) — HSN/SAC code lookup by code or keyword - [`decode_state_code`](docs/tools/state_code.md) — GST state code metadata +- [`lookup_bbps_biller`](docs/tools/bbps.md) — BBPS biller directory lookup +- [`lookup_bank`](docs/tools/bank.md) — Basic bank master lookup by name or code -### Validation Tools +### ✅ Validation Tools - [`validate_gstin`](docs/tools/gstin.md) — GSTIN structure and checksum - [`validate_pan`](docs/tools/pan.md) — PAN format and entity type decode - [`validate_upi_vpa`](docs/tools/upi.md) — UPI VPA structure and provider decode @@ -44,74 +76,75 @@ python -m mcp_india_stack - [`validate_passport`](docs/tools/passport.md) — Indian passport number format - [`validate_cin`](docs/tools/cin.md) — Company Identification Number with full field decode - [`validate_din`](docs/tools/din.md) — Director Identification Number format +- [`validate_fssai`](docs/tools/fssai.md) — FSSAI license number validation and decode +- [`validate_epf_code`](docs/tools/epf.md) — EPF establishment code validator +- [`validate_esic_code`](docs/tools/esic.md) — ESIC employer code validator +- [`decode_digilocker_uri`](docs/tools/digilocker.md) — DigiLocker URI decoder and validator mapper +- [`decode_pan_type`](docs/tools/pan.md) — Decode PAN entity type from the 4th character + +### ⚡ Bulk Operations +- [`bulk_validate_gstin`](docs/tools/gstin.md) — Parallel GSTIN batch validation +- [`bulk_validate_pan`](docs/tools/pan.md) — Parallel PAN batch validation +- [`bulk_validate_ifsc`](docs/tools/ifsc.md) — Parallel IFSC batch validation -### Tax Calculators (FY2025-26) +### 🧮 Tax & Financial Calculators (FY2025-26) - [`calculate_income_tax`](docs/tools/income_tax.md) — Old vs new regime comparison with surcharge, rebate, cess - [`calculate_tds`](docs/tools/tds.md) — TDS rate lookup and computation for 12+ sections - [`calculate_gst`](docs/tools/gst_calculator.md) — GST breakdown (CGST/SGST/IGST/cess) - [`calculate_surcharge`](docs/tools/surcharge.md) — Surcharge and marginal relief calculator - -### Additional Tools -- [`bulk_validate_gstin`](docs/tools/gstin.md) — Parallel GSTIN batch validation -- [`bulk_validate_pan`](docs/tools/pan.md) — Parallel PAN batch validation -- [`bulk_validate_ifsc`](docs/tools/ifsc.md) — Parallel IFSC batch validation -- [`validate_fssai`](docs/tools/fssai.md) — FSSAI license number validation and decode - [`calculate_hra_exemption`](docs/tools/hra.md) — HRA exemption calculator for salary planning - [`calculate_capital_gains`](docs/tools/capital_gains.md) — Capital gains tax helper - [`calculate_advance_tax`](docs/tools/advance_tax.md) — Advance tax estimator -- [`lookup_bbps_biller`](docs/tools/bbps.md) — BBPS biller directory lookup -- [`decode_pan_type`](docs/tools/pan.md) — Decode PAN entity type from the 4th character -- [`lookup_bank`](docs/tools/bank.md) — Basic bank master lookup by name or code -- [`validate_epf_code`](docs/tools/epf.md) — EPF establishment code validator -- [`validate_esic_code`](docs/tools/esic.md) — ESIC employer code validator -- [`decode_digilocker_uri`](docs/tools/digilocker.md) — DigiLocker URI decoder and validator mapper -### Prompt Workflows -- [`vendor_kyc`](docs/workflows/vendor_kyc.md) — GSTIN, PAN, and IFSC verification workflow -- [`salary_planner`](docs/workflows/salary_planner.md) — Income, HRA, and take-home salary workflow -- [`invoice_audit`](docs/workflows/invoice_audit.md) — GSTIN, HSN, and GST rate audit workflow +--- + +## 🔄 Agent Workflows & Resources -### Resources +### Prompt Workflows ([Overview](docs/prompts.md)) +Built-in prompt templates to guide AI agents through complex multi-step tasks: +- [`vendor_kyc`](docs/workflows/vendor_kyc.md) — GSTIN, PAN, and IFSC verification sequence. +- [`salary_planner`](docs/workflows/salary_planner.md) — Income, HRA, and optimized take-home salary planning. +- [`invoice_audit`](docs/workflows/invoice_audit.md) — Cross-referencing GSTINs, HSN codes, and applicable GST rates. + +### Server Resources ([Overview](docs/resources.md)) +Dynamic JSON resources provided directly to the LLM context: - `india://status` — Version, DB connectivity, and runtime flags - `india://changelog` — Structured changelog resource +- `india://schema/*` — JSON schemas for all tool outputs -## Data Freshness +--- -Datasets are bundled with the package for offline-first operation. An optional auto-update mechanism fetches the latest versions from jsDelivr CDN in the background. +## 📡 Data Architecture & Freshness -- **Auto-update is non-blocking** — stale data triggers a background refresh; the current request uses existing data. -- **Opt out** — set `MCP_INDIA_STACK_NO_AUTO_UPDATE=1` environment variable to disable all update checks. -- **Manual refresh** — run `mcp-india-stack --refresh-all` to synchronously refresh all datasets from CDN. -- **Cache location** — platform-specific via `platformdirs` (e.g., `~/.cache/mcp-india-stack` on Linux). +This package bundles static datasets for offline-first workflows (approx. 10-11MB compressed footprint), covering IFSCs, Pincodes, HSN/SAC masters, and curated UPI handles. -## Bundled Data Size +An optional auto-update mechanism fetches the latest versions from the jsDelivr CDN in the background: +- **Non-blocking**: Stale data triggers a background refresh; the current request immediately uses existing cached data to ensure zero latency. +- **Opt out**: Set the `MCP_INDIA_STACK_NO_AUTO_UPDATE=1` environment variable to disable all update checks. +- **Manual refresh**: Run `mcp-india-stack --refresh-all` to synchronously refresh all datasets from the CDN. +- **Cache location**: Platform-specific via `platformdirs` (e.g., `~/.cache/mcp-india-stack` on Linux). -This package bundles static datasets for offline-first workflows. +--- -- IFSC dataset (Razorpay releases) -- India pincode dataset (GeoNames IN postal dump, CC-BY) -- HSN/SAC master (GST tutorial workbook transformed to CSV) -- State codes and curated UPI handles +## ⚠️ Limitations -Expected install footprint includes approximately 10-11MB compressed static data. +- **Stateless Validation**: GSTIN, Aadhaar, Voter ID, DL, Passport, CIN, and DIN validators check structural formatting and checksums only. They **do not** verify active registration status with government issuing authorities. +- **Algorithmic Constraints**: PAN validation is structural; the PAN check character logic is not publicly verifiable. +- **Tax Estimates**: All tax calculations are algorithmic estimates based on FY2025-26 rules. Actual liability may differ. Always consult a Chartered Accountant. +- **Static Rates**: HSN/SAC rates are static references and may vary based on specific conditions or new government notifications. -## Limitations +--- -- GSTIN validation checks format and checksum, not active GSTN status. -- PAN validation is structural; PAN check character is not publicly algorithmic. -- HSN/SAC rates are static references and may vary by conditions/notifications. -- All tax calculations are estimates for FY2025-26. Actual liability may differ — consult a CA. -- Aadhaar, Voter ID, DL, Passport, CIN, DIN validators are format-only — they do not verify active status with issuing authorities. +## ⚖️ Legal & Attribution -## Legal and Attribution +See [`NOTICES`](NOTICES) for detailed dataset attribution, licensing details, and third-party acknowledgments. -See `NOTICES` for dataset attribution and licensing details. +--- -## Launch Notes +## 🚀 Launch Notes This repository is release-ready for GitHub launch with: - -- `0.3.0` package metadata and changelog coverage -- A complete MCP server-card under `docs/.well-known/mcp/server-card.json` -- Local setup and publishing steps in `SETUP.md` -- Contribution guidance and versioning policy in `CONTRIBUTING.md` +- `0.3.0` package metadata and changelog coverage. +- A complete MCP server-card under `docs/.well-known/mcp/server-card.json`. +- Local setup and publishing steps in [`SETUP.md`](SETUP.md). +- Contribution guidance and versioning policy in [`CONTRIBUTING.md`](CONTRIBUTING.md). diff --git a/docs/prompts.md b/docs/prompts.md new file mode 100644 index 0000000..d6e2988 --- /dev/null +++ b/docs/prompts.md @@ -0,0 +1,25 @@ +# MCP Prompts + +The `mcp-india-stack` server includes pre-defined prompts to guide AI agents through complex multi-step workflows. + +## Vendor KYC + +**Name:** `vendor_kyc` + +A workflow to verify a vendor's legitimacy by checking their GSTIN, PAN, and bank account (IFSC) in sequence. + +--- + +## Salary Planner + +**Name:** `salary_planner` + +A workflow to calculate an employee's take-home salary, including HRA exemptions and tax regime comparisons (Old vs New). + +--- + +## Invoice Audit + +**Name:** `invoice_audit` + +A workflow to validate an invoice's tax compliance by checking the supplier's GSTIN and verifying the HSN code and associated GST rate. diff --git a/docs/resources.md b/docs/resources.md new file mode 100644 index 0000000..b967bbb --- /dev/null +++ b/docs/resources.md @@ -0,0 +1,61 @@ +# MCP Resources + +The `mcp-india-stack` server exposes structured resources for server status, versioning, and tool schemas. + +## Server Status + +**URI:** `india://status` + +Returns the current server configuration, versioning, and runtime status. + +**Example Output:** +```json +{ + "version": "0.3.0", + "db_connected": true, + "live_lookup_enabled": false, + "dry_run_mode": false, + "db_url_configured": false, + "tool_count": 30, + "data_version": "2025.04" +} +``` + +--- + +## Changelog + +**URI:** `india://changelog` + +Returns a structured version of the project changelog. + +--- + +## Tool Schemas + +**URIs:** `india://schema/` + +Returns the JSON schema for the output of a specific tool. + +**Supported Tools:** +- `lookup_ifsc` +- `validate_gstin` +- `validate_pan` +- `validate_upi_vpa` +- `lookup_pincode` +- `lookup_hsn_code` +- `decode_state_code` +- `validate_aadhaar` +- `validate_voter_id` +- `validate_driving_license` +- `validate_passport` +- `validate_cin` +- `validate_din` +- `calculate_income_tax` +- `calculate_tds` +- `calculate_gst` +- `calculate_surcharge` +- `calculate_hra_exemption` +- `calculate_capital_gains` +- `calculate_advance_tax` +- `bulk_validate_gstin` diff --git a/docs/tools/gstin.md b/docs/tools/gstin.md index 00befbe..2b00b35 100644 --- a/docs/tools/gstin.md +++ b/docs/tools/gstin.md @@ -1,4 +1,6 @@ -# validate_gstin +# GSTIN Tools + +## validate_gstin Validates GSTIN structure and checksum, decodes state/PAN/entity metadata, and reports category limitations for special classes. Validates structure and checksum only; does not verify active GSTN registration status. @@ -10,3 +12,14 @@ Validates GSTIN structure and checksum, decodes state/PAN/entity metadata, and r **Limitations:** Validates format and checksum only. Cannot verify if the GSTIN is currently active or cancelled on the GST portal. +--- + +## bulk_validate_gstin + +Validate multiple GSTINs in parallel using a thread pool. Maximum 500 GSTINs per call. + +**Input:** `gstins` (list[str]) — List of GSTIN strings to validate. + +**Output:** `results` (list of single validation outputs), `total`, `valid_count`, `invalid_count`. + +**Example prompt:** "Validate these GSTINs in bulk: 27AAPFU0939F1ZV, 27AAPFU0939F1ZW" diff --git a/docs/tools/ifsc.md b/docs/tools/ifsc.md index 18e3f24..04cf34e 100644 --- a/docs/tools/ifsc.md +++ b/docs/tools/ifsc.md @@ -1,4 +1,6 @@ -# lookup_ifsc +# IFSC Tools + +## lookup_ifsc Validates IFSC format and returns bank branch metadata from bundled dataset with optional live fallback to Razorpay IFSC API. @@ -10,3 +12,14 @@ Validates IFSC format and returns bank branch metadata from bundled dataset with **Limitations:** Bundled data may be slightly behind newest branch openings. Live fallback requires internet connectivity. +--- + +## bulk_validate_ifsc + +Validate multiple IFSC codes in parallel. Maximum 500 IFSCs per call. + +**Input:** `ifscs` (list[str]) — List of IFSC codes to validate. + +**Output:** `results` (list of single lookup outputs), `total`, `found_count`. + +**Example prompt:** "Bulk lookup these IFSC codes: HDFC0000001, ICIC0000002" diff --git a/docs/tools/pan.md b/docs/tools/pan.md index 400ba50..24b8172 100644 --- a/docs/tools/pan.md +++ b/docs/tools/pan.md @@ -1,4 +1,6 @@ -# validate_pan +# PAN Tools + +## validate_pan Validates Indian PAN format and decodes entity type from the 4th character. Structural validation only. @@ -10,3 +12,26 @@ Validates Indian PAN format and decodes entity type from the 4th character. Stru **Limitations:** PAN check character (10th digit) is not publicly algorithmic. This tool validates the 4th character entity type and overall digit/letter structure. Cannot verify if the PAN is valid with IT Department. +--- + +## bulk_validate_pan + +Validate multiple PANs in parallel. Maximum 500 PANs per call. + +**Input:** `pans` (list[str]) — List of 10-character PAN strings. + +**Output:** `results` (list of single validation outputs), `total`, `valid_count`. + +**Example prompt:** "Bulk validate these PANs: AAAPL1234C, BBBCM5678D" + +--- + +## decode_pan_type + +Decodes the PAN entity type from the 4th character and provides KYC routing hints. + +**Input:** `pan` (str) — 10-character PAN. + +**Output:** `pan`, `entity_type_code`, `entity_type_label`, `kyc_routing_hint`. + +**Example prompt:** "What is the entity type for PAN AAAPL1234C?"