blindsbazaar-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,76 @@
1
+
2
+
3
+
4
+
5
+
6
+
7
+
8
+
9
+
10
+
11
+
12
+
13
+ # Build outputs
14
+ # Dependencies
15
+ # Django
16
+ # Docker
17
+ # Environment variables
18
+ # Expo (React Native)
19
+ # IDE
20
+ # Misc
21
+ # Never meant to be committed.
22
+ # OS
23
+ # Python
24
+ # Testing
25
+ # Turbo
26
+ # gst_service's self-learning captcha dataset (grows locally from real,
27
+ # successfully-solved lookups — see gst_service/learning/dataset.py).
28
+ *$py.class
29
+ *.egg
30
+ *.egg-info/
31
+ *.jks
32
+ *.key
33
+ *.log
34
+ *.mobileprovision
35
+ *.orig.*
36
+ *.p12
37
+ *.p8
38
+ *.pem
39
+ *.py[cod]
40
+ *.so
41
+ *.swo
42
+ *.swp
43
+ *.tsbuildinfo
44
+ *~
45
+ .DS_Store
46
+ .Python
47
+ .coverage
48
+ .docker/
49
+ .env
50
+ .env.development.local
51
+ .env.local
52
+ .env.production.local
53
+ .env.test.local
54
+ .envextra
55
+ .expo/
56
+ .idea/
57
+ .pnp
58
+ .pnp.js
59
+ .turbo/
60
+ .venv/
61
+ .vscode/
62
+ Thumbs.db
63
+ __pycache__/
64
+ backend/media/
65
+ backend/staticfiles/
66
+ build/
67
+ captcha_ds/
68
+ coverage/
69
+ dist/
70
+ env/
71
+ htmlcov/
72
+ node_modules/
73
+ pip-delete-this-directory.txt
74
+ pip-log.txt
75
+ secrets/backend/localtest.sqlite3
76
+ venv/
@@ -0,0 +1,128 @@
1
+ Metadata-Version: 2.5
2
+ Name: blindsbazaar-mcp
3
+ Version: 0.1.0
4
+ Summary: Read-only MCP server for the BlindsBazaar storefront: live catalog, authoritative window-price quotes, FAQs, buying guides and delivery info.
5
+ Project-URL: Homepage, https://blindsbazaar.in/mcp/
6
+ Project-URL: Repository, https://github.com/Kumar-vikalp/blindsbazaar
7
+ Project-URL: Issues, https://github.com/Kumar-vikalp/blindsbazaar/issues
8
+ Author: BlindsBazaar
9
+ License: MIT
10
+ Keywords: blinds,blindsbazaar,e-commerce,llm-tools,mcp,model-context-protocol
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Requires-Python: >=3.11
20
+ Requires-Dist: httpx>=0.27
21
+ Requires-Dist: mcp<2,>=1.2.0
22
+ Requires-Dist: uvicorn>=0.30
23
+ Description-Content-Type: text/markdown
24
+
25
+ # BlindsBazaar MCP server
26
+
27
+ A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
28
+ BlindsBazaar storefront — live catalog, authoritative pricing, FAQs, journal content and
29
+ delivery policies — to MCP clients (Claude Desktop, Claude Code, Codex CLI, Cursor, ChatGPT
30
+ connectors, pi, …).
31
+
32
+ **Distributed without sharing any source code.** Consumers get one of:
33
+
34
+ 1. **The hosted URL** (recommended) — `https://api.blindsbazaar.in/mcp` (Streamable HTTP).
35
+ Nothing to install; see `deploy/HOSTING.md` for the systemd + nginx setup.
36
+ 2. **The PyPI package** — `pip install blindsbazaar-mcp` / `uvx blindsbazaar-mcp`.
37
+ Publish with the included GitHub Actions workflow (see below).
38
+
39
+ No secrets ship with either: every tool calls the public storefront API, and there is
40
+ **no write access** — no tool can place orders, edit products or touch accounts.
41
+
42
+ ## Tools
43
+
44
+ | Tool | What it does |
45
+ |---|---|
46
+ | `search_products` | Search/filter the catalog (text, blind type, room, collection, opacity, price cap) |
47
+ | `get_product` | Full detail: prices, size ranges, materials, photos, colourways, ratings |
48
+ | `quote_blind` | Price an exact window size — calls the store's own pricing engine (the same one checkout charges) |
49
+ | `list_blind_types` | Blind types + rate card (₹/sq ft, minimum charge, motorizable) |
50
+ | `list_rooms` / `list_collections` | Taxonomy slugs for filtering, plus storefront URLs |
51
+ | `get_configurator_options` | Minimum billable area + fabric/control/mount options with ₹ add-ons |
52
+ | `search_faqs` / `search_journal` / `get_journal_story` | The store's own FAQs and buying guides |
53
+ | `delivery_coverage` | Where/how orders are delivered, making + transit times, self-install policy |
54
+
55
+ ## Run it
56
+
57
+ **Hosted (no install for consumers):** point the client at the URL —
58
+ `https://api.blindsbazaar.in/mcp`. Hosting setup: [`deploy/HOSTING.md`](deploy/HOSTING.md).
59
+
60
+ **Local stdio (for Claude Desktop / Claude Code / pi / Cursor):**
61
+
62
+ ```bash
63
+ uvx blindsbazaar-mcp # once published to PyPI
64
+ # or, from this folder:
65
+ uv run blindsbazaar-mcp
66
+ ```
67
+
68
+ | Variable | Default | Purpose |
69
+ |---|---|---|
70
+ | `BLINDSBAZAAR_API_URL` | `https://api.blindsbazaar.in/api/v1` | Point at a local backend (`http://localhost:8001/api/v1`) while developing |
71
+ | `BLINDSBAZAAR_SITE_URL` | `https://blindsbazaar.in` | Base used for the page URLs returned in tool output |
72
+ | `BB_MCP_TRANSPORT` | `stdio` | `streamable-http` to host |
73
+ | `BB_MCP_HOST` / `BB_MCP_PORT` / `BB_MCP_PATH` | `127.0.0.1` / `8817` / `/mcp` | HTTP hosting bind |
74
+
75
+ ## Client configuration
76
+
77
+ **Claude Code:** `claude mcp add --transport http blindsbazaar https://api.blindsbazaar.in/mcp`
78
+ (or stdio: `claude mcp add blindsbazaar -- uvx blindsbazaar-mcp`)
79
+
80
+ **Codex CLI** (`~/.codex/config.toml`):
81
+
82
+ ```toml
83
+ [mcp_servers.blindsbazaar]
84
+ url = "https://api.blindsbazaar.in/mcp" # remote; or command/args for stdio
85
+ ```
86
+
87
+ **Claude Desktop:** Settings → Connectors → Add custom connector → the URL
88
+ (or the stdio `mcpServers` JSON in `claude_desktop_config.json` — see the
89
+ [storefront setup page](https://blindsbazaar.in/mcp/) for every client).
90
+
91
+ ## Get listed in the MCP ecosystem
92
+
93
+ The old `modelcontextprotocol/servers` README list is frozen — it now only hosts
94
+ reference implementations. Discovery happens through the
95
+ **[official MCP Registry](https://registry.modelcontextprotocol.io/)** plus directory
96
+ sites (PulseMCP, Smithery, Glama, mcp.so). This folder ships everything needed:
97
+
98
+ - `server.json` — the registry descriptor (`io.github.Kumar-vikalp/blindsbazaar`,
99
+ the hosted remote URL and the PyPI package). Bump `version` together with `pyproject.toml`.
100
+ - `.github/workflows/publish-mcp.yml` — publishes to PyPI on every `v*` tag
101
+ (PyPI trusted publishing; one-time setup: on pypi.org add a pending publisher —
102
+ Owner `Kumar-vikalp`, repo `blindsbazaar`, workflow `publish-mcp.yml`,
103
+ environment `pypi`).
104
+
105
+ Steps:
106
+
107
+ 1. **Publish to PyPI** — `git tag v0.1.0 && git push origin v0.1.0` (after the one-time
108
+ trusted-publisher setup), or `cd mcp && uv build --wheel && uv publish` locally.
109
+ 2. **Submit to the official registry** — sign in at registry.modelcontextprotocol.io
110
+ with GitHub and submit `server.json`. Note: `io.github.*` names are validated against
111
+ the GitHub repo — if this repo becomes private, prove domain control instead and
112
+ register under the blindsbazaar.in name.
113
+ 3. **Optional directories** — PulseMCP, Smithery and Glama accept community submissions
114
+ and are how most users browse; submit the same descriptor there.
115
+
116
+ ## Architecture notes
117
+
118
+ - **Read-only by design.** There is deliberately no order/account tool: those endpoints need
119
+ customer tokens and would turn a chat assistant into something that can spend money. If that
120
+ is ever wanted, it should be a separate, authenticated, opt-in server.
121
+ - **Pricing is never reimplemented client-side.** `quote_blind` POSTs to
122
+ `/api/v1/configurator/quote/` — the endpoint the storefront configurator uses — so the cart,
123
+ the site and this server can never quote different numbers.
124
+ - The hosted HTTP endpoint is **stateless** and proxies only public data; `deploy/HOSTING.md`
125
+ includes an nginx rate-limit block so a script can't hammer the API through it.
126
+ - **Source-visibility note:** a PyPI *wheel* contains readable Python; the package ships only
127
+ this thin public-API wrapper — no backend, CRM or business code. The hosted URL is the
128
+ distribution mode that shares nothing at all.
@@ -0,0 +1,104 @@
1
+ # BlindsBazaar MCP server
2
+
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
4
+ BlindsBazaar storefront — live catalog, authoritative pricing, FAQs, journal content and
5
+ delivery policies — to MCP clients (Claude Desktop, Claude Code, Codex CLI, Cursor, ChatGPT
6
+ connectors, pi, …).
7
+
8
+ **Distributed without sharing any source code.** Consumers get one of:
9
+
10
+ 1. **The hosted URL** (recommended) — `https://api.blindsbazaar.in/mcp` (Streamable HTTP).
11
+ Nothing to install; see `deploy/HOSTING.md` for the systemd + nginx setup.
12
+ 2. **The PyPI package** — `pip install blindsbazaar-mcp` / `uvx blindsbazaar-mcp`.
13
+ Publish with the included GitHub Actions workflow (see below).
14
+
15
+ No secrets ship with either: every tool calls the public storefront API, and there is
16
+ **no write access** — no tool can place orders, edit products or touch accounts.
17
+
18
+ ## Tools
19
+
20
+ | Tool | What it does |
21
+ |---|---|
22
+ | `search_products` | Search/filter the catalog (text, blind type, room, collection, opacity, price cap) |
23
+ | `get_product` | Full detail: prices, size ranges, materials, photos, colourways, ratings |
24
+ | `quote_blind` | Price an exact window size — calls the store's own pricing engine (the same one checkout charges) |
25
+ | `list_blind_types` | Blind types + rate card (₹/sq ft, minimum charge, motorizable) |
26
+ | `list_rooms` / `list_collections` | Taxonomy slugs for filtering, plus storefront URLs |
27
+ | `get_configurator_options` | Minimum billable area + fabric/control/mount options with ₹ add-ons |
28
+ | `search_faqs` / `search_journal` / `get_journal_story` | The store's own FAQs and buying guides |
29
+ | `delivery_coverage` | Where/how orders are delivered, making + transit times, self-install policy |
30
+
31
+ ## Run it
32
+
33
+ **Hosted (no install for consumers):** point the client at the URL —
34
+ `https://api.blindsbazaar.in/mcp`. Hosting setup: [`deploy/HOSTING.md`](deploy/HOSTING.md).
35
+
36
+ **Local stdio (for Claude Desktop / Claude Code / pi / Cursor):**
37
+
38
+ ```bash
39
+ uvx blindsbazaar-mcp # once published to PyPI
40
+ # or, from this folder:
41
+ uv run blindsbazaar-mcp
42
+ ```
43
+
44
+ | Variable | Default | Purpose |
45
+ |---|---|---|
46
+ | `BLINDSBAZAAR_API_URL` | `https://api.blindsbazaar.in/api/v1` | Point at a local backend (`http://localhost:8001/api/v1`) while developing |
47
+ | `BLINDSBAZAAR_SITE_URL` | `https://blindsbazaar.in` | Base used for the page URLs returned in tool output |
48
+ | `BB_MCP_TRANSPORT` | `stdio` | `streamable-http` to host |
49
+ | `BB_MCP_HOST` / `BB_MCP_PORT` / `BB_MCP_PATH` | `127.0.0.1` / `8817` / `/mcp` | HTTP hosting bind |
50
+
51
+ ## Client configuration
52
+
53
+ **Claude Code:** `claude mcp add --transport http blindsbazaar https://api.blindsbazaar.in/mcp`
54
+ (or stdio: `claude mcp add blindsbazaar -- uvx blindsbazaar-mcp`)
55
+
56
+ **Codex CLI** (`~/.codex/config.toml`):
57
+
58
+ ```toml
59
+ [mcp_servers.blindsbazaar]
60
+ url = "https://api.blindsbazaar.in/mcp" # remote; or command/args for stdio
61
+ ```
62
+
63
+ **Claude Desktop:** Settings → Connectors → Add custom connector → the URL
64
+ (or the stdio `mcpServers` JSON in `claude_desktop_config.json` — see the
65
+ [storefront setup page](https://blindsbazaar.in/mcp/) for every client).
66
+
67
+ ## Get listed in the MCP ecosystem
68
+
69
+ The old `modelcontextprotocol/servers` README list is frozen — it now only hosts
70
+ reference implementations. Discovery happens through the
71
+ **[official MCP Registry](https://registry.modelcontextprotocol.io/)** plus directory
72
+ sites (PulseMCP, Smithery, Glama, mcp.so). This folder ships everything needed:
73
+
74
+ - `server.json` — the registry descriptor (`io.github.Kumar-vikalp/blindsbazaar`,
75
+ the hosted remote URL and the PyPI package). Bump `version` together with `pyproject.toml`.
76
+ - `.github/workflows/publish-mcp.yml` — publishes to PyPI on every `v*` tag
77
+ (PyPI trusted publishing; one-time setup: on pypi.org add a pending publisher —
78
+ Owner `Kumar-vikalp`, repo `blindsbazaar`, workflow `publish-mcp.yml`,
79
+ environment `pypi`).
80
+
81
+ Steps:
82
+
83
+ 1. **Publish to PyPI** — `git tag v0.1.0 && git push origin v0.1.0` (after the one-time
84
+ trusted-publisher setup), or `cd mcp && uv build --wheel && uv publish` locally.
85
+ 2. **Submit to the official registry** — sign in at registry.modelcontextprotocol.io
86
+ with GitHub and submit `server.json`. Note: `io.github.*` names are validated against
87
+ the GitHub repo — if this repo becomes private, prove domain control instead and
88
+ register under the blindsbazaar.in name.
89
+ 3. **Optional directories** — PulseMCP, Smithery and Glama accept community submissions
90
+ and are how most users browse; submit the same descriptor there.
91
+
92
+ ## Architecture notes
93
+
94
+ - **Read-only by design.** There is deliberately no order/account tool: those endpoints need
95
+ customer tokens and would turn a chat assistant into something that can spend money. If that
96
+ is ever wanted, it should be a separate, authenticated, opt-in server.
97
+ - **Pricing is never reimplemented client-side.** `quote_blind` POSTs to
98
+ `/api/v1/configurator/quote/` — the endpoint the storefront configurator uses — so the cart,
99
+ the site and this server can never quote different numbers.
100
+ - The hosted HTTP endpoint is **stateless** and proxies only public data; `deploy/HOSTING.md`
101
+ includes an nginx rate-limit block so a script can't hammer the API through it.
102
+ - **Source-visibility note:** a PyPI *wheel* contains readable Python; the package ships only
103
+ this thin public-API wrapper — no backend, CRM or business code. The hosted URL is the
104
+ distribution mode that shares nothing at all.
@@ -0,0 +1 @@
1
+ """BlindsBazaar MCP server package."""
@@ -0,0 +1,76 @@
1
+ """Thin HTTP client for the BlindsBazaar public storefront API.
2
+
3
+ Read-only: every call hits a public, unauthenticated endpoint, so the MCP
4
+ server carries no secrets and can be shipped to any client. The base URL is
5
+ overridable for local testing (BLINDSBAZAAR_API_URL); everything else comes
6
+ from the server, so prices/policies can never drift from what the site
7
+ actually charges.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import os
13
+ from typing import Any
14
+
15
+ import httpx
16
+
17
+ DEFAULT_API_URL = "https://api.blindsbazaar.in/api/v1"
18
+ DEFAULT_SITE_URL = "https://blindsbazaar.in"
19
+
20
+
21
+ class BbApiError(RuntimeError):
22
+ """A request the API rejected — surfaced to the MCP client verbatim."""
23
+
24
+
25
+ def api_base() -> str:
26
+ return (os.environ.get("BLINDSBAZAAR_API_URL") or DEFAULT_API_URL).rstrip("/")
27
+
28
+
29
+ def site_base() -> str:
30
+ return (os.environ.get("BLINDSBAZAAR_SITE_URL") or DEFAULT_SITE_URL).rstrip("/")
31
+
32
+
33
+ def product_url(slug: str) -> str:
34
+ return f"{site_base()}/product/{slug}/"
35
+
36
+
37
+ def journal_url(slug: str) -> str:
38
+ return f"{site_base()}/journal/{slug}/"
39
+
40
+
41
+ class BbClient:
42
+ """Shared httpx client — one connection pool for the server's lifetime."""
43
+
44
+ def __init__(self) -> None:
45
+ self._http = httpx.Client(base_url=api_base(), timeout=httpx.Timeout(20.0))
46
+
47
+ def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
48
+ return self._request("GET", path, params=params)
49
+
50
+ def post(self, path: str, json_body: dict[str, Any]) -> Any:
51
+ return self._request("POST", path, json=json_body)
52
+
53
+ def _request(self, method: str, path: str, **kwargs: Any) -> Any:
54
+ try:
55
+ response = self._http.request(method, path, **kwargs)
56
+ except httpx.HTTPError as exc:
57
+ raise BbApiError(f"Could not reach the BlindsBazaar API ({api_base()}): {exc}") from exc
58
+ if response.status_code >= 400:
59
+ # Detail payloads are DRF's {"detail": ...} or field errors; pass
60
+ # the useful text through instead of a bare status code.
61
+ try:
62
+ body = response.json()
63
+ except ValueError:
64
+ body = None
65
+ detail = (
66
+ body.get("detail")
67
+ if isinstance(body, dict)
68
+ else (body if isinstance(body, str) else None)
69
+ )
70
+ raise BbApiError(
71
+ f"BlindsBazaar API returned {response.status_code} for {path}"
72
+ + (f": {detail}" if detail else "")
73
+ )
74
+ if response.status_code == 204 or not response.content:
75
+ return None
76
+ return response.json()