roomvana-mcp 0.1.2__tar.gz

roomvana_mcp-0.1.2/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.DS_Store

roomvana_mcp-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roomvana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

roomvana_mcp-0.1.2/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: roomvana-mcp
+Version: 0.1.2
+Summary: MCP server for Roomvana — browse room types & design styles and get a direct link to the Roomvana studio. Redesign your house, yard or any room from a photo at https://roomvana.ai
+Project-URL: Homepage, https://roomvana.ai
+Project-URL: Source, https://github.com/TJLDC/roomvana-mcp
+Project-URL: Issues, https://github.com/TJLDC/roomvana-mcp/issues
+Author: Roomvana
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,home-design,interior-design,mcp,modelcontextprotocol,roomvana
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Internet
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3.0
+Description-Content-Type: text/markdown
+
+# Roomvana MCP server (Python)
+
+An [MCP](https://modelcontextprotocol.io) server for **[Roomvana](https://roomvana.ai)** — AI home design for houses, yards and rooms. It lets an AI assistant browse the room types and design styles Roomvana supports and hand the user a studio link with their choices pre-selected. Upload a photo of your house, yard or any room and see it redesigned at **[roomvana.ai](https://roomvana.ai)**.
+
+Read-only and no sign-in required: this server never uploads photos or spends credits. The actual redesign happens on the website.
+
+## Tools
+
+| Tool | Parameters | What it does |
+| --- | --- | --- |
+| `list_design_styles` | none | Lists the design styles Roomvana can render (modern, japandi, industrial, coastal, …), each with a short description. |
+| `list_room_types` | none | Lists the rooms and outdoor spaces Roomvana can redesign — interior rooms, house exterior, and garden/patio/backyard. |
+| `design_a_room` | `room` (string, required), `style` (string, optional), `notes` (string, optional) | Returns a [roomvana.ai](https://roomvana.ai) studio link with the chosen room and style pre-selected; validates both against Roomvana's live catalog. `notes` is free text that is echoed back to the user, not encoded in the link. |
+
+## Use the hosted endpoint
+
+Roomvana also runs the same tools over Streamable HTTP at `https://api.roomvana.co/mcp` — no install, no API key.
+
+Claude Code:
+
+```bash
+claude mcp add --transport http roomvana https://api.roomvana.co/mcp
+```
+
+Or point any MCP client at it with a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "roomvana": {
+      "type": "http",
+      "url": "https://api.roomvana.co/mcp"
+    }
+  }
+}
+```
+
+## Run locally
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```json
+{
+  "mcpServers": {
+    "roomvana": {
+      "command": "uvx",
+      "args": ["roomvana-mcp"]
+    }
+  }
+}
+```
+
+Add that to your MCP client config (Claude Desktop: `claude_desktop_config.json`; other clients: their MCP config file), then restart the client.
+
+### From source
+
+```bash
+uv sync
+uv run roomvana-mcp
+```
+
+## Example
+
+> "I want to redo my bedroom in a japandi style."
+
+The assistant calls `design_a_room` with `room=bedroom`, `style=japandi` and returns:
+
+```
+https://roomvana.ai/design?room=bedroom&style=japandi
+```
+
+Open it, upload a photo of the room, and generate a redesign. Your walls, windows and layout stay put — only the look changes.
+
+## How it works
+
+The list of supported rooms and styles is fetched live from Roomvana's public catalog endpoint (`https://api.roomvana.co/options`), so the server never offers something Roomvana can't render. If that endpoint is unreachable, it falls back to a bundled snapshot.
+
+## Links
+
+- Website: https://roomvana.ai
+- Design studio: https://roomvana.ai/design
+
+## License
+
+MIT

roomvana_mcp-0.1.2/README.md

