MCP重载器

一个用于使用Claude Code构建MCP（模型上下文协议）服务器的热重载开发工具。此工具使Claude Code能够动态重新加载修改过的MCP工具，使其非常适合迭代开发，其中Claude Code可以实时编写和测试MCP工具。

概述

MCP重载器特别设计用于使用Claude Code构建MCP工具的开发者。它解决了常见的开发痛点，即每当服务器工具被修改时，MCP客户端需要重启。通过实现文件监视和tools/list_changed通知，Claude Code可以在不手动重启的情况下修改工具并立即进行测试。

关键特性

• 实时工具开发：Claude Code可以在不重启的情况下编写、修改和测试MCP工具。
• 动态工具加载：自动从tools/目录加载JavaScript工具。
• 即时反馈循环：更改会立即反映在MCP客户端中。
• 文件监视：使用chokidar实时检测文件变化。
• 进程包装：为任何LSP/MCP进程添加热重载功能。
• 配置更改后自动重启：监视配置文件并在需要时重启。

快速开始使用Claude Code

1. 创建一个新的MCP项目

mkdir my-mcp-tools
cd my-mcp-tools
mkdir tools

2. 配置Claude桌面

在你的claude_desktop_config.json中添加：

{
  "mcpServers": {
    "my-tools": {
      "command": "npx",
      "args": ["mcp-reloader"],
      "cwd": "/path/to/my-mcp-tools"
    }
  }
}

3. 让Claude Code创建工具

现在Claude Code可以在tools/目录下创建和修改工具，并且它们将自动可用而无需重启Claude桌面！

示例：Claude Code创建工具

这里是如何让Claude Code创建一个立即可用的工具：

// tools/search-files.js
export default {
  name: "search_files",
  description: "搜索匹配模式的文件",
  inputSchema: {
    type: "object",
    properties: {
      pattern: {
        type: "string",
        description: "要搜索的文件的通配符模式"
      },
      directory: {
        type: "string",
        description: "要搜索的目录",
        default: "."
      }
    },
    required: ["pattern"]
  },
  handler: async ({ pattern, directory = "." }) => {
    const { glob } = await import('glob');
    const files = await glob(pattern, { cwd: directory });
    return `找到 ${files.length} 个文件:\n${files.join('\n')}`;
  }
};

Claude Code可以创建这个文件，它将立即可用！

安装

# 全局安装
npm install -g mcp-reloader

# 或者直接使用npx（推荐）
npx mcp-reloader --help

使用

基本服务器启动

# 启动默认的MCP服务器并启用热重载
npx mcp-reloader

# 或者如果全局安装了
mcp-reloader

使用包含模式

监视额外的文件并在它们发生变化时重启进程：

# 监视配置文件
npx mcp-reloader --include "config/**/*.json" --include "src/lib/**/*.js"

# 或者使用环境变量
MCP_HOT_RELOAD_INCLUDE='config/**/*.json,src/lib/**/*.js' npx m
cp-reloader

包装自定义LSP服务器

为任何LSP服务器添加热重载功能：

# 包装Python LSP服务器
npx mcp-reloader --include "**/*.yaml" -- python my-lsp-server.py --port 3000

# 包装具有复杂参数的Node.js服务器
npx mcp-reloader --include "**/*.ts" -- node --experimental-specifier-resolution=node ./dist/server.js --config ./config.json

# 旧命令格式（仍然支持）
npx mcp-reloader cmd:python server.py --port 3000

示例：包装现有的MCP服务器

这里是如何为任何MCP服务器添加热重载。这个例子包装了一个简单的回显服务器：

{
  "mcpServers": {
    "echo-with-reload": {
      "command": "npx",
      "args": [
        "mcp-reloader",
        "--include", "examples/echo-server/config.json",
        "--",
        "node",
        "examples/echo-server/server.js"
      ]
    }
  }
}

当config.json发生变化时，整个回显服务器会自动重启。

命令行参数

--include模式

指定要监视的文件的通配符模式。当匹配的文件发生变化时，整个进程会重启。

# 单一模式
npx mcp-reloader --include "config.json"

# 多种模式
npx mcp-reloader --include "**/*.yaml" --include "lib/**/*.js"

--分隔符

--之后的所有内容都被视为命令及其参数。这使得传递复杂的参数变得容易，而无需转义。

# 简单命令
npx mcp-reloader -- python server.py --port 3000

# 复杂的Node.js参数
npx mcp-reloader --include "**/*.ts" -- node --experimental-specifier-resolution=node ./dist/server.js --config ./config.json

# 包含空格和特殊字符的参数
npx mcp-reloader -- python script.py --message "Hello World!" --path "/path with spaces/"

工作原理

两级重载策略

1. 工具文件（tools/*.js）：无需进程重启即可热重载

   • 文件变化由chokidar检测
   • 工具动态导入并清除缓存
   • 发送tools/list_changed通知给客户端
   • MCP客户端可以立即使用更新的工具

2. 包含模式文件：完全进程重启

   • 包装进程监视指定的通配符模式
   • 在变化时，整个服务器进程会被重启
   • 对于配置文件或核心依赖项很有用

架构

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│ MCP客户端  │────▶│   包装器   │────▶│  MCP服务器  │
└─────────────┘     └─────────────┘     └──────────────┘
                           │                      │
                           ▼                      ▼
                    文件监视           工具加载
                    (--include)            (tools/*.js)

预期行为

初始启动

• 服务器从tools/加载所有工具
• 初始工具立即可用
• 客户端接收工具列表

添加一个工具

• 创建新文件（例如，tools/hello.js）
• 服务器检测到新文件
• 工具自动加载
• 发送tools/list_changed通知
• 工具立即在客户端可用

修改一个工具

• 编辑现有文件（例如，tools/echo.js）
• 服务器检测到变化
• 工具重新加载新的实现
• 发送tools/list_changed通知
• 更新的行为立即可用

删除一个工具

• 移除文件（例如，tools/time.js）
• 服务器检测到删除
• 工具从可用工具中移除
• 发送tools/list_changed通知
• 工具不再可调用

包含模式变化

• 修改被监视的文件（例如，config.json）
• 包装器检测到变化
• 整个服务器进程重启
• 所有工具都根据新的配置重新加载

本地开发

对于开发mcp-reloader本身：

# 克隆并安装
git clone https://github.com/mizchi/mcp-reloader.git
cd mcp-reloader
npm install

# 构建TypeScript
npm run build

# 运行测试
npm test

# 运行开发服务器
npm run dev

# 测试热重载功能
./test-include.sh

与类似工具的比较

工具	使用场景	状态保存	MCP集成
mcp-reloader	MCP/LSP服务器	两级策略	原生支持
nodemon	通用用途	无（全重启）	手动设置
tsx watch	TypeScript专用	无（全重启）	无
Bun --hot	Bun运行时	是	无

贡献

欢迎贡献！请随时提交Pull Request。

许可证

MIT

致谢

该项目实现了模型上下文协议规范，以增强Claude Code的开发体验。