# mcp-jazzcash

[![npm version](https://img.shields.io/badge/npm-mcp--jazzcash-cb3837?logo=npm)](https://www.npmjs.com/package/mcp-jazzcash)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A518.17-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-1.0-7c3aed)](https://modelcontextprotocol.io)
[![Status](https://img.shields.io/badge/status-alpha-orange)]()

An open-source [Model Context Protocol](https://modelcontextprotocol.io) server for **JazzCash** — Pakistan's largest mobile-money platform. Plug it into Claude Desktop, Cursor, Cline, or any MCP-aware agent and let it create checkouts, charge mobile wallets, look up transactions, and issue refunds against the JazzCash REST API.

> **Sandbox-by-default. Bring your own merchant credentials. No secrets bundled.**

---

## Table of contents

- [Why this exists](#why-this-exists)
- [Tools](#tools)
- [Quick start](#quick-start)
- [Configuration](#configuration)
- [Wire it into Claude Desktop](#wire-it-into-claude-desktop)
- [Use it from any MCP client](#use-it-from-any-mcp-client)
- [How the signature works](#how-the-signature-works)
- [Endpoint overrides](#endpoint-overrides)
- [Security model](#security-model)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

---

## Why this exists

The Pakistani payments stack is fragmented and English-language documentation for AI agents is thin. This MCP gives any agent a stable, typed interface to JazzCash so you don't have to teach it the signature scheme, field names, and gotchas every time. Prompt your agent in plain English; let the server do the cryptography and HTTP.

## Tools

| Tool | Purpose |
|---|---|
| `jazzcash_create_hosted_checkout` | Builds a signed Hosted Checkout (Page Redirection) form. Returns the action URL, hidden fields, and a ready-to-use HTML snippet your app can serve. |
| `jazzcash_charge_mobile_wallet` | Server-to-server MWALLET charge. Customer authorizes via MPIN on their phone. |
| `jazzcash_inquire_transaction` | Status lookup by `pp_TxnRefNo`. |
| `jazzcash_refund_transaction` | Full or partial refund (requires merchant role). |
| `jazzcash_environment_info` | Reports active environment, endpoint URLs, and which credentials are present. **Never returns secrets.** |

All amounts are passed as **PKR paisa** (rupees × 100) to avoid float rounding.

## Quick start

```bash
git clone https://github.com/TehreemArbab/JazzCashMCP.git
cd JazzCashMCP
npm install
cp .env.example .env       # then edit .env with your sandbox credentials
npm run build
npm start
```

The server speaks MCP over stdio, so `npm start` is most useful when launched by an MCP client (see below). To verify the build alone:

```bash
npm run typecheck
```

## Configuration

Copy `.env.example` to `.env` and fill in credentials from your JazzCash merchant portal:

```bash
JAZZCASH_MERCHANT_ID=MC...
JAZZCASH_PASSWORD=...
JAZZCASH_INTEGRITY_SALT=...
JAZZCASH_ENV=sandbox
JAZZCASH_RETURN_URL=https://yourapp.example.com/jazzcash/callback
```

Sandbox credentials are issued at <https://sandbox.jazzcash.com.pk>. To go live, switch `JAZZCASH_ENV=production` and swap in your live merchant credentials — no code changes required.

| Variable | Required | Notes |
|---|---|---|
| `JAZZCASH_MERCHANT_ID` | yes | From the merchant portal. |
| `JAZZCASH_PASSWORD` | yes | API password, not your portal login. |
| `JAZZCASH_INTEGRITY_SALT` | yes | HMAC key for `pp_SecureHash`. |
| `JAZZCASH_ENV` | yes | `sandbox` or `production`. |
| `JAZZCASH_RETURN_URL` | only for hosted checkout | Where JazzCash redirects the customer post-payment. |
| `JAZZCASH_LANGUAGE` | no | Default `EN`. |
| `JAZZCASH_CURRENCY` | no | Default `PKR`. |
| `JAZZCASH_VERSION` | no | Default `1.1`. |
| `JAZZCASH_*_URL` | no | Per-endpoint URL override; see [Endpoint overrides](#endpoint-overrides). |

## Wire it into Claude Desktop

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "jazzcash": {
      "command": "node",
      "args": ["C:/path/to/mcp-jazzcash/dist/index.js"],
      "env": {
        "JAZZCASH_MERCHANT_ID": "MC...",
        "JAZZCASH_PASSWORD": "...",
        "JAZZCASH_INTEGRITY_SALT": "...",
        "JAZZCASH_ENV": "sandbox",
        "JAZZCASH_RETURN_URL": "https://yourapp.example.com/jazzcash/callback"
      }
    }
  }
}
```

Restart Claude Desktop, then try:

> *"Using the JazzCash MCP, create a hosted checkout for PKR 1500 with description 'Order #1023' and bill reference 'INV1023'."*

Claude will call `jazzcash_create_hosted_checkout` and hand back the form HTML.

## Use it from any MCP client

The server uses stdio transport, so it works with anything that speaks MCP — Cursor, Cline, Continue, Zed, and custom agents built on the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk). Point the client at `node /path/to/dist/index.js` and pass the same env vars shown above.

## How the signature works

JazzCash uses **HMAC-SHA256** over alphabetically sorted, non-empty `pp_*` fields, joined with `&`, with the merchant's Integrity Salt as both the HMAC key and a prepended salt:

```text
message = integritySalt + "&" + sortedField1Value + "&" + sortedField2Value + ...
hash    = hex(HMAC_SHA256(key=integritySalt, message))
```

`pp_SecureHash` itself is excluded from the message. Empty values are skipped. The implementation lives in [`src/signature.ts`](./src/signature.ts) — small enough to audit in 30 seconds.

## Endpoint overrides

Default endpoint URLs ship for both sandbox and production. If JazzCash rotates a path, override the relevant variable without changing code:

```bash
JAZZCASH_HOSTED_CHECKOUT_URL=https://sandbox.jazzcash.com.pk/.../HostedCheckout
JAZZCASH_MOBILE_WALLET_URL=https://sandbox.jazzcash.com.pk/.../DoMWalletTransaction
JAZZCASH_INQUIRY_URL=https://sandbox.jazzcash.com.pk/.../StatusInquiry
JAZZCASH_REFUND_URL=https://sandbox.jazzcash.com.pk/.../DoRefundTransaction
```

## Security model

- **No bundled secrets.** Credentials are read from environment variables only.
- **No secrets in tool output.** `jazzcash_environment_info` returns only booleans for which credentials are configured.
- **Sandbox is the default.** Production requires explicitly setting `JAZZCASH_ENV=production`.
- **Stdio transport.** The server has no network listener; it talks only to the parent MCP client process.
- **Audit-friendly.** Signature logic is isolated in one short file. No vendored crypto.

If you find a security issue, please open a private advisory on GitHub rather than a public issue.

## Roadmap

- [ ] Card / Tokenization tools (Authorize, Capture, Retrieve/Delete Token)
- [ ] IPN webhook signature-verification helper
- [ ] Voucher / OTC payment flow
- [ ] CLI (`mcp-jazzcash inspect`) for hash debugging
- [ ] Published npm package + automated releases

## Contributing

Issues and PRs welcome. A few ground rules:

- Don't paste real merchant credentials into bug reports — use the placeholder `JAZZCASH_*` names.
- Keep new tools framework-agnostic; the server should remain usable from any MCP client.
- Run `npm run typecheck` before opening a PR.

## License

[MIT](./LICENSE). Not affiliated with or endorsed by JazzCash, Mobilink Microfinance Bank, or VEON.