@@ -0,0 +1,85 @@
+# Roomvana MCP server (Python)
+
+An [MCP](https://modelcontextprotocol.io) server for **[Roomvana](https://roomvana.ai)** — AI home design for houses, yards and rooms. It lets an AI assistant browse the room types and design styles Roomvana supports and hand the user a studio link with their choices pre-selected. Upload a photo of your house, yard or any room and see it redesigned at **[roomvana.ai](https://roomvana.ai)**.
+
+Read-only and no sign-in required: this server never uploads photos or spends credits. The actual redesign happens on the website.
+
+## Tools
+
+| Tool | Parameters | What it does |
+| --- | --- | --- |
+| `list_design_styles` | none | Lists the design styles Roomvana can render (modern, japandi, industrial, coastal, …), each with a short description. |
+| `list_room_types` | none | Lists the rooms and outdoor spaces Roomvana can redesign — interior rooms, house exterior, and garden/patio/backyard. |
+| `design_a_room` | `room` (string, required), `style` (string, optional), `notes` (string, optional) | Returns a [roomvana.ai](https://roomvana.ai) studio link with the chosen room and style pre-selected; validates both against Roomvana's live catalog. `notes` is free text that is echoed back to the user, not encoded in the link. |
+
+## Use the hosted endpoint
+
+Roomvana also runs the same tools over Streamable HTTP at `https://api.roomvana.co/mcp` — no install, no API key.
+
+Claude Code:
+
+```bash
+claude mcp add --transport http roomvana https://api.roomvana.co/mcp
+```
+
+Or point any MCP client at it with a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "roomvana": {
+      "type": "http",
+      "url": "https://api.roomvana.co/mcp"
+    }
+  }
+}
+```
+
+## Run locally
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+```json
+{
+  "mcpServers": {
+    "roomvana": {
+      "command": "uvx",
+      "args": ["roomvana-mcp"]
+    }
+  }
+}
+```
+
+Add that to your MCP client config (Claude Desktop: `claude_desktop_config.json`; other clients: their MCP config file), then restart the client.
+
+### From source
+
+```bash
+uv sync
+uv run roomvana-mcp
+```
+
+## Example
+
+> "I want to redo my bedroom in a japandi style."
+
+The assistant calls `design_a_room` with `room=bedroom`, `style=japandi` and returns:
+
+```
+https://roomvana.ai/design?room=bedroom&style=japandi
+```
+
+Open it, upload a photo of the room, and generate a redesign. Your walls, windows and layout stay put — only the look changes.
+
+## How it works
+
+The list of supported rooms and styles is fetched live from Roomvana's public catalog endpoint (`https://api.roomvana.co/options`), so the server never offers something Roomvana can't render. If that endpoint is unreachable, it falls back to a bundled snapshot.
+
+## Links
+
+- Website: https://roomvana.ai
+- Design studio: https://roomvana.ai/design
+
+## License
+
+MIT

roomvana_mcp-0.1.2/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roomvana-mcp"
+version = "0.1.2"
+description = "MCP server for Roomvana — browse room types & design styles and get a direct link to the Roomvana studio. Redesign your house, yard or any room from a photo at https://roomvana.ai"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Roomvana" }]
+keywords = [
+    "mcp",
+    "modelcontextprotocol",
+    "interior-design",
+    "ai",
+    "home-design",
+    "roomvana",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Artistic Software",
+    "Topic :: Internet",
+]
+dependencies = [
+    "httpx>=0.27",
+    "mcp>=2.3.0,<3",
+]
+
+[project.scripts]
+roomvana-mcp = "roomvana_mcp:main"
+
+[project.urls]
+Homepage = "https://roomvana.ai"
+Source = "https://github.com/TJLDC/roomvana-mcp"
+Issues = "https://github.com/TJLDC/roomvana-mcp/issues"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roomvana_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

roomvana_mcp-0.1.2/src/roomvana_mcp/__init__.py

@@ -0,0 +1,19 @@
+"""Roomvana MCP server (Python port of the ``roomvana-mcp`` npm package)."""
+
+from .server import (
+    SERVER_NAME,
+    SERVER_VERSION,
+    TOOL_NAMES,
+    TOOLS,
+    create_server,
+    main,
+)
+
+__all__ = [
+    "main",
+    "create_server",
+    "TOOL_NAMES",
+    "TOOLS",
+    "SERVER_NAME",
+    "SERVER_VERSION",
+]

roomvana_mcp-0.1.2/src/roomvana_mcp/__main__.py

@@ -0,0 +1,4 @@
+from . import main
+
+if __name__ == "__main__":
+    main()

