Hot-Reload for MCP Server Configuration

[butschster]

Implement automatic hot-reload capability for the MCP server that detects changes in context.yaml configuration files and dynamically updates tools, prompts, and resources without requiring server restart.

---

Problem Statement

Current Behavior

When the MCP server starts, it loads the configuration from context.yaml once during initialization:

// src/McpServer/ActionsBootloader.php
ServerRunnerInterface::class => function (
    McpConfig $config,
    ServerRunner $factory,
    ConfigLoaderInterface $loader,
) {
    $loader->load();  // ← Configuration loaded ONCE at startup
    // ...
}

After this initial load, any changes to context.yaml (adding new tools, modifying prompts, updating resources) are not reflected in the running server until a full restart.

User Pain Points

1. Workflow Disruption: Developers must manually restart the MCP server every time they add or modify tools in context.yaml
2. Client Reconnection: MCP clients (Claude Desktop, Cursor, VS Code, etc.) lose their connection and must re-initialize
3. Context Loss: Ongoing conversations in AI assistants may lose context due to server restart
4. Development Friction: Rapid iteration on custom tools becomes tedious

Use Case Example

A developer is building a custom MCP tool for their project:

# context.yaml
tools:
  - id: my-custom-tool
    name: my-tool
    description: "Does something useful"
    command:
      name: php
      args: ["artisan", "my:command"]

They realize they need to add another tool. Currently, they must:

1. Edit context.yaml
2. Stop the MCP server
3. Restart the MCP server
4. Wait for client reconnection
5. Re-establish conversation context

With hot-reload, steps 2-5 would be eliminated.

---

Proposed Solution

Overview

Implement a ConfigWatcher system that:

1. Monitors context.yaml and all imported configuration files for changes
2. Detects modifications using efficient file watching mechanisms
3. Parses only the changed sections of configuration
4. Updates the appropriate registries (tools, prompts, resources)
5. Emits MCP protocol notifications to inform connected clients

MCP Protocol Support

The MCP specification already supports dynamic list updates through notifications:

Notification	Purpose
notifications/tools/list_changed	Informs clients that available tools have changed
notifications/prompts/list_changed	Informs clients that available prompts have changed
notifications/resources/list_changed	Informs clients that available resources have changed

These notifications are already implemented in the schema:

• PhpMcp\Schema\Notification\ToolListChangedNotification
• PhpMcp\Schema\Notification\PromptListChangedNotification
• PhpMcp\Schema\Notification\ResourceListChangedNotification

The Mcp\Server\Registry already has the infrastructure to emit list_changed events:

// vendor/llm/mcp-server/src/Protocol.php
$this->registry->on('list_changed', function (string $listType): void {
    $this->handleListChanged($listType);
});