Metadata-Version: 2.4
Name: paybito-mcp
Version: 0.1.4
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://auth`, `paybito://domains`, `paybito://domain/{slug}`, `paybito://operation/{id}`, `paybito://playbook/{name}` | Clients that read MCP resources (Claude) |
| **Tools** (read-only) | `paybito_overview`, `paybito_search`, `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 |

## 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.