roomvana_mcp-0.1.2/src/roomvana_mcp/catalog.py

@@ -0,0 +1,198 @@
+"""Roomvana's room/style taxonomy.
+
+The AUTHORITATIVE list of what exists is the live, public, no-auth endpoint
+``GET https://api.roomvana.co/options`` (the API domain stays on .co forever --
+the shipped iOS build has it compiled in). We fetch it so this server never
+offers a room or style the product can't actually render. The maps below are a
+hand-maintained MIRROR used only to attach a human-readable label to each id
+(the /options payload carries ids only); an id present live but missing here
+still gets listed, just with a title-cased fallback label. Refresh these when
+app/options.py changes -- they are enrichment, not the source of truth.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+
+API_BASE = "https://api.roomvana.co"
+SITE_BASE = "https://roomvana.ai"
+
+# style id -> short description (mirror of app/options.py STYLES)
+STYLE_LABELS: dict[str, str] = {
+    "modern": "sleek modern — clean lines, uncluttered surfaces, neutral palette with bold accents",
+    "minimalist": "minimalist — essential furniture only, calm neutral tones, hidden storage",
+    "scandinavian": "Scandinavian — light woods, white walls, cozy textiles, functional simplicity",
+    "japandi": "Japandi — Japanese-Scandinavian fusion, warm woods, low-profile furniture, serene neutrals",
+    "mid-century-modern": "mid-century modern — walnut and teak furniture, organic curves, retro accents",
+    "industrial": "industrial loft — exposed brick and metal, dark tones, raw finishes",
+    "bohemian": "bohemian — layered patterns and textures, plants, warm eclectic decor",
+    "modern-farmhouse": "modern farmhouse — shiplap accents, warm woods, black fixtures, cozy rustic-meets-clean",
+    "coastal": "coastal — airy whites and blues, natural fibers, beach-house freshness",
+    "traditional": "traditional — classic furniture silhouettes, rich woods, elegant symmetry",
+    "contemporary": "contemporary — current-day polish, mixed materials, comfortable sophistication",
+    "rustic": "rustic — reclaimed wood, stone textures, warm cabin comfort",
+    "french-country": "French country — soft pastels, carved wood, linen fabrics, Provencal charm",
+    "mediterranean": "Mediterranean — terracotta, wrought iron, warm plaster walls, arched details",
+    "art-deco": "Art Deco — geometric patterns, brass and velvet, glamorous jewel tones",
+    "modern-luxury": "modern luxury — marble, brass details, statement lighting, hotel-suite polish",
+    "vintage": "vintage retro — curated second-hand furniture, nostalgic colors, timeless character",
+    "dark-academia": "dark academia — moody deep tones, wood paneling, library-inspired warmth",
+    "tropical": "tropical — lush green plants, rattan and bamboo, resort-like brightness",
+    "cottagecore": "cottagecore — floral patterns, soft vintage furniture, whimsical countryside coziness",
+    "transitional": "transitional — traditional silhouettes with contemporary lines, soft neutral palette",
+    "spanish-colonial-revival": "Spanish Colonial Revival — white stucco, dark carved wood beams, terracotta tile, arched openings",
+    "2026-trends": "2026 interior trends — organic curved furniture, earthy color-drenched walls, sculptural lighting",
+}
+
+# room/space id -> human-readable name (mirror of app/options.py)
+ROOM_LABELS: dict[str, str] = {
+    # interior
+    "kitchen": "kitchen",
+    "living-room": "living room",
+    "bedroom": "bedroom",
+    "bathroom": "bathroom",
+    "dining-room": "dining room",
+    "home-office": "home office",
+    "kids-room": "kids room",
+    "nursery": "nursery",
+    "basement": "basement",
+    "attic": "attic bedroom",
+    "entryway": "entryway",
+    "laundry-room": "laundry room",
+    "closet": "walk-in closet",
+    "home-theater": "home theater room",
+    "home-gym": "home gym",
+    "wine-cellar": "wine cellar",
+    "basement-bar": "basement bar",
+    "staircase": "staircase and stairwell",
+    # exterior
+    "exterior": "house exterior",
+    # gardens / outdoor
+    "garden": "garden",
+    "backyard": "backyard",
+    "landscape": "yard and surrounding landscape",
+    "patio": "patio and outdoor seating area",
+    "deck": "deck",
+    "porch": "porch",
+    "balcony": "balcony",
+}
+
+# Offline fallback: the id lists as of the last mirror refresh. Used only when
+# the live /options fetch fails (e.g. a sandbox with no network) so tool calls
+# still return something sensible.
+FALLBACK = {
+    "rooms": [
+        "kitchen", "living-room", "bedroom", "bathroom", "dining-room", "home-office",
+        "kids-room", "nursery", "basement", "attic", "entryway", "laundry-room", "closet",
+        "home-theater", "home-gym", "wine-cellar", "basement-bar", "staircase",
+    ],
+    "exteriors": ["exterior"],
+    "gardens": ["garden", "backyard", "landscape", "patio", "deck", "porch", "balcony"],
+    "styles": list(STYLE_LABELS),
+}
+
+
+class Catalog(dict):
+    """Catalog payload: rooms/exteriors/gardens/styles plus a ``live`` flag.
+
+    A dict subclass keeps attribute access convenient while remaining easy to
+    print or serialise.
+    """
+
+    @property
+    def rooms(self) -> list[str]:
+        return self["rooms"]
+
+    @property
+    def exteriors(self) -> list[str]:
+        return self["exteriors"]
+
+    @property
+    def gardens(self) -> list[str]:
+        return self["gardens"]
+
+    @property
+    def styles(self) -> list[str]:
+        return self["styles"]
+
+    @property
+    def live(self) -> bool:
+        return self["live"]
+
+
+_cache: dict[str, Any] = {"at": 0.0, "data": None}
+_TTL_SECONDS = 10 * 60
+
+
+def _strings(payload: dict[str, Any], key: str) -> list[str]:
+    value = payload.get(key)
+    if isinstance(value, list):
+        return [item for item in value if isinstance(item, str)]
+    return []
+
+
+async def get_catalog() -> Catalog:
+    """Fetch the live taxonomy from /options, cached for 10 min, falling back to
+    the bundled lists if the network is unavailable.
+    """
+    cached = _cache["data"]
+    if cached is not None and time.monotonic() - _cache["at"] < _TTL_SECONDS:
+        return cached
+    try:
+        async with httpx.AsyncClient(timeout=8.0, follow_redirects=True) as client:
+            response = await client.get(f"{API_BASE}/options")
+        response.raise_for_status()
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ValueError("/options payload is not an object")
+
+        def arr(key: str) -> list[str]:
+            return _strings(payload, key)
+
+        data = Catalog(
+            rooms=arr("rooms") or FALLBACK["rooms"],
+            exteriors=arr("exteriors") or FALLBACK["exteriors"],
+            gardens=arr("gardens") or FALLBACK["gardens"],
+            styles=arr("styles") or FALLBACK["styles"],
+            live=True,
+        )
+    except Exception:
+        data = Catalog(
+            rooms=list(FALLBACK["rooms"]),
+            exteriors=list(FALLBACK["exteriors"]),
+            gardens=list(FALLBACK["gardens"]),
+            styles=list(FALLBACK["styles"]),
+            live=False,
+        )
+    _cache["at"] = time.monotonic()
+    _cache["data"] = data
+    return data
+
+
+def _title_case(room_id: str) -> str:
+    text = room_id.replace("-", " ")
+    return re.sub(r"\b\w", lambda match: match.group(0).upper(), text, flags=re.ASCII)
+
+
+def style_label(style_id: str) -> str:
+    return STYLE_LABELS.get(style_id) or _title_case(style_id)
+
+
+def room_label(room_id: str) -> str:
+    return ROOM_LABELS.get(room_id) or _title_case(room_id)
+
+
+def design_link(room: str, style: str | None = None) -> str:
+    """Build the deep link that opens the Roomvana studio with a room (and,
+    optionally, a style) pre-selected. Verified against DesignTool.tsx, which
+    reads ?room= and ?style= at mount.
+    """
+    params = {"room": room}
+    if style:
+        params["style"] = style
+    return f"{SITE_BASE}/design?{urlencode(params)}"