Merge branch 'readme' into mcp-anyio

Author: CNSeniorious000

.github/workflows/ci.yml

@@ -12,15 +12,16 @@ jobs:
   check:
     strategy:
       matrix:
-        os: [ubuntu, macos]
+        os: [ubuntu, macos, windows]
+        py: ["3.12", "3.13", "3.14"]
       fail-fast: false
     runs-on: ${{ matrix.os }}-latest
     steps:
       - uses: actions/checkout@v5
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.py }}
         uses: astral-sh/setup-uv@v7
         with:
-          python-version: 3.13
+          python-version: ${{ matrix.py }}
           activate-environment: true
       - name: Install dependencies
         run: |
@@ -55,14 +56,14 @@ jobs:
       - name: Set up Python
         uses: astral-sh/setup-uv@v7
         with:
-          python-version: 3.13
+          python-version: 3.14
       - name: Remove admonitions from READMEs
         run: |
           find . -type f -name "README.md" -exec sed -i -E '/^> \[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]$/d' {} +
       - name: Remove all noqa comments
         run: |
           uvx ruff check --select RUF100 --show-fixes --fix packages/${{ matrix.dir }}
-      - name: Build packages
+      - name: Build wheel for ${{ matrix.dir }}
         run: |
           uv build packages/${{ matrix.dir }} --wheel
       - name: Publish to PyPI

README.md

