Metadata-Version: 2.3
Name: spherepay-mcp
Version: 0.0.1
Summary: SpherePay MCP server - curated Model Context Protocol tools for the SpherePay API
Keywords: mcp,modelcontextprotocol,spherepay,payments,fintech,financial data
Author: Dobri Danchev
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Dist: fastmcp>=2.8.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Python: >=3.12
Project-URL: Source, https://github.com/danchev/spherepay-mcp
Project-URL: Issues, https://github.com/danchev/spherepay-mcp/issues
Description-Content-Type: text/markdown

# SpherePay MCP Server

A curated [Model Context Protocol](https://modelcontextprotocol.io/) server for the [SpherePay](https://spherepay.co) payment platform. Exposes 13 tools (5 workflow + 8 read-only) for managing customers, bank accounts, wallets, and transfers directly from AI assistants like Claude.

Built with a hexagonal architecture that separates domain logic, application workflows, and API transport for testability and reliability.

## Features

- **Workflow tools** for multi-step operations (customer onboarding, verification, funding setup, transfers, business rep onboarding)
- **Read-only tools** for instant lookups (get/list customers, transfers, bank accounts, wallets)
- **Reliability** built in: automatic retries with exponential backoff, rate limit handling, idempotency keys for transfers
- **Security-first**: PII redaction in logs, production environment guardrail, no destructive operations exposed
- **Desktop Extension** packaging (.mcpb) for Claude Desktop

## Architecture

```
src/spherepay_mcp/
  domain/             # Value objects, enums, validation
    value_objects.py  # Currency, Network, CustomerId, Amount, ApiError
  application/        # Workflow orchestration services
    customer_onboarding.py
    funding_instrument.py
    transfer_workflow.py
    business_rep.py
  ports/              # Protocol interfaces (outbound)
    spherepay_gateway.py
  adapters/           # HTTP client, reliability policy
    spherepay_client.py
    reliability.py
  interfaces/         # MCP tool registration, route config
    tools.py
    route_config.py
  server.py           # Composition root
  config.py           # Environment configuration
```

```
LLM Client --> Tool Layer --> Service Layer --> Gateway Protocol --> HTTP Adapter --> SpherePay API
                                                     ^
                                                     |
                                              ReliabilityPolicy
                                           (retry, backoff, idempotency)
```

## Tools

### Workflow Tools (multi-step operations)

| Tool | Description |
|------|-------------|
| `onboard_customer` | Create customer + generate TOS/KYC verification links |
| `verify_customer` | OTP verification + face verification + submit |
| `setup_funding` | Create bank account or crypto wallet for a customer |
| `execute_transfer` | Transfer money with automatic idempotency |
| `onboard_business_rep` | Create and verify a business representative |

### Read-Only Tools (instant lookups)

| Tool | Description |
|------|-------------|
| `get_customer` / `list_customers` | Retrieve customer details |
| `get_transfer` / `list_transfers` | Retrieve transfer details with filters |
| `get_bank_account` / `list_bank_accounts` | Retrieve bank account details |
| `get_wallet` / `list_wallets` | Retrieve wallet details |

## Quickstart

### Prerequisites

- Python 3.12+
- A SpherePay API key ([get one here](https://dashboard.spherepay.co))

### Install

```bash
# Clone and install
git clone https://github.com/danchev/spherepay-mcp.git
cd spherepay-mcp
uv sync
```

### Configure

```bash
# Required
export SPHEREPAY_API_KEY="your_api_key_here"

# Optional (defaults shown)
export SPHEREPAY_BASE_URL="https://api.sandbox.spherepay.co"
export SPHEREPAY_TIMEOUT="30"
export SPHEREPAY_MAX_RETRIES="3"

# Required for production use
export SPHEREPAY_CONFIRM_PRODUCTION="true"
```

### Run

```bash
# As MCP server (stdio transport)
uv run spherepay-mcp

# Or directly
uv run python -m spherepay_mcp
```

### Claude Desktop Configuration

Add to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "spherepay": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/spherepay-mcp", "spherepay-mcp"],
      "env": {
        "SPHEREPAY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or install the Desktop Extension (`.mcpb`) for a GUI-based setup:

```bash
python scripts/build_mcpb.py --output dist/
# Double-click the .mcpb file to install in Claude Desktop
```

## Development

```bash
# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

# Lint
uv run ruff check src/ tests/
uv run pyright src/
```

## Supported Currencies and Networks

| Currency | Type |
|----------|------|
| `usd`, `eur` | Fiat |
| `usdc`, `usdt`, `eurc` | Crypto |

| Network | Type |
|---------|------|
| `ach`, `wire`, `sepa` | Fiat |
| `ethereum`, `polygon`, `sol`, `base`, `arbitrum`, `tron`, `avalanche`, `optimism` | Crypto |

## ADR Index

Architectural decisions are documented in [docs/adr/](docs/adr/):

| ADR | Title | Status |
|-----|-------|--------|
| [0001](docs/adr/0001-curated-openapi-not-full-mirror.md) | Curated OpenAPI (not full mirror) | Accepted |
| [0002](docs/adr/0002-hexagonal-workflow-centric-server.md) | Hexagonal workflow-centric architecture | Accepted |
| [0003](docs/adr/0003-safe-exposure-via-route-maps-transforms-visibility.md) | Safe exposure via route maps and visibility | Accepted |
| [0004](docs/adr/0004-reliability-policy-idempotency-rate-limits.md) | Reliability policy, idempotency, rate limits | Accepted |
| [0005](docs/adr/0005-workflow-tool-composition-over-atomic-endpoints.md) | Workflow tool composition over atomic endpoints | Accepted |
| [0006](docs/adr/0006-openapi-spec-management-and-drift-prevention.md) | OpenAPI spec management and drift prevention | Accepted |
| [0007](docs/adr/0007-desktop-extension-packaging-strategy.md) | Desktop extension packaging strategy | Accepted |
| [0008](docs/adr/0008-user-config-secrets-management-for-desktop-extension.md) | User config and secrets management | Accepted |
| [0009](docs/adr/0009-mcpb-bundle-structure-and-entry-point.md) | MCPB bundle structure and entry point | Accepted |
| [0010](docs/adr/0010-desktop-extension-spec-alignment.md) | Desktop extension spec alignment | Accepted |
| [0011](docs/adr/0011-critical-runtime-fixes.md) | Critical runtime fixes | Accepted |
| [0012](docs/adr/0012-security-hardening.md) | Security hardening | Accepted |
| [0013](docs/adr/0013-domain-validation-at-tool-boundary.md) | Domain validation at tool boundary | Proposed |
| [0014](docs/adr/0014-structured-logging-and-request-tracing.md) | Structured logging and request tracing | Proposed |
| [0015](docs/adr/0015-mcp-resources-for-discovery.md) | MCP resources for LLM discovery | Proposed |

## License

MIT

<!-- mcp-name: io.github.danchev/spherepay -->
