# SIBS Payment MCP

> A Model Context Protocol (MCP) server that exposes the SIBS payment gateway as tools for AI agents — enabling LLMs to create checkouts, verify payments, issue refunds, and generate Multibanco references natively in any MCP-compatible environment.

![MCP](https://img.shields.io/badge/MCP-Model_Context_Protocol-purple)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
![SIBS](https://img.shields.io/badge/SIBS-Payment_Gateway-orange)
![License](https://img.shields.io/badge/license-MIT-lightgrey)

---

## What It Does

Bridges the SIBS payment gateway to the MCP ecosystem. Any AI agent or LLM-powered tool running in an MCP-compatible host (Claude Desktop, n8n, custom agents) can:

- **Check payment status** in real time
- **Create checkout sessions** with configurable payment methods
- **Capture, refund, or cancel** authorised payments
- **Generate Multibanco references** for ATM/homebanking payment
- **Initiate MB WAY** push notifications to a customer's phone

---

## Architecture

```mermaid
flowchart LR
    A[AI Agent\nClaude / n8n] -->|MCP tool call| B[sibs-payment-mcp\nMCP Server]
    B -->|REST API| C[SIBS Gateway\nAPI]
    C -->|response| B
    B -->|structured result| A

    subgraph Tools
        T1[sibs_create_checkout]
        T2[sibs_payment_status]
        T3[sibs_capture_payment]
        T4[sibs_refund_payment]
        T5[sibs_cancel_payment]
        T6[sibs_generate_mb_reference]
        T7[sibs_mbway_payment]
        T8[sibs_test]
    end
```

---

## Tools (8 total)

| Tool | Description |
|------|-------------|
| `sibs_create_checkout` | Create a new checkout. Returns `transactionID` and hosted checkout URL |
| `sibs_payment_status` | Get payment state, amount, method, and timestamps by transaction ID |
| `sibs_capture_payment` | Capture an authorised payment — full or partial |
| `sibs_refund_payment` | Refund a captured payment — full or partial |
| `sibs_cancel_payment` | Cancel an authorised payment before capture |
| `sibs_generate_mb_reference` | Generate a Multibanco entity/reference for ATM payment |
| `sibs_mbway_payment` | Send MB WAY push to customer phone (`351#912345678` format) |
| `sibs_test` | Validate credentials and connectivity |

---

## Stack

| Component | Tool |
|-----------|------|
| Protocol | [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) |
| Language | TypeScript 5 + Node.js |
| Schema validation | [Zod](https://zod.dev) |
| Payment gateway | SIBS API (Portugal) |
| Build | `tsc` → `dist/` |

---

## Setup

### Prerequisites
- Node.js 18+
- SIBS merchant account with API credentials
- MCP-compatible host (Claude Desktop, n8n, custom agent)

### 1. Install

```bash
git clone https://github.com/RobsonAdvincula/sibs-payment-mcp.git
cd sibs-payment-mcp
npm install
npm run build
```

### 2. Configure environment

```env
SIBS_BASE_URL=https://stargate.sibs.pt/m001/v1
SIBS_BEARER_TOKEN=your_bearer_token
SIBS_CLIENT_ID=your_client_id
SIBS_TERMINAL_ID=your_terminal_id
```

### 3. Add to MCP host

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "sibs-payment": {
      "command": "node",
      "args": ["/path/to/sibs-payment-mcp/dist/index.js"],
      "env": {
        "SIBS_BEARER_TOKEN": "...",
        "SIBS_CLIENT_ID": "...",
        "SIBS_TERMINAL_ID": "..."
      }
    }
  }
}
```

**n8n MCP Client node**: point to the compiled `dist/index.js` with the same env vars.

---

## Example Interactions

**Create a payment and send MB WAY:**
```
Agent: "Create a €29.99 checkout for customer +351912345678"

→ sibs_create_checkout({ amount: 2999, currency: "EUR", paymentMethods: ["MBWAY"] })
→ sibs_mbway_payment({ transactionId: "txn_xxx", amount: 2999, customerPhone: "351#912345678" })

Result: "MB WAY notification sent. Customer has 4 minutes to confirm."
```

**Verify and refund:**
```
Agent: "Check transaction txn_abc and refund if paid"

→ sibs_payment_status({ transactionId: "txn_abc" })
  ← { status: "Success", amount: 4999 }
→ sibs_refund_payment({ transactionId: "txn_abc" })
  ← { refunded: true }
```

---

## Payment Methods Supported

- `CARD` — Visa / Mastercard
- `MBWAY` — MB WAY mobile payment
- `REFERENCE` — Multibanco ATM reference
- `COFIDIS` — Instalments
- `PAYPAL` — PayPal

---

## License

MIT — free to use, adapt, and build on.

---

*Built by [Robson Advincula](https://linkedin.com/in/robsonadvincula) — AI & Automation Consultant*