@@ -36,11 +36,29 @@ If you have `uv` installed, you can try `hmr` directly with:
 uvx hmr path/to/your/entry-file.py
 ```
 
+## Ecosystem
+
+HMR provides a rich ecosystem of tools for different Python development scenarios:
+
+| Package                                            | Use Case                                                     |
+| -------------------------------------------------- | ------------------------------------------------------------ |
+| [`hmr`][repo]                                      | Reactive programming lib and HMR core implementation         |
+| [`uvicorn-hmr`](./packages/uvicorn-hmr/)           | HMR-enabled Uvicorn server for ASGI apps                     |
+| [`mcp-hmr`](./packages/mcp-hmr/)                   | HMR-enabled MCP / FastMCP servers                            |
+| [`hmr-daemon`](./packages/hmr-daemon/)             | Background daemon that refreshes modules on changes          |
+| [`fastapi-reloader`](./packages/fastapi-reloader/) | Browser auto-refresh middleware for automatic page reloading |
+
 > [!TIP]
-> The hmr ecosystem is now production-ready. It has been carefully designed to handle many common edge cases and Pythonic *magic* patterns, including lazy imports, circular dependencies, dynamic imports, module-level `__getattr__`, decorators, and more. You can confidently use hmr in production environments if needed.
+> The hmr ecosystem is basically stable and production-ready for most use cases. It has been carefully designed to handle many common edge cases and Pythonic *magic* patterns, including lazy imports, dynamic imports, module-level `__getattr__`, decorators, and more. However, circular dependencies in some edge cases may still cause unexpected behavior. Use with caution if you have a lot of code in `__init__.py`.
 
 https://github.com/user-attachments/assets/fb247649-193d-4eed-b778-05b02d47c3f6
 
+## Other demos
+
+- [`demo/`](./examples/demo/) - Basic script with hot module reloading
+- [`fastapi/`](./examples/fastapi/) - FastAPI server with hot reloading and browser refresh
+- [`flask/`](./examples/flask/) - Flask app with hot module reloading
+- [`mcp/`](./examples/mcp/) - MCP server with live code updates without connection drops
 
 ## Motivation
 

examples/fastapi/pyproject.toml

@@ -3,7 +3,7 @@ name = "fastapi-example"
 version = "0"
 requires-python = ">=3.12"
 dependencies = [
-    "fastapi~=0.119.0",
+    "fastapi~=0.120.0",
     "uvicorn-hmr[all]",
 ]
 

examples/mcp/README.md

@@ -0,0 +1,43 @@
+# MCP Example
+
+This example demonstrates how to use `mcp-hmr` with a FastMCP server.
+
+First, install the required dependencies and activate the venv:
+
+```sh
+uv sync
+source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+```
+
+## Demo 1 - with `@modelcontextprotocol/inspector`
+
+First, open the inspector with `npx` / `pnpx` / `bunx`, etc:
+
+```sh
+npx @modelcontextprotocol/inspector --config mcp.json --server main
+```
+
+Click the "Connect" button in the inspector UI. It will connect to the MCP server with `mcp-hmr main.py:app`.
+
+<img width="3200" height="1116" alt="The MCP Inspector" src="https://github.com/user-attachments/assets/3e96039f-2720-4b14-be4d-2a54678d49dc" />
+
+Now you can view the resources and tools as normal. Then change them in `main.py` and save the file WITHOUT clicking "Restart" in the inspector. Any call to get the resource / run the tool will reflect the updated code.
+
+https://github.com/user-attachments/assets/fe8810a3-916d-49ab-91e5-5a595ae0b3f9
+
+## Demo 2 - with FastMCP client
+
+Run the client to start and use the server:
+
+```sh
+python client.py
+```
+
+It uses the MCP server defined in `main.py`. Now open your favorite editor and modify `main.py` to see the printing update in real-time!
+
+## What to Observe
+
+- Try changing the `echo` tool's return value or the `greet` resource's content.
+- You will see the client output update to reflect your changes without restarting the connection.
+
+This demo shows how to use `mcp-hmr` to enable seamless hot reloading for MCP servers, maintaining the connection between client and server while updating the code on-the-fly.

examples/mcp/client.py

@@ -0,0 +1,29 @@
+from contextlib import suppress
+from pathlib import Path
+
+from anyio import run, sleep
+from fastmcp import Client
+
+config = {
+    "mcpServers": {
+        "": {
+            "transport": "stdio",
+            "command": "mcp-hmr",
+            "args": [f"{Path(__file__).parent / 'main.py'}:app"],
+        },
+    }
+}
+
+
+with suppress(KeyboardInterrupt):
+
+    @run
+    async def _():
+        async with Client(config) as client:
+            while True:
+                print("\033c", end="")  # clear the console
+
+                print("from tool echo:", (await client.call_tool("echo", {"message": "Hello from HMR!"})).content[0].text)  # type: ignore
+                print("from resource example://greet:", (await client.read_resource("example://greet"))[0].text)  # type: ignore
+
+                await sleep(1)

examples/mcp/main.py

@@ -0,0 +1,22 @@
+from fastmcp import FastMCP
+
+# from mcp.server.fastmcp import FastMCP  # FastMCP v1 is also supported!
+
+
+app = FastMCP()
+
+
+@app.tool()
+def echo(message: str):
+    return message
+
+
+@app.resource("example://greet")
+def greet():
+    return "hello world"
+
+
+# `mcp-hmr main:app` is equivalent to:
+
+if __name__ == "__main__":
+    app.run("stdio")

examples/mcp/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "main": {
+      "command": "mcp-hmr",
+      "args": ["main.py:app"]
+    }
+  }
+}

examples/mcp/pyproject.toml

@@ -0,0 +1,14 @@
+[project]
+name = "mcp-example"
+version = "0"
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp~=2.12.5",
+    "mcp-hmr",
+]
+
+[tool.uv]
+package = false
+
+[tool.uv.sources]
+mcp-hmr = { workspace = true }

packages/mcp-hmr/README.md

@@ -5,22 +5,22 @@
 
 Provides [Hot Module Reloading](https://pyth-on-line.promplate.dev/hmr) for MCP/FastMCP servers.
 
-It acts as **a drop-in replacement for `mcp run module:app` or `fastmcp run module:app`.** Both [FastMCP v2](https://github.com/jlowin/fastmcp) and the [official python SDK](https://github.com/modelcontextprotocol/python-sdk) are supported.
+It acts as **a drop-in replacement for `mcp run path:app` or `fastmcp run path:app`.** Both [FastMCP v2](https://github.com/jlowin/fastmcp) and the [official python SDK](https://github.com/modelcontextprotocol/python-sdk) are supported.
 
 ## Usage
 
-If your server instance is named `app` in `path/to/main.py`, you can run:
+If your server instance is named `app` in `./path/to/main.py`, you can run:
 
 ```sh
-mcp-hmr path.to.main:app
+mcp-hmr ./path/to/main.py:app
 ```
 
-Which will be equivalent to the following code but with [HMR](https://github.com/promplate/hmr) enabled:
+Which will be equivalent to `fastmcp run ./path/to/main.py:app` but with [HMR](https://github.com/promplate/hmr) enabled.
 
-```py
-from path.to.main import app
+Or using module import format:
 
-app.run("stdio")
+```sh
+mcp-hmr main:app
 ```
 
 Now, whenever you save changes to your source code, the server will automatically reload without dropping the connection to the client.

packages/mcp-hmr/mcp_hmr.py

@@ -1,20 +1,23 @@
 import sys
+from importlib import import_module
+from importlib.machinery import ModuleSpec
+from importlib.util import find_spec, module_from_spec
+from pathlib import Path
 
-__version__ = "0.0.1"
+__version__ = "0.0.2.3"
 
 
 async def run_with_hmr(target: str, log_level: str | None = None):
-    module, attr = target.split(":")
+    module, attr = target.rsplit(":", 1)
 
