docs: add Windows UV guide and reorganize assets (#34)

* docs: add Windows UV guide and reorganize assets

* Revise Windows UV installation and Claude setup guide

Updated installation instructions for uv and Git, streamlined the setup process, and revised configuration steps for Claude Desktop.

* docs: simplify uv method instructions

* Revise Method 3 for running Python with UV

Updated method description and prerequisites for running Python with UV. Modified command examples for clarity.

* docs: add uvx HTTP mode; feat: add ha-mcp-web console script

* docs: switch Method 3 web client to uvx ha-mcp-web and simplify instructions

* docs: restore cloudflared guidance for uvx web clients

* docs: clean uvx method prerequisites and web instructions

* docs: generalize web client instructions

* Revise README for UV setup and client configuration

Updated prerequisites and instructions for running Python with UV, including environment variable setup and Cloudflare Tunnel usage.

* Update README with Cloudflare Tunnel instructions

Clarify instructions for using Cloudflare Tunnel with public URL.

* Clarify HTTP entry point comment in __main__.py

Updated comment to clarify the HTTP entry point for web clients.

* Update winget command and args format in guide

* Update README.md

* Update contributor links in README.md

---------

Co-authored-by: julienld <julien@LAPTOP.localdomain>

Author: julienld

README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="img/ha-mcp-logo.png" alt="Home Assistant MCP Server Logo" width="300"/>
+  <img src="docs/img/ha-mcp-logo.png" alt="Home Assistant MCP Server Logo" width="300"/>
 
   # The Unofficial and Awesome Home Assistant MCP Server
 
@@ -22,7 +22,7 @@
 
 ---
 
-![Home Assistant MCP Demo](img/demo.webp)
+![Home Assistant MCP Demo](docs/img/demo.webp)
 
 **[YouTube version →](https://youtu.be/eCO93KfSvIM)**
 
@@ -182,114 +182,91 @@ claude mcp add-json home-assistant '{
 
 ---
 
-### Method 3: Python+UV
+### Method 3: Running Python with UV
 
 **Best for:** When Docker is not available
 
-**Prerequisites:**
-- [Git](ttps://git-scm.com/downloads)
-- [UV package manager](https://docs.astral.sh/uv/getting-started/installation/)
-- A long-lived token: ** Home Assistant → Your Profile → Security → Long-Lived Access Tokens
-
-**Installation Steps:**
-
-1. **Clone the repository:**
-   ```bash
-   git clone https://github.com/homeassistant-ai/ha-mcp
-   cd ha-mcp
-   ```
+> **Windows users:** Follow the [Windows UV setup guide](docs/Windows-uv-guide.md)
 
-2. **(optional) Install dependencies and make sure uv is working:**
-   ```bash
-   uv sync
-   ```
+**Prerequisites:**
+- [UV package manager](https://docs.astral.sh/uv/getting-started/installation/) and [Git binary](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+  - Windows: winget install astral-sh.uv Git.Git -e
+  - MacOS: brew install git uv
+- Your Home assistant URL (ex: http://localhost:8123) for HOMEASSISTANT_URL variable
+- A Home Assistant long-lived access token (Profile → Security → Long-Lived Access Tokens) for HOMEASSISTANT_TOKEN variable
 
 **Client Configuration:**
 
 <details>
 <summary><b>📱 Claude Desktop or any mcp.json format</b></summary>
 
-**Location:**
+**Config file:**
 - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Add to your `mcp.json`:
-
-Linux/WSL/macOS:
-```json
-{
-  "mcpServers": {
-
-    "Home Assistant": {
-      "command": "path/to/ha-mcp/run_mcp_server.sh",
-      "args": [],
-      "env": {
-        "HOMEASSISTANT_URL": "http://localhost:8123",
-        "HOMEASSISTANT_TOKEN": "your_long_lived_access_token_from_home_assistant_profile"
-      }
-    }
-
-  }
-}
-```
-
-Windows:
 ```json
 {
   "mcpServers": {
-
     "Home Assistant": {
-      "command": "C:\\path\\to\\ha-mcp\\run_mcp_server.bat",
-      "args": [],
+      "command": "uvx",
+      "args": ["--from=git+https://github.com/homeassistant-ai/ha-mcp", "ha-mcp"],
       "env": {
         "HOMEASSISTANT_URL": "http://localhost:8123",
-        "HOMEASSISTANT_TOKEN": "your_long_lived_access_token_from_home_assistant_profile"
+        "HOMEASSISTANT_TOKEN": "your_long_lived_token"
       }
     }
-
   }
 }
 ```
+Note: replace both HOMEASSISTANT_URL and HOMEASSISTANT_TOKEN with your values.
 
 </details>
 
 <details>
 <summary><b>💻 Claude Code</b></summary>
 
 ```bash
-claude mcp add-json home-assistant '{
-  "command": "C:\\path\\to\\ha-mcp\\run_mcp_server.bat",
-  "args": [],
-  "env": {
-    "HOMEASSISTANT_URL": "http://localhost:8123",
-    "HOMEASSISTANT_TOKEN": "your_long_lived_access_token_from_home_assistant_profile"
-  }
-}'
+claude mcp add --transport stdio home-assistant \
+  --env HOMEASSISTANT_URL=http://localhost:8123 \
+  --env HOMEASSISTANT_TOKEN=your_long_lived_token \
+  -- uvx --from=git+https://github.com/homeassistant-ai/ha-mcp ha-mcp
 ```
 
 </details>
 
 <details>
 <summary><b>🌐 Web Clients (Claude.ai, ChatGPT, etc.)</b></summary>
 
-1. **Download cloudflared binary:**
-   - Download from: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
+Run the MCP server with uvx (replace the values of the environement variables):
 
-2. **Start the MCP server with secret path:**
-   ```bash
-   export HOMEASSISTANT_URL=http://localhost:8123
-   export HOMEASSISTANT_TOKEN=your_long_lived_token
-   export MCP_SECRET_PATH=/__my_secret__
-   uv run fastmcp run fastmcp-webclient.json
-   ```
+Windows:
+```bash
+set HOMEASSISTANT_URL=http://localhost:8123
+set HOMEASSISTANT_TOKEN=your_long_lived_token
+set MCP_PORT=8086
+set MCP_SECRET_PATH=/__my_secret__
+uvx --from=git+https://github.com/homeassistant-ai/ha-mcp ha-mcp-web
+```
+Others:
+```bash
+export HOMEASSISTANT_URL=http://localhost:8123
+export HOMEASSISTANT_TOKEN=your_long_lived_token
+export MCP_PORT=8086
+export MCP_SECRET_PATH=/__my_secret__
+uvx --from=git+https://github.com/homeassistant-ai/ha-mcp ha-mcp-web
+```
 
-3. **In another terminal, start Cloudflare Tunnel:**
-   ```bash
-   cloudflared tunnel --url http://localhost:8086
-   ```
+Web client required https and a public URL. You need to use a proxy in front of `http://localhost:8086`.
 
-4. **Use the URL from cloudflared output:** `https://abc-def.trycloudflare.com/__my_secret__`
+Easiest option is to download [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/#latest-release)
 
+**In another terminal, start Cloudflare Tunnel:**
+
+```bash
+cloudflared tunnel --url http://localhost:8086
+```
+
+Use the public url provided and add your secret path like so `https://XYZ.trycloudflare.com/__my_secret__`. This url must be used in your Web client MCP configuration and kept secret.
 </details>
 
 **Development:** See [CONTRIBUTING.md](CONTRIBUTING.md) for testing and contribution guidelines.
@@ -405,3 +382,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[Model Context Protocol](https://modelcontextprotocol.io/)**: Standardized AI-application communication
 - **[Claude Code](https://github.com/anthropics/claude-code)**: AI-powered coding assistant
 
+## 👥 Contributors
+
+- **[@julienld](https://github.com/julienld)** — Project maintainer & core contributor.
+- **[@kingbear2](https://github.com/kingbear2)** — Windows UV setup guide.

docs/Windows-uv-guide.md

@@ -0,0 +1,46 @@
+# Windows UV Setup Guide for ha-mcp
+
+_Based on steps shared by @kingbear2._
+
+This guide walks through running the ha-mcp server locally on Windows with Claude using the [uv](https://docs.astral.sh/uv/) package manager. Expect the process to take about 10 minutes.
+
+## 1. Install uv and git
+
+Open **PowerShell** or **cmd** and run:
+
+```powershell
+winget install astral-sh.uv Git.Git -e
+```
+
+## 2. Configure Claude Desktop
+
+1. Open **Claude Desktop → Settings → Developer → Edit Config**.
+2. Replace `claude_desktop_config.json` with:
+
+    ```json
+    {
+      "mcpServers": {
+        "Home Assistant": {
+          "command": "uvx",
+          "args": ["--from=git+https://github.com/homeassistant-ai/ha-mcp", "ha-mcp"],
+          "env": {
+            "HOMEASSISTANT_URL": "http://homeassistant.local:8123",
+            "HOMEASSISTANT_TOKEN": "your_long_lived_token"
+          }
+        }
+      }
+    }
+    ```
+
+- HOMEASSISTANT_URL: use the same url (https or http) that you use for accessing home assistant
+- HOMEASSISTANT_TOKEN: : click your username on the bottom left of HA, click Security at the top, and scroll all the way down and create a new token. Note: this token will be displayed only once
+
+3. Exit Claude completely, then relaunch it. Under **Settings → Developer** you should see the MCP server running.
+
+Ask Claude to verify access (e.g., “Can you see my Home Assistant interface?”). If it enumerates integrations or entities, the setup succeeded.
+
+## Troubleshooting
+
+- **`uvx` not found:** Re-run the PATH export or use the full path to `uvx.exe`.
+- **Authentication failures:** Regenerate the long-lived token and update Claude’s config.
+- **Server closes immediately:** Check the console log for missing dependencies or incorrect configuration.

img/demo.webp docs/img/demo.webpimg/demo.webp renamed to docs/img/demo.webp

@@ -7,7 +7,7 @@ name = "ha-mcp"
 version = "3.1.6"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.11,<3.14"
 license = {text = "MIT"}
 authors = [
     {name = "Julien", email = "github@qc-h.net"}
@@ -59,6 +59,7 @@ dev = [
 [project.scripts]
 ha-mcp = "ha_mcp.__main__:main"
 hamcp-test-env = "tests.test_env_manager:main"
+ha-mcp-web = "ha_mcp.__main__:main_web"
 
 [tool.setuptools]
 package-dir = {"" = "src"}

img/ha-mcp-logo.png docs/img/ha-mcp-logo.pngimg/ha-mcp-logo.png renamed to docs/img/ha-mcp-logo.png

@@ -1,5 +1,6 @@
 """Home Assistant MCP Server."""
 
+import os
 from ha_mcp.server import HomeAssistantSmartMCPServer  # type: ignore[import-not-found]
 
 # Create server instance once
@@ -15,5 +16,27 @@ def main() -> None:
     mcp.run()
 
 
+# HTTP entry point for web clients
+def main_web() -> None:
+    """Run server over HTTP for web-capable MCP clients.
+
+    Environment:
+    - HOMEASSISTANT_URL (required)
+    - HOMEASSISTANT_TOKEN (required)
+    - MCP_PORT (optional, default: 8086)
+    - MCP_SECRET_PATH (optional, default: "/mcp")
+    """
+
+    port = int(os.getenv("MCP_PORT", "8086"))
+    path = os.getenv("MCP_SECRET_PATH", "/mcp")
+
+    mcp.run(
+        transport="streamable-http",
+        host="0.0.0.0",
+        port=port,
+        path=path,
+    )
+
+
 if __name__ == "__main__":
     main()