项目介绍
测试和热重载 MCP 服务器，带有 CLI 检查工具和透明代理功能
双模式 MCP 开发工具，作为 CLI 检查工具和 Model Context Protocol (MCP) 的透明代理服务器运行。与 VSCode MCP 配合良好，支持其他 MCP 启用的客户端。
🔄 两种模式，一个工具
reloaderoo 提供两种不同的操作模式以适应不同的开发工作流程：
🔍 CLI 模式（检查和测试）
无需客户端设置即可直接访问 MCP 服务器的命令行：
- ✅ 一次性命令 - 测试工具，列出资源，获取服务器信息
- ✅ 无需 MCP 客户端 - 完美用于测试和调试
- ✅ 原始 JSON 输出 - 适合脚本和自动化
- ✅ 8 个检查命令 - 完整覆盖 MCP 协议
🔄 代理模式（热重载开发）
透明代理服务器，实现无缝热重载：
- ✅ 热重载 MCP 服务器 而不中断你的 AI 客户端
- ✅ 会话持久性 - 保持你的开发上下文完整
- ✅ 自动
restart_server工具 - AI 代理可以按需重启服务器 - ✅ 透明转发 - 完全 MCP 协议通过
🎯 为什么选择 reloaderoo？
在开发 MCP 服务器时，通常面临两个问题：
- 测试需要复杂的 MCP 客户端设置 → CLI 模式解决了这个问题
- 代码更改需要重新启动整个 AI 会话 → 代理模式解决了这个问题
两种模式协同工作，创建无缝的 MCP 开发体验。
🚀 快速开始
安装
# 全局安装以便于访问
npm install -g reloaderoo
# 或使用 npx（无需安装）
npx reloaderoo --help
选择你的模式
🔍 CLI 模式 - 测试和调试
无需客户端设置即可完美测试 MCP 服务器：
# 列出服务器中的所有工具
reloaderoo inspect list-tools -- node my-mcp-server.js
# 调用特定工具
reloaderoo inspect call-tool echo --params '{"message":"hello"}' -- node my-mcp-server.js
# 获取服务器信息
reloaderoo inspect server-info -- node my-mcp-server.js
🔄 代理模式 - 热重载开发
具有热重载能力的 AI 客户端集成：
# 启动代理服务器（你的 AI 客户端连接到此）
reloaderoo proxy -- node my-mcp-server.js
# 带有调试日志
reloaderoo proxy --log-level debug -- node my-mcp-server.js
然后配置你的 AI 客户端连接到 reloaderoo 而不是直接连接到你的服务器。
🎯 推荐客户端
最佳体验：VSCode & Cursor - 完整协议支持并自动检测功能 良好体验：Claude Code & Windsurf - 运行良好，可能需要手动刷新新工具
🛠️ 开发工作流程
🔍 CLI 模式工作流程（测试和调试）
完美用于测试单个工具或调试服务器问题：
# 1. 快速测试你的服务器
reloaderoo inspect list-tools -- node my-mcp-server.js
# 2. 调用特定工具以验证行为
reloaderoo inspect call-tool my_tool --params '{"param":"value"}' -- node my-mcp-server.js
# 3. 检查服务器健康状况
reloaderoo inspect ping -- node my-mcp-server.js
🔄 代理模式工作流程（热重载开发）
用于完整的开发会话与 AI 客户端：
1. 开始开发会话
配置你的 AI 客户端连接到 reloaderoo 代理而不是直接连接到你的服务器：
reloaderoo proxy -- node my-mcp-server.js
# 或带调试日志：
reloaderoo proxy --log-level debug -- node my-mcp-server.js
2. 开发你的 MCP 服务器
像平常一样工作在你的服务器代码上：
// my-mcp-server.js
export const server = new Server({
name: "my-awesome-server",
version: "1.0.0"
});
// 添加新的工具，修改现有的工具等。
server.addTool("new_feature", /* ... */);
3. 即时测试更改
请求你的 AI 代理重启服务器：
"请重启 MCP 服务器以加载我的更改"
代理将自动调用 restart_server 工具。你的新功能立即可用！
4. 继续开发
你的 AI 会话将继续使用更新的服务器功能。没有连接丢失，没有上下文重置。
📋 命令行界面
reloaderoo 提供两种主要的操作模式：
reloaderoo [选项] [命令]
全局选项：
-V, --version 显示版本号
-h, --help 显示命令帮助
命令：
proxy [选项] -- <子命令> 🔄 作为 MCP 代理服务器运行（热重载模式）
inspect [子命令] 🔍 检查和调试 MCP 服务器（CLI 模式）
info [选项] 📊 显示版本和配置信息
help [命令] ❓ 显示命令帮助
🔄 代理模式命令（热重载开发）
reloaderoo proxy [选项] -- <子命令> [子命令参数...]
选项：
-w, --working-dir <目录> 子进程的工作目录
-l, --log-level <级别> 日志级别（debug, info, notice, warning, error, critical）
-f, --log-file <路径> 自定义日志文件路径（默认输出到 stderr）
-t, --restart-timeout <毫秒> 重启操作超时时间（默认：30000毫秒）
-m, --max-restarts <次数> 最大重启尝试次数 0-10（默认：3）
-d, --restart-delay <毫秒> 重启尝试之间的延迟（默认：11000毫秒）
-q, --quiet 抑制非必要输出
--no-auto-restart 禁用崩溃时的自动重启
--debug 启用调试模式并启用详细日志记录
--dry-run 验证配置而不启动代理
示例：
reloaderoo proxy -- node server.js
reloaderoo -- node server.js # 与上面相同（代理是默认模式）
reloaderoo proxy --log-level debug -- python mcp_server.py --port 8080
🔍 CLI 模式命令（检查和测试）
reloaderoo inspect [子命令] [选项] -- <子命令> [子命令参数...]
子命令：
server-info [选项] 获取服务器信息和功能
list-tools [选项] 列出所有可用工具
call-tool [选项] <名称> 调用特定工具
list-resources [选项] 列出所有可用资源
read-resource [选项] <URI> 读取特定资源
list-prompts [选项] 列出所有可用提示
get-prompt [选项] <名称> 获取特定提示
ping [选项] 检查服务器连通性
mcp [选项] 启动 MCP 检查服务器（作为 MCP 服务器暴露调试工具）
常见选项（适用于所有子命令）：
-w, --working-dir <目录> 子进程的工作目录
-t, --timeout <毫秒> 操作超时时间（默认：30000毫秒）
-q, --quiet 抑制子进程 stderr 输出（获得干净的 JSON）
示例：
reloaderoo inspect list-tools -- node server.js
reloaderoo inspect call-tool get_weather --params '{"location": "London"}' -- node server.js
reloaderoo inspect server-info -- node server.js
reloaderoo inspect mcp -- node server.js # 启动 MCP 检查服务器
# 获取干净的 JSON 输出而无服务器日志
reloaderoo inspect list-tools --quiet -- node server.js
reloaderoo inspect call-tool echo --quiet --params '{"message":"test"}' -- node server.js
Info 命令（诊断）
reloaderoo info [选项]
选项：
--verbose 显示详细的系统信息
示例：
reloaderoo info # 显示基本系统信息
reloaderoo info --verbose # 显示详细的诊断信息
🔍 CLI 模式深入（检查和测试）
CLI 模式提供直接的命令行访问 MCP 服务器，无需客户端设置 - 完美用于测试和调试。
🤖 AI 代理用例 - 主要设计目标
CLI 模式特别设计用于 AI 代理（如 Claude Code, Cursor 等），这些代理具有终端访问权限但不具备 MCP 服务器配置能力。这解决了关键的开发工作流程问题：
问题：当 AI 代理帮助你开发 MCP 服务器时，它需要测试更改，但是：
- ❌ 代理无法自行配置以直接使用你的 MCP 服务器
- ❌ 请求用户手动配置 MCP 客户端会中断开发流程
- ❌ 使用资源工具或网络获取是间接且有限的
解决方案：CLI 模式给 AI 代理提供了直接的基于终端的访问你的 MCP 服务器：
- ✅ 无需客户端配置：代理使用终端命令，而非 MCP 客户端设置
- ✅ 无状态且可靠：每个命令独立运行 - 没有持久连接失败的风险
- ✅ 原始协议访问：代理可以看到确切的 MCP 输入/输出，便于透明调试
- ✅ 即时测试：代理可以在没有用户干预的情况下即时验证更改
🔧 技术优势
无状态执行：
- 每个 CLI 命令都会启动服务器，执行请求，然后终止
- 完美的可靠性 - 没有持久状态会被破坏
- 没有连接管理和会话处理复杂性
⚠️ 重要限制：
- 内存状态机的服务器在 CLI 模式下不会正常工作
- 每个命令都是隔离的 - 调用之间没有共享状态
- 对于有状态的服务器，请使用代理模式
透明调试：
- 原始 JSON 输出显示确切的 MCP 协议请求/响应
- 没有代理层或客户端解释
- 完美理解实际发生的协议层面的情况
- 使用
--quiet标志抑制服务器日志，获得干净的 JSON 用于脚本
📝 直接 CLI 命令（一次性执行）
执行单个命令并立即获得结果：
# 列出服务器中的所有工具
reloaderoo inspect list-tools -- node my-server.js
# 调用特定工具
reloaderoo inspect call-tool echo --params '{"message":"hello"}' -- node my-server.js
# 获取服务器信息
reloaderoo inspect server-info -- node my-server.js
# 检查服务器连通性
reloaderoo inspect ping -- node my-server.js
# 获取干净的 JSON 输出而无服务器日志（适合脚本）
reloaderoo inspect list-tools --quiet -- node my-server.js
reloaderoo inspect call-tool echo --quiet --params '{"message":"hello"}' -- node my-server.js
🔧 MCP 检查服务器（持久 CLI 模式用于 MCP 客户端）
以持久 MCP 服务器的形式启动 CLI 模式进行交互式调试：
# 以 CLI 模式启动 reloaderoo 作为 MCP 服务器
reloaderoo inspect mcp -- node my-server.js
这将以持久 MCP 服务器的形式运行 CLI 模式，通过 MCP 协议暴露 8 个调试工具：
list_tools- 列出所有服务器工具call_tool- 调用任何服务器工具list_resources- 列出所有服务器资源read_resource- 读取任何服务器资源list_prompts- 列出所有服务器提示get_prompt- 获取任何服务器提示get_server_info- 获取全面的服务器信息ping- 测试服务器连通性
🏗️ 两种模式如何工作
🔄 代理模式架构（热重载开发）
graph LR
A[AI 客户端] -->|MCP 协议| B[reloaderoo 代理]
B -->|转发消息| C[你的 MCP 服务器]
B -->|管理生命周期| C
B -->|添加 restart_server 工具| A
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
代理模式魔力：
- 透明转发 - 所有 MCP 消息无缝通过
- 功能增强 - 在你的服务器功能中添加
restart_server工具 - 进程管理 - 启动、监控和重启你的服务器进程
- 会话持久性 - 客户端连接在服务器重启期间保持活动
- 协议合规性 - 完整支持 MCP v2025-03-26 并具有智能回退
🔍 CLI 模式架构（直接测试）
graph LR
A[你的终端] -->|直接命令| B[reloaderoo 检查]
B -->|启动并查询| C[你的 MCP 服务器]
B -->|返回 JSON| A
style A fill:#e8f5e8
style B fill:#f3e5f5
style C fill:#e1f5fe
CLI 模式魔力：
- 直接执行 - 没有代理层，直接命令执行
- 一次性查询 - 每个命令启动服务器，执行并返回结果
- 原始 JSON 输出 - 完美用于自动化和脚本
- 无需客户端设置 - 测试 MCP 服务器无需配置 MCP 客户端
- 8 个检查命令 - 完整覆盖 MCP 协议以进行测试
🔧 配置
环境变量
通过环境变量配置 reloaderoo 行为：
# 日志配置
export MCPDEV_PROXY_LOG_LEVEL=debug # 日志级别（debug, info, notice, warning, error, critical）
export MCPDEV_PROXY_LOG_FILE=/path/to/log # 自定义日志文件路径（默认：stderr）
export MCPDEV_PROXY_DEBUG_MODE=true # 启用调试模式（true/false）
# 进程管理
export MCPDEV_PROXY_RESTART_LIMIT=5 # 最大重启尝试次数（0-10，默认：3）
export MCPDEV_PROXY_AUTO_RESTART=true # 启用/禁用自动重启（true/false）
export MCPDEV_PROXY_TIMEOUT=30000 # 操作超时时间（毫秒）
export MCPDEV_PROXY_RESTART_DELAY=1000 # 重启尝试之间的延迟（毫秒）
export MCPDEV_PROXY_CWD=/path/to/directory # 默认工作目录
🎨 集成示例
🔄 代理模式集成（MCP 客户端设置）
配置你的 MCP 客户端连接到 reloaderoo 代理而不是直接连接到你的服务器：
{
"mcpServers": {
"my-dev-server": {
"command": "reloaderoo",
"args": [
"proxy",
"--",
"node",
"my-dev-server.js"
]
}
}
}
🔍 CLI 模式集成（自动化和测试）
完美用于 CI/CD，测试脚本和自动化工作流：
#!/bin/bash
# 示例：你的 MCP 服务器测试脚本
# 检查服务器是否健康（使用 --quiet 获得干净输出）
if reloaderoo inspect ping --quiet -- node my-server.js >/dev/null 2>&1; then
echo "✅ 服务器健康"
else
echo "❌ 服务器健康检查失败"
exit 1
fi
# 使用干净的 JSON 输出测试特定功能
echo "测试 echo 工具..."
result=$(reloaderoo inspect call-tool echo --quiet --params '{"message":"test"}' -- node my-server.js)
# 解析并验证 JSON 响应（无服务器日志干扰）
if echo "$result" | jq -e '.content[0].text' >/dev/null; then
echo "✅ Echo 工具测试通过"
echo "响应：$(echo "$result" | jq -r '.content[0].text')"
else