Implement mcp-hmr: Hot Module Reloading for Model Context Protocol servers

[Copilot]

This PR introduces mcp-hmr, a new package that brings Hot Module Reload capabilities to Model Context Protocol (MCP) servers, similar to how uvicorn-hmr provides HMR for ASGI applications.

Problem Statement

When developing MCP servers, traditional reload mechanisms restart the entire server process on any code change. This approach has significant drawbacks:

• Slow feedback loops: Large ML models that take seconds to initialize must be reloaded on every change
• State loss: Database connections, caches, and authentication contexts are lost during restarts
• Development friction: Even simple docstring changes trigger full server restarts

Solution

MCP-HMR provides incremental reloading that updates only what changed while preserving long-lived state. Key differences from traditional approaches:

Feature	Traditional Reload	MCP-HMR
Server Restart	Full process restart	Server keeps running
State Loss	All state lost	Preserves long-lived state
Reload Speed	Slow (full initialization)	Fast (incremental updates)
Client Impact	Connection lost	Seamless capability updates

Implementation

Core Components

1. Reactive Registry (registry.py): Uses hmr's fine-grained reactivity to track MCP tools and resources

   @hmr_tool()
   def my_tool(param: str) -> str:
       return f"Processed: {param}"

2. Smart Reloader (reloader.py): Extends SyncReloader with MCP-specific logic for capability change detection and state preservation

3. Protocol Integration (notifications.py): Sends capability change notifications to MCP clients when supported

4. CLI Interface (cli.py): Provides mcp-hmr command with uvicorn-hmr-like options

   mcp-hmr my_server:create_server --reload-include src --reload-exclude .venv

Usage Example

from mcp_hmr import hmr_tool, hmr_resource, begin_module_declare, finalize_module_declare

# Module-level setup for cleanup tracking
_gen = begin_module_declare()

@hmr_tool()
def calculate_sum(x: int, y: int) -> int:
    """Add two numbers together."""
    return x + y

@hmr_resource(uri_template="file://{path}")
def read_file(path: str) -> str:
    """Read file contents."""
    return Path(path).read_text()

# Cleanup registration
finalize_module_declare(_gen)

Key Features

• 🔥 Hot reloading: Updates tools/resources without server restart
• 🧠 Smart dependency tracking: Only reloads what actually changed
• 📡 Protocol-aware: Sends MCP capability change notifications
• 💾 State preservation: Maintains models, connections, caches across reloads
• 🛠️ Easy integration: Simple decorators and CLI interface

Testing

The implementation includes comprehensive verification:

• ✅ Package imports and module structure
• ✅ CLI availability and help system
• ✅ Registry registration and change tracking
• ✅ Reloader creation and file watching
• ✅ Notification system with graceful fallbacks
• ✅ Schema generation utilities

Integration

The package follows the existing workspace patterns:

• Added to workspace dependencies in root pyproject.toml
• Uses PDM backend for consistent build system
• Follows established code quality standards (ruff linting)
• Includes comprehensive README with examples and troubleshooting

This implementation leverages hmr's existing reactive infrastructure while providing MCP-specific functionality, enabling efficient development workflows for MCP server authors.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[hyperlint-ai-deprecated]

PR Change Summary

Introduced the mcp-hmr package for hot module reloading in Model Context Protocol servers, enhancing development efficiency.

• Created package structure and implemented a basic CLI interface.
• Developed a reactive registry system for MCP tools and resources.
• Implemented core reloader logic and protocol notification handling.
• Added comprehensive documentation with usage examples.

Added Files

• packages/mcp-hmr/README.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[hyperlint-ai-deprecated]

PR Change Summary

Introduced the mcp-hmr package for hot module reloading in Model Context Protocol servers, enhancing development efficiency.

• Created package structure and implemented a basic CLI interface.
• Developed a reactive registry system for MCP tools and resources.
• Implemented core reloader logic and protocol notification handling.
• Added comprehensive documentation with usage examples.

Added Files

• packages/mcp-hmr/README.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[CNSeniorious000]

• mcp-hmr #39 is a much simpler approach