# @payretailers/mcp

> Official Model Context Protocol (MCP) server for the PayRetailers Payments API.

Turn any MCP-compatible AI assistant into a PayRetailers integration expert. This server exposes the official Guides, tactical Skills, endpoint reference, and integration tools (search, country-specific validation, webhook playbook) as first-class MCP Resources, Tools, and Prompts.

Works with **Cursor**, **Claude Desktop**, **Claude Code**, **Windsurf**, **Antigravity**, **Zed**, **VS Code + Copilot**, **JetBrains IDEs**, **Continue.dev**, **Cline**, and any other client that speaks MCP over stdio.

---

## Why use it

When you install this server, your AI assistant stops guessing about PayRetailers and starts consulting the source of truth on every step.

- **Correct code on the first try.** The assistant reads the real OpenAPI shape for each endpoint (`get_endpoint_spec`), so generated code uses the actual field names, types, and required combinations — not something borrowed from another PSP.
- **Country-aware from the start.** Ask for a PIX payin and the assistant knows PIX is Brazil-only, expects BRL, needs a valid 11-digit CPF, and that the QR expires fast. Ask for SPEI and it knows Mexico wants a CURP or RFC, MXN, and that CLABE is provisioned asynchronously. All powered by `get_country_rules`.
- **Payloads validated before they hit the sandbox.** `validate_payload` runs real checksum validation on CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE — plus cross-cutting rules (integer minor units, HTTPS notification URLs, currency/country match, method/country compatibility, idempotency keys, customer required-fields matrix, subscription AmountModel shape, PIX Automático retry contract). You catch bugs in your editor, not in a `400 INVALID_MODEL_SCHEMA` response.
- **Webhook receivers designed correctly.** `get_webhook_playbook` returns the canonical event vocabulary, retry policies, and signature/replay contract. `validate_webhook_handler` catches the six most damaging anti-patterns (ack-after-processing, missing eventId de-duplication, business-errors-as-500, disabled signature in production, wall-clock-order assumptions, HTTPS missing) **before** you write a single line of receiver code.
- **Slash-command prompts for the hard flows.** Type `/integrate-pix-payin`, `/integrate-subscriptions`, `/implement-webhook-handler`, `/integrate-payout-fx`, `/build-checkout`, `/debug-401-auth`, or `/reconcile-with-graphql` and get a production-shaped implementation in the stack of your choice.
- **Zero-config, zero-network, offline-friendly.** Everything ships bundled in the release zip. No account, no API key, no outbound calls just to answer a question about the docs. Credentials are only needed for the (planned) `simulate_transaction` tool.

