Hot-reloads changed Python modules at variable-level granularity so an AI client's MCP server keeps state and connections alive.
Also known as promplate/hmr
- Stars
- 60
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.2
- Last commit
- Nov 13, 2026
- License
- —
What is HMR MCP?
HMR is an MCP server. Hot-reloads changed Python modules at variable-level granularity so an AI client's MCP server keeps state and connections alive.
Summary generated from the project's README
About HMR MCP server
Updating Python code during development without losing active connections or application state is the primary function of hmr. It provides a reactive programming engine that enables variable-level hot module reloading, allowing developers to modify specific parts of a codebase while the process remains running. This is particularly useful for long-running tasks like machine learning services where full restarts are time-consuming.
Developers can use this tool via the command line by running hmr followed by an entry file path, or through uvx. The system uses runtime dependency tracking and a signal and observer pattern to identify exactly which modules need to rerun when a change occurs. This approach is more precise than traditional reloaders that restart the entire process upon any file modification.
The ecosystem includes specialized packages such as mcp-hmr for live updates to MCP servers, uvicorn-hmr for ASGI applications, and fastapi-reloader for browser synchronization. By tracking file system changes through watchfiles and monitoring file reads via sys.addaudithook, the engine can react to updates in both Python modules and non-Python files like JSON or YAML.
What you can do with it
- 1Enable fine-grained reactive updatesTrigger reloads only for the specific modules affected by a variable change rather than restarting the whole app.
Written from the project's README. Every use case is checked against a quote from it.
How to install HMR MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall HMR MCP in Claude Code
$ claude mcp add --transport http hmr https://pyth-on-line.promplate.dev/hmr/mcpInstall HMR MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hmr": {
"url": "https://pyth-on-line.promplate.dev/hmr/mcp"
}
}
}Install HMR MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hmr": {
"type": "http",
"url": "https://pyth-on-line.promplate.dev/hmr/mcp"
}
}
}Install HMR MCP in VS Code CLI
$ code --add-mcp '{"name":"hmr","type":"http","url":"https://pyth-on-line.promplate.dev/hmr/mcp"}'Install HMR MCP in Codex
$ codex mcp add hmr --url https://pyth-on-line.promplate.dev/hmr/mcpInstall HMR MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hmr] url = "https://pyth-on-line.promplate.dev/hmr/mcp"
Install HMR MCP in Gemini CLI
$ gemini mcp add -s user --transport http hmr https://pyth-on-line.promplate.dev/hmr/mcpInstall HMR MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hmr": {
"url": "https://pyth-on-line.promplate.dev/hmr/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablepromplate/hmr is public and reachablegithub.com/promplate/hmr ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-11github.com/promplate/hmr ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 235 msPass
README
View on GitHubHMR for Python
HMR provides a pythonic, flexible, progressive-yet-intuitive reactive programming engine / framework, and on top of that, a fine-grained, on-demand hot-reload tool.
In Python, HMR stands for Hot Module Reload, though in JavaScript it commonly refers to Hot Module Replacement—essentially the same concept. It is a feature that allows part of your app to be updated at runtime without a full rerun, without needing to restart the entire process.
Unlike traditional Python reloaders (such as watchfiles CLI, uvicorn --reload, or Flask's debug mode), HMR is much more efficient and robust. These tools typically restart the entire process whenever a file changes, which is wasteful. HMR instead intelligently reruns only what's necessary, keeping your app state intact.
https://github.com/user-attachments/assets/f9ac6302-44dc-4a6d-86ae-f299fae7be80
Imagine you're developing an ML service using FastAPI with a model that requires 5 seconds to initialize. When using uvicorn --reload, any change—even updating a simple docstring—triggers a full process restart, forcing you to wait those 5 seconds every time. It's as frustrating as encountering a red light at every intersection.
HMR offers a smoother experience. Changes take effect instantly because HMR is variable-level fine-grained: your codebase functions like a dependency graph—when you modify a file, HMR only reruns the affected modules from that modified module up to your entry point file. If you update a variable that nothing depends on, nothing happens.
[!CAUTION]
What this package is not?
hmrshould not be confused with client-side hot reloading that updates browser content when server code changes. This package implements server-side HMR, which only reloads python code upon changes.
Usage
The quickest way to experience HMR is through the CLI:
pip install hmr
hmr path/to/your/entry-file.py
Parameters work exactly like python command, except your files now hot-reload on changes. Try saving files to see instant updates without losing state.
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 |
Reactive programming library and HMR core implementation |
uvicorn-hmr |
HMR-enabled Uvicorn server for ASGI apps (FastAPI, Starlette, etc.) |
mcp-hmr |
HMR-enabled MCP / FastMCP servers |
hmr-daemon |
Background daemon that refreshes modules on changes |
fastapi-reloader |
Browser auto-refresh middleware for automatic page reloading |
[!TIP] The hmr ecosystem is essentially 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/- Basic script with hot module reloadingfastapi/- FastAPI server with hot reloading and browser refreshflask/- Flask app with hot module reloadingmcp/- MCP server with live code updates without connection drops
Motivation
HMR is already a common feature in the frontend world. Web frameworks like Vite supports syncing changes to the browser without a full refresh. Test frameworks like Vitest supports on-demand updating test results without a full rerun.
So, why not bring this magic to Python?
How it works
HMR uses runtime dependency tracking instead of static analysis to achieve fine-grained reactivity:
- Signal & Observer Pattern: Signal is an alternative to the observer pattern. I implemented a simple signal system to notify changes whenever data is accessed or modified.
- Custom Module Class: I implemented a custom Module class which tracks every
__getattr__and__setattr__call. When a variable is changed, it notifies the modules that use it. This notification is recursive but fine-grained. - File System Tracking:
watchfilesis used to detect file changes. If a change's path is a Python module that has been imported, it triggers reloading of affected code. Additionally, HMR monitors all file reads (viasys.addaudithook) so changes to non-Python files (YAML, JSON, etc.) also trigger appropriate reloads.
This runtime approach enables variable-level granularity and can track dependencies across any file type—far more precise than static analysis.
Contributing
This might just be one of the first variable-level fine-grained HMR frameworks in the Python ecosystem—and honestly, the real magic lies in the ecosystem we build around it.
Pair uvicorn + hmr, and you've got yourself a Vite-like development experience. Combine pytest + hmr for test-driven development that rivals Vitest. The possibilities with other libraries? Endless. Let's brainstorm together—who knows what fun (or mildly chaotic) things we might create!
[!TIP] A little backstory: the code for hmr lives in another repo because, truth be told, I wasn't planning on building an HMR framework. This started as an experiment in bringing reactive programming to Python. Along the way, I realized: why not make a module's globals reactive? And that's how HMR was born! While it began as a side project, I see tremendous potential in it for advancing Python's development experience.
For now, this repo is home to the main implementation and examples. If you think HMR has potential, or you just want to throw ideas around, I'd love to hear from you. We believe that the Python community deserves a more dynamic, responsive development experience, and we're excited to see where this can take us!
Further reading
About fine-grained reactivity, I recommend reading SolidJS’s excellent explanation.
HMR MCP questions
How do I add HMR MCP to Claude Code?
Run claude mcp add --transport http hmr https://pyth-on-line.promplate.dev/hmr/mcp in your terminal. Add --scope user to make it available in every project.
How do I add HMR MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What is HMR for Python?
HMR is a reactive programming engine and hot-reload tool that reruns only the affected modules when files change, keeping application state intact instead of restarting the process.
How do I run a script with hot reload?
Install the package with pip and run the hmr CLI with the path to your entry file; arguments work like the python command but files hot-reload on changes.
Can I use HMR with MCP or FastMCP servers?
Yes, the ecosystem includes mcp-hmr, an HMR-enabled MCP / FastMCP server, so code updates apply without dropping connections.
How does HMR detect which code to reload?
It uses runtime dependency tracking with a signal system, a custom Module class, and watchfiles-based file tracking, plus an audit hook to catch non-Python file reads.
Does HMR reload browser content when server code changes?
No, this package implements server-side HMR that only reloads Python code on changes; browser refresh is a separate middleware.