docs: refresh launch documentation

README.md

@@ -1,40 +1,72 @@
-# 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)
 [![CI](https://github.com/rehan1020/MCP-India-Stack/actions/workflows/ci.yml/badge.svg)](https://github.com/rehan1020/MCP-India-Stack/actions/workflows/ci.yml)
 [![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).

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.

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/<tool_name>`
+
+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`

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"

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"

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?"