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.
@@ -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,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Question or idea
4
+ url: https://github.com/sepehr071/payping-mcp/discussions
5
+ about: Ask how to use it or suggest a new tool
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -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,7 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
7
+ .env
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/payping-mcp?color=2563eb)](https://pypi.org/project/payping-mcp/)
37
+ [![Python](https://img.shields.io/pypi/pyversions/payping-mcp)](https://pypi.org/project/payping-mcp/)
38
+ [![CI](https://github.com/sepehr071/payping-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/payping-mcp/actions/workflows/ci.yml)
39
+ [![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fpayping--mcp-7c3aed)](https://registry.modelcontextprotocol.io/v0/servers?search=payping-mcp)
40
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/payping-mcp/blob/main/LICENSE)
41
+
42
+ [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=payping&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJwYXlwaW5nLW1jcCJdLCJlbnYiOnsiUEFZUElOR19UT0tFTiI6InlvdXItdG9rZW4ifX0=)
43
+ [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_payping--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](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
+ | آی&zwnj;پی&zwnj;های مجاز (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
+ | دسترسی&zwnj;ها (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 **گزارش پرداخت&zwnj;ها** and **ساخت پرداخت**. Remove **ساخت پرداخت**: this server never uses it. Then add what you need:
92
+
93
+ | Panel label | Scope | Tools that need it |
94
+ |---|---|---|
95
+ | گزارش پرداخت&zwnj;ها | `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">فاکتورهای پرداخت&zwnj;نشده این ماه را نشان بده.</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 **آی&zwnj;پی&zwnj;های مجاز** 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 و ...) اجازه می&zwnj;دهد موجودی، فروش، تراکنش&zwnj;ها، تسویه&zwnj;ها، مشتریان، محصولات، کدهای تخفیف و فاکتورهای حساب پی&zwnj;پینگ شما را ببیند، و پس از تأیید شما مشتری، محصول، لینک پرداخت، کد تخفیف و فاکتور بسازد.
317
+
318
+ - روی سیستم خود شما اجرا می&zwnj;شود و توکن فقط به سرورهای پی&zwnj;پینگ فرستاده می&zwnj;شود.
319
+ - برداشت، استرداد، برگشت پرداخت و حذف با این ابزار ممکن نیست.
320
+ - مبالغ به تومان و تاریخ&zwnj;ها به وقت UTC هستند.
321
+
322
+ **ساخت توکن:**
323
+
324
+ 1. در [پنل پی&zwnj;پینگ](https://app.payping.ir) به «اتصالات ← توسعه دهندگان» بروید و «توکن جدید» را بزنید.
325
+ 2. نام توکن، تاریخ انقضا و توضیحات را وارد کنید. «آی&zwnj;پی&zwnj;های مجاز» اختیاری است؛ اگر پر کنید، درخواست از آی&zwnj;پی دیگر با خطای 166 رد می&zwnj;شود.
326
+ 3. در «دسترسی&zwnj;ها» فقط موارد لازم را انتخاب کنید و «ساخت پرداخت» را حذف کنید؛ این ابزار به آن نیازی ندارد.
327
+ 4. رمز پیامکی را بگیرید و وارد کنید. توکن فقط یک بار نمایش داده می&zwnj;شود؛ همان لحظه کپی کنید.
328
+ 5. پروفایل شما باید کامل باشد. کارشناس پی&zwnj;پینگ توکن را تأیید می&zwnj;کند و تا حدود ۱۰ دقیقه بعد از تأیید ممکن است خطای 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
+ بعد بپرسید: «موجودی پی&zwnj;پینگ من چقدر است و این ماه چقدر فروختم؟»
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)