bharatpay-mcp: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code working in this repo.

What this is

bharatpay-mcp — a public MCP server (PyPI: bharatpay-mcp, MIT) that exposes Indian fintech utilities to AI agents over stdio: IFSC lookups, PAN/GSTIN validation, pincode lookups, mutual fund NAVs, UPI VPA identification, INR formatting. Seven tools, no auth, no API keys, no paid upstreams.

It deliberately complements Razorpay's official MCP server rather than competing: Razorpay executes transactions, BharatPay validates and enriches. Keep that boundary — don't add tools that move money or need credentials.

Layout

src/bharatpay_mcp/
  server.py        # FastMCP instance + all @mcp.tool() registrations. Thin wrappers only.
  __main__.py      # `python -m bharatpay_mcp` → server.main()
  tools/           # one module per domain; all real logic lives here
    gstin.py  ifsc.py  inr.py  mutual_fund.py  pan.py  pincode.py  upi.py
tests/test_validators.py   # offline validators only, no network
scripts/smoke_test.py      # manual end-to-end incl. live APIs (not part of pytest)

Engineering standards

These are the rules that matter here. Follow them; don't relax them for convenience.

1. Every tool has a pure-function offline validator

Each tool module must be able to reject bad input without touching the network. Format checks, checksums, and metadata extraction are pure functions over strings — they run before any HTTP call and they never raise.

• Fully offline tools (pan.py, gstin.py, upi.py, inr.py) are pure end to end.
• Network tools validate first, then fetch: see _validate_format() in ifsc.py and PIN_PATTERN in pincode.py.

The point is graceful degradation: when ifsc.razorpay.com or India Post is down, a malformed IFSC still gets a precise, useful answer, and a well-formed one gets an honest network error — never a traceback across the MCP boundary.

Known gap: mutual_fund.py only checks for an empty query before hitting AMFI. If you touch that file, add a real offline validator (scheme codes are digits; name fragments have a minimum length) and a test.