Under the hood you have **7 tools, 7 prompts, 158 documentation resources** (Guides + Skills + Reference + Recipes + concept docs), all mirrored verbatim from the [`payretailers-ai-docs`](https://github.com/payretailers-dev/payretailers-ai-docs) repository.

---

## What it exposes

### Resources

Structured, LLM-friendly access to the PayRetailers documentation.

| URI pattern | What it returns |
|---|---|
| `payretailers://guide/{slug}` | An end-to-end integration guide with architecture, sequence diagrams, implementation steps, and production checklist. |
| `payretailers://skill/{slug}` | A task-focused workflow that combines multiple endpoints (e.g. `brazil-pix-payin`, `payout-fx-quote-flow`). |
| `payretailers://reference/{slug}` | A single API reference page (parameters, response, error codes). |
| `payretailers://recipe/{slug}` | A short code recipe for a common operation. |
| `payretailers://doc/{slug}` | A concept/documentation page (subscription-concepts, webhooks-and-notifications, retry-policies, automatic-scheduling, clabe-per-customer, ...). |

The full list is announced dynamically at connect time — clients can browse them via their resource picker.

### Tools

Actions the LLM can invoke instead of guessing.

| Tool | What it does | Phase |
|---|---|---|
| `search_docs` | Full-text search across Guides, Skills, Reference, Recipes and concept Docs with fuzzy matching and boosted title/slug fields. | ✅ 0.1 |
| `get_country_rules` | Return the customer fields, personalId format (CPF, DNI, CURP, CC, RUT, ...), currencies, and payment-method constraints for a country + method. | ✅ 0.2 |
| `get_test_data` | Return sandbox test data (customers, cards, PIX keys, Bre-B keys) for a given country. | ✅ 0.2 |
| `get_endpoint_spec` | Return the full reference page (parameters, response, error codes) for a specific endpoint by slug. | ✅ 0.2 |
| `validate_payload` | Validate a payload against country-specific rules **with real checksum validation** for CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE. Also validates subscription products, subscriptions, and subscription payments (billing cycle, PIX_SPECIFIC retry policy, immutability). Catches non-integer minor units, wrong currency for the country, non-HTTPS webhooks, method/country mismatches, missing idempotency keys, and more. | ✅ 0.3 / 0.4 |
| `get_webhook_playbook` | Canonical PayRetailers webhook contract: envelope schema, complete event vocabulary (transactions, payouts, subscriptions, subscription payments), retry policies, signature/replay guidance, top 6 common mistakes. | ✅ 0.4 |
| `validate_webhook_handler` | Analyse a declarative description of a webhook receiver design and return machine-readable `{errors, warnings, info}`. Catches ack-after-processing, missing idempotency, business-errors-as-500, wall-clock-order assumptions, disabled signature in production. | ✅ 0.4 |
| `simulate_transaction` | Execute a real request against the PayRetailers sandbox using the developer's env credentials. | 🚧 planned |

### Prompts

Ready-to-use templates that the developer can select with `/` in Cursor / Claude Desktop / etc.

| Prompt | What it triggers | Phase |
|---|---|---|
| `integrate-pix-payin` | Generate a complete Brazil PIX payin integration in the language of your choice. | ✅ 0.1 |
| `integrate-payout-fx` | Cross-currency payout with 5-min FX quote TTL handling. | ✅ 0.2 |
| `build-checkout` | Country-aware checkout: frontend picker + backend endpoint + webhook receiver. | ✅ 0.2 |
| `debug-401-auth` | Diagnose HTTP 401/403 (subscription key, Basic Auth, IP whitelist, env mix-up). | ✅ 0.2 |
| `reconcile-with-graphql` | Build a reconciliation pipeline using the Merchant Data GraphQL API. | ✅ 0.2 |
| `implement-webhook-handler` | Generate a production-grade webhook receiver for the requested stack, scope, and queue backend. Enforces the four non-negotiables (200 fast, dedupe by eventId, strict signature, never confirm before terminal status). | ✅ 0.4 |
| `integrate-subscriptions` | Generate a full subscription integration for the given country + channel (product + activation + subscription + charge + retry + cancellation). | ✅ 0.4 |

---

## Install

Two supported paths. Pick one:

- **Option A — Prebuilt zip from GitHub Releases (recommended today)**: no npm account, no compilation, works fully offline once downloaded. This is the officially supported distribution while `@payretailers/mcp` is not yet on npm.
- **Option B — Build from source**: for contributors and security-conscious deployments that want to audit the code before running it.

Option C — installing from npm as `@payretailers/mcp` — is planned but not yet available. When the package is published, the `npx -y @payretailers/mcp` snippets in the [Configuration by client](#configuration-by-client) section will work out of the box.

### Option A — Install from GitHub Releases

**Prerequisites**: Node.js **20 or later** (`node --version`). Nothing else — the release zip is self-contained.

1. Open the [Releases page](https://github.com/payretailers-dev/payretailers-mcp/releases) and download the latest `payretailers-mcp-vX.Y.Z.zip` from the "Assets" section of the top release.
2. Unzip it anywhere. Common locations:
   - Windows: `C:\Tools\payretailers-mcp`
   - macOS / Linux: `~/tools/payretailers-mcp`
3. Add the server to your MCP client (see [Configuration by client](#configuration-by-client) below, or the step-by-step guides linked there). Point it at the absolute path of `dist/index.js` inside the unzipped folder.
4. Reload / restart your MCP client. The server will show up alongside your other tools.

**Step-by-step setup guides with screenshots and verification prompts:**

- [Cursor](docs/setup/cursor.md)
- [Claude Code CLI](docs/setup/claude-code.md)
- [Claude Desktop](docs/setup/claude-desktop.md)
- [VS Code + GitHub Copilot](docs/setup/vscode-copilot.md)

Optional smoke check before or after wiring it in — proves the bundle is healthy end-to-end:

```bash
cd /path/to/payretailers-mcp-X.Y.Z
node scripts/smoke-test.mjs
```

Expected: `PASS ✅` at the end, with **7 tools, 158 resources, 7 prompts, 5 resource templates** announced.

### Option B — Build from source

For contributors, or if your security policy requires you to audit the code before running it. **Prerequisites**: Node.js **20 or later**, git.

```bash
git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js (bundle + runtime deps)
npm start              # optional: run over stdio manually (Ctrl+C to stop)
```

`data/` (Guides, Skills, Reference, Recipes, concept docs, curated JSON) is checked in — you do **not** need `npm run sync:docs` unless you are mirroring an updated `payretailers-ai-docs` checkout on the same machine.

Then wire `dist/index.js` into your MCP client the same way as Option A.

---

## Configuration by client

> Prefer a full walkthrough with verification prompts and troubleshooting? See the step-by-step guides in [`docs/setup/`](docs/setup/README.md) for Cursor, Claude Code, Claude Desktop, and VS Code + Copilot. The snippets below are the minimal JSON needed if you already know your way around your client.

Every client takes the same three pieces of information: a **command** (`node`), an **args** array pointing at the absolute path of `dist/index.js`, and an optional **env** block for the future `simulate_transaction` tool.

Replace `C:/Tools/payretailers-mcp/dist/index.js` below with the absolute path where you unzipped the release. **On Windows use forward slashes in JSON** — backslashes need to be escaped and cause confusing errors.

### Cursor

Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

```json
{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"],
      "env": {
        "PAYRETAILERS_ENV": "sandbox",
        "PAYRETAILERS_SHOP_ID": "your_sandbox_shop_id",
        "PAYRETAILERS_SECRET_KEY": "your_sandbox_secret_key",
        "PAYRETAILERS_SUBSCRIPTION_KEY": "your_sandbox_subscription_key"
      }
    }
  }
}
```

The `env` block is optional — Resources, `search_docs`, and all validators work without any credentials.

### Claude Desktop

Add to your `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "payretailers": {
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}
```

### VS Code + Copilot

Add to `.vscode/mcp.json` (workspace) or open the user-scoped file with Command Palette → **MCP: Open User Configuration**:

```json
{
  "servers": {
    "payretailers": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  }
}
```

> Note: VS Code is the odd one out — the root key is `"servers"` (not `"mcpServers"`). MCP tools only run in Copilot Chat's **Agent** mode.

### Zed

Add to `~/.config/zed/settings.json`:

```json
{
  "context_servers": {
    "payretailers": {
      "command": {
        "path": "node",
        "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
      }
    }
  }
}
```

### Continue.dev

Add to `~/.continue/config.json`:

```json
{
  "mcpServers": [
    {
      "name": "payretailers",
      "command": "node",
      "args": ["C:/Tools/payretailers-mcp/dist/index.js"]
    }
  ]
}
```

### JetBrains AI Assistant

Open **Settings → AI Assistant → MCP Servers → Add** and enter:

- **Name**: `payretailers`
- **Command**: `node`
- **Arguments**: `C:/Tools/payretailers-mcp/dist/index.js` (absolute path)

### Other clients

Any client that speaks MCP over stdio can consume this server. Point it at `node <absolute-path-to>/dist/index.js` and you are done.

### Once npm is available

When `@payretailers/mcp` is published to npm, the same configs work with the shorter form:

```json
{ "command": "npx", "args": ["-y", "@payretailers/mcp"] }
```

No changes to `env`, no need to keep an unzipped folder around.

---

## Verify it works

After reloading your MCP client you should see, on the server's status entry, something like:

> **7 tools · 158 resources · 7 prompts · 5 resource templates**

- **Cursor**: `Ctrl+Shift+P` → **Customize** → **MCPs** tab. Look for `payretailers` with a green dot and expand it.
- **Claude Desktop**: check the tools drawer in a new chat; the PayRetailers tools should appear alongside your other MCPs.
- **VS Code / Zed / Continue.dev / Windsurf**: consult each client's docs for its MCP status panel.

If your assistant does not appear to call the tools, force it once by prefixing a prompt with *"Use the PayRetailers MCP to..."*. Once it has invoked a tool once in a conversation, it tends to keep doing so.

---

## Troubleshooting

**The server fails to start.** Run the bundle manually from a terminal:

```bash
node /path/to/payretailers-mcp/dist/index.js
```

If it stays silent waiting for input, the bundle is fine — the issue is on the client side (path typo in the config, forward-slashes vs backslashes on Windows, wrong process being restarted). If it prints an error, the most common causes are Node < 20 (upgrade Node) or a truncated download (re-download the zip).

**The client shows old counts (e.g. 5 tools, 89 resources).** Some clients cache the MCP tool/resource enumeration. Toggle the server OFF → ON in the client's MCP panel, or add an unused `env` entry to the config (e.g. `"MCP_VERSION": "0.4.1"`) to force a re-spawn.

**The model does not seem to call any MCP tool.** Make sure the chat is in Agent mode (not Ask / read-only mode). Some lightweight models are less eager to call tools — switch to a top-tier model for the first invocations, and the assistant will remember the tools are available for the rest of the conversation.

**Where are the logs?** Every MCP client has an MCP logs panel that captures the JSON-RPC handshake, parse errors, and server stderr. In Cursor: `Ctrl+Shift+U` → dropdown → **MCP Logs**.

---

## Environment variables

Optional — required only for the future `simulate_transaction` tool (Phase 4). Everything else (Resources, `search_docs`, Prompts) works without any credentials.

| Variable | Description | Default |
|---|---|---|
| `PAYRETAILERS_ENV` | `sandbox` or `production`. | `sandbox` |
| `PAYRETAILERS_SHOP_ID` | Your Shop ID from the merchant portal. | *(unset)* |
| `PAYRETAILERS_SECRET_KEY` | Your Secret Key for HTTP Basic Auth. | *(unset)* |
| `PAYRETAILERS_SUBSCRIPTION_KEY` | Value of the `Ocp-Apim-Subscription-Key` header. | *(unset)* |

**Security:** the server never logs credentials and never persists them. They live in-memory for the duration of the session and are only sent to `api-sandbox.payretailers.com` or `api.payretailers.com` when you invoke `simulate_transaction`.

---

## Example usage

Once configured, ask your AI assistant in plain language:

> *"Create my first PIX payin in the sandbox for R$50 in Brazil. Use Node.js."*

Under the hood, the assistant will:

1. Call `search_docs({ query: "pix payin brazil" })` → find the `brazil-pix-payin` skill.
2. Read `payretailers://skill/brazil-pix-payin` for the exact steps.
3. Generate runnable code with the right endpoint, headers, minor units, and CPF format.

Or use the `/integrate-pix-payin` prompt directly for a fully-scaffolded answer.

### Validating a payload before submission

Once the assistant has drafted a payload it can validate it before hitting the API:

```jsonc
// tools/call → validate_payload
{
  "operation": "create-transaction",
  "country": "BR",
  "method": "PIX",
  "payload": {
    "trackingId": "abc-12345678",
    "amount": 100.50,              // will be flagged: use 10050 (minor units)
    "currency": "USD",             // will be flagged: BR expects BRL
    "notificationUrl": "http://example.com/wh", // will be flagged: must be HTTPS
    "customer": {
      "firstName": "Ana",
      "lastName": "Santos",
      "email": "ana@example.com",
      "personalId": "12345678900"  // will be flagged: invalid CPF checksum
    }
  }
}
```

The response lists every issue with a `code`, `severity`, `path`, `message`, and often a `hint` and `suggestion` — the LLM can fix the payload before wasting a network round-trip.

---

## Development

```bash
git clone https://github.com/payretailers-dev/payretailers-mcp.git
cd payretailers-mcp
npm install
npm run build          # generates dist/index.js
npm test               # 93 unit tests
node scripts/smoke-test.mjs   # end-to-end stdio handshake + tool calls
npm start              # optional: run the server manually on stdio
```

`data/` (Guides, Skills, Reference, Recipes, concept docs, curated JSON) is checked into the repository. Run `npm run sync:docs` **only** if you have `../payretailers-ai-docs` checked out and want to refresh the mirror.

The server can be inspected with the official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

---

## Releasing (maintainers)

Releases are automated via GitHub Actions on tag push (`v*.*.*`). The workflow:

1. Runs lint, typecheck, unit tests, build, and smoke test.
2. Runs `npm run pack:release` to produce `release/payretailers-mcp-vX.Y.Z.zip` (bundled `dist/index.js` + `data/` mirror + README + LICENSE + CHANGELOG + smoke test).
3. Creates a GitHub Release and attaches the zip.
4. Publishes to npm as `@payretailers/mcp` **only if the `NPM_TOKEN` repository secret is configured** — otherwise the release is GitHub-only.

To cut a release locally, then push the tag:

```bash
# 1. Bump version in package.json, config.ts, CHANGELOG.md
# 2. Verify locally
npm run clean && npm ci && npm test && npm run build
node scripts/smoke-test.mjs
npm run pack:release        # writes release/payretailers-mcp-vX.Y.Z.zip

# 3. Commit + tag + push
git add -A
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z      # this triggers .github/workflows/release.yml
```

Semver is enforced strictly: patch releases fix bugs, minor releases add tools/prompts/resources without breaking existing ones, major releases only for renames/removals.

---

## Roadmap

- **0.1** ✅ Resources (Guides, Skills), `search_docs`, `integrate-pix-payin` prompt.
- **0.2** ✅ Resources (Reference, Recipes), `get_country_rules`, `get_test_data`, `get_endpoint_spec`, prompts `integrate-payout-fx`, `build-checkout`, `debug-401-auth`, `reconcile-with-graphql`.
- **0.3** ✅ `validate_payload` with real checksum validation for CPF, CNPJ, RUT, DNI, RUC, CC, NIT, CURP, RFC, CLABE + cross-cutting rules (minor units, currency/country, HTTPS webhooks, method/country, idempotency).
- **0.4** ✅ Concept docs resource category, `get_webhook_playbook`, `validate_webhook_handler`, expanded `validate_payload` for subscription operations, prompts `implement-webhook-handler`, `integrate-subscriptions`.
- **0.4.1** ✅ Subscriptions schema alignment (AmountModel, frequency enum, authorizationType) — [CHANGELOG.md](CHANGELOG.md#041).
- **0.5** — `simulate_transaction` (dry-run against sandbox), `get_error_code`, expanded country coverage.
- **1.0** — Stable public release + listing in the [official MCP Registry](https://modelcontextprotocol.io/servers) + npm publish.

See [CHANGELOG.md](CHANGELOG.md) for details.

---

## Related

- **Step-by-step setup guides** for Cursor, Claude Code, Claude Desktop and VS Code + Copilot: [`docs/setup/`](docs/setup/README.md).
- **Companion documentation repository**: [payretailers-dev/payretailers-ai-docs](https://github.com/payretailers-dev/payretailers-ai-docs) — the source of Guides, Skills, and the docs mirror.
- **Official documentation**: [www.payretailers.dev](https://www.payretailers.dev).
- **Develop with LLMs guide**: [www.payretailers.dev/docs/develop-with-llms](https://www.payretailers.dev/docs/develop-with-llms).
- **Model Context Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io).

---

## License

Source code: **MIT**. See [LICENSE](LICENSE).

Documentation content bundled in `data/` (Guides, Skills, Reference, Recipes) is licensed under **CC BY-ND 4.0**, inherited from the [payretailers-ai-docs](https://github.com/payretailers-dev/payretailers-ai-docs) repository. The curated data files (`data/country-rules.json`, `data/test-data.json`) are also released under CC BY-ND 4.0.

---

## Contributing

Bug reports and feature requests are welcome via [GitHub Issues](https://github.com/payretailers-dev/payretailers-mcp/issues). Pull requests from the community are reviewed but merged at the discretion of the PayRetailers team — see [CONTRIBUTING.md](CONTRIBUTING.md) when available.