payping-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- payping_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +45 -0
- payping_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
- payping_mcp-0.1.0/.github/dependabot.yml +10 -0
- payping_mcp-0.1.0/.github/workflows/ci.yml +21 -0
- payping_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- payping_mcp-0.1.0/.gitignore +7 -0
- payping_mcp-0.1.0/CLAUDE.md +43 -0
- payping_mcp-0.1.0/LICENSE +21 -0
- payping_mcp-0.1.0/PKG-INFO +370 -0
- payping_mcp-0.1.0/README.md +345 -0
- payping_mcp-0.1.0/pyproject.toml +55 -0
- payping_mcp-0.1.0/server.json +38 -0
- payping_mcp-0.1.0/src/payping_mcp/__init__.py +5 -0
- payping_mcp-0.1.0/src/payping_mcp/http.py +128 -0
- payping_mcp-0.1.0/src/payping_mcp/registry.py +17 -0
- payping_mcp-0.1.0/src/payping_mcp/reports.py +123 -0
- payping_mcp-0.1.0/src/payping_mcp/server.py +43 -0
- payping_mcp-0.1.0/src/payping_mcp/shop.py +232 -0
- payping_mcp-0.1.0/tests/conftest.py +60 -0
- payping_mcp-0.1.0/tests/test_http.py +88 -0
- payping_mcp-0.1.0/tests/test_live.py +42 -0
- payping_mcp-0.1.0/tests/test_reports.py +104 -0
- payping_mcp-0.1.0/tests/test_server.py +56 -0
- payping_mcp-0.1.0/tests/test_shop.py +168 -0
- payping_mcp-0.1.0/uv.lock +1112 -0
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: A tool failed or returned wrong data
|
|
3
|
+
labels: [bug]
|
|
4
|
+
body:
|
|
5
|
+
- type: markdown
|
|
6
|
+
attributes:
|
|
7
|
+
value: Never paste your PayPing token. Remove customer names, phone numbers and anything else you don't want public.
|
|
8
|
+
- type: input
|
|
9
|
+
id: tool
|
|
10
|
+
attributes:
|
|
11
|
+
label: Tool
|
|
12
|
+
description: Which tool, e.g. payping_list_invoices
|
|
13
|
+
validations:
|
|
14
|
+
required: true
|
|
15
|
+
- type: textarea
|
|
16
|
+
id: input
|
|
17
|
+
attributes:
|
|
18
|
+
label: Arguments and result
|
|
19
|
+
description: The arguments the agent sent and the error or wrong output. Keep the PayPing trace id if there is one.
|
|
20
|
+
render: json
|
|
21
|
+
validations:
|
|
22
|
+
required: true
|
|
23
|
+
- type: textarea
|
|
24
|
+
id: expected
|
|
25
|
+
attributes:
|
|
26
|
+
label: What you expected
|
|
27
|
+
description: e.g. what the PayPing panel shows for the same invoice
|
|
28
|
+
- type: input
|
|
29
|
+
id: client
|
|
30
|
+
attributes:
|
|
31
|
+
label: MCP client and OS
|
|
32
|
+
placeholder: Claude Desktop 1.x on Windows 11
|
|
33
|
+
- type: dropdown
|
|
34
|
+
id: network
|
|
35
|
+
attributes:
|
|
36
|
+
label: Network
|
|
37
|
+
options:
|
|
38
|
+
- Direct, no VPN
|
|
39
|
+
- VPN or proxy
|
|
40
|
+
- PAYPING_MCP_PROXY set
|
|
41
|
+
- type: input
|
|
42
|
+
id: version
|
|
43
|
+
attributes:
|
|
44
|
+
label: payping-mcp version
|
|
45
|
+
placeholder: "0.1.0"
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.11", "3.12", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v7
|
|
16
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
|
|
4
|
+
# pyproject.toml and server.json.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
tags: ["v*"]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
pypi:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment: pypi
|
|
13
|
+
permissions:
|
|
14
|
+
id-token: write # PyPI trusted publishing
|
|
15
|
+
contents: write # GitHub Release
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v7
|
|
18
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
19
|
+
- name: Check versions match the tag
|
|
20
|
+
run: |
|
|
21
|
+
TAG=${GITHUB_REF_NAME#v}
|
|
22
|
+
grep -q "^version = \"$TAG\"" pyproject.toml
|
|
23
|
+
test "$(jq -r .version server.json)" = "$TAG"
|
|
24
|
+
test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
|
|
25
|
+
- run: uv sync --locked && uv run pytest -q
|
|
26
|
+
- run: uv build
|
|
27
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
28
|
+
- run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
|
|
29
|
+
env:
|
|
30
|
+
GH_TOKEN: ${{ github.token }}
|
|
31
|
+
|
|
32
|
+
mcp-registry:
|
|
33
|
+
needs: pypi
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
permissions:
|
|
36
|
+
id-token: write # MCP Registry login via GitHub OIDC
|
|
37
|
+
contents: read
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v7
|
|
40
|
+
- name: Wait for PyPI to serve the new version
|
|
41
|
+
run: |
|
|
42
|
+
for i in $(seq 1 30); do
|
|
43
|
+
curl -sf "https://pypi.org/pypi/payping-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
|
|
44
|
+
sleep 10
|
|
45
|
+
done
|
|
46
|
+
exit 1
|
|
47
|
+
- name: Install mcp-publisher
|
|
48
|
+
run: |
|
|
49
|
+
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
|
|
50
|
+
- run: ./mcp-publisher login github-oidc
|
|
51
|
+
- run: ./mcp-publisher publish
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# payping-mcp
|
|
2
|
+
|
|
3
|
+
Local MCP server for PayPing (payping.ir) merchant accounts. Published: GitHub `sepehr071/payping-mcp`, PyPI
|
|
4
|
+
`payping-mcp`, MCP Registry `io.github.sepehr071/payping-mcp` (release on a `v*` tag; bump `pyproject.toml` and
|
|
5
|
+
`server.json`). Sibling of `../bale-mcp`; keep layout and
|
|
6
|
+
idioms in step. The API map it is built on lives in `../payping/` (official spec, dashboard catalog, captured shapes).
|
|
7
|
+
|
|
8
|
+
Scope (owner's decision 2026-10-03): read + create. No raw `/v3/pay`, verify, reverse, withdraw, refund, update or
|
|
9
|
+
delete tools; do not add them without the owner asking.
|
|
10
|
+
|
|
11
|
+
## Layout
|
|
12
|
+
|
|
13
|
+
- `src/payping_mcp/http.py`: the only HTTP code. Shared `httpx.AsyncClient` (`trust_env=False`, proxy only from
|
|
14
|
+
`PAYPING_MCP_PROXY`), `call(method, path, params=, json=, host=)`, `ApiError(ToolError)` with `redact()` of the
|
|
15
|
+
token, error text from problem JSON (`detail`, `errorCode` / `metaData.code`, `paypingTraceId`).
|
|
16
|
+
- `reports.py`: profile (oauth host), balance, sales summary, transactions, payment, withdrawals. Shared `Offset`,
|
|
17
|
+
`Limit` (1-50), `Code`, `segment()`.
|
|
18
|
+
- `shop.py`: customers, products, coupons, invoices (list/get), create tools (`sends=True`), send invoice.
|
|
19
|
+
- `registry.py` + `server.py`: `@tool("Title", sends=...)`, annotations, `INSTRUCTIONS`. 21 tools, all `payping_*`.
|
|
20
|
+
- `tests/`: offline (`conftest.py` MockTransport keyed `"METHOD /path"`), `test_live.py` (`-m live`, read-only).
|
|
21
|
+
|
|
22
|
+
## Commands
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
uv sync
|
|
26
|
+
uv run ruff check . && uv run ruff format --check .
|
|
27
|
+
uv run pytest -q
|
|
28
|
+
set -a; . ../.env; set +a; uv run pytest -m live # PAYPING_TOKEN in ../.env
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Rules for changes
|
|
32
|
+
|
|
33
|
+
- Never put the token in output, errors or logs.
|
|
34
|
+
- Create/send tools: `sends=True`, docstring tells the agent to confirm with the user.
|
|
35
|
+
- Keep `README.md` tool tables equal to `list_tools()` (`test_readme_lists_every_tool`). Deps stay `mcp` + `httpx`.
|
|
36
|
+
- Persian ZWNJ and Arabic yeh/kaf in code: escapes, never literals.
|
|
37
|
+
|
|
38
|
+
## Unverified (check on first live run)
|
|
39
|
+
|
|
40
|
+
- Whether a panel API token is accepted by `/v1/report/Balance` and `/v1/report/DashboardSummery` (dashboard-only).
|
|
41
|
+
- Coupon/discount `type`: Percent=0, Toman=1, from the dashboard bundle enum.
|
|
42
|
+
- Pay page links `https://ppng.ir/d/{product code}` and `https://ppng.ir/v/{invoice code}`, from the dashboard bundle.
|
|
43
|
+
- `/v1/coupon/ListCount` and `/v1/product/ListCount` response shape (`{"count": n}` seen on the dashboard).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sepehr
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: payping-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Local MCP server for PayPing (payping.ir) merchants: let AI agents read balance, sales, transactions, withdrawals, customers, products, coupons and invoices, and create customers, products, payment links, coupons and invoices.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/payping-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/sepehr071/payping-mcp/issues
|
|
7
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: ai-agent,invoice,iran,mcp,model-context-protocol,payment-gateway,payping
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Requires-Dist: httpx>=0.27
|
|
23
|
+
Requires-Dist: mcp<3,>=2.2
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
<!-- mcp-name: io.github.sepehr071/payping-mcp -->
|
|
27
|
+
|
|
28
|
+
<div align="center">
|
|
29
|
+
|
|
30
|
+
# 💳 payping-mcp
|
|
31
|
+
|
|
32
|
+
**Your PayPing merchant account, for AI agents.**<br>
|
|
33
|
+
Let Claude, Cursor or Copilot read your balance, sales, transactions, customers, products, coupons and invoices,<br>
|
|
34
|
+
and create invoices, payment links and coupons after you confirm, all from your own machine.
|
|
35
|
+
|
|
36
|
+
[](https://pypi.org/project/payping-mcp/)
|
|
37
|
+
[](https://pypi.org/project/payping-mcp/)
|
|
38
|
+
[](https://github.com/sepehr071/payping-mcp/actions/workflows/ci.yml)
|
|
39
|
+
[](https://registry.modelcontextprotocol.io/v0/servers?search=payping-mcp)
|
|
40
|
+
[](https://github.com/sepehr071/payping-mcp/blob/main/LICENSE)
|
|
41
|
+
|
|
42
|
+
[](https://cursor.com/en/install-mcp?name=payping&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJwYXlwaW5nLW1jcCJdLCJlbnYiOnsiUEFZUElOR19UT0tFTiI6InlvdXItdG9rZW4ifX0=)
|
|
43
|
+
[](https://vscode.dev/redirect/mcp/install?name=payping&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22payping-mcp%22%5D%2C%22env%22%3A%7B%22PAYPING_TOKEN%22%3A%22your-token%22%7D%7D)
|
|
44
|
+
|
|
45
|
+
[Quick start](#quick-start) · [Token](#1-create-a-payping-token) · [Tools](#tools) · [Security](#privacy-and-security) · [Troubleshooting](#troubleshooting) · [فارسی](#فارسی)
|
|
46
|
+
|
|
47
|
+
</div>
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## What it can do
|
|
52
|
+
|
|
53
|
+
- 💰 **Money:** wallet balance, sales totals for a period, transactions, one payment's real status, settlements to your bank
|
|
54
|
+
- 🗂️ **Shop data:** list and search customers, products, coupons and invoices
|
|
55
|
+
- 🧾 **Get paid:** create a customer and an invoice with a pay page link, or a reusable payment link for a product, then have PayPing send the invoice by SMS/email
|
|
56
|
+
- 🔒 **Safe by design:** runs on your machine, talks only to PayPing, asks before creating anything, and cannot withdraw, refund, reverse a payment or delete anything
|
|
57
|
+
|
|
58
|
+
## Quick start
|
|
59
|
+
|
|
60
|
+
You need:
|
|
61
|
+
|
|
62
|
+
- a PayPing merchant account with a **complete profile** (PayPing only approves tokens for complete profiles)
|
|
63
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
|
|
64
|
+
- an MCP client: Claude Code, Claude Desktop, Cursor, VS Code, or any other
|
|
65
|
+
|
|
66
|
+
Then:
|
|
67
|
+
|
|
68
|
+
1. [Create a PayPing token](#1-create-a-payping-token) and wait for PayPing to approve it.
|
|
69
|
+
2. [Add the server](#2-add-the-server-to-your-mcp-client) to your MCP client.
|
|
70
|
+
3. [Check that it works](#3-check-that-it-works).
|
|
71
|
+
|
|
72
|
+
### 1. Create a PayPing token
|
|
73
|
+
|
|
74
|
+
1. Sign in at [app.payping.ir](https://app.payping.ir).
|
|
75
|
+
2. Open **اتصالات** (Connections) → **توسعه دهندگان** (Developers). The page title is **توکن ها** (Tokens).
|
|
76
|
+
3. Click **توکن جدید** (New token) and fill in the form:
|
|
77
|
+
|
|
78
|
+
| Field | What to enter |
|
|
79
|
+
|---|---|
|
|
80
|
+
| توکن تست (test token) | Leave off to work with your real account. |
|
|
81
|
+
| نام توکن (token name) | Any name, e.g. `payping-mcp on my laptop` |
|
|
82
|
+
| آی‌پی‌های مجاز (allowed IPs) | Optional. If you fill it in, list the public IP your computer reaches PayPing from. Calls from any other IP fail with error code 166. |
|
|
83
|
+
| تاریخ انقضا (expiry date) | When the token stops working. Shorter is safer. |
|
|
84
|
+
| دسترسی‌ها (scopes) | See the table below. |
|
|
85
|
+
| توضیحات (description) | e.g. `MCP server for AI agents` |
|
|
86
|
+
| رمز پیامکی (SMS code) | Click **ارسال رمز** (send code) and type the code PayPing sends to your phone. |
|
|
87
|
+
|
|
88
|
+
4. Click **توکن جدید** to submit. **Copy the token now: PayPing shows it only once.**
|
|
89
|
+
5. Wait for approval. PayPing staff review every new token. After approval, wait about 10 more minutes; until then the token gets HTTP 401.
|
|
90
|
+
|
|
91
|
+
**Scopes.** The form preselects **گزارش پرداخت‌ها** and **ساخت پرداخت**. Remove **ساخت پرداخت**: this server never uses it. Then add what you need:
|
|
92
|
+
|
|
93
|
+
| Panel label | Scope | Tools that need it |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| گزارش پرداخت‌ها | `pay:read` | transactions, payment detail, withdrawals |
|
|
96
|
+
| مشاهده و گزارش از مشتریان | `customer:read` | list and get customers |
|
|
97
|
+
| ساخت و ویرایش مشتریان | `customer:write` | create customer |
|
|
98
|
+
| مشاهده و گزارش از محصولات | `product:read` | list and get products |
|
|
99
|
+
| ساخت و ویرایش محصولات | `product:write` | create product, create payment link |
|
|
100
|
+
| مشاهده و گزارش کدهای تخفیف | `coupon:read` | list and get coupons |
|
|
101
|
+
| ساخت و ویرایش کدهای تخفیف | `coupon:write` | create coupon |
|
|
102
|
+
| مشاهده و گزارش از فاکتورها | `invoice:read` | list and get invoices |
|
|
103
|
+
| ساخت و ویرایش فاکتور | `invoice:write` | create and send invoices |
|
|
104
|
+
| ساخت پرداخت | `pay:write` | none: leave it out |
|
|
105
|
+
|
|
106
|
+
Want a read-only agent? Select only the read scopes. The create tools then fail with HTTP 403 and nothing in the account can change.
|
|
107
|
+
|
|
108
|
+
### 2. Add the server to your MCP client
|
|
109
|
+
|
|
110
|
+
Put your token where it says `your-token`.
|
|
111
|
+
|
|
112
|
+
<details open>
|
|
113
|
+
<summary><b>Claude Code</b></summary>
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
This saves the server, with the token, in your user config (`~/.claude.json`), not in the project. Add `--scope user` to use it in every project.
|
|
120
|
+
</details>
|
|
121
|
+
|
|
122
|
+
<details>
|
|
123
|
+
<summary><b>Claude Desktop</b></summary>
|
|
124
|
+
|
|
125
|
+
Settings → Developer → Edit Config, then add:
|
|
126
|
+
|
|
127
|
+
```json
|
|
128
|
+
{
|
|
129
|
+
"mcpServers": {
|
|
130
|
+
"payping": {
|
|
131
|
+
"command": "uvx",
|
|
132
|
+
"args": ["payping-mcp"],
|
|
133
|
+
"env": { "PAYPING_TOKEN": "your-token" }
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Restart Claude Desktop after saving.
|
|
140
|
+
</details>
|
|
141
|
+
|
|
142
|
+
<details>
|
|
143
|
+
<summary><b>Cursor</b></summary>
|
|
144
|
+
|
|
145
|
+
Click **Install in Cursor** at the top and fill in the token, or add the Claude Desktop block to `~/.cursor/mcp.json`.
|
|
146
|
+
</details>
|
|
147
|
+
|
|
148
|
+
<details>
|
|
149
|
+
<summary><b>VS Code (Copilot agent mode)</b></summary>
|
|
150
|
+
|
|
151
|
+
Add to `.vscode/mcp.json`. VS Code asks for the token once and stores it securely, so the file is safe to commit:
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"inputs": [
|
|
156
|
+
{ "type": "promptString", "id": "payping-token", "description": "PayPing API token", "password": true }
|
|
157
|
+
],
|
|
158
|
+
"servers": {
|
|
159
|
+
"payping": {
|
|
160
|
+
"type": "stdio",
|
|
161
|
+
"command": "uvx",
|
|
162
|
+
"args": ["payping-mcp"],
|
|
163
|
+
"env": { "PAYPING_TOKEN": "${input:payping-token}" }
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
</details>
|
|
169
|
+
|
|
170
|
+
<details>
|
|
171
|
+
<summary><b>From GitHub instead of PyPI</b></summary>
|
|
172
|
+
|
|
173
|
+
Replace `uvx payping-mcp` with:
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
uvx --from git+https://github.com/sepehr071/payping-mcp payping-mcp
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
In JSON configs: `"args": ["--from", "git+https://github.com/sepehr071/payping-mcp", "payping-mcp"]`.
|
|
180
|
+
</details>
|
|
181
|
+
|
|
182
|
+
<details>
|
|
183
|
+
<summary><b>Anything else</b></summary>
|
|
184
|
+
|
|
185
|
+
It's a standard stdio MCP server: run `uvx payping-mcp`, or `pip install payping-mcp` and run `payping-mcp`, with
|
|
186
|
+
`PAYPING_TOKEN` in the environment.
|
|
187
|
+
</details>
|
|
188
|
+
|
|
189
|
+
### 3. Check that it works
|
|
190
|
+
|
|
191
|
+
Ask the agent: *"Show my PayPing profile."* You should see your PayPing username. If you see an error, look it up in
|
|
192
|
+
[Troubleshooting](#troubleshooting).
|
|
193
|
+
|
|
194
|
+
Then try:
|
|
195
|
+
|
|
196
|
+
- "What is my PayPing balance and how much did I sell this month?"
|
|
197
|
+
- "List this week's received payments and tell me which ones failed."
|
|
198
|
+
- "Create an invoice for Ali Rezaei: 2 hours of consulting at 1,500,000 Toman each. Show me before you create it."
|
|
199
|
+
- <span dir="rtl">فاکتورهای پرداخت‌نشده این ماه را نشان بده.</span>
|
|
200
|
+
|
|
201
|
+
## Tools
|
|
202
|
+
|
|
203
|
+
All amounts are Toman, all dates UTC. Lists return at most 50 items per call and include `total`.
|
|
204
|
+
|
|
205
|
+
Read-only:
|
|
206
|
+
|
|
207
|
+
| Tool | What it does |
|
|
208
|
+
|---|---|
|
|
209
|
+
| `payping_get_profile` | Account behind the token: username, name, contact, verification flags |
|
|
210
|
+
| `payping_get_balance` | Wallet balance |
|
|
211
|
+
| `payping_get_sales_summary` | Total sales, count and daily averages for a period (default last 30 days) |
|
|
212
|
+
| `payping_list_transactions` | Payments in a date range, received or paid |
|
|
213
|
+
| `payping_get_payment` | One payment by code, with its real status (paid and verified, cancelled, ...) |
|
|
214
|
+
| `payping_list_withdrawals` | Settlements to your bank account |
|
|
215
|
+
| `payping_get_withdrawal` | One settlement by code: IBAN, bank tracking number |
|
|
216
|
+
| `payping_list_customers` | Saved customers, searchable |
|
|
217
|
+
| `payping_get_customer` | One customer |
|
|
218
|
+
| `payping_list_products` | Products (financial items), searchable |
|
|
219
|
+
| `payping_get_product` | One product |
|
|
220
|
+
| `payping_list_coupons` | Discount coupons |
|
|
221
|
+
| `payping_get_coupon` | One coupon with buyer count and total |
|
|
222
|
+
| `payping_list_invoices` | Invoices, filter by status or customer |
|
|
223
|
+
| `payping_get_invoice` | One invoice with items and its pay page url |
|
|
224
|
+
|
|
225
|
+
Create and send (the agent must confirm with you first):
|
|
226
|
+
|
|
227
|
+
| Tool | What it does |
|
|
228
|
+
|---|---|
|
|
229
|
+
| `payping_create_customer` | Save a customer; returns its code |
|
|
230
|
+
| `payping_create_product` | Create a product with a fixed or payer-set price |
|
|
231
|
+
| `payping_create_payment_link` | Public pay page for a product: `https://ppng.ir/d/<product code>` |
|
|
232
|
+
| `payping_create_coupon` | Percent or Toman discount coupon |
|
|
233
|
+
| `payping_create_invoice` | Invoice for a saved customer; returns its pay page `https://ppng.ir/v/<invoice code>` |
|
|
234
|
+
| `payping_send_invoice` | PayPing sends the invoice to the customer by SMS/email |
|
|
235
|
+
|
|
236
|
+
## Privacy and security
|
|
237
|
+
|
|
238
|
+
- **Local only.** The server runs on your machine and talks only to `api.payping.ir` and `oauth.payping.ir`. There is no relay server and no telemetry.
|
|
239
|
+
- **The token never leaks.** It is sent only in the `Authorization` header to PayPing and never appears in tool output, errors or logs.
|
|
240
|
+
- **Treat the token like a password.** Anyone who has it can use your account within its scopes. Don't commit it; use VS Code `inputs` or your client's user config. Give it only the scopes you need and an expiry date.
|
|
241
|
+
- **Lost or leaked token?** In the panel, open the token and use **حذف** (delete) or **تعویض توکن** (swap token, which issues a new value). Then update your MCP config.
|
|
242
|
+
- **Confirm before creating.** Create and send tools are annotated `destructiveHint`, so MCP clients ask before running them. Their descriptions also tell the agent to confirm the details with you.
|
|
243
|
+
- **No money moves out.** No tool can withdraw, refund, reverse a payment or delete anything.
|
|
244
|
+
- **Prompt-injection aware.** Customer names, descriptions and notes come from other people. The server tells the agent to treat them as data, never as instructions.
|
|
245
|
+
|
|
246
|
+
## Good to know
|
|
247
|
+
|
|
248
|
+
- **Toman, not Rial.** PayPing uses Toman in every service, and so does every tool.
|
|
249
|
+
- **Balance and sales summary are less certain.** `payping_get_balance` and `payping_get_sales_summary` use endpoints from the PayPing dashboard, not the public API docs. If PayPing rejects them for API tokens, the tool error says so, and every other tool keeps working.
|
|
250
|
+
- **No raw payments.** Raw `POST /v3/pay` payments are left out on purpose. They need your own callback server and a verify call within 10 minutes, or PayPing refunds the payer. Invoices and payment links use PayPing's own pay page instead.
|
|
251
|
+
- **Changing scopes needs a swap.** After you edit a token's website, return URL or scopes, PayPing applies the change only after **تعویض توکن** (swap token). The swap gives a new token value; put it in your MCP config.
|
|
252
|
+
|
|
253
|
+
## Troubleshooting
|
|
254
|
+
|
|
255
|
+
<details>
|
|
256
|
+
<summary><b>"PAYPING_TOKEN is not set"</b></summary>
|
|
257
|
+
|
|
258
|
+
The MCP client did not pass the token. Check the `env` block (or `-e PAYPING_TOKEN=...` for Claude Code) and restart the client.
|
|
259
|
+
</details>
|
|
260
|
+
|
|
261
|
+
<details>
|
|
262
|
+
<summary><b>"PayPing rejected the token (HTTP 401)"</b></summary>
|
|
263
|
+
|
|
264
|
+
One of these:
|
|
265
|
+
|
|
266
|
+
- PayPing has not approved the token yet, or approved it less than 10 minutes ago.
|
|
267
|
+
- The token expired. The panel shows **منقضی شده** (expired) on it.
|
|
268
|
+
- The token was swapped or deleted, or was copied incompletely.
|
|
269
|
+
</details>
|
|
270
|
+
|
|
271
|
+
<details>
|
|
272
|
+
<summary><b>HTTP 403: "The token may lack the scope this tool needs"</b></summary>
|
|
273
|
+
|
|
274
|
+
Add the scope from the [scope table](#1-create-a-payping-token) to the token, then **تعویض توکن** (swap token) and use the new value.
|
|
275
|
+
</details>
|
|
276
|
+
|
|
277
|
+
<details>
|
|
278
|
+
<summary><b>"code 166"</b></summary>
|
|
279
|
+
|
|
280
|
+
Your IP is not in the token's allowed IPs. Add your current public IP to **آی‌پی‌های مجاز** or clear the list. If you route through a proxy, the IP PayPing sees is the proxy's exit IP.
|
|
281
|
+
</details>
|
|
282
|
+
|
|
283
|
+
<details>
|
|
284
|
+
<summary><b>"Could not reach PayPing" or "PayPing did not answer in time"</b></summary>
|
|
285
|
+
|
|
286
|
+
The server ignores system proxy settings on purpose. If your network needs a proxy to reach PayPing, set `PAYPING_MCP_PROXY`, e.g. `http://127.0.0.1:10809`. In testing, PayPing's API hosts answered both from Iran and from a foreign exit.
|
|
287
|
+
</details>
|
|
288
|
+
|
|
289
|
+
<details>
|
|
290
|
+
<summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
|
|
291
|
+
|
|
292
|
+
Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
|
|
293
|
+
</details>
|
|
294
|
+
|
|
295
|
+
<details>
|
|
296
|
+
<summary><b>How do I see exactly what the agent sees?</b></summary>
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
npx @modelcontextprotocol/inspector -e PAYPING_TOKEN=your-token uvx payping-mcp
|
|
300
|
+
```
|
|
301
|
+
</details>
|
|
302
|
+
|
|
303
|
+
Errors that carry a PayPing trace id: give that id to PayPing support.
|
|
304
|
+
|
|
305
|
+
## Configuration
|
|
306
|
+
|
|
307
|
+
| Variable | Required | Meaning |
|
|
308
|
+
|---|---|---|
|
|
309
|
+
| `PAYPING_TOKEN` | yes | API token from the PayPing panel |
|
|
310
|
+
| `PAYPING_MCP_PROXY` | no | HTTP proxy URL for every request, e.g. `http://user:pass@host:port`. System proxy settings are ignored. |
|
|
311
|
+
|
|
312
|
+
## فارسی
|
|
313
|
+
|
|
314
|
+
<div dir="rtl">
|
|
315
|
+
|
|
316
|
+
**payping-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد موجودی، فروش، تراکنش‌ها، تسویه‌ها، مشتریان، محصولات، کدهای تخفیف و فاکتورهای حساب پی‌پینگ شما را ببیند، و پس از تأیید شما مشتری، محصول، لینک پرداخت، کد تخفیف و فاکتور بسازد.
|
|
317
|
+
|
|
318
|
+
- روی سیستم خود شما اجرا می‌شود و توکن فقط به سرورهای پی‌پینگ فرستاده می‌شود.
|
|
319
|
+
- برداشت، استرداد، برگشت پرداخت و حذف با این ابزار ممکن نیست.
|
|
320
|
+
- مبالغ به تومان و تاریخ‌ها به وقت UTC هستند.
|
|
321
|
+
|
|
322
|
+
**ساخت توکن:**
|
|
323
|
+
|
|
324
|
+
1. در [پنل پی‌پینگ](https://app.payping.ir) به «اتصالات ← توسعه دهندگان» بروید و «توکن جدید» را بزنید.
|
|
325
|
+
2. نام توکن، تاریخ انقضا و توضیحات را وارد کنید. «آی‌پی‌های مجاز» اختیاری است؛ اگر پر کنید، درخواست از آی‌پی دیگر با خطای 166 رد می‌شود.
|
|
326
|
+
3. در «دسترسی‌ها» فقط موارد لازم را انتخاب کنید و «ساخت پرداخت» را حذف کنید؛ این ابزار به آن نیازی ندارد.
|
|
327
|
+
4. رمز پیامکی را بگیرید و وارد کنید. توکن فقط یک بار نمایش داده می‌شود؛ همان لحظه کپی کنید.
|
|
328
|
+
5. پروفایل شما باید کامل باشد. کارشناس پی‌پینگ توکن را تأیید می‌کند و تا حدود ۱۰ دقیقه بعد از تأیید ممکن است خطای 401 بگیرید.
|
|
329
|
+
|
|
330
|
+
**نصب در Claude Code:**
|
|
331
|
+
|
|
332
|
+
</div>
|
|
333
|
+
|
|
334
|
+
```bash
|
|
335
|
+
claude mcp add payping -e PAYPING_TOKEN=your-token -- uvx payping-mcp
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
<div dir="rtl">
|
|
339
|
+
|
|
340
|
+
بعد بپرسید: «موجودی پی‌پینگ من چقدر است و این ماه چقدر فروختم؟»
|
|
341
|
+
|
|
342
|
+
توکن را مثل رمز عبور نگه دارید و در گیت قرار ندهید. اگر لو رفت، در پنل آن را حذف یا «تعویض توکن» کنید.
|
|
343
|
+
|
|
344
|
+
</div>
|
|
345
|
+
|
|
346
|
+
## Development
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
git clone https://github.com/sepehr071/payping-mcp && cd payping-mcp
|
|
350
|
+
uv sync
|
|
351
|
+
uv run ruff check . && uv run ruff format --check .
|
|
352
|
+
uv run pytest -q # offline, against a mocked PayPing API
|
|
353
|
+
PAYPING_TOKEN=your-token uv run pytest -m live # read-only calls to the real API
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
Tools live in `src/payping_mcp/reports.py` (account, money) and `shop.py` (customers, products, coupons, invoices);
|
|
357
|
+
`http.py` is the only HTTP code. Each tool is a typed async function with a docstring that tells the agent when to
|
|
358
|
+
use it. Issues and PRs are welcome.
|
|
359
|
+
|
|
360
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
|
|
361
|
+
publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
|
|
362
|
+
|
|
363
|
+
## Disclaimer
|
|
364
|
+
|
|
365
|
+
Unofficial and not affiliated with or endorsed by PayPing. It uses PayPing's API with your own token. Follow
|
|
366
|
+
PayPing's terms.
|
|
367
|
+
|
|
368
|
+
## License
|
|
369
|
+
|
|
370
|
+
[MIT](https://github.com/sepehr071/payping-mcp/blob/main/LICENSE)
|