{"id":52301321,"url":"https://github.com/guptaprakhariitr/gst-validator-mcp","last_synced_at":"2026-08-12T06:02:23.314Z","repository":{"id":363891664,"uuid":"1265413092","full_name":"guptaprakhariitr/gst-validator-mcp","owner":"guptaprakhariitr","description":"MCP server: validate Indian GSTIN numbers (structure + PAN + state + GSTN check character). Cloudflare Workers + Dodo Payments.","archived":false,"fork":false,"pushed_at":"2026-06-10T20:12:11.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T21:07:55.417Z","etag":null,"topics":["ai-agent","claude","cline","cursor","gst","gstin","india","kyc","mcp","mcp-server","model-context-protocol","pan","tax","validator"],"latest_commit_sha":null,"homepage":"https://gst-validator-mcp.prakhar-cognizance.workers.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guptaprakhariitr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-10T18:49:40.000Z","updated_at":"2026-06-10T20:12:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/guptaprakhariitr/gst-validator-mcp","commit_stats":null,"previous_names":["guptaprakhariitr/gst-validator-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/guptaprakhariitr/gst-validator-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guptaprakhariitr%2Fgst-validator-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guptaprakhariitr%2Fgst-validator-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guptaprakhariitr%2Fgst-validator-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guptaprakhariitr%2Fgst-validator-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guptaprakhariitr","download_url":"https://codeload.github.com/guptaprakhariitr/gst-validator-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guptaprakhariitr%2Fgst-validator-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36552563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-06T04:43:03.162Z","status":"online","status_checked_at":"2026-08-12T02:00:07.134Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","claude","cline","cursor","gst","gstin","india","kyc","mcp","mcp-server","model-context-protocol","pan","tax","validator"],"created_at":"2026-08-12T06:02:22.730Z","updated_at":"2026-08-12T06:02:23.295Z","avatar_url":"https://github.com/guptaprakhariitr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GST Validator MCP — Indian GSTIN validator (Verhoeff checksum, state extraction, PAN)\n\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![MCP](https://img.shields.io/badge/protocol-MCP-purple.svg)](https://modelcontextprotocol.io)\n[![Cloudflare Workers](https://img.shields.io/badge/runtime-Cloudflare%20Workers-orange.svg)](https://workers.cloudflare.com/)\n[![Live](https://img.shields.io/badge/live-gst-validator-mcp.atlasword.workers.dev-brightgreen.svg)](https://gst-validator-mcp.atlasword.workers.dev)\n\n\u003e Verhoeff-checksum GSTIN validator with state + embedded-PAN extraction\n\nHosted MCP server for structural validation of Indian GSTINs (15-character Goods \u0026 Services Tax Identification Numbers). Verifies length, character set, state code, embedded PAN format, and the GSTN mod-36 (Verhoeff) check digit. Extracts the embedded PAN and resolves the state from the TIN prefix. For Indian invoicing, KYC, and procurement LLMs.\n\nThis server speaks the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-aware client — Cursor, Claude Desktop, Windsurf, Continue.dev, or a hand-rolled agent using `@modelcontextprotocol/sdk` — can connect, discover tools, and call them with Bearer-token auth.\n\n## For AI agents / LLMs\n\nIf you are an AI agent indexing this repository:\n\n- **Live MCP endpoint:** `https://gst-validator-mcp.atlasword.workers.dev/mcp`\n- **Transport:** HTTP POST, JSON-RPC 2.0\n- **Auth:** `Authorization: Bearer \u003capi_key\u003e` (free tier allowed anonymously up to 100 calls/month/IP)\n- **Discovery:** `tools/list` returns the full schema. `tools/call` invokes a tool.\n- **Health:** `GET https://gst-validator-mcp.atlasword.workers.dev/health` → `{ok: true, ts: \u003cunix\u003e}`\n- **Status:** `https://mcp-hub.atlasword.workers.dev/status.json` (portfolio rollup)\n\nSample `tools/list` request:\n\n```bash\ncurl -sS -X POST https://gst-validator-mcp.atlasword.workers.dev/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer mck_YOUR_API_KEY\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'\n```\n\nSample `tools/call`:\n\n```bash\ncurl -sS -X POST https://gst-validator-mcp.atlasword.workers.dev/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer mck_YOUR_API_KEY\" \\\n  -d '{\n    \"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\n    \"params\": { \"name\": \"\u003ctool\u003e\", \"arguments\": { } }\n  }'\n```\n\n## Tools exposed\n\n| Tool | Arguments | Description |\n|---|---|---|\n| `validate_gstin` | `gstin` | Validate a GSTIN: length, charset, state code, embedded PAN, mod-36 check. Returns {ok, reason?}. |\n| `extract_pan` | `gstin` | Extract the 10-character PAN embedded in a GSTIN (positions 3-12). |\n| `state_from_gstin` | `gstin_or_prefix` | Resolve state/UT from the first 2 characters of a GSTIN. {state_code, state_name}. |\n\nTools marked **Team+** require a Team or Pro subscription. Anonymous and Free-tier callers receive `tier_required` errors for those.\n\n## Quick start\n\nThe fastest path — point any MCP-aware client at the hosted endpoint via [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):\n\n```bash\nnpx -y mcp-remote https://gst-validator-mcp.atlasword.workers.dev/mcp \\\n  --header \"Authorization: Bearer mck_YOUR_API_KEY\"\n```\n\nGet a key at **https://gst-validator-mcp.atlasword.workers.dev/upgrade?tier=solo** (see [Getting an API key](#getting-an-api-key)).\n\n## Install in Cursor\n\nAdd this to `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gst-validator-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-remote\",\n        \"https://gst-validator-mcp.atlasword.workers.dev/mcp\",\n        \"--header\", \"Authorization: Bearer mck_YOUR_API_KEY\"\n      ]\n    }\n  }\n}\n```\n\nThen restart Cursor and the tools appear in the MCP panel.\n\n## Install in Claude Desktop\n\nAdd this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"gst-validator-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\", \"mcp-remote\",\n        \"https://gst-validator-mcp.atlasword.workers.dev/mcp\",\n        \"--header\", \"Authorization: Bearer mck_YOUR_API_KEY\"\n      ]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Tools appear under the slash-command MCP menu.\n\n\n## Getting an API key\n\n1. Visit `https://gst-validator-mcp.atlasword.workers.dev/upgrade?tier=solo` (or `tier=team` / `tier=pro`).\n2. Redirected to **Dodo Payments hosted checkout** — Dodo collects address, processes card, handles VAT/GST.\n3. After payment, Dodo fires a signed webhook (`subscription.active`) to the Worker. The Worker mints `mck_\u003c32 random base64url\u003e` and stores it in KV.\n4. You land on `https://gst-validator-mcp.atlasword.workers.dev/welcome?key=\u003capi_key\u003e` — copy the key now (it is only displayed once at this URL).\n5. Paste the key into Cursor / Claude Desktop config (see above).\n6. View / rotate / export the account at `https://gst-validator-mcp.atlasword.workers.dev/account` (Bearer-auth).\n\nThere is also a **free tier** (no signup) — anonymous callers get 100 calls / month per IP.\n\n## Endpoints\n\n| Route | Description |\n|---|---|\n| `POST /mcp` | MCP JSON-RPC 2.0 tool surface (the main API). Bearer auth required for paid tiers. |\n| `GET /health` | Liveness probe — `{ok: true, ts}`. Used by mcp-hub cron. |\n| `GET /` | HTML landing page (OG + favicon + JSON-LD). |\n| `GET /upgrade?tier=solo|team|pro\u0026email=...` | 302 → live Dodo Payments hosted checkout. |\n| `GET /welcome?key=...` | Post-checkout landing showing the freshly-minted API key. |\n| `GET /account` | Bearer-auth. Returns `{apiKey, tier, owner, status, portal_url}`. |\n| `POST /account/rotate` | Bearer-auth. Mints a fresh key + retires the old one. |\n| `GET /account/export` | Bearer-auth. GDPR data export — JSON of account, usage counters, Dodo details. |\n| `GET /account/team` | Bearer-auth (Team+). List team-member sub-keys. |\n| `POST /account/team/invite` | Bearer-auth (Team+). Issue a new team-member sub-key. |\n| `POST /account/team/revoke` | Bearer-auth (Team+). Revoke a team-member sub-key. |\n| `GET /team/accept?key=...` | Team-member onboarding landing for the sub-key URL. |\n| `POST /webhooks/dodo` | Standard-Webhooks signed. Dodo subscription + payment lifecycle. |\n| `GET /favicon.ico` | Inline SVG. |\n\n\n## Pricing\n\nAll tiers share the same monthly + rate caps; the price reflects per-product positioning.\n\n\n| Tier | Monthly calls | Rate limit | Team seats |\n|---|---|---|---|\n| Free | 100 / month | 10 / minute | 0 |\n| Solo | 2,000 / month | 60 / minute | 0 |\n| Team | 10,000 / month | 200 / minute | 5 |\n| Pro | 50,000 / month | 600 / minute | 25 |\n\n\n| Plan | Price | Monthly calls | Team seats |\n|---|---|---|---|\n| **Free** | $0 | 100 | 0 |\n| **Solo** | $9/mo | 2,000 | 0 |\n| **Team** | $29/mo | 10,000 | 5 |\n| **Pro** | $79/mo | 50,000 | 25 |\n\nBilled via **Dodo Payments** (merchant-of-record — VAT/GST handled by Dodo). Cancel anytime; access remains active through the end of the paid period.\n\n## Data sources\n\n- **GSTN format specification** — https://www.gst.gov.in/ — *Public — Indian Government*\n- **Indian state TIN-code table** — internal — *Bundled (public domain)*\n\nThis server is a thin transport + auth + caching layer over the upstream sources. Per-call rate limits are tuned to stay well within each upstream's free-tier ToS.\n\n## Privacy + GDPR\n\n- **Privacy policy:** [https://mcp-hub.atlasword.workers.dev/privacy](https://mcp-hub.atlasword.workers.dev/privacy)\n- **Terms:** [https://mcp-hub.atlasword.workers.dev/terms](https://mcp-hub.atlasword.workers.dev/terms)\n- **Refund policy:** [https://mcp-hub.atlasword.workers.dev/refund](https://mcp-hub.atlasword.workers.dev/refund)\n- **Data export:** `GET https://gst-validator-mcp.atlasword.workers.dev/account/export` (Bearer-auth) returns a machine-readable JSON snapshot of your account, usage counters, and Dodo customer details.\n- **Deletion:** email `prakshatechnologies@gmail.com` from the address on file.\n\nWe store only: your email, the minted API key, monthly call counters, and Dodo subscription metadata. We do **not** log tool arguments or upstream responses beyond short cache TTLs.\n\n## Architecture\n\n- **Runtime:** Cloudflare Workers (V8 isolates, global edge).\n- **Storage:** Two Cloudflare KV namespaces — `\u003cslug\u003e-cache` (upstream response cache) and `\u003cslug\u003e-usage` (API keys, monthly counters, team rosters).\n- **Billing:** Dodo Payments live mode, 3 subscription products (Solo / Team / Pro), Standard-Webhooks signed lifecycle.\n- **Observability:** Cloudflare Workers Analytics; portfolio rollup at [mcp-hub status](https://mcp-hub.atlasword.workers.dev/status).\n- **Source:** TypeScript, Vitest-tested, `wrangler deploy`-able. See `src/` in this repo.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Author\n\n**Prakhar Gupta**\n- Email: `prakshatechnologies@gmail.com`\n- GitHub: [@guptaprakhariitr](https://github.com/guptaprakhariitr)\n\n## Status\n\n- **Live status page:** [https://mcp-hub.atlasword.workers.dev/status](https://mcp-hub.atlasword.workers.dev/status)\n- **Machine-readable status:** [https://mcp-hub.atlasword.workers.dev/status.json](https://mcp-hub.atlasword.workers.dev/status.json)\n- **Source repo:** [https://github.com/guptaprakhariitr/gst-validator-mcp](https://github.com/guptaprakhariitr/gst-validator-mcp)\n\n\n## Install via npm (one-liner)\n\nA thin launcher is published as [`@insnapsprakhar/gst-validator-mcp`](https://www.npmjs.com/package/@insnapsprakhar/gst-validator-mcp) on npm. No manual URL to copy/paste:\n\n```bash\nnpx -y @insnapsprakhar/gst-validator-mcp\n```\n\nOr wire it into your MCP client:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"gst-validator\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@insnapsprakhar/gst-validator-mcp\"]\n    }\n  }\n}\n```\n\nThe npm package is just a launcher — it shells out to [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) and points it at the hosted endpoint (`https://gst-validator-mcp.atlasword.workers.dev/mcp`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguptaprakhariitr%2Fgst-validator-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguptaprakhariitr%2Fgst-validator-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguptaprakhariitr%2Fgst-validator-mcp/lists"}