masterkala-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.
- masterkala_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
- masterkala_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
- masterkala_mcp-0.1.0/.github/dependabot.yml +10 -0
- masterkala_mcp-0.1.0/.github/workflows/ci.yml +21 -0
- masterkala_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- masterkala_mcp-0.1.0/.gitignore +6 -0
- masterkala_mcp-0.1.0/LICENSE +21 -0
- masterkala_mcp-0.1.0/PKG-INFO +297 -0
- masterkala_mcp-0.1.0/README.md +273 -0
- masterkala_mcp-0.1.0/pyproject.toml +52 -0
- masterkala_mcp-0.1.0/server.json +32 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/__init__.py +5 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/blog.py +100 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/catalog.py +409 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/http.py +116 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/product.py +302 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/registry.py +16 -0
- masterkala_mcp-0.1.0/src/masterkala_mcp/server.py +57 -0
- masterkala_mcp-0.1.0/tests/conftest.py +69 -0
- masterkala_mcp-0.1.0/tests/fixtures/attributes.json +77 -0
- masterkala_mcp-0.1.0/tests/fixtures/attributes_24855.json +36 -0
- masterkala_mcp-0.1.0/tests/fixtures/blog_comments.json +166 -0
- masterkala_mcp-0.1.0/tests/fixtures/blog_posts.json +44 -0
- masterkala_mcp-0.1.0/tests/fixtures/brands.html +30 -0
- masterkala_mcp-0.1.0/tests/fixtures/categories.html +42 -0
- masterkala_mcp-0.1.0/tests/fixtures/category.html +4 -0
- masterkala_mcp-0.1.0/tests/fixtures/delivery_badge.json +3 -0
- masterkala_mcp-0.1.0/tests/fixtures/offer.html +263 -0
- masterkala_mcp-0.1.0/tests/fixtures/product_24855.html +75 -0
- masterkala_mcp-0.1.0/tests/fixtures/product_26634.html +75 -0
- masterkala_mcp-0.1.0/tests/fixtures/product_27034.html +109 -0
- masterkala_mcp-0.1.0/tests/fixtures/product_list.html +304 -0
- masterkala_mcp-0.1.0/tests/fixtures/reviews.json +65 -0
- masterkala_mcp-0.1.0/tests/fixtures/search.json +136 -0
- masterkala_mcp-0.1.0/tests/fixtures/shipping.json +34 -0
- masterkala_mcp-0.1.0/tests/fixtures/shipping_free.json +34 -0
- masterkala_mcp-0.1.0/tests/fixtures/stores.html +107 -0
- masterkala_mcp-0.1.0/tests/test_blog.py +39 -0
- masterkala_mcp-0.1.0/tests/test_catalog.py +209 -0
- masterkala_mcp-0.1.0/tests/test_http.py +80 -0
- masterkala_mcp-0.1.0/tests/test_live_blog.py +23 -0
- masterkala_mcp-0.1.0/tests/test_live_catalog.py +55 -0
- masterkala_mcp-0.1.0/tests/test_live_product.py +38 -0
- masterkala_mcp-0.1.0/tests/test_product.py +157 -0
- masterkala_mcp-0.1.0/uv.lock +1112 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: A tool failed or returned wrong data
|
|
3
|
+
labels: [bug]
|
|
4
|
+
body:
|
|
5
|
+
- type: input
|
|
6
|
+
id: tool
|
|
7
|
+
attributes:
|
|
8
|
+
label: Tool
|
|
9
|
+
description: Which tool, e.g. mk_find_cheapest
|
|
10
|
+
validations:
|
|
11
|
+
required: true
|
|
12
|
+
- type: textarea
|
|
13
|
+
id: input
|
|
14
|
+
attributes:
|
|
15
|
+
label: Arguments and result
|
|
16
|
+
description: The arguments the agent sent and the error or wrong output. Remove anything personal.
|
|
17
|
+
render: json
|
|
18
|
+
validations:
|
|
19
|
+
required: true
|
|
20
|
+
- type: textarea
|
|
21
|
+
id: expected
|
|
22
|
+
attributes:
|
|
23
|
+
label: What you expected
|
|
24
|
+
description: e.g. the price shown on masterkala.com for the same product
|
|
25
|
+
- type: input
|
|
26
|
+
id: client
|
|
27
|
+
attributes:
|
|
28
|
+
label: MCP client and OS
|
|
29
|
+
placeholder: Claude Desktop 1.x on Windows 11
|
|
30
|
+
- type: dropdown
|
|
31
|
+
id: network
|
|
32
|
+
attributes:
|
|
33
|
+
label: Network
|
|
34
|
+
options:
|
|
35
|
+
- Direct, no VPN
|
|
36
|
+
- VPN or proxy
|
|
37
|
+
- MASTERKALA_MCP_PROXY set
|
|
38
|
+
- type: input
|
|
39
|
+
id: version
|
|
40
|
+
attributes:
|
|
41
|
+
label: masterkala-mcp version
|
|
42
|
+
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/masterkala-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,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,297 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: masterkala-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for MasterKala: search gadgets and accessories, compare prices and specs, find deals.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/masterkala-mcp
|
|
6
|
+
Project-URL: Issues, https://github.com/sepehr071/masterkala-mcp/issues
|
|
7
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: e-commerce,gadgets,iran,masterkala,mcp,model-context-protocol,shopping
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
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 :: Scientific/Engineering :: Artificial Intelligence
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Requires-Dist: httpx>=0.27
|
|
22
|
+
Requires-Dist: mcp<3,>=2.2
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
|
|
25
|
+
<!-- mcp-name: io.github.sepehr071/masterkala-mcp -->
|
|
26
|
+
|
|
27
|
+
<div align="center">
|
|
28
|
+
|
|
29
|
+
# 🎧 masterkala-mcp
|
|
30
|
+
|
|
31
|
+
**Let your AI agent shop for gadgets on MasterKala.**<br>
|
|
32
|
+
Search earbuds, chargers, power banks and smart watches, compare real prices and specs,<br>
|
|
33
|
+
read reviews, check stock and delivery dates, and catch today's discounts, all from Claude, Cursor or Copilot.
|
|
34
|
+
|
|
35
|
+
[](https://pypi.org/project/masterkala-mcp/)
|
|
36
|
+
[](https://pypi.org/project/masterkala-mcp/)
|
|
37
|
+
[](https://github.com/sepehr071/masterkala-mcp/actions/workflows/ci.yml)
|
|
38
|
+
[](https://registry.modelcontextprotocol.io/v0/servers?search=masterkala-mcp)
|
|
39
|
+
[](https://github.com/sepehr071/masterkala-mcp/blob/main/LICENSE)
|
|
40
|
+
|
|
41
|
+
[](https://cursor.com/en/install-mcp?name=masterkala&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtYXN0ZXJrYWxhLW1jcCJdfQ==)
|
|
42
|
+
[](https://vscode.dev/redirect/mcp/install?name=masterkala&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22masterkala-mcp%22%5D%7D)
|
|
43
|
+
|
|
44
|
+
[Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
|
|
45
|
+
|
|
46
|
+
</div>
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## Why
|
|
51
|
+
|
|
52
|
+
MasterKala lists thousands of accessories, and a search for "power bank" mixes real power banks with
|
|
53
|
+
silicone covers, out-of-stock items and things sold only in its shops. Finding *the cheapest one you can
|
|
54
|
+
actually order, and what it costs delivered*, means paging through results and opening product pages.
|
|
55
|
+
An agent with `masterkala-mcp` does that in seconds:
|
|
56
|
+
|
|
57
|
+
> **You:** Cheapest Xiaomi power bank I can order now, delivered in Tehran?
|
|
58
|
+
>
|
|
59
|
+
> **Agent:** *calls* `mk_find_cheapest(query="پاوربانک شیائومی")` → `mk_shipping(product_id=26935)`
|
|
60
|
+
>
|
|
61
|
+
> | Total | Product | Price | Shipping |
|
|
62
|
+
> |---:|---|---:|---|
|
|
63
|
+
> | **4,338,000** | پاوربانک 10000 شیائومی گلوریمی Glorimi LightCore 22.5W | 4,188,000 (5% off) | 150,000, Saturday 15:00-18:00 |
|
|
64
|
+
> | **5,291,000** | پاوربانک فوق نازک مگنتی 5000 Glorimi FitCore Mag 20W | 5,291,000 (4% off) | free (over 5M) |
|
|
65
|
+
> | **5,401,000** | پاوربانک 20000 شیائومی گلوریمی Glorimi LightCore 22.5W | 5,401,000 (6% off) | free (over 5M) |
|
|
66
|
+
>
|
|
67
|
+
> The 10,000 mAh LightCore is cheapest even with the 150,000 courier fee. The 20,000 mAh LightCore ships
|
|
68
|
+
> free and costs 1,063,000 more for twice the capacity. Want me to compare their specs with `mk_specs`?
|
|
69
|
+
|
|
70
|
+
<sub>Real tool output from 2026-10-03; prices change all the time. Prices are in Toman.</sub>
|
|
71
|
+
|
|
72
|
+
## What it can do
|
|
73
|
+
|
|
74
|
+
- 🔎 **Search** products by name in Persian or English, with price, discount and stock
|
|
75
|
+
- 💸 **Find the cheapest** in-stock match, with cases and covers filtered out
|
|
76
|
+
- 🗂️ **Browse** any category, brand or tag sorted by price, stock or date, with price range and brand/color filters
|
|
77
|
+
- 📋 **Read** full product details: colors, stock count, specs, side-by-side comparison, reviews
|
|
78
|
+
- 🚚 **Check delivery**: next Tehran courier slot, post to other cities, shipping fee, same-day cut-off
|
|
79
|
+
- ⚡ **Catch deals** on the discount page, plus buying guides from the MasterKala blog
|
|
80
|
+
- 🔒 **Read-only by design**: no login, no cart, no orders, no reviews posted
|
|
81
|
+
|
|
82
|
+
## Quick start
|
|
83
|
+
|
|
84
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
|
|
85
|
+
|
|
86
|
+
<details open>
|
|
87
|
+
<summary><b>Claude Code</b></summary>
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
claude mcp add masterkala -- uvx masterkala-mcp
|
|
91
|
+
```
|
|
92
|
+
</details>
|
|
93
|
+
|
|
94
|
+
<details>
|
|
95
|
+
<summary><b>Claude Desktop</b></summary>
|
|
96
|
+
|
|
97
|
+
Settings → Developer → Edit Config, then add:
|
|
98
|
+
|
|
99
|
+
```json
|
|
100
|
+
{
|
|
101
|
+
"mcpServers": {
|
|
102
|
+
"masterkala": { "command": "uvx", "args": ["masterkala-mcp"] }
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
</details>
|
|
107
|
+
|
|
108
|
+
<details>
|
|
109
|
+
<summary><b>Cursor</b></summary>
|
|
110
|
+
|
|
111
|
+
Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
|
|
112
|
+
</details>
|
|
113
|
+
|
|
114
|
+
<details>
|
|
115
|
+
<summary><b>VS Code (Copilot agent mode)</b></summary>
|
|
116
|
+
|
|
117
|
+
Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"servers": {
|
|
122
|
+
"masterkala": { "type": "stdio", "command": "uvx", "args": ["masterkala-mcp"] }
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
</details>
|
|
127
|
+
|
|
128
|
+
<details>
|
|
129
|
+
<summary><b>Anything else</b></summary>
|
|
130
|
+
|
|
131
|
+
It's a standard stdio MCP server: run `uvx masterkala-mcp`, or `pip install masterkala-mcp` and run `masterkala-mcp`.
|
|
132
|
+
</details>
|
|
133
|
+
|
|
134
|
+
Then just ask:
|
|
135
|
+
|
|
136
|
+
- "Cheapest Bluetooth earbuds between 3 and 5 million Toman, and which one has the best reviews?"
|
|
137
|
+
- "Compare the specs of the Green Lion Ocean and the Awei T66."
|
|
138
|
+
- "Is the blue CMF Buds Pro 2 in stock? When would it reach Tehran?"
|
|
139
|
+
- <span dir="rtl">بهترین تخفیف‌های امروز مسترکالا روی پاوربانک چیه؟</span>
|
|
140
|
+
|
|
141
|
+
## How it works
|
|
142
|
+
|
|
143
|
+
```text
|
|
144
|
+
AI agent (Claude, Cursor, Copilot, ...)
|
|
145
|
+
│
|
|
146
|
+
│ MCP over stdio
|
|
147
|
+
▼
|
|
148
|
+
masterkala-mcp (runs on your machine)
|
|
149
|
+
│
|
|
150
|
+
│ HTTPS
|
|
151
|
+
└──────▶ masterkala.com JSON API, listing fragments, product pages
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`masterkala-mcp` runs locally and calls the same public endpoints the masterkala.com website uses.
|
|
155
|
+
There's no hosted server in between, no API key, and nothing about you is sent anywhere else.
|
|
156
|
+
|
|
157
|
+
## Tools
|
|
158
|
+
|
|
159
|
+
<details open>
|
|
160
|
+
<summary><b>🔎 Find products</b> (7)</summary>
|
|
161
|
+
|
|
162
|
+
| Tool | What it does |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `mk_search` | Search by keyword: price, discount, stock, plus matching categories and tag pages |
|
|
165
|
+
| `mk_find_cheapest` | Cheapest in-stock matches for a keyword, one flat list (accessories filtered out) |
|
|
166
|
+
| `mk_browse` | A category, brand or tag sorted by price / stock / date, with price range and filters |
|
|
167
|
+
| `mk_filters` | Brand, color and feature filter ids and the price range of a category, brand or tag |
|
|
168
|
+
| `mk_categories` | Product categories and their ids |
|
|
169
|
+
| `mk_brands` | Brands and their slugs |
|
|
170
|
+
| `mk_deals` | Everything on the discount page, biggest discount first, with the time left |
|
|
171
|
+
</details>
|
|
172
|
+
|
|
173
|
+
<details open>
|
|
174
|
+
<summary><b>📦 One product</b> (5)</summary>
|
|
175
|
+
|
|
176
|
+
| Tool | What it does |
|
|
177
|
+
|---|---|
|
|
178
|
+
| `mk_product` | Price, discount, stock status and count, colors, brand, category, rating, shops that have it |
|
|
179
|
+
| `mk_specs` | Specification table of 1-4 products side by side |
|
|
180
|
+
| `mk_reviews` | Customer reviews with star breakdown and the store's replies |
|
|
181
|
+
| `mk_shipping` | Next delivery slot and fee for Tehran and other cities, same-day cut-off |
|
|
182
|
+
| `mk_branches` | MasterKala's physical shops with address, phone and map location |
|
|
183
|
+
</details>
|
|
184
|
+
|
|
185
|
+
<details open>
|
|
186
|
+
<summary><b>📝 Blog</b> (2)</summary>
|
|
187
|
+
|
|
188
|
+
| Tool | What it does |
|
|
189
|
+
|---|---|
|
|
190
|
+
| `mk_blog_posts` | Buying guides, comparisons and how-tos, newest first |
|
|
191
|
+
| `mk_blog_comments` | Readers' questions on a post with the store writer's answers |
|
|
192
|
+
</details>
|
|
193
|
+
|
|
194
|
+
All tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
|
|
195
|
+
|
|
196
|
+
## Good to know
|
|
197
|
+
|
|
198
|
+
- **Prices are in Toman.** `final_price` is what you pay, `price` is before discount, `discount_pct` is a whole percent. The site's structured data is in Rial; the server converts it.
|
|
199
|
+
- **Shipping is free from 5,000,000 Toman** per order for most items (bulky goods such as large speakers never ship free; `mk_shipping` gives `free_shipping_from: null` for them); below that, Tehran courier and post were 150,000 / 155,000 Toman on 2026-10-03. There is no address API, so `mk_shipping` estimates for Tehran and "other cities by post".
|
|
200
|
+
- **Stock**: `in_stock` means orderable online now. Other statuses: ناموجود (sold out), به زودی (coming soon), موجود در شعب حضوری (only in the physical shops).
|
|
201
|
+
- **Ratings are 1–5**, `null` when nobody has reviewed the product yet.
|
|
202
|
+
- **Persian queries match best** (`هندزفری`, `پاوربانک`), but English brand and model names work too (`xiaomi`, `Buds Pro`).
|
|
203
|
+
|
|
204
|
+
## FAQ
|
|
205
|
+
|
|
206
|
+
<details>
|
|
207
|
+
<summary><b>Can it place an order for me?</b></summary>
|
|
208
|
+
|
|
209
|
+
No, and that's deliberate. It has no login and never touches the cart, order, payment, wishlist or review endpoints.
|
|
210
|
+
The agent finds the best option; you buy it on masterkala.com.
|
|
211
|
+
</details>
|
|
212
|
+
|
|
213
|
+
<details>
|
|
214
|
+
<summary><b>Why does <code>mk_find_cheapest</code> skip some items?</b></summary>
|
|
215
|
+
|
|
216
|
+
It keeps only items you can order online now, whose title contains every word of your query, and drops cases,
|
|
217
|
+
covers and screen protectors unless you ask for them (`include_accessories: true`, or a query like "کاور ...").
|
|
218
|
+
It scans the first 500 results by default (in-stock items come first); `complete: false` in the reply means more
|
|
219
|
+
in-stock items lie past that, so raise `scan` (up to 1500). `mk_search` shows everything.
|
|
220
|
+
</details>
|
|
221
|
+
|
|
222
|
+
<details>
|
|
223
|
+
<summary><b>I get "Could not reach masterkala.com"</b></summary>
|
|
224
|
+
|
|
225
|
+
The server retries a dropped connection once. If it still fails, check your internet connection. System proxy
|
|
226
|
+
variables are ignored on purpose; set `MASTERKALA_MCP_PROXY` if you need a proxy.
|
|
227
|
+
</details>
|
|
228
|
+
|
|
229
|
+
<details>
|
|
230
|
+
<summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
|
|
231
|
+
|
|
232
|
+
Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
|
|
233
|
+
</details>
|
|
234
|
+
|
|
235
|
+
<details>
|
|
236
|
+
<summary><b>How do I debug what the agent sees?</b></summary>
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
npx @modelcontextprotocol/inspector uvx masterkala-mcp
|
|
240
|
+
```
|
|
241
|
+
</details>
|
|
242
|
+
|
|
243
|
+
## Configuration
|
|
244
|
+
|
|
245
|
+
| Variable | Default | Meaning |
|
|
246
|
+
|---|---|---|
|
|
247
|
+
| `MASTERKALA_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port` |
|
|
248
|
+
|
|
249
|
+
## فارسی
|
|
250
|
+
|
|
251
|
+
<div dir="rtl">
|
|
252
|
+
|
|
253
|
+
**masterkala-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در مسترکالا جستجو کند،
|
|
254
|
+
ارزان‌ترین کالای موجود را پیدا کند، مشخصات و نظرات را مقایسه کند و زمان و هزینه ارسال و تخفیف‌های روز را ببیند.
|
|
255
|
+
|
|
256
|
+
- فقط خواندنی است: وارد حساب نمی‌شود، سبد خرید نمی‌سازد، سفارش ثبت نمی‌کند و نظر نمی‌فرستد.
|
|
257
|
+
- قیمت‌ها به تومان است و کاور و قاب را از نتایج «ارزان‌ترین» جدا می‌کند.
|
|
258
|
+
- روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.
|
|
259
|
+
|
|
260
|
+
**نصب در Claude Code:**
|
|
261
|
+
|
|
262
|
+
</div>
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
claude mcp add masterkala -- uvx masterkala-mcp
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
<div dir="rtl">
|
|
269
|
+
|
|
270
|
+
بعد بپرسید: «ارزان‌ترین هندزفری بلوتوث بین ۳ تا ۵ میلیون تومان کدام است و کی به تهران می‌رسد؟»
|
|
271
|
+
|
|
272
|
+
</div>
|
|
273
|
+
|
|
274
|
+
## Development
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
git clone https://github.com/sepehr071/masterkala-mcp && cd masterkala-mcp
|
|
278
|
+
uv sync
|
|
279
|
+
uv run pytest # offline, against recorded responses
|
|
280
|
+
uv run pytest -m live # real masterkala.com
|
|
281
|
+
uv run ruff check .
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
Tools live in `src/masterkala_mcp/catalog.py`, `product.py` and `blog.py`; each is a typed async function with a
|
|
285
|
+
docstring that tells the agent when to use it. Issues and PRs are welcome, especially new tools and fixes for site changes.
|
|
286
|
+
|
|
287
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
|
|
288
|
+
publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
|
|
289
|
+
|
|
290
|
+
## Disclaimer
|
|
291
|
+
|
|
292
|
+
Unofficial and not affiliated with or endorsed by MasterKala. It uses the public endpoints of the masterkala.com
|
|
293
|
+
website, which can change without notice. Please keep request rates reasonable.
|
|
294
|
+
|
|
295
|
+
## License
|
|
296
|
+
|
|
297
|
+
[MIT](https://github.com/sepehr071/masterkala-mcp/blob/main/LICENSE)
|