From 0def4fc8023d556c1c3ea7f5072f231bd3da8d80 Mon Sep 17 00:00:00 2001 From: butschster Date: Sun, 18 Jan 2026 11:24:43 +0400 Subject: [PATCH] feat: implement hot-reload for MCP server configuration Add automatic configuration hot-reload that detects changes in context.yaml and updates tools/prompts without server restart. --- docs/.vitepress/config.mts | 1 + docs/mcp/hot-reload.md | 249 +++++++++++++++++++++++++++++++++++++ docs/mcp/index.md | 14 +++ 3 files changed, 264 insertions(+) create mode 100644 docs/mcp/hot-reload.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 5eafb8a..e417293 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -52,6 +52,7 @@ export default withMermaid({ items: [ {text: 'Integration', link: '/mcp'}, {text: 'Configuration', link: '/mcp/config'}, + {text: 'Hot-Reload', link: '/mcp/hot-reload'}, {text: 'HTTP Server', link: '/mcp/http'}, {text: 'Docker', link: '/mcp/docker'}, {text: 'Projects', link: '/mcp/projects'}, diff --git a/docs/mcp/hot-reload.md b/docs/mcp/hot-reload.md new file mode 100644 index 0000000..c502944 --- /dev/null +++ b/docs/mcp/hot-reload.md @@ -0,0 +1,249 @@ +# Hot-Reload Configuration + +The MCP Server supports automatic hot-reload of configuration changes. When you modify your `context.yaml` file, the +server detects the changes and updates tools, prompts, and resources without requiring a restart. + +## Overview + +Hot-reload eliminates the need to restart the MCP server when making configuration changes. This is especially useful +during development when you're iterating on custom tools or prompts. + +### Benefits + +- **No restart required** - Changes are applied automatically within seconds +- **No client reconnection** - MCP clients stay connected during updates +- **Preserves conversation context** - AI assistants maintain their conversation state +- **Rapid iteration** - Test new tools and prompts immediately + +## How It Works + +```mermaid +sequenceDiagram + participant Editor as "Your Editor" + participant Watcher as "Config Watcher" + participant Registry as "Tool/Prompt Registry" + participant Client as "MCP Client" + + Editor->>Editor: Save context.yaml + Watcher->>Watcher: Detect file change + Watcher->>Watcher: Parse new config + Watcher->>Watcher: Calculate diff + Watcher->>Registry: Apply changes + Registry->>Client: ToolListChangedNotification + Client->>Client: Refresh tool list +``` + +1. **File Watching** - The server monitors your configuration files for changes +2. **Change Detection** - When a file is modified, the server calculates what changed +3. **Incremental Updates** - Only the changed items are updated (added, removed, or modified) +4. **Client Notification** - Connected MCP clients receive notifications about the changes + +## Configuration + +Hot-reload is **enabled by default**. You can configure it using environment variables: + +| Variable | Default | Description | +|----------|---------|-------------| +| `MCP_HOT_RELOAD` | `true` | Enable or disable hot-reload | +| `MCP_HOT_RELOAD_INTERVAL` | `2000` | Polling interval in milliseconds | + +### Disabling Hot-Reload + +To disable hot-reload, set the environment variable before starting the server: + +```bash +MCP_HOT_RELOAD=false ctx server +``` + +Or in your MCP client configuration: + +```json +{ + "mcpServers": { + "ctx": { + "command": "ctx", + "args": ["server", "-c", "/path/to/project"], + "env": { + "MCP_HOT_RELOAD": "false" + } + } + } +} +``` + +### Adjusting Poll Interval + +If you want faster or slower change detection: + +```bash +# Check every 500ms for faster updates +MCP_HOT_RELOAD_INTERVAL=500 ctx server + +# Check every 5 seconds for lower CPU usage +MCP_HOT_RELOAD_INTERVAL=5000 ctx server +``` + +## Watch Strategies + +The server automatically selects the best file watching strategy for your platform: + +| Strategy | Platform | Description | +|----------|----------|-------------| +| **inotify** | Linux | Kernel-level file system events, zero CPU when idle | +| **Polling** | All platforms | Checks file modification time periodically | + +### Linux with inotify + +On Linux systems with the `inotify` PHP extension installed, the server uses kernel-level file watching. This is the +most efficient option with virtually no CPU overhead when files aren't changing. + +To install the inotify extension: + +```bash +pecl install inotify +``` + +### Polling Fallback + +On macOS, Windows, or Linux without inotify, the server falls back to polling. This checks file modification times at +the configured interval (default: 2 seconds). + +## What Gets Reloaded + +Hot-reload supports the following configuration sections: + +| Section | Supported | Notes | +|---------|-----------|-------| +| `tools` | ✅ Yes | Custom tools are added, removed, or updated | +| `prompts` | ✅ Yes | Prompts are added, removed, or updated | +| `documents` | ⚠️ Partial | Document definitions reload, but cached content may persist | + +### Example: Adding a New Tool + +1. Your server is running with this configuration: + +```yaml +tools: + - id: list-files + description: List files in directory + commands: + - name: ls + args: ["-la"] +``` + +2. You add a new tool to `context.yaml`: + +```yaml +tools: + - id: list-files + description: List files in directory + commands: + - name: ls + args: ["-la"] + + - id: disk-usage # New tool + description: Show disk usage + commands: + - name: df + args: ["-h"] +``` + +3. Save the file - within 2-3 seconds: + - The server detects the change + - Parses the new configuration + - Registers the `disk-usage` tool + - Sends `ToolListChangedNotification` to clients + - Your AI assistant can now use the new tool + +## Error Handling + +Hot-reload is designed to be resilient: + +### Invalid Configuration + +If you save a configuration with syntax errors: +- The server **keeps the previous valid configuration** +- An error is logged for debugging +- No crash or restart required +- Fix the error and save again + +### Partial Failures + +If one tool fails to register: +- Other tools continue to register normally +- The failed tool is logged +- The server remains operational + +## Debouncing + +To handle rapid file saves (common with auto-save features), the server implements debouncing: + +- Changes are detected immediately +- A 200ms delay is applied before processing +- Multiple rapid saves result in a single reload +- This prevents unnecessary processing during active editing + +## Monitoring + +You can monitor hot-reload activity in the server logs: + +``` +[INFO] Starting config watcher +[DEBUG] Config file changes detected: ["/path/to/context.yaml"] +[INFO] Processing config changes +[INFO] Applied changes: tools: 1 added +[DEBUG] Emitted tools list_changed notification +``` + +## Troubleshooting + +### Changes Not Detected + +1. **Check if hot-reload is enabled:** + ```bash + # Ensure MCP_HOT_RELOAD is not set to false + echo $MCP_HOT_RELOAD + ``` + +2. **Verify file permissions:** + The server needs read access to your configuration files. + +3. **Check the logs:** + Look for watcher-related messages in the server output. + +### High CPU Usage + +If you notice high CPU usage with polling: + +1. **Increase the poll interval:** + ```bash + MCP_HOT_RELOAD_INTERVAL=5000 ctx server + ``` + +2. **Install inotify (Linux):** + ```bash + pecl install inotify + ``` + +3. **Disable hot-reload** if not needed: + ```bash + MCP_HOT_RELOAD=false ctx server + ``` + +### Client Not Receiving Updates + +1. **Verify client supports notifications:** + Not all MCP clients support `list_changed` notifications. + +2. **Check client connection:** + The client must maintain an active connection to receive notifications. + +3. **Refresh manually:** + Some clients may require manual refresh of the tool list. + +## Best Practices + +1. **Use version control** - Track your configuration changes with git +2. **Test incrementally** - Add one tool at a time to isolate issues +3. **Monitor logs** - Watch for errors during development +4. **Keep configs valid** - Use IDE schema validation to catch errors before save diff --git a/docs/mcp/index.md b/docs/mcp/index.md index fec7d6e..c2a1fbd 100644 --- a/docs/mcp/index.md +++ b/docs/mcp/index.md @@ -14,6 +14,8 @@ This allows AI models to request specific information about your codebase withou - [Quick Start](#quick-start) - [Configuration Guide](#configuration-guide) - [HTTP Server Mode](#http-server-mode) +- [Dynamic Projects Switching](#dynamic-projects-switching) +- [Hot-Reload Configuration](#hot-reload-configuration) ## How Integration Works @@ -168,3 +170,15 @@ SSE (Server-Sent Events). Learn more about [HTTP Server Configuration](http.md). The MCP server supports dynamic project switching, allowing you to work with multiple projects. Read more about dynamic project switching in the [Projects](projects.md) section. + +## Hot-Reload Configuration + +The MCP server supports automatic hot-reload of configuration changes. When you modify your `context.yaml` file, +tools, prompts, and resources are updated automatically without requiring a server restart. + +Key features: +- **No restart required** - Changes apply within seconds +- **No client reconnection** - MCP clients stay connected +- **Incremental updates** - Only changed items are processed + +Learn more in the [Hot-Reload Configuration](hot-reload.md) guide.