Metadata-Version: 2.4
Name: paybito-mcp
Version: 0.1.11
Summary: PayBito infrastructure knowledge helper for AI agents — injects PayBito API expertise (Resources + Prompts, no live actions) into any MCP-capable AI platform.
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# PayBito MCP — AI Integration Knowledge Helper

A **knowledge helper** that injects PayBito infrastructure expertise into any AI coding
agent, so a developer can implement PayBito integrations (websites, exchanges, payment
flows, trading apps) in natural language.

> It is **not** an action executor. It never calls PayBito's live API, never moves funds,
> never reads balances. It serves *documentation and code guidance* so the AI writes the
> correct integration code for you — the same way the `frontend-design` skill makes an AI
> produce great UIs without "running" anything.

Built from **all 6 of PayBito's published OpenAPI specs** (1,344 endpoints → **1,058
unique operations** across 28 domains and 6 hosts), normalized into one clean model.

## What it exposes

| Surface | Contents | For |
|---|---|---|
| **Resources** | `paybito://overview`, `paybito://modules`, `paybito://auth`, `paybito://domains`, `paybito://domain/{slug}`, `paybito://operation/{id}`, `paybito://playbook/{name}` | Clients that read MCP resources (Claude) |
| **Tools** (read-only) | `paybito_overview`, `paybito_modules`, `paybito_search` (accepts a `module` filter), `paybito_get_operation`, `paybito_get_domain`, `paybito_get_auth`, `paybito_list_playbooks`, `paybito_get_playbook` | Clients that only invoke tools (ChatGPT, Cursor, Gemini, …). These return **documentation only**. |
| **Prompts** | `integrate_paybito`, `add_payment_button`, `spot_trading_code` | Guided workflows |

### Product modules (so a prompt hits the right API)

**STEP 0 — the AI asks the developer one question first.** PayBito serves several audiences with
overlapping endpoints, so the most reliable router is the developer's own answer: *"What are you
building?"* —
- **(a)** an app for the **PayBito App Store / dev console** → PayBito host;
- **(b)** **crypto payments** into your own existing site/product (a **merchant**) → your own domain;
- **(c)** your **own branded white-label platform — exchange and/or payments** (a **broker**, e.g.
  `trade.coinstrendexchange.com` with `…/api-documentation/` + `…/payments/api-doc/`) → your own broker domain;
- **(d)** a **trading / market-data** integration only → your platform domain.

The answer sets both the module **and** the base-URL environment (your own domain vs a PayBito
host). The `build-your-*-app` "App Developer" tiles (Launch / Exchange / Payment platform) are
tagged on each operation via `app_platforms`.

**Payments also has a test/live sandbox** — so for any payments work the AI also asks *"test or
live?"*. Test mode only prepends `Test` to the service segment (`/PaymentsApiKeyService` →
`/TestPaymentsApiKeyService`, `/Payments-Apikey-V2` → `/TestPayments-Apikey-V2`); same params,
auth, and host. Exchange has no test mode. Each payments operation shows both its Live and Test path.

Every operation is also tagged with a **module**, and `paybito_search` takes a `module` filter to
keep results on the right surface:

| Module | Use when building… | Base URL | Auth |
|---|---|---|---|
| `exchange` | spot/futures/options trading, market data, copy-trading, ICO | 🏷️ broker's own domain | exchange-base64 |
| `payments` | merchant invoicing, billing, KYC, transactions, recurring, campaigns, reports | 🏷️ broker's own domain | payments-dual |
| `gateway` | storefront/checkout — products, catalogs, cart, hosted checkout, **payment link**/button | 🏷️ broker's own domain | payments-dual / payments-pk |
| `platform` | launch your own white-label exchange, or build apps across PayBito platforms | `institutional-bo.paybito.com:8443` | bearer |

