# payport

payport gives an agent a working doorway into a Stripe account: open a
customer record, put a product and a price in the catalog, hand a buyer
a hosted payment link, draft an invoice and finalize it, check the
balance, refund a payment, issue a coupon, answer a dispute, and manage
subscriptions. Each operation is one call against the Stripe REST API,
and the API's JSON answer comes back as-is. It runs from the command
line or as an MCP server for agents.

A Stripe secret key is required. Put it in the `STRIPE_SECRET_KEY`
environment variable; the key is sent to the API as a Bearer token and
never appears in output. When the variable is missing, every operation
fails with an error that names it.

## Install

```bash
npx @reneturcios/payport list-customers --limit 5
```

Or run the container image:

```bash
docker run -i -e STRIPE_SECRET_KEY ghcr.io/cloudcorprecords/payport
```

The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.

## CLI

```bash
export STRIPE_SECRET_KEY="your secret key"

payport create-customer --name "Ada Lovelace" --email ada@example.com
payport list-customers --email ada@example.com --limit 5
payport create-product --name "Trail Guide" --description "A field guide"
payport list-products --limit 10
payport retrieve-balance

payport --version
```

Exit codes: `0` on success, `1` when an API call fails (including a
missing `STRIPE_SECRET_KEY`), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/payport mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "payport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/payport", "mcp"],
      "env": { "STRIPE_SECRET_KEY": "your secret key" }
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `create_customer` | `name` (string, required), `email` (string, optional) | Create a customer. |
| `list_customers` | `email` (string, optional), `limit` (integer, optional) | List customers, optionally filtered by exact email. |
| `create_product` | `name` (string, required), `description` (string, optional) | Create a catalog product. |
| `list_products` | `limit` (integer, optional) | List products. |
| `create_price` | `product`, `currency`, `unit_amount` (all required) | Create a price for a product; `unit_amount` is in the smallest currency unit. |
| `list_prices` | `product` (optional), `limit` (optional) | List prices, optionally for one product. |
| `create_payment_link` | `price`, `quantity` (required), `redirect_url` (optional) | Create a hosted payment link. |
| `list_payment_intents` | `customer` (optional), `limit` (optional) | List payment intents. |
| `create_invoice` | `customer` (required), `days_until_due` (optional) | Create a draft invoice sent by email (`send_invoice`). |
| `create_invoice_item` | `customer`, `price`, `invoice` (all required) | Add a priced line item to a draft invoice. |
| `list_invoices` | `customer` (optional), `limit` (optional) | List invoices. |
| `finalize_invoice` | `invoice` (required) | Finalize a draft invoice. |
| `retrieve_balance` | — | Retrieve the account balance. |
| `create_refund` | `payment_intent` (required), `amount` (optional) | Refund a payment intent, in full or in part. |
| `create_coupon` | `duration` (required), `percent_off`, `amount_off`, `currency`, `name`, `duration_in_months` (optional) | Create a coupon. |
| `list_coupons` | `limit` (optional) | List coupons. |
| `list_disputes` | `charge`, `payment_intent`, `limit` (all optional) | List disputes. |
| `update_dispute` | `dispute` (required), `evidence` (object, optional), `submit` (boolean, optional) | Add evidence to a dispute and optionally submit it. |
| `list_subscriptions` | `customer`, `status`, `limit` (all optional) | List subscriptions. |
| `cancel_subscription` | `subscription` (required) | Cancel a subscription. |
| `update_subscription` | `subscription` (required), `price`, `cancel_at_period_end` (optional) | Update a subscription. |

This is the documented core subset of the Stripe agent toolkit's
22-tool MCP set: `search_stripe_documentation` (a hosted documentation
search, not a Stripe API operation) is not implemented.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.