-    from contextlib import contextmanager
-    from importlib import import_module
+    from contextlib import contextmanager, suppress
 
     import mcp.server
     from anyio import Event, Lock, create_task_group
     from fastmcp import FastMCP
     from fastmcp.server.proxy import ProxyClient
     from reactivity import async_effect, derived
-    from reactivity.hmr.core import HMR_CONTEXT, AsyncReloader
+    from reactivity.hmr.core import HMR_CONTEXT, AsyncReloader, _loader
     from reactivity.hmr.hooks import call_post_reload_hooks, call_pre_reload_hooks
 
     base_app = FastMCP(name="proxy", include_fastmcp_meta=False)
@@ -28,9 +31,10 @@ def mount(app: FastMCP | mcp.server.FastMCP):
             for mounted_server in list(base_app._mounted_servers):  # noqa: SLF001
                 if mounted_server.server is proxy:
                     base_app._mounted_servers.remove(mounted_server)  # noqa: SLF001
-                    base_app._tool_manager._mounted_servers.remove(mounted_server)  # noqa: SLF001
-                    base_app._resource_manager._mounted_servers.remove(mounted_server)  # noqa: SLF001
-                    base_app._prompt_manager._mounted_servers.remove(mounted_server)  # noqa: SLF001
+                    with suppress(AttributeError):
+                        base_app._tool_manager._mounted_servers.remove(mounted_server)  # noqa: SLF001
+                        base_app._resource_manager._mounted_servers.remove(mounted_server)  # noqa: SLF001
+                        base_app._prompt_manager._mounted_servers.remove(mounted_server)  # noqa: SLF001
                     break
 
     lock = Lock()
@@ -41,9 +45,17 @@ async def using(app: FastMCP | mcp.server.FastMCP, stop_event: Event, finish_eve
                 await stop_event.wait()
                 finish_event.set()
 
-    @derived(context=HMR_CONTEXT)
-    def get_app():
-        return getattr(import_module(module), attr)
+    if Path(module).is_file():  # module:attr
+
+        @derived(context=HMR_CONTEXT)
+        def get_app():
+            return getattr(module_from_spec(ModuleSpec("server_module", _loader, origin=module)), attr)
+
+    else:  # path:attr
+
+        @derived(context=HMR_CONTEXT)
+        def get_app():
+            return getattr(import_module(module), attr)
 
     stop_event: Event | None = None
     finish_event: Event = ...  # type: ignore
@@ -87,8 +99,10 @@ async def __aexit__(self, *_):
 def cli(argv: list[str] = sys.argv[1:]):
     from argparse import SUPPRESS, ArgumentParser
 
-    parser = ArgumentParser(prog="mcp-hmr", description="Hot Reloading for MCP Servers • Automatically reload on code changes")
-    parser.add_argument("target", help="The import path of the FastMCP instance, e.g. `main:app` means `from main import app`", metavar="module:attr")
+    parser = ArgumentParser("mcp-hmr", description="Hot Reloading for MCP Servers • Automatically reload on code changes")
+    if sys.version_info >= (3, 14):
+        parser.suggest_on_error = True
+    parser.add_argument("target", help="The import path of the FastMCP instance. Supports module:attr and path:attr")
     parser.add_argument("-l", "--log-level", choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"], type=str.upper, default=None)
     parser.add_argument("--version", action="version", version=f"mcp-hmr {__version__}", help=SUPPRESS)
 
@@ -100,17 +114,27 @@ def cli(argv: list[str] = sys.argv[1:]):
 
     target: str = args.target
 
-    if target.count(":") != 1 or target.startswith(":") or target.endswith(":"):
-        parser.exit(1, f"The target argument must be in the format 'module:attr', e.g. 'main:app'. Got: '{target}'")
+    if ":" not in target[1:-1]:
+        parser.exit(1, f"The target argument must be in the format 'module:attr' (e.g. 'main:app') or 'path:attr' (e.g. './path/to/main.py:app'). Got: '{target}'")
 
     from contextlib import suppress
-    from pathlib import Path
 
     from anyio import run
 
     if (cwd := str(Path.cwd())) not in sys.path:
         sys.path.append(cwd)
 
+    if (file := Path(module_or_path := target[: target.rindex(":")])).is_file():
+        sys.path.insert(0, str(file.parent))
+    else:
+        if "." in module_or_path:  # find_spec may cause implicit imports of parent packages
+            from reactivity.hmr.core import patch_meta_path
+
+            patch_meta_path()
+
+        if find_spec(module_or_path) is None:
+            parser.exit(1, f"The target '{module_or_path}' not found. Please provide a valid module name or a file path.")
+
     with suppress(KeyboardInterrupt):
         run(run_with_hmr, target, args.log_level, backend="trio")