# Yugo MCP Server

An MCP (Model Context Protocol) server for the [Yugo Payments API](https://docs.yugo.finance). Auto-generates tools from the OpenAPI spec — new API endpoints are supported with zero code changes.

## Features

- **OpenAPI-driven** — Tools are auto-generated from the Yugo OpenAPI spec
- **Future-proof** — New endpoints auto-register when the spec is updated
- **Dual transport** — stdio (local) and SSE (remote) support
- **MCP Resources** — Exposes the OpenAPI spec and payment rails reference data
- **Idempotency** — Auto-generates idempotency keys for POST requests
- **Error handling** — Parses RFC 9457 problem details into readable messages

## Quick Start

### 1. Install dependencies

```bash
npm install
```

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env and set your YUGO_API_KEY
```

### 3. Build & run

```bash
npm run build
npm start
```

Or for development:

```bash
npm run dev
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `YUGO_API_KEY` | Yes | — | Your Yugo API key (contact support@yugo.finance) |
| `YUGO_BASE_URL` | No | `https://sandbox-api.yugo.finance/api/v2` | API base URL. Set to `https://api.yugo.finance/api/v2` for production |
| `TRANSPORT` | No | `stdio` | Transport type: `stdio` or `sse` |
| `PORT` | No | `3000` | HTTP port (only used with SSE transport) |

## Available Tools

Auto-generated from the OpenAPI spec. Currently includes:

| Tool | Description |
|------|-------------|
| `create_payin` | Create a new payin — accept funds from a payer |
| `get_payin_by_id` | Get payin details by ID |
| `get_payins` | List payins (paginated, filterable by reference) |
| `create_payout` | Create a new payout — send funds to a recipient |
| `get_payout_by_id` | Get payout details by ID |
| `get_payouts` | List payouts (paginated, filterable by reference) |
| `get_banks` | List available banks for open banking |
| `get_accounts` | List merchant accounts and balances |

## MCP Resources

| URI | Description |
|-----|-------------|
| `yugo://spec` | Full OpenAPI 3.1 specification |
| `yugo://rails` | Supported payment methods, settlement methods, and currencies |

## Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "yugo": {
      "command": "node",
      "args": ["/path/to/yugo-mcp-server/dist/index.js"],
      "env": {
        "YUGO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Usage with Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "yugo": {
      "command": "node",
      "args": ["/path/to/yugo-mcp-server/dist/index.js"],
      "env": {
        "YUGO_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Usage with SSE (Remote)

```bash
TRANSPORT=sse PORT=3000 YUGO_API_KEY=your_key node dist/index.js
```

Connect your MCP client to `http://localhost:3000/sse`.

## Updating the OpenAPI Spec

To pick up new API endpoints:

```bash
curl -sL https://docs.yugo.finance/openapi/payments.yaml -o openapi/payments.yaml
npm run build
```

Restart the server and new tools will be available automatically.

## Architecture

This server is the **MCP Server** interface layer in the [Yugo System Architecture](https://docs.yugo.finance). It runs as a separate process that calls the Yugo REST API.

```
AI Agent → MCP Server → Yugo REST API → Payment Core → Settlement Rails
```

## License

MIT