A merchant/payments app is **`payments`**/**`gateway`**, never `exchange`. Call `paybito_modules`
first, then `paybito_search(query, module=…)`.

### 🏷️ White-label base URL

This MCP is used by each **broker's developers**, who run on their **own domain**. For the
**exchange**, **payments** and **gateway** modules the base URL is the broker's own platform
domain (e.g. `https://trade.coinstrendexchange.com` or `https://exchange.axada.co`) — the
**developer supplies it**, the AI only fills in the endpoint path. Generated code reads a
`BASE_URL` config/env var; it never hardcodes a PayBito host. Only the `platform` module (apps
built *on* PayBito infrastructure) targets a fixed PayBito host.

## Install

```bash
pip install -e .          # or: pipx install .   /   uvx --from . paybito-mcp
paybito-build             # generate build/model.json + build/corpus from specs/
```

`paybito-mcp` then runs the server over stdio.

## Inject it into your AI (one-time setup per tool)

There are two delivery modes. Use the **MCP server** for agentic/coding tools, and the
**portable bundle** for web chat UIs.

### Mode A — MCP server (agentic & coding tools)

The command is `paybito-mcp` (after `pip install`), or `npx -y paybito-mcp` once published
(see `typescript/`).

**Claude Code**
```bash
claude mcp add paybito -- paybito-mcp          # then: /mcp to verify it's connected
```

**Claude Desktop** — edit `claude_desktop_config.json`
(Windows: `%APPDATA%\Claude\`, macOS: `~/Library/Application Support/Claude/`):
```jsonc
{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }
```

**Cursor** — `.cursor/mcp.json` in your project (or global `~/.cursor/mcp.json`):
```jsonc
{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }
```

**VS Code (Copilot agent mode)** — `.vscode/mcp.json`:
```jsonc
{ "servers": { "paybito": { "type": "stdio", "command": "paybito-mcp" } } }
```

**OpenAI Codex CLI** — `~/.codex/config.toml`:
```toml
[mcp_servers.paybito]
command = "paybito-mcp"
```

**Gemini CLI** — `~/.gemini/settings.json`:
```jsonc
{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }
```

**Windsurf** — `~/.codeium/windsurf/mcp_config.json`:
```jsonc
{ "mcpServers": { "paybito": { "command": "paybito-mcp" } } }
```

**ChatGPT (Developer mode / connectors)** — host the server over HTTP and add it as a
custom connector. (Local stdio is for desktop tools; for ChatGPT web, prefer Mode B or a
hosted HTTP deployment.)

> If `paybito-mcp` isn't on your PATH, use the absolute path, or
> `{ "command": "python", "args": ["-m", "paybito_mcp.server"] }`.

### Mode B — Portable knowledge bundle (web chat UIs, no install)

Run `paybito-build`, then upload the generated **`build/corpus/`** folder as knowledge files:

- **ChatGPT** — Custom GPT → *Configure → Knowledge* (upload the files), or a Project's files.
- **Claude (web/Projects)** — create a Project → add the files to *Project knowledge*.
- **Gemini (Gems)** — create a Gem → add the files as knowledge.

Start the system/instruction with: *"Use the PayBito knowledge files to write integration
code; read `overview.md` and `auth.md` first."*

## Use cases — what to ask, and what the AI does

Once injected, the developer works in plain language. Examples:

| You ask… | The AI does (via this knowledge) |
|---|---|
| *"Add a PayBito crypto payment button to my WooCommerce checkout."* | Reads the `woocommerce` + `payment-button` playbooks, pulls `GetMerchant_settings` / `payNowCheckout` / `get_invoice_status_paid_amount` fields, and writes a PHP gateway plugin with correct `X-MBX-APIKEY` auth and settlement polling. |
| *"Build a Node endpoint to place a spot limit buy and check the order."* | Reads `spot-trading`, gets `tradeCreateOffer`, `getUserBalance`, `assetpairPrecision`, and writes server-side code with precision + error handling and a ⚠️ confirmation step. |
| *"Generate a Python client for PayBito withdrawals."* | Finds `createWithdrawalOrder` / `validateAddress` / `getFees`, flags them as state-changing, and writes a client that validates the address and confirms before sending. |
| *"How do I launch my own branded exchange on PayBito?"* | Reads `build-your-platform`, surveys the Broker/Exchange/Access-Control domains, and outlines the onboarding + OAuth + configuration calls with the correct `institutional-bo` host. |
| *"What does the response of `getUserBalance` look like?"* | Calls `paybito_get_operation` and returns the documented fields + a ready request example. |

The AI **writes the code**; you run it. The server never executes a PayBito call itself.

### Quick prompts (MCP prompts)

In MCP-aware clients you can also invoke the bundled prompts directly:
`integrate_paybito`, `add_payment_button`, `use_playbook`, `spot_trading_code`.

## Rebuild when PayBito updates their specs

The specs in `specs/` were downloaded from the Redoc `spec-url` endpoints under
`https://service.hashcashconsultants.com/Api/…`. Re-download them and run `paybito-build`.

## Architecture

```
specs/*.yaml ──► normalize.py ──► build/model.json ──► corpus.py ──► resources/tools/prompts
  (6 OpenAPI)     (Phase 0:          (1,058 unique     (Phase 1:        (server.py)
                   repair quirks,     operations,       layered
                   merge, dedup)      provenance)       markdown)
```

**Spec quirks the normalizer repairs:** empty `servers.url`; hostnames + query strings
baked into path keys; missing `securitySchemes` (auth is prose-only); 6 mixed hosts incl.
WebSocket pseudo-endpoints; heavy overlap across the 6 files.

## Auth model (for generated code)

⚠️ PayBito uses **three different auth schemes by product** — the server resolves the right
one **per operation** (see each operation's Authentication section, or `paybito://auth`):

- **Exchange / Trading** (`accounts.paybito.com`) — one header `X-MBX-APIKEY: base64(API_KEY:SECRET)`.
- **Payments Platform** — **two** verbatim headers `X-MBX-APIKEY: <key>` + `X-MBX-SECRETKEY: <secret>`
  (not base64), plus `Origin` + IP whitelisting on private endpoints.
- **Cart / Checkout V2** — `X-MBX-PUBLIC-KEY` + `CLIENT-SECRET-KEY` (call `createClientSecretKey`
  first to get the per-domain `secretHash`; see the `cart-v2-pk-domain` playbook).
- **Build-your-exchange / launch** — `Authorization: Bearer <JWT>` from the login endpoint.

Permissions: READ / DEPOSIT / WITHDRAW / TRADE. Rate limit 5 req/s per IP.
